RegEnumValueA, 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 RegEnumValueA(
  [in]                HKEY    hKey,
  [in]                DWORD   dwIndex,
  [out]               LPSTR   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.

Si la mémoire tampon spécifiée par lpValueName n’est pas suffisamment grande pour contenir les données, la fonction retourne ERROR_MORE_DATA et la taille de la mémoire tampon dans la variable pointée par lpValueName n’est pas modifiée. Dans ce cas, le contenu de lpcchValueName n’est pas défini.

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 lpType peut être null si le code de type n’est pas obligatoire.

[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 spécifiée par lpValueName ou lpData est trop petite pour recevoir la valeur, la fonction retourne ERROR_MORE_DATA.

Remarques

Pour énumérer des valeurs, une application doit initialement appeler la fonction RegEnumValue avec le paramètre dwIndex défini sur zéro. L’application doit ensuite incrémenter dwIndex et appeler la fonction RegEnumValue jusqu’à ce qu’il n’y ait plus de valeurs (jusqu’à ce que la fonction retourne ERROR_NO_MORE_ITEMS).

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.

Exigences

Voir aussi

RegCreateKeyEx

RegEnumKeyEx

RegOpenKeyEx

regQueryInfoKey

fonctions de Registre

Vue d’ensemble du Registre