RegEnumValueW, fonction (winreg.h)
Énumère les valeurs de la clé de Registre ouverte spécifiée. La fonction copie un nom de valeur indexé et un bloc de données pour la clé chaque fois qu’elle est appelée.
Syntaxe
LSTATUS RegEnumValueW(
[in] HKEY hKey,
[in] DWORD dwIndex,
[out] LPWSTR lpValueName,
[in, out] LPDWORD lpcchValueName,
LPDWORD lpReserved,
[out, optional] LPDWORD lpType,
[out, optional] LPBYTE lpData,
[in, out, optional] LPDWORD lpcbData
);
Paramètres
[in] hKey
Handle vers une clé de Registre ouverte. La clé doit avoir été ouverte avec le droit d’accès KEY_QUERY_VALUE. Pour plus d’informations, consultez sécurité des clés de Registre et droits d’accès.
Ce handle est retourné par le RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyExou fonction RegOpenKeyTransacted. Il peut également s’agir de l’une des clés prédéfinies:
- HKEY_CLASSES_ROOT
- HKEY_CURRENT_CONFIG
- HKEY_CURRENT_USER
- HKEY_LOCAL_MACHINE
- HKEY_PERFORMANCE_DATA
- HKEY_USERS
[in] dwIndex
Index de la valeur à récupérer. Ce paramètre doit être égal à zéro pour le premier appel à la fonction RegEnumValue, puis incrémenté pour les appels suivants.
Étant donné que les valeurs ne sont pas ordonnées, toute nouvelle valeur aura un index arbitraire. Cela signifie que la fonction peut retourner des valeurs dans n’importe quel ordre.
[out] lpValueName
Pointeur vers une mémoire tampon qui reçoit le nom de la valeur sous la forme d’une chaîne null-terminated string.
Cette mémoire tampon doit être suffisamment grande pour inclure la fin caractère null.
Pour plus d’informations, consultez Limites de taille des éléments de Registre.
[in, out] lpcchValueName
Pointeur vers une variable qui spécifie la taille de la mémoire tampon pointée par le paramètre lpValueName, en caractères. Lorsque la fonction est retournée, la variable reçoit le nombre de caractères stockés dans la mémoire tampon, sans inclure la fin caractère null.
Les noms de valeurs de Registre sont limités à 32 767 octets. La version ANSI de cette fonction traite ce paramètre comme une valeur SHORT. Par conséquent, si vous spécifiez une valeur supérieure à 32 767 octets, il existe un dépassement de capacité et la fonction peut retourner ERROR_MORE_DATA.
lpReserved
Ce paramètre est réservé et doit être NULL.
[out, optional] lpType
Pointeur vers une variable qui reçoit un code indiquant le type de données stockées dans la valeur spécifiée. Pour obtenir la liste des codes de type possibles, consultez Types de valeurs de Registre. Le paramètre
[out, optional] lpData
Pointeur vers une mémoire tampon qui reçoit les données de l’entrée de valeur. Ce paramètre peut être NULL si les données ne sont pas requises.
Si lpData est NULL et lpcbData n’est pasNULL, la fonction stocke la taille des données, en octets, dans la variable pointée par lpcbData. Cela permet à une application de déterminer la meilleure façon d’allouer une mémoire tampon pour les données.
[in, out, optional] lpcbData
Pointeur vers une variable qui spécifie la taille de la mémoire tampon pointée par le paramètre lpData, en octets. Lorsque la fonction est retournée, la variable reçoit le nombre d’octets stockés dans la mémoire tampon.
Ce paramètre peut être NULL uniquement si lpData est NULL.
Si les données ont le REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ type, cette taille inclut toute fin caractère ou caractères null. Pour plus d’informations, consultez Remarques.
Si la mémoire tampon spécifiée par lpData n’est pas suffisamment grande pour contenir les données, la fonction retourne ERROR_MORE_DATA et stocke la taille de mémoire tampon requise dans la variable pointée par lpcbData. Dans ce cas, le contenu de lpData n’est pas défini.
Valeur de retour
Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.
Si la fonction échoue, la valeur de retour est un code d’erreur système . S’il n’y a plus de valeurs disponibles, la fonction retourne ERROR_NO_MORE_ITEMS.
Si la mémoire tampon
Remarques
Pour énumérer des valeurs, une application doit initialement appeler la fonction RegEnumValue
L’application peut également définir dwIndex sur l’index de la dernière valeur lors du premier appel à la fonction et décrémenter l’index jusqu’à ce que la valeur avec l’index 0 soit énumérée. Pour récupérer l’index de la dernière valeur, utilisez la fonction RegQueryInfoKey.
Lors de l’utilisation de RegEnumValue, une application ne doit pas appeler de fonctions de Registre susceptibles de modifier la clé interrogée.
Si les données ont la REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ type, la chaîne n’a peut-être pas été stockée avec les caractères null null appropriés. Par conséquent, même si la fonction retourne ERROR_SUCCESS, l’application doit s’assurer que la chaîne est correctement arrêtée avant de l’utiliser ; sinon, il peut remplacer une mémoire tampon. (Notez que les chaînes REG_MULTI_SZ doivent avoir deux caractères null-terminant.)
Pour déterminer la taille maximale des mémoires tampons de noms et de données, utilisez la fonction RegQueryInfoKey.
Exemples
Pour obtenir un exemple, consultez énumération des sous-clés de Registre.
Note
L’en-tête winreg.h définit RegEnumValue 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 | winreg.h (inclure Windows.h) |
| bibliothèque | Advapi32.lib |
| DLL | Advapi32.dll |