RegEnumKeyA, fonction (winreg.h)

Article
11/20/2024

Énumère les sous-clés de la clé de Registre ouverte spécifiée. La fonction récupère le nom d’une sous-clé chaque fois qu’elle est appelée.

Remarque Cette fonction est fournie uniquement pour la compatibilité avec les versions 16 bits de Windows. Les applications doivent utiliser la fonction RegEnumKeyEx.

Syntaxe

LSTATUS RegEnumKeyA(
  [in]  HKEY  hKey,
  [in]  DWORD dwIndex,
  [out] LPSTR lpName,
  [in]  DWORD cchName
);

Paramètres

[in] hKey

Handle vers une clé de Registre ouverte. La clé doit avoir été ouverte avec le droit d’accès KEY_ENUMERATE_SUB_KEYS. 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_USERS

[in] dwIndex

Index de la sous-clé de clé hKey à récupérer. Cette valeur doit être égale à zéro pour le premier appel à la fonction RegEnumKey, puis incrémentée pour les appels suivants.

Étant donné que les sous-clés ne sont pas ordonnées, toute nouvelle sous-clé aura un index arbitraire. Cela signifie que la fonction peut retourner des sous-clés dans n’importe quel ordre.

[out] lpName

Pointeur vers une mémoire tampon qui reçoit le nom de la sous-clé, y compris le caractère null de fin. Cette fonction copie uniquement le nom de la sous-clé, et non la hiérarchie de clé complète, dans la mémoire tampon.

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

[in] cchName

Taille de la mémoire tampon pointée par le paramètre lpName, dans TCHAR. Pour déterminer la taille de mémoire tampon requise, utilisez la fonction RegQueryInfoKey pour déterminer la taille de la plus grande sous-clé pour la clé identifiée par le paramètre hKey .

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 sous-clés disponibles, la fonction retourne ERROR_NO_MORE_ITEMS.

Si la mémoire tampon lpName est trop petite pour recevoir le nom de la clé, la fonction retourne ERROR_MORE_DATA.

Remarques

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

L’application peut également définir dwIndex à l’index de la dernière clé lors du premier appel à la fonction et décrémenter l’index jusqu’à ce que la sous-clé avec l’index 0 soit énumérée. Pour récupérer l’index de la dernière sous-clé, utilisez la RegQueryInfoKey.

Bien qu’une application utilise la fonction RegEnumKey , elle ne doit pas effectuer d’appels à des fonctions d’inscription susceptibles de modifier la clé interrogée.

Note

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