ZwEnumerateKey, fonction (wdm.h)

Article
02/29/2024

La routine ZwEnumerateKey retourne des informations sur une sous-clé d’une clé de Registre ouverte.

Syntaxe

NTSYSAPI NTSTATUS ZwEnumerateKey(
  [in]            HANDLE                KeyHandle,
  [in]            ULONG                 Index,
  [in]            KEY_INFORMATION_CLASS KeyInformationClass,
  [out, optional] PVOID                 KeyInformation,
  [in]            ULONG                 Length,
  [out]           PULONG                ResultLength
);

Paramètres

[in] KeyHandle

Gérez la clé de Registre qui contient les sous-clés à énumérer. Le handle est créé par un appel réussi à ZwCreateKey ou ZwOpenKey.

[in] Index

Index de la sous-clé pour laquelle vous souhaitez obtenir des informations. Si la clé a n sous-clés, les sous-clés sont numérotées de 0 à n-1.

[in] KeyInformationClass

Spécifie une valeur d’énumération KEY_INFORMATION_CLASS qui détermine le type d’informations à recevoir par la mémoire tampon KeyInformation . Définissez KeyInformationClass sur l’une des valeurs suivantes :

KeyBasicInformation
KeyFullInformation
KeyNodeInformation

Si une valeur qui ne figure pas dans cette liste est spécifiée, la routine retourne le code d’erreur STATUS_INVALID_PARAMETER.

[out, optional] KeyInformation

Pointeur vers une mémoire tampon allouée à l’appelant qui reçoit les informations demandées. Le paramètre KeyInformationClass détermine le type d’informations fournies.

[in] Length

Spécifie la taille, en octets, de la mémoire tampon KeyInformation .

[out] ResultLength

Pointeur vers une variable qui reçoit la taille, en octets, des informations de clé de Registre. Si ZwEnumerateKey retourne STATUS_SUCCESS, vous pouvez utiliser la valeur de cette variable pour déterminer la quantité de données retournées. Si la routine retourne STATUS_BUFFER_OVERFLOW ou STATUS_BUFFER_TOO_SMALL, vous pouvez utiliser la valeur de cette variable pour déterminer la taille de la mémoire tampon requise pour contenir les informations de clé.

Valeur retournée

ZwEnumerateKey retourne STATUS_SUCCESS en cas de réussite ou le code d’erreur NTSTATUS approprié en cas d’échec. Les valeurs de code d’erreur possibles sont les suivantes :

Code de retour	Description
STATUS_BUFFER_OVERFLOW	La mémoire tampon fournie est trop petite et seules des données partielles ont été écrites dans la mémoire tampon. *ResultLength est défini sur la taille minimale requise pour contenir les informations demandées.
STATUS_BUFFER_TOO_SMALL	La mémoire tampon fournie est trop petite et aucune donnée n’a été écrite dans la mémoire tampon. *ResultLength est défini sur la taille minimale requise pour contenir les informations demandées.
STATUS_INVALID_PARAMETER	Le paramètre KeyInformationClass n’est pas une valeur KEY_INFORMATION_CLASS valide.
STATUS_NO_MORE_ENTRIES	La valeur Index est hors plage pour la clé de Registre spécifiée par KeyHandle. Par exemple, si une clé a n sous-clés, la routine retourne STATUS_NO_MORE_ENTRIES pour toute valeur supérieure à n-1.

Remarques

Le handle doit avoir été ouvert avec un accès KEY_ENUMERATE_SUB_KEYS. Pour ce faire, transmettez KEY_ENUMERATE_SUB_KEYS, KEY_READ ou KEY_ALL_ACCESS en tant que paramètre DesiredAccess à ZwCreateKey ou ZwOpenKey.

Le paramètre Index est simplement un moyen de sélectionner parmi les sous-clés de la clé référencée par keyHandle. Il n’est pas garanti que deux appels à ZwEnumerateKey avec le même index retournent le même résultat.

Pour plus d’informations sur l’utilisation des clés de Registre, consultez Utilisation du Registre dans un pilote.

Si l’appel à cette fonction se produit en mode utilisateur, vous devez utiliser le nom « NtEnumerateKey » au lieu de « ZwEnumerateKey ».

Pour les appels provenant de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment dans la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Using Nt and Zw Versions of the Native System Services Routines.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(storport), ZwRegistryOpen(storport), ZwRegistryOpen(wdm)