Función ZwEnumerateKey (wdm.h)

Artículo
02/27/2024

La rutina ZwEnumerateKey devuelve información sobre una subclave de una clave del Registro abierta.

Sintaxis

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

Parámetros

[in] KeyHandle

Identificador de la clave del Registro que contiene las subclaves que se van a enumerar. El identificador se crea mediante una llamada correcta a ZwCreateKey o ZwOpenKey.

[in] Index

Índice de la subclave para la que desea obtener información. Si la clave tiene n subclaves, las subclaves se numeran de 0 a n-1.

[in] KeyInformationClass

Especifica un valor de enumeración KEY_INFORMATION_CLASS que determina el tipo de información que va a recibir el búfer KeyInformation . Establezca KeyInformationClass en uno de los valores siguientes:

KeyBasicInformation
KeyFullInformation
KeyNodeInformation

Si se especifica algún valor que no esté en esta lista, la rutina devuelve el código de error STATUS_INVALID_PARAMETER.

[out, optional] KeyInformation

Puntero a un búfer asignado por el autor de la llamada que recibe la información solicitada. El parámetro KeyInformationClass determina el tipo de información proporcionada.

[in] Length

Especifica el tamaño, en bytes, del búfer KeyInformation .

[out] ResultLength

Puntero a una variable que recibe el tamaño, en bytes, de la información de clave del Registro. Si ZwEnumerateKey devuelve STATUS_SUCCESS, puede usar el valor de esta variable para determinar la cantidad de datos devueltos. Si la rutina devuelve STATUS_BUFFER_OVERFLOW o STATUS_BUFFER_TOO_SMALL, puede usar el valor de esta variable para determinar el tamaño del búfer necesario para contener la información de clave.

Valor devuelto

ZwEnumerateKey devuelve STATUS_SUCCESS si se ejecuta correctamente o el código de error NTSTATUS adecuado en caso de error. Entre los posibles valores de código de error se incluyen:

Código devuelto	Descripción
STATUS_BUFFER_OVERFLOW	El búfer proporcionado es demasiado pequeño y solo se han escrito datos parciales en el búfer. *ResultLength se establece en el tamaño mínimo necesario para contener la información solicitada.
STATUS_BUFFER_TOO_SMALL	El búfer proporcionado es demasiado pequeño y no se ha escrito ningún dato en el búfer. *ResultLength se establece en el tamaño mínimo necesario para contener la información solicitada.
STATUS_INVALID_PARAMETER	El parámetro KeyInformationClass no es un valor de KEY_INFORMATION_CLASS válido.
STATUS_NO_MORE_ENTRIES	El valor de Índice está fuera del intervalo de la clave del Registro especificada por KeyHandle. Por ejemplo, si una clave tiene n subclaves, para cualquier valor mayor que n-1, la rutina devuelve STATUS_NO_MORE_ENTRIES.

Comentarios

El identificador debe haberse abierto con KEY_ENUMERATE_SUB_KEYS acceso. Esto se logra pasando KEY_ENUMERATE_SUB_KEYS, KEY_READ o KEY_ALL_ACCESS como parámetro DesiredAccess a ZwCreateKey o ZwOpenKey.

El parámetro Index es simplemente una manera de seleccionar entre subclaves de la clave a la que hace referencia KeyHandle. No se garantiza que dos llamadas a ZwEnumerateKey con el mismo índice devuelvan el mismo resultado.

Para obtener más información sobre cómo trabajar con claves del Registro, consulte Uso del Registro en un controlador.

Si la llamada a esta función se produce en modo de usuario, debe usar el nombre "NtEnumerateKey" en lugar de "ZwEnumerateKey".

En el caso de las llamadas desde controladores en modo kernel, las versiones NtXxx y ZwXxx de una rutina de Windows Native System Services pueden comportarse de forma diferente en la forma en que controlan e interpretan los parámetros de entrada. Para obtener más información sobre la relación entre las versiones NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(storport), ZwRegistryOpen(storport), ZwRegistryOpen(wdm)