GetPrivateProfileSectionA, fonction (winbase.h)
Récupère toutes les clés et valeurs de la section spécifiée d’un fichier d’initialisation.
Syntaxe
DWORD GetPrivateProfileSectionA(
[in] LPCSTR lpAppName,
[out] LPSTR lpReturnedString,
[in] DWORD nSize,
[in] LPCSTR lpFileName
);
Paramètres
[in] lpAppName
Nom de la section dans le fichier d’initialisation.
[out] lpReturnedString
Pointeur vers une mémoire tampon qui reçoit les paires nom et valeur de clé associées à la section nommée. La mémoire tampon est remplie d’une ou plusieurs chaînes terminées par null ; la dernière chaîne est suivie d’un deuxième caractère null.
[in] nSize
Taille de la mémoire tampon pointée par le paramètre lpReturnedString, en caractères.
La taille maximale de la section de profil est de 32 767 caractères.
[in] lpFileName
Nom du fichier d’initialisation. Si ce paramètre ne contient pas de chemin d’accès complet au fichier, le système recherche le fichier dans le répertoire Windows.
Valeur de retour
La valeur de retour spécifie le nombre de caractères copiés dans la mémoire tampon, sans inclure le caractère null de fin. Si la mémoire tampon n’est pas suffisamment grande pour contenir toutes les paires nom de clé et valeur associées à la section nommée, la valeur de retour est égale à nSize moins deux.
Remarques
Les données de la mémoire tampon pointées par le paramètre lpReturnedString se composent d’une ou plusieurs chaînes terminées par null, suivies d’un caractère null final. Chaque chaîne a le format suivant :
chaîne de=clé
La fonction GetPrivateProfileSection n’est pas sensible à la casse ; la chaîne pointée par le paramètre lpAppName peut être une combinaison de lettres majuscules et minuscules.
Cette opération est atomique ; aucune mise à jour du fichier d’initialisation spécifié n’est autorisée alors que les paires nom et valeur de clé pour la section sont copiées dans la mémoire tampon pointée par le paramètre lpReturnedString.
Le système mappe la plupart des références de fichiers .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 probablement si une application modifie les fichiers d’initialisation des composants système, tels que Control.ini, System.iniet Winfile.ini. Dans ces cas, la fonction récupère les informations du Registre, et non à partir du 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 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é.
- 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.
- 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é.
- 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.
- 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.
- ! - 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 GetPrivateProfileSection 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. 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 |