GetProfileStringW, fonction (winbase.h)
Récupère la chaîne associée à une clé dans la section spécifiée du fichier Win.ini.
Syntaxe
DWORD GetProfileStringW(
[in] LPCWSTR lpAppName,
[in] LPCWSTR lpKeyName,
[in] LPCWSTR lpDefault,
[out] LPWSTR lpReturnedString,
[in] DWORD nSize
);
Paramètres
[in] lpAppName
Nom de la section contenant la clé. Si ce paramètre est null, la fonction copie tous les noms de section du 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 est NULL, la fonction copie toutes les clés de la section donnée dans la mémoire tampon fournie. Chaque chaîne est suivie d’un caractère null
[in] lpDefault
Chaîne par défaut. Si la clé lpKeyName est introuvable dans le fichier d’initialisation, GetProfileStr ing copie la chaîne par défaut dans la mémoire tampon lpReturnedString. Si ce paramètre est 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
[out] lpReturnedString
Pointeur vers une mémoire tampon qui reçoit la chaîne de caractères.
[in] nSize
Taille de la mémoire tampon pointée par le paramètre lpReturnedString, en caractères.
Valeur de retour
La valeur de retour est le nombre de caractères copiés dans la mémoire tampon, sans inclure le caractère null-terminant.
Si aucun lpAppName ni lpKeyName n’est 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 est 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.
Remarques
Si la chaîne associée au paramètre lpKeyName est placée entre guillemets simples ou doubles, les marques sont ignorées lorsque la fonction GetProfileString retourne la chaîne.
La fonction GetProfileString
Une section du fichier Win.ini doit avoir le formulaire suivant :
[section]
key=string
.
.
.
Une application peut utiliser la fonction GetPrivateProfileString pour récupérer une chaîne à partir d’un fichier d’initialisation spécifié.
Le paramètre lpDefault doit pointer vers une chaîne valide, même si la chaîne est vide (autrement dit, même si son premier caractère est un caractère null).
Windows Server 2003 et Windows XP/2000 : appels aux fonctions de profil peuvent être mappés au registre au lieu des fichiers d’initialisation. Ce mappage se produit lorsque le fichier d’initialisation et la section sont spécifiés dans le Registre sous les clés suivantes :
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\IniFileMapping
Lorsque l’opération a été mappée, la fonction GetProfileString récupère des informations à partir 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 GetProfileString en tant qu’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 |