WriteProfileStringW, fonction (winbase.h)

  • Article

Copie une chaîne dans la section spécifiée du fichier Win.ini. Si Win.ini utilise des caractères Unicode, la fonction écrit des caractères Unicode dans le fichier. Sinon, la fonction écrit des caractères ANSI.

Remarque 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 WriteProfileStringW(
  [in] LPCWSTR lpAppName,
  [in] LPCWSTR lpKeyName,
  [in] LPCWSTR lpString
);

Paramètres

[in] lpAppName

Section vers laquelle la chaîne doit être copiée. Si la section n’existe pas, elle est créée. Le nom de la section n’est pas sensible à la casse ; la chaîne peut être n’importe quelle combinaison de lettres majuscules et minuscules.

[in] lpKeyName

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

[in] lpString

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

Valeur de retour

Si la fonction copie correctement la chaîne dans le fichier Win.ini, la valeur de retour n’est pas nulle.

Si la fonction échoue ou si elle vide la version mise en cache de Win.ini, la valeur de retour est égale à zéro. Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Remarques

Une section du fichier Win.ini doit avoir la forme suivante : clé=chaîne.

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 sont 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 ait été effacé.

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

HKEY_LOCAL_MACHINE
   SOFTWARE
      Microsoft
         Windows NT
            CurrentVersion
               IniFileMapping

Lorsque l’opération a été mappée, la fonction WriteProfileString écrit des informations dans le Registre, et non dans le fichier d’initialisation ; la modification 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 :

  1. Recherchez dans le Registre le nom du fichier d’initialisation sous la clé IniFileMapping.
  2. Recherchez le nom de section spécifié par lpAppName. Il s’agit d’une valeur nommée sous la clé qui a le nom du fichier d’initialisation, ou d’une sous-clé portant ce nom, ou le nom n’existe pas comme valeur ou sous-clé.
  3. Si le nom de section spécifié par lpAppName est une valeur nommée, cette valeur spécifie l’emplacement dans le Registre où vous trouverez les clés de la section.
  4. 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 non nommée (indiquée comme <Aucun nom>) qui spécifie l’emplacement par défaut dans le Registre où vous trouverez la clé.
  5. Si le nom de section spécifié par lpAppName n’existe pas en tant que valeur nommée ou en tant que sous-clé, il y aura une valeur non nommée (indiquée comme <Aucun nom>) qui spécifie l’emplacement par défaut dans le Registre où vous trouverez les clés de la section.
  6. S’il n’y a pas de sous-clé ou d’entrée pour le nom de section, recherchez le fichier d’initialisation réel sur le disque et lisez son contenu.
Lorsque vous examinez des 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 de Registre 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’accéder au fichier .ini sur le disque si les données demandées ne sont pas trouvées dans le Registre.
  • USR : - ce préfixe signifie HKEY_CURRENT_USER, et le texte après le préfixe est relatif à cette clé.
  • SYS : - ce préfixe signifie HKEY_LOCAL_MACHINE\SOFTWARE, et le texte après le préfixe est relatif à cette clé.

Note

L’en-tête winbase.h définit WriteProfileString en tant qu’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.

Exigences

Exigence Valeur
client minimum pris en charge Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge Windows 2000 Server [applications de bureau uniquement]
plateforme cible Windows
d’en-tête winbase.h (inclure Windows.h)
bibliothèque Kernel32.lib
DLL Kernel32.dll

Voir aussi

GetProfileString

WritePrivateProfileString