WritePrivateProfileStringW-Funktion (winbase.h)
Kopiert eine Zeichenfolge in den angegebenen Abschnitt einer Initialisierungsdatei.
Syntax
BOOL WritePrivateProfileStringW(
[in] LPCWSTR lpAppName,
[in] LPCWSTR lpKeyName,
[in] LPCWSTR lpString,
[in] LPCWSTR 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 fallunabhängig; 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--terminated-Zeichenfolge, die in die Datei geschrieben werden soll. Wenn dieser Parameter NULL-ist, wird der schlüssel, auf den der parameter lpKeyName verweist, gelöscht.
[in] lpFileName
Der Name der Initialisierungsdatei.
Wenn die Datei bereits vorhanden ist und aus Unicode-Zeichen besteht, 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. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Bemerkungen
Ein Abschnitt in der Initialisierungsdatei muss das folgende Formular aufweisen:
[section]
key=string
.
.
.
Wenn der parameter lpFileName keinen vollständigen Pfad und Dateinamen für die Datei enthält, WritePrivateProfileString das Windows-Verzeichnis nach der Datei durchsucht. 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 neuesten Registrierungsdateizuordnung bei, um die Leistung zu verbessern. Wenn alle Parameter NULL-sind, löscht 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.iniund Winfile.iniändert. In diesem Fall schreibt die Funktion Informationen in die Registrierung, nicht in die 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.
- 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\IniFileMappingbefinden.
- 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 registrierungseintrag angezeigt wird. Hier ist ein Beispiel: [Mein Abschnitt].
- Geben Sie für Systemdateien SYS für einen Mehrwert an.
- Geben Sie für Anwendungsdateien USR innerhalb des Mehrwerts an. Hier ist ein Beispiel: "Mein Abschnitt: USR: App-Name\Abschnitt". Und da USR eine Zuordnung unter HKEY_CURRENT_USERangibt, 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 vorstehenden Schritte ausgeführt haben, sollte ein Anwendungssetupprogramm WritePrivateProfileString- aufrufen, wobei die ersten drei Parameter auf NULL-festgelegt sind, und der vierte Parameter, der auf den INI-Dateinamen festgelegt ist. Zum 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 gemeinsam genutzten Speicher um. 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 vorstehenden Richtlinien und basiert auf mehreren Annahmen:
- Es gibt eine Anwendung mit dem Namen "App-Name".
- Diese Anwendung verwendet eine .ini Datei namens AppName.ini.
- In der datei .ini befindet sich ein Abschnitt, 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);
}
Anmerkung
Der winbase.h-Header definiert WritePrivateProfileString als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante 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 |