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 .