GetProfileStringA-Funktion (winbase.h)

Artikel
08/27/2023

Ruft die Zeichenfolge ab, die einem Schlüssel im angegebenen Abschnitt der Win.ini-Datei zugeordnet ist.

Hinweis Diese Funktion wird nur aus Gründen der Kompatibilität mit 16-Bit-Windows-basierten Anwendungen bereitgestellt. Daher sollte diese Funktion nicht vom Servercode aufgerufen werden. Anwendungen sollten Initialisierungsinformationen in der Registrierung speichern.

Syntax

DWORD GetProfileStringA(
  [in]  LPCSTR lpAppName,
  [in]  LPCSTR lpKeyName,
  [in]  LPCSTR lpDefault,
  [out] LPSTR  lpReturnedString,
  [in]  DWORD  nSize
);

Parameter

[in] lpAppName

Der Name des Abschnitts, der den Schlüssel enthält. Wenn dieser Parameter NULL ist, kopiert die 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, kopiert die Funktion alle Schlüssel im angegebenen Abschnitt in den angegebenen Puffer. Auf jede Zeichenfolge folgt ein NULL-Zeichen , und auf die letzte Zeichenfolge folgt ein zweites NULL-Zeichen .

[in] lpDefault

Eine Standardzeichenfolge. Wenn der Schlüssel lpKeyName in der Initialisierungsdatei nicht gefunden werden kann, kopiert GetProfileString die Standardzeichenfolge in den puffer lpReturnedString . 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 den lpReturnedString-Puffer ein, um nachgestellte Leerzeichen zu entfernen.

[out] lpReturnedString

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

[in] nSize

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

Rückgabewert

Der Rückgabewert ist die Anzahl der Zeichen, die in den Puffer kopiert werden, ohne dass das NULL-Endzeichen enthalten ist.

Wenn weder lpAppName noch lpKeyNameNULL 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 lpAppName oder lpKeyNameNULL ist und der angegebene Zielpuffer zu klein ist, um alle Zeichenfolgen zu enthalten, wird die letzte Zeichenfolge abgeschnitten und von zwei NULL-Zeichen gefolgt. In diesem Fall ist der Rückgabewert gleich nSize minus 2.

Hinweise

Wenn die dem lpKeyName-Parameter zugeordnete Zeichenfolge in einfache oder doppelte Anführungszeichen eingeschlossen wird, werden die Markierungen verworfen, wenn die GetProfileString-Funktion die Zeichenfolge zurückgibt.

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

Ein Abschnitt in der Win.ini-Datei muss die folgende Form aufweisen:

[section]
key=string
      .
      .
      .

Eine Anwendung kann die GetPrivateProfileString-Funktion verwenden, um eine Zeichenfolge aus einer angegebenen Initialisierungsdatei abzurufen.

Der lpDefault-Parameter muss auf eine gültige Zeichenfolge verweisen, auch wenn die Zeichenfolge leer ist (das heißt, auch wenn das erste Zeichen ein NULL-Zeichen ist).

Windows Server 2003 und Windows XP/2000: Aufrufe von Profilfunktionen können der Registrierung und nicht den Initialisierungsdateien zugeordnet werden. Diese Zuordnung tritt auf, wenn die Initialisierungsdatei und der Abschnitt in der Registrierung unter den folgenden Schlüsseln angegeben sind:

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\Currentversion\IniFileMapping

Wenn der Vorgang zugeordnet wurde, ruft die GetProfileString-Funktion Informationen aus der Registrierung und nicht aus der Initialisierungsdatei ab. die Änderung des Speicherorts hat keine Auswirkungen auf das Verhalten der Funktion.

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

Suchen Sie in der Registrierung nach dem Namen der Initialisierungsdatei unter dem Schlüssel IniFileMapping .
Suchen Sie nach dem abschnittsnamen, der von lpAppName angegeben wurde. Dies ist ein benannter Wert unter dem Schlüssel, der den Namen der Initialisierungsdatei enthält, oder ein Unterschlüssel mit diesem Namen, oder der Name ist weder als Wert noch als Unterschlüssel vorhanden.
Wenn der von lpAppName angegebene Abschnittsname ein benannter Wert ist, gibt dieser Wert an, wo sie in der Registrierung die Schlüssel für den Abschnitt finden.
Wenn der von lpAppName angegebene Abschnittsname ein Unterschlüssel ist, geben benannte Werte unter diesem Unterschlüssel an, wo sie in der Registrierung die Schlüssel für den Abschnitt finden. Wenn der gesuchte Schlüssel nicht als benannter Wert vorhanden ist, gibt es einen unbenannten Wert (angezeigt als <No Name>), der den Standardspeicherort in der Registrierung angibt, an dem Sie den Schlüssel finden werden.
Wenn der von lpAppName angegebene Abschnittsname nicht als benannter Wert oder Als Unterschlüssel vorhanden ist, gibt es einen unbenannten Wert (angezeigt als <No Name>), der den Standardspeicherort in der Registrierung angibt, an dem Sie die Schlüssel für den Abschnitt finden.
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 den 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 erzwingt, dass alle Schreibvorgänge sowohl in die Registrierung als auch in die .ini-Datei auf dem Datenträger 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 nicht in der Registrierung 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\SOFTWARE, und der Text nach dem Präfix ist relativ zu diesem Schlüssel.

Hinweis

Der winbase.h-Header definiert GetProfileString als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll

Siehe auch

GetPrivateProfileString

WriteProfileString

Share via