ZwEnumerateKey function

The ZwEnumerateKey routine returns information about a subkey of an open registry key.

Syntax

NTSTATUS ZwEnumerateKey(
  _In_      HANDLE                KeyHandle,
  _In_      ULONG                 Index,
  _In_      KEY_INFORMATION_CLASS KeyInformationClass,
  _Out_opt_ 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 index of the subkey that you want information for. If the key has n subkeys, the subkeys are numbered from 0 to n-1.

KeyInformationClass

Specifies a KEY_INFORMATION_CLASS enumeration value that determines the type of information to be received by the KeyInformation buffer. Set KeyInformationClass to one of the following values:

  • KeyBasicInformation
  • KeyFullInformation
  • KeyNodeInformation
If any value not in this list is specified, the routine returns error code STATUS_INVALID_PARAMETER.

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:

Return code Description
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-1 the routine returns STATUS_NO_MORE_ENTRIES.

Remarks

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".
For calls from kernel-mode drivers, the NtXxx and ZwXxx versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

Requirements

   
Windows version Available starting with Windows 2000. Available starting with Windows 2000.
Target Platform Universal
Header wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI compliance rules IrqlZwPassive, PowerIrpDDis, ZwRegistryCreate, ZwRegistryOpen, HwStorPortProhibitedDDIs, ZwRegistryCreate(storport), ZwRegistryOpen(storport)

See Also

RtlCheckRegistryKey

KEY_FULL_INFORMATION

RtlWriteRegistryValue

ZwOpenKey

RtlCreateRegistryKey

KEY_NODE_INFORMATION

KEY_BASIC_INFORMATION

RtlDeleteRegistryValue

ZwCreateKey

KEY_INFORMATION_CLASS

ZwEnumerateValueKey

RtlQueryRegistryValues

Send comments about this topic to Microsoft