Fonction RegEnumKeyExA (winreg.h)

Article
03/11/2023

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

Syntaxe

LSTATUS RegEnumKeyExA(
  [in]                HKEY      hKey,
  [in]                DWORD     dwIndex,
  [out]               LPSTR     lpName,
  [in, out]           LPDWORD   lpcchName,
                      LPDWORD   lpReserved,
  [in, out]           LPSTR     lpClass,
  [in, out, optional] LPDWORD   lpcchClass,
  [out, optional]     PFILETIME lpftLastWriteTime
);

Paramètres

[in] hKey

Handle d’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é 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 sous-clé à récupérer. Ce paramètre doit être égal à zéro pour le premier appel à la fonction RegEnumKeyEx , puis incrémenté pour les appels suivants.

Étant donné que les sous-clés ne sont pas trié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. La fonction copie uniquement le nom de la sous-clé, et non la hiérarchie de clés complète, dans la mémoire tampon.

Si la fonction échoue, aucune information n’est copiée dans cette mémoire tampon.

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

[in, out] lpcchName

Pointeur vers une variable qui spécifie la taille de la mémoire tampon spécifiée par le paramètre lpName , en caractères. Cette taille doit inclure le caractère null de fin. Si la fonction réussit, la variable pointée vers lpcchName contient le nombre de caractères stockés dans la mémoire tampon, sans inclure le caractère null de fin.

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

lpReserved

Ce paramètre est réservé et doit avoir la valeur NULL.

[in, out] lpClass

Pointeur vers une mémoire tampon qui reçoit la classe définie par l’utilisateur de la sous-clé énumérée. Ce paramètre peut être NULL.

[in, out, optional] lpcchClass

Pointeur vers une variable qui spécifie la taille de la mémoire tampon spécifiée par le paramètre lpClass , en caractères. La taille doit inclure le caractère null de fin. Si la fonction réussit, lpcchClass contient le nombre de caractères stockés dans la mémoire tampon, sans inclure le caractère null de fin. Ce paramètre ne peut être NULL que si lpClass a la valeur NULL.

[out, optional] lpftLastWriteTime

Pointeur vers la structure FILETIME qui reçoit l’heure à laquelle la sous-clé énumérée a été écrite pour la dernière fois. Ce paramètre peut être NULL.

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 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 RegEnumKeyEx avec le paramètre dwIndex défini sur zéro. L’application doit ensuite incrémenter le paramètre dwIndex et appeler RegEnumKeyEx 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 sur l’index de la dernière sous-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 fonction RegQueryInfoKey .

Lorsqu’une application utilise la fonction RegEnumKeyEx , elle ne doit pas appeler les fonctions d’inscription susceptibles de modifier la clé énumérée.

Notez que les opérations qui accèdent à certaines clés de Registre sont redirigées. Pour plus d’informations, consultez Virtualisation du Registre et Données d’application 32 bits et 64 bits dans le Registre.

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 RegEnumKeyEx 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