WritePrivateProfileStringA-Funktion (winbase.h)
Kopiert eine Zeichenfolge in den angegebenen Abschnitt einer Initialisierungsdatei.
Syntax
BOOL WritePrivateProfileStringA(
[in] LPCSTR lpAppName,
[in] LPCSTR lpKeyName,
[in] LPCSTR lpString,
[in] LPCSTR lpFileName
);
Parameter
[in] lpAppName
Der Name des Abschnitts, in den die Zeichenfolge kopiert wird. Wenn der Abschnitt nicht vorhanden ist, wird er erstellt. Der Name des Abschnitts ist unabhängig von der Groß-/Kleinschreibung; Die Zeichenfolge kann eine beliebige Kombination aus Groß- und Kleinbuchstaben sein.
[in] lpKeyName
Der Name des Schlüssels, der einer Zeichenfolge zugeordnet werden soll. Wenn der Schlüssel im angegebenen Abschnitt nicht vorhanden ist, wird er erstellt. Wenn dieser Parameter NULL ist, wird der gesamte Abschnitt einschließlich aller Einträge innerhalb des Abschnitts gelöscht.
[in] lpString
Eine NULL-endende Zeichenfolge, die in die Datei geschrieben werden soll. Wenn dieser Parameter NULL ist, wird der Schlüssel gelöscht, auf den der lpKeyName-Parameter verweist.
[in] lpFileName
Der Name der Initialisierungsdatei.
Wenn die Datei mit Unicode-Zeichen erstellt wurde, schreibt die Funktion Unicode-Zeichen in die Datei. Andernfalls schreibt die Funktion ANSI-Zeichen.
Rückgabewert
Wenn die Funktion die Zeichenfolge erfolgreich in die Initialisierungsdatei kopiert, ist der Rückgabewert ungleich null.
Wenn die Funktion fehlschlägt oder die zwischengespeicherte Version der zuletzt aufgerufenen Initialisierungsdatei geleert wird, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
Hinweise
Ein Abschnitt in der Initialisierungsdatei muss die folgende Form aufweisen:
[section]
key=string
.
.
.
Wenn der lpFileName-Parameter keinen vollständigen Pfad und Dateinamen für die Datei enthält, durchsucht WritePrivateProfileString das Windows-Verzeichnis nach der Datei. Wenn die Datei nicht vorhanden ist, erstellt diese Funktion die Datei im Windows-Verzeichnis.
Wenn lpFileName einen vollständigen Pfad und Dateinamen enthält und die Datei nicht vorhanden ist, erstellt WritePrivateProfileString die Datei. Das angegebene Verzeichnis muss bereits vorhanden sein.
Das System behält eine zwischengespeicherte Version der letzten Registrierungsdateizuordnung bei, um die Leistung zu verbessern. Wenn alle Parameter NULL sind, leert die Funktion den Cache. Während das System die zwischengespeicherte Version der Datei bearbeitet, verwenden Prozesse, die die Datei selbst bearbeiten, die ursprüngliche Datei, bis der Cache gelöscht wurde.
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.ini und Winfile.ini ändert. In diesem Fall schreibt die Funktion Informationen in die Registrierung, nicht in die Initialisierungsdatei. 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.
- ! – 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.
- Stellen Sie sicher, dass im System keine .ini Datei mit dem angegebenen Namen vorhanden ist.
- Stellen Sie sicher, dass in der Registrierung ein Schlüsseleintrag vorhanden ist, der die .ini-Datei angibt. Dieser Eintrag sollte sich unter dem Pfad HKEY_LOCAL_MACHINE\SOFTWARE \Microsoft\Windows NT\CurrentVersion\IniFileMapping befinden.
- Geben Sie einen Wert für diesen .ini Dateischlüsseleintrag an, der einen Abschnitt angibt. Das heißt, eine Anwendung muss einen Abschnittsnamen angeben, wie er in einer .ini-Datei oder einem Registrierungseintrag angezeigt wird. Hier ist ein Beispiel: [Mein Abschnitt].
- Geben Sie für Systemdateien SYS für einen Zusätzlichen Wert an.
- Geben Sie für Anwendungsdateien usr innerhalb des Mehrwerts an. Hier ist ein Beispiel: "Mein Abschnitt: USR: App-Name\Abschnitt". Da USR eine Zuordnung unter HKEY_CURRENT_USER angibt, sollte die Anwendung auch einen Schlüssel unter HKEY_CURRENT_USER erstellen, der den im Mehrwert aufgeführten Anwendungsnamen angibt. Für das soeben angegebene Beispiel wäre dies "App-Name".
- Nachdem Sie die vorherigen Schritte ausgeführt haben, sollte ein Programm für die Anwendungseinrichtung WritePrivateProfileString aufrufen, wobei die ersten drei Parameter auf NULL und der vierte Parameter auf den INI-Dateinamen festgelegt ist. Beispiel:
WritePrivateProfileString( NULL, NULL, NULL, L"appname.ini" ); - Ein solcher Aufruf bewirkt, dass die Zuordnung einer .ini-Datei zur Registrierung vor dem nächsten Systemneustart wirksam wird. Das System liest die Zuordnungsinformationen erneut in freigegebenen Speicher. Ein Benutzer muss seinen Computer nach der Installation einer Anwendung nicht neu starten, damit zukünftige Aufrufe der Anwendung die Zuordnung der .ini-Datei zur Registrierung sehen.
Beispiele
Der folgende Beispielcode veranschaulicht die vorangehenden Richtlinien und basiert auf mehreren Annahmen:
- Es gibt eine Anwendung namens App-Name.
- Diese Anwendung verwendet eine .ini-Datei namens AppName.ini.
- Es gibt einen Abschnitt in der .ini-Datei, der wie folgt aussehen soll:
[Section1] FirstKey = It all worked out okay. SecondKey = By golly, it works. ThirdKey = Another test. - Der Benutzer muss das System nicht neu starten, damit zukünftige Aufrufe der Anwendung die Zuordnung der .ini-Datei zur Registrierung sehen.
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
int main()
{
TCHAR inBuf[80];
HKEY hKey1, hKey2;
DWORD dwDisposition;
LONG lRetCode;
TCHAR szData[] = TEXT("USR:App Name\\Section1");
// Create the .ini file key.
lRetCode = RegCreateKeyEx ( HKEY_LOCAL_MACHINE,
TEXT("SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\IniFileMapping\\appname.ini"),
0,
NULL,
REG_OPTION_NON_VOLATILE,
KEY_WRITE,
NULL,
&hKey1,
&dwDisposition);
if (lRetCode != ERROR_SUCCESS)
{
printf ("Error in creating appname.ini key (%d).\n", lRetCode);
return (0) ;
}
// Set a section value
lRetCode = RegSetValueEx ( hKey1,
TEXT("Section1"),
0,
REG_SZ,
(BYTE *)szData,
sizeof(szData));
if (lRetCode != ERROR_SUCCESS)
{
printf ("Error in setting Section1 value\n");
// Close the key
lRetCode = RegCloseKey( hKey1 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return (0) ;
}
}
// Create an App Name key
lRetCode = RegCreateKeyEx ( HKEY_CURRENT_USER,
TEXT("App Name"),
0,
NULL,
REG_OPTION_NON_VOLATILE,
KEY_WRITE,
NULL,
&hKey2,
&dwDisposition);
if (lRetCode != ERROR_SUCCESS)
{
printf ("Error in creating App Name key (%d).\n", lRetCode);
// Close the key
lRetCode = RegCloseKey( hKey2 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return (0) ;
}
}
// Force the system to read the mapping into shared memory
// so that future invocations of the application will see it
// without the user having to reboot the system
WritePrivateProfileStringW( NULL, NULL, NULL, L"appname.ini" );
// Write some added values
WritePrivateProfileString (TEXT("Section1"),
TEXT("FirstKey"),
TEXT("It all worked out OK."),
TEXT("appname.ini"));
WritePrivateProfileString (TEXT("Section1"),
TEXT("SecondKey"),
TEXT("By golly, it works!"),
TEXT("appname.ini"));
WritePrivateProfileString (TEXT("Section1"),
TEXT("ThirdKey"),
TEXT("Another test..."),
TEXT("appname.ini"));
// Test
GetPrivateProfileString (TEXT("Section1"),
TEXT("FirstKey"),
TEXT("Error: GPPS failed"),
inBuf,
80,
TEXT("appname.ini"));
_tprintf (TEXT("Key: %s\n"), inBuf);
// Close the keys
lRetCode = RegCloseKey( hKey1 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return(0);
}
lRetCode = RegCloseKey( hKey2 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return(0);
}
return(1);
}
Hinweis
Der winbase.h-Header definiert WritePrivateProfileString 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
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für