Export (0) Print
Expand All

ZwQueryKey routine

The ZwQueryKey routine provides information about the class of a registry key, and the number and sizes of its subkeys.

Syntax


NTSTATUS ZwQueryKey(
  _In_       HANDLE KeyHandle,
  _In_       KEY_INFORMATION_CLASS KeyInformationClass,
  _Out_opt_  PVOID KeyInformation,
  _In_       ULONG Length,
  _Out_      PULONG ResultLength
);

Parameters

KeyHandle [in]

Handle to the registry key to obtain information about. This handle is created by a successful call to ZwCreateKey or ZwOpenKey.

KeyInformationClass [in]

Specifies a KEY_INFORMATION_CLASS value that determines the type of information returned in the KeyInformation buffer.

KeyInformation [out, optional]

Pointer to a caller-allocated buffer that receives the requested information.

Length [in]

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

ResultLength [out]

Pointer to a variable that receives the size, in bytes, of the requested key information. If ZwQueryKey returns STATUS_SUCCESS, the variable contains the amount of data returned. If ZwQueryKey returns STATUS_BUFFER_OVERFLOW or STATUS_BUFFER_TOO_SMALL, you can use the value of the variable to determine the required buffer size.

Return value

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

Return codeDescription
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.

 

Remarks

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

ZwQueryKey can be used to obtain information that you can use to allocate buffers to hold registry data, such as the maximum size of a key's value entries or subkey names, or the number of subkeys. For example, you can call ZwQueryKey, use the returned information to allocate a buffer for a subkey, call ZwEnumerateKey to get the name of the subkey, and pass that name to an RtlXxxRegistry routine.

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 "NtQueryKey" instead of "ZwQueryKey".

Requirements

Version

Available starting with Windows 2000.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

Ntoskrnl.lib

IRQL

PASSIVE_LEVEL

DDI compliance rules

IrqlZwPassive, PowerIrpDDis, ZwRegistryCreate, ZwRegistryOpen, HwStorPortProhibitedDDIs, ZwRegistryCreate(storport), ZwRegistryOpen(storport)

See also

KEY_BASIC_INFORMATION
KEY_CACHED_INFORMATION
KEY_FULL_INFORMATION
KEY_INFORMATION_CLASS
KEY_NAME_INFORMATION
KEY_NODE_INFORMATION
KEY_VIRTUALIZATION_INFORMATION
ZwClose
ZwEnumerateKey
ZwOpenKey

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft