WritePrivateProfileStringA-Funktion (winbase.h)

Artikel
03/03/2024

Kopiert eine Zeichenfolge in den angegebenen Abschnitt einer Initialisierungsdatei.

Hinweis Diese Funktion wird nur aus Gründen der Kompatibilität mit 16-Bit-Versionen von Windows bereitgestellt. Anwendungen sollten Initialisierungsinformationen in der Registrierung speichern.

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.

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.

Eine Anwendung, die die WritePrivateProfileString-Funktion verwendet, um .ini Dateiinformationen in die Registrierung einzugeben, sollte die folgenden Richtlinien befolgen:

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

GetPrivateProfileString

WriteProfileString

Freigeben über