GetPrivateProfileStringW-Funktion (winbase.h)

Ruft eine Zeichenfolge aus dem angegebenen Abschnitt in einer Initialisierungsdatei ab.

Syntax

DWORD GetPrivateProfileStringW(
  [in]  LPCWSTR lpAppName,
  [in]  LPCWSTR lpKeyName,
  [in]  LPCWSTR lpDefault,
  [out] LPWSTR  lpReturnedString,
  [in]  DWORD   nSize,
  [in]  LPCWSTR lpFileName
);

Parameter

[in] lpAppName

Der Name des Abschnitts, der den Schlüsselnamen enthält. Wenn dieser Parameter NULL-ist, kopiert die GetPrivateProfileString--Funktion alle Abschnittsnamen in der Datei in den angegebenen Puffer.

[in] lpKeyName

Der Name des Schlüssels, dessen zugeordnete Zeichenfolge abgerufen werden soll. Wenn dieser Parameter NULL-ist, werden alle Schlüsselnamen im Abschnitt, der durch den parameter lpAppName angegeben wird, in den durch den parameter lpReturnedString angegebenen Puffer kopiert.

[in] lpDefault

Eine Standardzeichenfolge. Wenn der lpKeyName Schlüssel in der Initialisierungsdatei nicht gefunden werden kann, kopiert GetPrivateProfileString die Standardzeichenfolge in den lpReturnedString Puffer.

Wenn dieser Parameter NULL-ist, ist der Standardwert eine leere Zeichenfolge , "".

Vermeiden Sie die Angabe einer Standardzeichenfolge mit nachfolgenden leeren Zeichen. Die Funktion fügt ein NULL- Zeichen in das lpReturnedString- Puffer ein, um nachfolgende Leerzeichen zu entfernen.

[out] lpReturnedString

Ein Zeiger auf den Puffer, der die abgerufene Zeichenfolge empfängt.

[in] nSize

Die Größe des Puffers, auf den der lpReturnedString Parameter in Zeichen verweist.

[in] lpFileName

Der Name der Initialisierungsdatei. Wenn dieser Parameter keinen vollständigen Pfad zur Datei enthält, sucht das System im Windows-Verzeichnis nach der Datei.

Rückgabewert

Der Rückgabewert ist die Anzahl der Zeichen, die in den Puffer kopiert wurden, nicht einschließlich des endenden NULL- Zeichens.

Wenn weder lpAppName noch lpKeyName-NULL- ist und der angegebene Zielpuffer zu klein ist, um die angeforderte Zeichenfolge zu speichern, wird die Zeichenfolge abgeschnitten und gefolgt von einem Null- Zeichen, und der Rückgabewert ist gleich nSize minus 1.

Wenn entweder lpAppName- oder lpKeyName-NULL- ist und der angegebene Zielpuffer zu klein ist, um alle Zeichenfolgen zu speichern, wird die letzte Zeichenfolge abgeschnitten und gefolgt von zwei null Zeichen. In diesem Fall entspricht der Rückgabewert nSize minus zwei.

Wenn die durch lpFileName- angegebene Initialisierungsdatei nicht gefunden wird oder ungültige Werte enthält, legt diese Funktion errorno mit dem Wert "0x2" (Datei nicht gefunden) fest. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen abzurufen.

Bemerkungen

Die GetPrivateProfileString--Funktion durchsucht die angegebene Initialisierungsdatei nach einem Schlüssel, der dem namen entspricht, der durch den parameter lpKeyName unter der Abschnittsüberschrift angegeben wird, die durch den lpAppName Parameter angegeben ist. Wenn der Schlüssel gefunden wird, kopiert die Funktion die entsprechende Zeichenfolge in den Puffer. Wenn der Schlüssel nicht vorhanden ist, kopiert die Funktion die durch den parameter lpDefault angegebene Standardzeichenzeichenfolge. Ein Abschnitt in der Initialisierungsdatei muss das folgende Formular aufweisen:

[section]
key=string
      .
      .
      .

Wenn lpAppName-NULL-ist, kopiert GetPrivateProfileString alle Abschnittsnamen in der angegebenen Datei in den angegebenen Puffer. Wenn lpKeyName-NULL-ist, kopiert die Funktion alle Schlüsselnamen im angegebenen Abschnitt in den angegebenen Puffer. Eine Anwendung kann diese Methode verwenden, um alle Abschnitte und Schlüssel in einer Datei aufzählen zu können. In beiden Fällen folgt auf jede Zeichenfolge ein NULL- Zeichen, und auf die letzte Zeichenfolge folgt ein zweites NULL- Zeichen. Wenn der angegebene Zielpuffer zu klein ist, um alle Zeichenfolgen zu speichern, wird die letzte Zeichenfolge abgeschnitten und gefolgt von zwei NULL- Zeichen.

Wenn die mit lpKeyName verknüpfte Zeichenfolge in einfache oder doppelte Anführungszeichen eingeschlossen ist, werden die Markierungen verworfen, wenn die GetPrivateProfileString-Funktion die Zeichenfolge abruft.

Bei der GetPrivateProfileString--Funktion wird die Groß-/Kleinschreibung nicht beachtet. Die Zeichenfolgen können eine Kombination aus Groß- und Kleinbuchstaben sein.

Um eine Zeichenfolge aus der Win.ini-Datei abzurufen, verwenden Sie die GetProfileString--Funktion.

Das System ordnet die meisten .ini Dateiverweise der Registrierung zu, wobei die unter dem folgenden Registrierungsschlüssel definierte Zuordnung verwendet wird:HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\IniFileMapping

Diese Zuordnung ist wahrscheinlich, wenn eine Anwendung Systemkomponenteninitialisierungsdateien wie Control.ini, System.iniund Winfile.iniändert. In diesen Fällen ruft die Funktion Informationen aus der Registrierung ab, nicht aus der Initialisierungsdatei; die Änderung am Speicherort hat keine Auswirkungen auf das Verhalten der Funktion.

Die Profilfunktionen verwenden die folgenden Schritte, um Initialisierungsinformationen zu finden:

1. Suchen Sie in der Registrierung nach dem Namen der Initialisierungsdatei unter dem schlüssel IniFileMapping.
2. Suchen Sie nach dem durch lpAppNameangegebenen Abschnittsnamen. Dies ist ein benannter Wert unter dem Schlüssel, der den Namen der Initialisierungsdatei oder einen Unterschlüssel mit diesem Namen enthält, oder der Name ist nicht als Wert oder Unterschlüssel vorhanden.
3. Wenn der durch lpAppName angegebene Abschnittsname ein benannter Wert ist, gibt dieser Wert an, wo in der Registrierung die Schlüssel für den Abschnitt gefunden werden.
4. Wenn der durch lpAppName angegebene Abschnittsname ein Unterschlüssel ist, geben benannte Werte unter diesem Unterschlüssel an, wo in der Registrierung die Schlüssel für den Abschnitt gefunden werden. Wenn der gesuchte Schlüssel nicht als benannter Wert vorhanden ist, gibt es einen unbenannten Wert (wie <No Name>), der den Standardspeicherort in der Registrierung angibt, an dem Sie den Schlüssel finden.
5. Wenn der durch lpAppName angegebene Abschnittsname nicht als benannter Wert oder als Unterschlüssel vorhanden ist, gibt es einen unbenannten Wert (wie <No Name>), der den Standardspeicherort in der Registrierung angibt, an dem Sie die Schlüssel für den Abschnitt finden.
6. Wenn kein Unterschlüssel oder Eintrag für den Abschnittsnamen vorhanden ist, suchen Sie nach der tatsächlichen Initialisierungsdatei auf dem Datenträger, und lesen Sie deren Inhalt.

Beim Betrachten von Werten in der Registrierung, die andere Registrierungsspeicherorte angeben, gibt es mehrere Präfixe, die das Verhalten der .ini Dateizuordnung ändern:

• ! - Dieses Zeichen zwingt alle Schreibvorgänge, sowohl zur Registrierung als auch zur .ini Datei auf dem Datenträger zu wechseln.
• # - Dieses Zeichen bewirkt, dass der Registrierungswert auf den Wert in der Windows 3.1-.ini-Datei festgelegt wird, wenn sich ein neuer Benutzer nach dem Setup zum ersten Mal anmeldet.
• @ - Dieses Zeichen verhindert, dass lesevorgänge zur .ini Datei auf dem Datenträger wechseln, wenn die angeforderten Daten in der Registrierung nicht gefunden werden.
• USR: - Dieses Präfix steht für HKEY_CURRENT_USER, und der Text nach dem Präfix ist relativ zu diesem Schlüssel.
• SYS: - Dieses Präfix steht für HKEY_LOCAL_MACHINE\SOFTWAREund der Text nach dem Präfix relativ zu diesem Schlüssel.

Beispiel

Im folgenden Beispiel wird die Verwendung von GetPrivateProfileString-veranschaulicht.

// Gets a profile string called "Preferred line" and converts it to an int.
GetPrivateProfileString (
      "Preference",
      "Preferred Line",
      gszNULL, 
      szBuffer,
      MAXBUFSIZE,
      gszINIfilename
);

// if szBuffer is not empty.
if ( lstrcmp ( gszNULL, szBuffer ) )
{
      dwPreferredPLID = (DWORD) atoi( szBuffer );	
}
else	
{
      dwPreferredPLID = (DWORD) -1;
}

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 2000 Professional [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winbase.h (enthalten Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll

Siehe auch

GetProfileString-

WritePrivateProfileString-