NtQueryKey - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
#ifndef _NTREGAPI_H
/**
* Queries metadata for the supplied key itself. Use basic/node/name information
* to identify it, full/cached information for counts and buffer-planning maxima,
* and the fixed flag records for registry metadata. This does not read value data.
*
* \param[in] KeyHandle Normally requires KEY_QUERY_VALUE. KeyNameInformation
* and KeyHandleTagsInformation instead require any nonzero granted access mask
* on the ordinary path; a valid zero-access handle is still denied.
* \param[in] KeyInformationClass A KEY_INFORMATION_CLASS infoclass. The native/WoW64 paths accept 0 through 8; unsupported classes return
* STATUS_INVALID_PARAMETER, not STATUS_INVALID_INFO_CLASS.
* \param[out] KeyInformation Caller-owned output storage. NULL with Length = 0
* supports size discovery. Prefer natural alignment; the native entry probes
* nonempty buffers at 4-byte alignment, including records containing LARGE_INTEGER.
* \param[in] Length Output capacity in bytes. Preserve this for bounds checks.
* \param[out] ResultLength Required pointer receiving the complete required size
* on success, STATUS_BUFFER_TOO_SMALL or STATUS_BUFFER_OVERFLOW. On overflow it
* can exceed Length; embedded name/class lengths also remain full lengths.
* Do not use an unchanged ResultLength after unrelated failures as a valid size.
* \return STATUS_SUCCESS for a complete record; STATUS_BUFFER_TOO_SMALL when
* the fixed prefix/record cannot fit; STATUS_BUFFER_OVERFLOW for a partial
* variable record; or another NTSTATUS describing the failure.
* \remarks Returned names/class strings are not NUL-terminated. Counts/maxima
* can change before a later query; sizing does not reserve a registry snapshot.
* The WoW64 thunk realigns output not aligned to 8 bytes through
* temporary storage and copies the requested Length back regardless of status.
* Unlike its enumeration counterpart, it does not first copy the caller's buffer
* into that storage. Do not rely on failure-buffer or spare-byte preservation in
* that path, and consume only fields covered by a valid returned record.
* It still supports zero-length sizing with an unaligned non-NULL pointer.
* Registry filters, layered keys, transactions and virtualization have separate
* paths and can affect ordinary behavior.
* \sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwquerykey
*/
_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
NtQueryKey(
_In_ HANDLE KeyHandle,
_In_ KEY_INFORMATION_CLASS KeyInformationClass,
_Out_writes_bytes_to_opt_(Length, *ResultLength) PVOID KeyInformation,
_In_ ULONG Length,
_Out_ PULONG ResultLength
);
View code on GitHub#ifndef _NTZWAPI_H
_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwQueryKey(
_In_ HANDLE KeyHandle,
_In_ KEY_INFORMATION_CLASS KeyInformationClass,
_Out_writes_bytes_to_opt_(Length, *ResultLength) PVOID KeyInformation,
_In_ ULONG Length,
_Out_ PULONG ResultLength
);
View code on GitHub// wdm.h
NTSYSAPI NTSTATUS ZwQueryKey(
[in] HANDLE KeyHandle,
[in] KEY_INFORMATION_CLASS KeyInformationClass,
[out, optional] PVOID KeyInformation,
[in] ULONG Length,
[out] PULONG ResultLength
);
View the official Windows Driver Kit DDI referenceNo description available.
The ZwQueryKey routine provides information about the class of a registry key, and the number and sizes of its subkeys.
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.
ZwQueryKey returns STATUS_SUCCESS on success, or the appropriate 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. |
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.
If KeyInformationClass is KeyNameInformation or KeyHandleTagsInformation, the KEY_QUERY_VALUE requirement does not apply.
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.
If the call to this function occurs in user mode, you should use the name "NtQueryKey" instead of "ZwQueryKey".
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.
KEY_VIRTUALIZATION_INFORMATION
Using Nt and Zw Versions of the Native System Services Routines
This function is documented in Windows Driver Kit.
See ZwQueryKey in NT DDK or 2000 DDK for detailed description.