ZwEnumerateKey

ZwEnumerateKey

The ZwEnumerateKey routine returns information about the subkeys of an open registry key.

NTSTATUS
ZwEnumerateKey(
IN HANDLE KeyHandle ,
IN ULONG Index ,
IN KEY_INFORMATION_CLASS KeyInformationClass ,
OUT PVOID KeyInformation ,
IN ULONG Length ,
OUT PULONG ResultLength
);

Parameters

KeyHandle

Handle to the registry key that contains the subkeys to be enumerated. The handle is created by a successful call to ZwCreateKey or ZwOpenKey .

Index

The zero-based index of the subkey that you want information for.

KeyInformationClass

Specifies a KEY_INFORMATION_CLASS value that determines the type of information to be received by the KeyInformation buffer.

KeyInformation

Pointer to a caller-allocated buffer that receives the requested information. The KeyInformationClass parameter determines the type of information provided.

Length

Specifies the size, in bytes, of the KeyInformation buffer.

ResultLength

Pointer to a variable that receives the size, in bytes, of the registry-key information. If ZwEnumerateKey returns STATUS_SUCCESS, you can use the value of this variable to determine the amount of data returned. If the routine returns STATUS_BUFFER_OVERFLOW or STATUS_BUFFER_TOO_SMALL, you can use the value of this variable to determine the size of buffer required to hold the key information.

Return Value

ZwEnumerateKey returns STATUS_SUCCESS on success, or the appropriate NTSTATUS error code on failure. Possible error code values include:

STATUS_BUFFER_OVERFLOW

The buffer supplied is too small, and only partial data has been written to the buffer. * ResultLength is set to the minimum size required to hold the requested information.

STATUS_BUFFER_TOO_SMALL

The buffer supplied is too small, and no data has been written to the buffer. * ResultLength is set to the minimum size required to hold the requested information.

STATUS_INVALID_PARAMETER

The KeyInformationClass parameter is not a valid KEY_INFORMATION_CLASS value.

STATUS_NO_MORE_ENTRIES

The Index value is out of range for the registry key specified by KeyHandle . For example, if a key has n subkeys, then for any value greater than n -1the routine returns STATUS_NO_MORE_ENTRIES.

Comments

The handle must have been opened with KEY_ENUMERATE_SUB_KEYS access. This is accomplished by passing KEY_ENUMERATE_SUB_KEYS, KEY_READ, or KEY_ALL_ACCESS as the DesiredAccess parameter to ZwCreateKey or ZwOpenKey .

The Index parameter is simply a way to select among subkeys of the key referred to by the KeyHandle . Two calls to ZwEnumerateKey with the same Index are not guaranteed to return the same result.

For more information about working with registry keys, see Using the Registry in a Driver.

Note  If the call to this function occurs in user mode, you should use the name "NtEnumerateKey " instead of "ZwEnumerateKey ".

Requirements

IRQL : PASSIVE_LEVEL

Headers: Declared in wdm.h . Include wdm.h , ntddk.h , or ntifs.h .