GetPrivateProfileSection, fonction (winbase.h)

Article
08/27/2023

Récupère toutes les clés et valeurs pour la section spécifiée d’un fichier d’initialisation.

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

Syntaxe

DWORD GetPrivateProfileSection(
  [in]  LPCTSTR lpAppName,
  [out] LPTSTR  lpReturnedString,
  [in]  DWORD   nSize,
  [in]  LPCTSTR 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 de clé et valeur 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 vers 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 retournée

La valeur de retour spécifie le nombre de caractères copiés dans la mémoire tampon, à l’exception du caractère null de fin. Si la mémoire tampon n’est pas assez 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 dans la mémoire tampon pointées vers 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 :

Clé=String

La fonction GetPrivateProfileSection ne respecte pas la casse ; la chaîne pointée vers 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 pendant que les paires nom de clé et valeur de la section sont copiées dans la mémoire tampon vers laquelle pointe le paramètre lpReturnedString .

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 récupère des informations à partir du Registre, et non du 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é.

Les commentaires (toute ligne commençant par un point-virgule) sont supprimés et ne sont pas retournés dans la mémoire tampon lpReturnedString .

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

GetPrivateProfileSectionNames

GetProfileSection

WritePrivateProfileSection

Share via