Fonction WritePrivateProfileStringA (winbase.h)

Article
03/03/2024

Copie une chaîne dans la section spécifiée d’un fichier d’initialisation.

Note Cette fonction est fournie uniquement pour la compatibilité avec les versions 16 bits de Windows. Les applications doivent stocker des informations d’initialisation dans le Registre.

Syntaxe

BOOL WritePrivateProfileStringA(
  [in] LPCSTR lpAppName,
  [in] LPCSTR lpKeyName,
  [in] LPCSTR lpString,
  [in] LPCSTR lpFileName
);

Paramètres

[in] lpAppName

Nom de la section dans laquelle la chaîne sera copiée. Si la section n’existe pas, elle est créée. Le nom de la section est indépendant de la casse ; la chaîne peut être n’importe quelle combinaison de lettres majuscules et minuscules.

[in] lpKeyName

Nom de la clé à associer à une chaîne. Si la clé n’existe pas dans la section spécifiée, elle est créée. Si ce paramètre a la valeur NULL, la section entière, y compris toutes les entrées de la section, est supprimée.

[in] lpString

Chaîne terminée par null à écrire dans le fichier. Si ce paramètre a la valeur NULL, la clé pointée vers le paramètre lpKeyName est supprimée.

[in] lpFileName

Nom du fichier d’initialisation.

Si le fichier a été créé à l’aide de caractères Unicode, la fonction écrit des caractères Unicode dans le fichier. Sinon, la fonction écrit des caractères ANSI.

Valeur retournée

Si la fonction copie correctement la chaîne dans le fichier d’initialisation, la valeur de retour est différente de zéro.

Si la fonction échoue ou si elle vide la version mise en cache du fichier d’initialisation le plus récemment consulté, la valeur de retour est zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Une section du fichier d’initialisation doit avoir la forme suivante :

[section]
key=string
      .
      .
      .

Si le paramètre lpFileName ne contient pas de chemin d’accès complet et de nom de fichier pour le fichier, WritePrivateProfileString recherche le fichier dans le répertoire Windows. Si le fichier n’existe pas, cette fonction crée le fichier dans le répertoire Windows.

Si lpFileName contient un chemin d’accès complet et un nom de fichier et que le fichier n’existe pas, WritePrivateProfileString crée le fichier. Le répertoire spécifié doit déjà exister.

Le système conserve une version mise en cache du mappage de fichiers de Registre le plus récent pour améliorer les performances. Si tous les paramètres ont la valeur NULL, la fonction vide le cache. Pendant que le système modifie la version mise en cache du fichier, les processus qui modifient le fichier lui-même utilisent le fichier d’origine jusqu’à ce que le cache soit effacé.

Le système mappe la plupart des références de fichier .ini au Registre, à l’aide du mappage défini sous la clé de Registre suivante :

HKEY_LOCAL_MACHINE
   SOFTWARE
      Microsoft
         Windows NT
            CurrentVersion
               IniFileMapping

Ce mappage est probable si une application modifie les fichiers d’initialisation des composants système, tels que Control.ini, System.ini et Winfile.ini. Dans ce cas, la fonction écrit des informations dans le Registre, et non dans le fichier d’initialisation ; le changement de l’emplacement de stockage n’a aucun effet sur le comportement de la fonction.

Les fonctions de profil utilisent les étapes suivantes pour localiser les informations d’initialisation :

Recherchez dans le Registre le nom du fichier d’initialisation sous la clé IniFileMapping .
Recherchez le nom de section spécifié par lpAppName. Il s’agit d’une valeur nommée sous la clé portant le nom du fichier d’initialisation, ou d’une sous-clé portant ce nom, ou le nom n’existe pas en tant que valeur ou sous-clé.
Si le nom de section spécifié par lpAppName est une valeur nommée, cette valeur spécifie où, dans le Registre, vous trouverez les clés de la section.
Si le nom de section spécifié par lpAppName est une sous-clé, les valeurs nommées sous cette sous-clé spécifient où, dans le Registre, vous trouverez les clés de la section. Si la clé que vous recherchez n’existe pas en tant que valeur nommée, il y aura une valeur sans nom (affichée sous la forme <No Name>) qui spécifie l’emplacement par défaut dans le Registre où vous trouverez la clé.
Si le nom de section spécifié par lpAppName n’existe pas en tant que valeur nommée ou sous-clé, il y aura une valeur sans nom (affichée sous la forme <No Name>) qui spécifie l’emplacement par défaut dans le Registre où vous trouverez les clés de la section.
S’il n’existe aucune sous-clé ou entrée pour le nom de section, recherchez le fichier d’initialisation réel sur le disque et lisez son contenu.

Lorsque vous examinez les valeurs dans le Registre qui spécifient d’autres emplacements de Registre, plusieurs préfixes modifient le comportement du mappage de fichiers .ini :

! - ce caractère force toutes les écritures à accéder au Registre et au fichier .ini sur le disque.
# : ce caractère entraîne la définition de la valeur du Registre sur la valeur dans le fichier .ini Windows 3.1 lorsqu’un nouvel utilisateur se connecte pour la première fois après l’installation.
@ : ce caractère empêche toute lecture d’atteindre le fichier .ini sur le disque si les données demandées sont introuvables dans le Registre.
USR : - ce préfixe correspond à HKEY_CURRENT_USER, et le texte après le préfixe est relatif à cette clé.
SYS : - ce préfixe représente HKEY_LOCAL_MACHINE\SOFTWARE, et le texte après le préfixe est relatif à cette clé.

Une application utilisant la fonction WritePrivateProfileString pour entrer .ini informations de fichier dans le Registre doit suivre ces instructions :

Vérifiez qu’aucun fichier .ini du nom spécifié n’existe sur le système.
Vérifiez qu’il existe une entrée de clé dans le Registre qui spécifie le fichier .ini. Cette entrée doit se trouver sous le chemin HKEY_LOCAL_MACHINE\SOFTWARE \Microsoft\Windows NT\CurrentVersion\IniFileMapping.
Spécifiez une valeur pour cette .ini entrée de clé de fichier qui spécifie une section. Autrement dit, une application doit spécifier un nom de section, tel qu’il apparaît dans un fichier .ini ou une entrée de Registre. Voici un exemple : [Ma section].
Pour les fichiers système, spécifiez SYS comme valeur ajoutée.
Pour les fichiers d’application, spécifiez USR dans la valeur ajoutée. Voici un exemple : « Ma section : USR : Nom de l’application\Section ». Et, étant donné qu’USR indique un mappage sous HKEY_CURRENT_USER, l’application doit également créer une clé sous HKEY_CURRENT_USER qui spécifie le nom de l’application répertorié dans la valeur ajoutée. Pour l’exemple qui vient d’être donné, il s’agit de « Nom de l’application ».
Après avoir suivi les étapes précédentes, un programme d’installation d’application doit appeler WritePrivateProfileString avec les trois premiers paramètres définis sur NULL et le quatrième paramètre défini sur le nom de fichier INI. Par exemple :
WritePrivateProfileString( NULL, NULL, NULL, L"appname.ini" );
Un tel appel entraîne l’effet du mappage d’un fichier .ini au Registre avant le prochain redémarrage du système. Le système relit les informations de mappage dans la mémoire partagée. Un utilisateur n’aura pas à redémarrer son ordinateur après l’installation d’une application pour que les appels futurs de l’application voient le mappage du fichier .ini au Registre.

Exemples

L’exemple de code suivant illustre les instructions précédentes et est basé sur plusieurs hypothèses :

Il existe une application nommée Nom de l’application.
Cette application utilise un fichier .ini nommé AppName.ini.

Il existe une section dans le fichier .ini que nous voulons ressembler à ceci :

[Section1] 
  FirstKey = It all worked out okay. 
  SecondKey = By golly, it works. 
  ThirdKey = Another test.

L’utilisateur n’aura pas à redémarrer le système pour que les appels futurs de l’application voient le mappage du fichier .ini au Registre.

#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); 
}

Notes

L’en-tête winbase.h définit WritePrivateProfileString comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll

Voir aussi

GetPrivateProfileString

WriteProfileString

Partager via