GetProfileStringA-Funktion (winbase.h)
Ruft die Zeichenfolge ab, die einem Schlüssel im angegebenen Abschnitt der Win.ini Datei zugeordnet ist.
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 Nullzeichen Zeichen.
[in] lpDefault
Eine Standardzeichenfolge. Wenn der lpKeyName Schlüssel in der Initialisierungsdatei nicht gefunden werden kann, kopiert GetProfileString 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 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 in den Puffer kopierten Zeichen, nicht einschließlich des NULL-zeichens-endating-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.
Bemerkungen
Wenn die dem lpKeyName Parameter zugeordnete Zeichenfolge in einfache oder doppelte Anführungszeichen eingeschlossen ist, 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 datei Win.ini muss das folgende Formular aufweisen:
[section]
key=string
.
.
.
Eine Anwendung kann die GetPrivateProfileString--Funktion verwenden, um eine Zeichenfolge aus einer angegebenen Initialisierungsdatei abzurufen.
Der parameter lpDefault muss auf eine gültige Zeichenfolge verweisen, auch wenn die Zeichenfolge leer ist (d. h., wenn es sich bei dem ersten Zeichen um ein Null- Zeichen handelt).
Windows Server 2003 und Windows XP/2000: Aufrufe an Profilfunktionen können der Registrierung anstelle der Initialisierungsdateien zugeordnet werden. Diese Zuordnung tritt auf, wenn die Initialisierungsdatei und der Abschnitt in der Registrierung unter den folgenden Schlüsseln angegeben werden:
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\IniFileMapping
Wenn der Vorgang zugeordnet wurde, ruft die GetProfileString--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:
- Suchen Sie in der Registrierung nach dem Namen der Initialisierungsdatei unter dem schlüssel IniFileMapping.
- 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.
- 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.
- 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.
- 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.
- 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.
- ! - 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.
Anmerkung
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 |
|---|---|
| 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 |