Fonction RegEnumValueA (winreg.h)

Article
08/27/2023

É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 d’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é de la clé de Registre et droits d’accès.

Ce handle est retourné par la fonction RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyEx ou RegOpenKeyTransacted . Il peut également s’agir de l’une des clés prédéfinies suivantes :

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 être incrémenté pour les appels suivants.

Étant donné que les valeurs ne sont pas trié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 terminée par null.

Cette mémoire tampon doit être suffisamment grande pour inclure le caractère null de fin.

Pour plus d’informations, consultez Limites de taille des éléments du Registre.

[in, out] lpcchValueName

Pointeur vers une variable qui spécifie la taille de la mémoire tampon pointée vers le paramètre lpValueName , en caractères. Lorsque la fonction retourne, la variable reçoit le nombre de caractères stockés dans la mémoire tampon, sans inclure le caractère null de fin.

Si la mémoire tampon spécifiée par lpValueName n’est pas assez grande pour contenir les données, la fonction retourne ERROR_MORE_DATA et la taille de 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 y a un dépassement de capacité et la fonction peut retourner ERROR_MORE_DATA.

lpReserved

Ce paramètre est réservé et doit avoir la valeur 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 avoir la valeur NULL si le code de type n’est pas requis.

[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 avoir la valeur NULL si les données ne sont pas requises.

Si lpData a la valeur NULL et lpcbData n’est pas NULL, 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 vers le paramètre lpData , en octets. Lorsque la fonction retourne, la variable reçoit le nombre d’octets stockés dans la mémoire tampon.

Ce paramètre peut avoir la valeur NULL uniquement si lpData a la valeur NULL.

Si les données ont le type REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ, cette taille inclut le ou les caractères null de fin. Pour plus d'informations, consultez la section Notes.

Si la mémoire tampon spécifiée par lpData n’est pas assez 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 retournée

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 des fonctions de Registre susceptibles de modifier la clé interrogée.

Si les données ont le type REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ, la chaîne n’a peut-être pas été stockée avec les caractères de fin 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 REG_MULTI_SZ chaînes doivent avoir deux caractères de fin null.)

Pour déterminer la taille maximale des mémoires tampons de nom et de données, utilisez la fonction RegQueryInfoKey .

Notes

Sur les versions héritées de Windows, cette API est également exposée par kernel32.dll.

Exemples

Pour obtenir un exemple, consultez Énumération des sous-clés de Registre.

Notes

L’en-tête winreg.h définit RegEnumValue comme un 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.

Configuration requise


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	winreg.h (inclure Windows.h)
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll