GetPrivateProfileString, fonction (winbase.h)
Récupère une chaîne de la section spécifiée dans un fichier d’initialisation.
Syntaxe
DWORD GetPrivateProfileString(
[in] LPCTSTR lpAppName,
[in] LPCTSTR lpKeyName,
[in] LPCTSTR lpDefault,
[out] LPTSTR lpReturnedString,
[in] DWORD nSize,
[in] LPCTSTR lpFileName
);
Paramètres
[in] lpAppName
Nom de la section contenant le nom de la clé. Si ce paramètre a la valeur NULL, la fonction GetPrivateProfileString copie tous les noms de section dans le fichier dans la mémoire tampon fournie.
[in] lpKeyName
Nom de la clé dont la chaîne associée doit être récupérée. Si ce paramètre a la valeur NULL, tous les noms de clé dans la section spécifiée par le paramètre lpAppName sont copiés dans la mémoire tampon spécifiée par le paramètre lpReturnedString .
[in] lpDefault
Chaîne par défaut. Si la clé lpKeyName est introuvable dans le fichier d’initialisation, GetPrivateProfileString copie la chaîne par défaut dans la mémoire tampon lpReturnedString .
Si ce paramètre a la valeur NULL, la valeur par défaut est une chaîne vide, « ».
Évitez de spécifier une chaîne par défaut avec des caractères vides de fin. La fonction insère un caractère Null dans la mémoire tampon lpReturnedString pour supprimer les espaces de fin.
[out] lpReturnedString
Pointeur vers la mémoire tampon qui reçoit la chaîne récupérée.
[in] nSize
Taille de la mémoire tampon vers laquelle pointe le paramètre lpReturnedString , en 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 est le nombre de caractères copiés dans la mémoire tampon, sans compter le caractère null de fin.
Si ni lpAppName ni lpKeyName n’ont la valeur NULL et que la mémoire tampon de destination fournie est trop petite pour contenir la chaîne demandée, la chaîne est tronquée et suivie d’un caractère Null , et la valeur de retour est égale à nSize moins un.
Si lpAppName ou lpKeyName a la valeur NULL et que la mémoire tampon de destination fournie est trop petite pour contenir toutes les chaînes, la dernière chaîne est tronquée et suivie de deux caractères Null . Dans ce cas, la valeur de retour est égale à nSize moins deux.
Si le fichier d’initialisation spécifié par lpFileName est introuvable ou contient des valeurs non valides, l’appel de GetLastError renvoie « 0x2 » (Fichier introuvable). Pour récupérer des informations d’erreur étendues, appelez GetLastError.
Remarques
La fonction GetPrivateProfileString recherche dans le fichier d’initialisation spécifié une clé qui correspond au nom spécifié par le paramètre lpKeyName sous l’en-tête de section spécifié par le paramètre lpAppName . Si elle trouve la clé, la fonction copie la chaîne correspondante dans la mémoire tampon. Si la clé n’existe pas, la fonction copie la chaîne de caractères par défaut spécifiée par le paramètre lpDefault . Une section du fichier d’initialisation doit avoir la forme suivante :
[section]
key=string
.
.
.
Si lpAppName a la valeur NULL, GetPrivateProfileString copie tous les noms de section dans le fichier spécifié dans la mémoire tampon fournie. Si lpKeyName a la valeur NULL, la fonction copie tous les noms de clé de la section spécifiée dans la mémoire tampon fournie. Une application peut utiliser cette méthode pour énumérer toutes les sections et clés d’un fichier. Dans les deux cas, chaque chaîne est suivie d’un caractère null et la chaîne finale est suivie d’un deuxième caractère null . Si la mémoire tampon de destination fournie est trop petite pour contenir toutes les chaînes, la dernière chaîne est tronquée et suivie de deux caractères Null .
Si la chaîne associée à lpKeyName est placée entre guillemets simples ou doubles, les marques sont ignorées lorsque la fonction GetPrivateProfileString récupère la chaîne.
La fonction GetPrivateProfileString ne respecte pas la casse ; les chaînes peuvent être une combinaison de lettres majuscules et minuscules.
Pour récupérer une chaîne du fichier Win.ini, utilisez la fonction GetProfileString .
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 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 ; 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é.
Exemple
L’exemple suivant illustre l’utilisation de GetPrivateProfileString.
// Gets a profile string called "Preferred line" and converts it to an int.
GetPrivateProfileString (
"Preference",
"Preferred Line",
gszNULL,
szBuffer,
MAXBUFSIZE,
gszINIfilename
);
// if szBuffer is not empty.
if ( lstrcmp ( gszNULL, szBuffer ) )
{
dwPreferredPLID = (DWORD) atoi( szBuffer );
}
else
{
dwPreferredPLID = (DWORD) -1;
}
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 |