Fonction WritePrivateProfileStructW (winbase.h)
Copie les données dans une clé dans la section spécifiée d’un fichier d’initialisation. Quand elle copie les données, la fonction calcule une somme de contrôle et l’ajoute à la fin des données. La fonction GetPrivateProfileStruct utilise la somme de contrôle pour garantir l’intégrité des données.
Syntaxe
BOOL WritePrivateProfileStructW(
[in] LPCWSTR lpszSection,
[in] LPCWSTR lpszKey,
[in] LPVOID lpStruct,
[in] UINT uSizeStruct,
[in] LPCWSTR szFile
);
Paramètres
[in] lpszSection
Nom de la section dans laquelle les données struct seront copiées. Si la section n’existe pas, elle est créée. Le nom de la section est indépendant de la casse.
[in] lpszKey
Nom de la clé à associer à un struct. 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 clés et entrées de la section, est supprimée.
[in] lpStruct
Données à copier. Si ce paramètre a la valeur NULL, la clé est supprimée.
[in] uSizeStruct
Taille de la mémoire tampon pointée vers le paramètre lpStruct , en octets.
[in] szFile
Nom du fichier d’initialisation. Si ce paramètre a la valeur NULL, les informations sont copiées dans le fichier Win.ini.
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 le struct 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=struct
.
.
.
Si le paramètre szFile 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 szFile contient un chemin d’accès complet et un nom de fichier et que le fichier n’existe pas, WriteProfileString 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.
- ! - 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é.
Notes
L’en-tête winbase.h définit WritePrivateProfileStruct 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 |