GetPrivateProfileSectionA-Funktion (winbase.h)

Ruft alle Schlüssel und Werte für den angegebenen Abschnitt einer Initialisierungsdatei ab.

Syntax

DWORD GetPrivateProfileSectionA(
  [in]  LPCSTR lpAppName,
  [out] LPSTR  lpReturnedString,
  [in]  DWORD  nSize,
  [in]  LPCSTR lpFileName
);

Parameter

[in] lpAppName

Der Name des Abschnitts in der Initialisierungsdatei.

[out] lpReturnedString

Ein Zeiger auf einen Puffer, der den Schlüsselnamen und Wertpaare empfängt, die dem benannten Abschnitt zugeordnet sind. Der Puffer wird mit einer oder mehreren mit Null beendeten Zeichenfolgen gefüllt. auf die letzte Zeichenfolge folgt ein zweites NULL-Zeichen.

[in] nSize

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

Die maximale Profilabschnittsgröße beträgt 32.767 Zeichen.

[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 gibt die Anzahl der in den Puffer kopierten Zeichen an, nicht einschließlich des endenden Nullzeichens. Wenn der Puffer nicht groß genug ist, um alle Schlüsselnamen und Wertpaare zu enthalten, die dem benannten Abschnitt zugeordnet sind, ist der Rückgabewert gleich nSize minus zwei.

Bemerkungen

Die Daten im Puffer, auf die vom lpReturnedString Parameter verwiesen wird, bestehen aus einer oder mehreren null-beendeten Zeichenfolgen, gefolgt von einem endgültigen Nullzeichen. Jede Zeichenfolge weist das folgende Format auf:

Schlüssel=Zeichenfolge

Bei der GetPrivateProfileSection--Funktion wird die Groß-/Kleinschreibung nicht beachtet. Die Zeichenfolge, auf die der parameter lpAppName verweist, kann eine Kombination aus Groß- und Kleinbuchstaben sein.

Dieser Vorgang ist atomar; Es sind keine Aktualisierungen der angegebenen Initialisierungsdatei zulässig, während die Schlüsselnamen- und Wertpaare für den Abschnitt in den Puffer kopiert werden, auf den der lpReturnedString-Parameter verweist.

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.

Kommentare (alle Zeilen, die mit einem Semikolon beginnen) werden entfernt und nicht im lpReturnedString Puffer zurückgegeben.

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

GetPrivateProfileSectionNames-

GetProfileSection-

WritePrivateProfileSection-