NtQueryValueKey - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
#ifndef _NTREGAPI_H
/**
* Retrieves one named value without changing its data. Supports size discovery by passing KeyValueInformation
* = NULL and Length = 0 with a valid ResultLength.
*
* \param[in] KeyHandle Key handle with KEY_QUERY_VALUE (0x1).
* \param[in] ValueName Required readable counted UNICODE_STRING, matched without case sensitivity. A
* zero-length descriptor selects the default value. Trailing WCHAR NULs are trimmed; embedded NULs remain
* name characters.
* \param[in] KeyValueInformationClass Classes 0 through 4 are accepted; class 5 (KeyValueLayerInformation)
* and other infoclasses return STATUS_INVALID_PARAMETER. Preserve newer class definitions for other OS targets.
* \param[out] KeyValueInformation Optional caller buffer, required when Length is nonzero. Native x64 checks
* 4-byte alignment for all accepted classes on this build; portable Align64 callers should still supply an
* 8-byte-aligned buffer.
* \param[in] Length Output capacity in bytes, not a number of records or WCHARs.
* \param[out] ResultLength Required ULONG receiving the total size needed on STATUS_SUCCESS,
* STATUS_BUFFER_OVERFLOW or STATUS_BUFFER_TOO_SMALL. It can exceed Length and must not be treated as the
* number of initialized bytes on overflow.
* \return STATUS_BUFFER_TOO_SMALL if the fixed prefix does not fit (no record copied), STATUS_BUFFER_OVERFLOW
* if the prefix fits but the complete record does not, STATUS_OBJECT_NAME_NOT_FOUND if absent, or another
* NTSTATUS.
* \remarks Returned NameLength/DataLength describe the full value even on overflow. Validate the available
* prefix and clamp all reads to Length before using offsets or lengths. Missing-value, invalid-class and
* access failures leave ResultLength unchanged on ordinary paths; do not use a stale output size. WoW64
* copies non-8-byte-aligned query output through a temporary native buffer, even for ordinary classes. That
* thunk copies the requested Length back, so do not rely on untouched buffer contents on failure or beyond
* the valid returned record. Size discovery and retrieval are separate snapshots; the value may change
* between them.
* \sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwqueryvaluekey
*/
_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
NtQueryValueKey(
_In_ HANDLE KeyHandle,
_In_ PCUNICODE_STRING ValueName,
_In_ KEY_VALUE_INFORMATION_CLASS KeyValueInformationClass,
_Out_writes_bytes_to_opt_(Length, *ResultLength) PVOID KeyValueInformation,
_In_ ULONG Length,
_Out_ PULONG ResultLength
);
View code on GitHub#ifndef _NTZWAPI_H
_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwQueryValueKey(
_In_ HANDLE KeyHandle,
_In_ PCUNICODE_STRING ValueName,
_In_ KEY_VALUE_INFORMATION_CLASS KeyValueInformationClass,
_Out_writes_bytes_to_opt_(Length, *ResultLength) PVOID KeyValueInformation,
_In_ ULONG Length,
_Out_ PULONG ResultLength
);
View code on GitHub// wdm.h
NTSYSAPI NTSTATUS ZwQueryValueKey(
[in] HANDLE KeyHandle,
[in] PUNICODE_STRING ValueName,
[in] KEY_VALUE_INFORMATION_CLASS KeyValueInformationClass,
[out, optional] PVOID KeyValueInformation,
[in] ULONG Length,
[out] PULONG ResultLength
);
View the official Windows Driver Kit DDI referenceNo description available.
The ZwQueryValueKey routine returns a value entry for a registry key.
KeyHandle [in]Handle to the key to read value entries from. This handle is created by a successful call to ZwCreateKey or ZwOpenKey.
ValueName [in]Pointer to the name of the value entry to obtain data for.
KeyValueInformationClass [in]A KEY_VALUE_INFORMATION_CLASS value that determines the type of information returned in the KeyValueInformation buffer.
KeyValueInformation [out, optional]Pointer to a caller-allocated buffer that receives the requested information.
Length [in]Specifies the size, in bytes, of the KeyValueInformation buffer.
ResultLength [out]Pointer to a variable that receives the size, in bytes, of the key information. If the ZwQueryValueKey routine returns STATUS_SUCCESS, callers 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, callers can use the value of this variable to determine the size of buffer required to hold the key information.
ZwQueryValueKey returns STATUS_SUCCESS on success, or the appropriate error code on failure. Possible error code values include:
| Return code | Description |
|---|---|
| STATUS_OBJECT_NAME_NOT_FOUND | The registry value was not available. |
| 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_VALUE_INFORMATION_CLASS value. |
The KeyHandle passed to ZwQueryValueKey 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.
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 "NtQueryValueKey" instead of "ZwQueryValueKey". 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.
Using Nt and Zw Versions of the Native System Services Routines
This function is documented in Windows Driver Kit.
See ZwQueryValueKey in NT DDK or 2000 DDK for detailed description.