WritePrivateProfileSectionA, fonction (winbase.h)
Remplace les clés et les valeurs de la section spécifiée dans un fichier d’initialisation.
Syntaxe
BOOL WritePrivateProfileSectionA(
[in] LPCSTR lpAppName,
[in] LPCSTR lpString,
[in] LPCSTR lpFileName
);
Paramètres
[in] lpAppName
Nom de la section dans laquelle les données sont écrites. Ce nom de section est généralement le nom de l’application appelante.
[in] lpString
Les nouveaux noms de clés et les valeurs associées qui doivent être écrits dans la section nommée. Cette chaîne est limitée à 65 535 octets.
[in] lpFileName
Nom du fichier d’initialisation. Si ce paramètre ne contient pas de chemin d’accès complet pour le fichier, la fonction recherche le fichier dans le répertoire Windows. Si le fichier n’existe pas et que lpFileName ne contient pas de chemin d’accès complet, la fonction crée le fichier dans le répertoire Windows.
Si le fichier existe et a été créé à l’aide de caractères Unicode, la fonction écrit des caractères Unicode dans le fichier. Sinon, la fonction crée un fichier à l’aide de caractères ANSI.
Valeur retournée
Si la fonction réussit, la valeur de retour est différente de zéro.
Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.
Remarques
Les données dans la mémoire tampon pointées par le paramètre lpString se composent d’une ou plusieurs chaînes terminées par null, suivies d’un caractère Null final. Chaque chaîne a la forme suivante :
Clé=String
La fonction WritePrivateProfileSection ne respecte pas la casse ; La chaîne pointée par le paramètre lpAppName peut être une combinaison de lettres majuscules et minuscules.
Si aucun nom de section ne correspond à la chaîne pointée par le paramètre lpAppName , WritePrivateProfileSection crée la section à la fin du fichier d’initialisation spécifié et initialise la nouvelle section avec les paires nom de clé et valeur spécifiées.
WritePrivateProfileSection supprime les clés et valeurs existantes pour la section nommée et insère les noms de clés et les valeurs dans la mémoire tampon vers laquelle pointe le paramètre lpString . La fonction ne tente pas de mettre en corrélation les anciens et les nouveaux noms de clés ; si les nouveaux noms apparaissent dans un ordre différent des anciens noms, tous les commentaires associés aux clés et valeurs préexistantes dans le fichier d’initialisation seront probablement associés à des clés et des valeurs incorrectes.
Cette opération est atomique ; aucune opération qui lit ou écrit dans le fichier d’initialisation spécifié n’est autorisée pendant l’écriture des informations.
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 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
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 ; 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 :
- 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é qui porte 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 existe 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 existe 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.
- ! - 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’aller au fichier .ini sur le disque si les données demandées sont introuvables dans le Registre.
- USR : - ce préfixe signifie HKEY_CURRENT_USER, et le texte qui suit le préfixe est relatif à cette clé.
- SYS : - ce préfixe signifie HKEY_LOCAL_MACHINE\SOFTWARE, et le texte qui suit le préfixe est relatif à cette clé.
Notes
L’en-tête winbase.h définit WritePrivateProfileSection comme 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. La combinaison 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 |