NtSetValueKey - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
#ifndef _NTREGAPI_H
/**
* Creates or replaces one value entry under a registry key, including its type
* and data. This does not create or rename the containing key.
*
* \param[in] KeyHandle Key handle with KEY_SET_VALUE (0x2) in the ordinary path.
* Registry virtualization, layered keys and filter callbacks can affect the operation.
* \param[in] ValueName Required readable counted UNICODE_STRING. Use an empty
* descriptor (Length = 0, Buffer may be NULL) for the default value, not a NULL
* descriptor pointer. Names are case-insensitive. On x64, the name
* length must be even and at most 32766 bytes (16383 WCHARs); a nonempty user-mode
* name buffer must be 2-byte aligned. Captured trailing WCHAR NULs are trimmed,
* whereas embedded NULs are part of the counted name.
* \param[in, optional] TitleIndex Reserved; pass 0. The native path
* exposes it to registry callbacks but does not pass it to the core value writer.
* Basic/full/partial query records in the ordinary path return TitleIndex = 0.
* \param[in] Type REG_* data type. The caller is responsible for the type's format.
* \param[in, optional] Data Readable DataSize bytes; NULL is valid when DataSize = 0.
* The native operation copies the counted bytes, not a string inferred from Type.
* \param[in] DataSize Byte count, including any required string terminators.
* The native entry rejects values above 0x7FFFF000; this is an entry
* validation bound, not a guarantee that a value that large can be allocated/stored.
* \return NTSTATUS describing the update. Odd or oversized name lengths return
* STATUS_INVALID_PARAMETER in the ordinary path.
* \remarks A zero-length data value still exists; use NtDeleteValueKey to remove it.
* A REG_SZ input without its NUL can be stored as supplied, so do not assume the
* kernel repairs malformed strings. The WoW64 REG_SZ/REG_EXPAND_SZ path can rewrite
* recognized paths according to key tags; byte-for-byte passthrough is not universal.
* \sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwsetvaluekey
*/
_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
NtSetValueKey(
_In_ HANDLE KeyHandle,
_In_ PCUNICODE_STRING ValueName,
_In_opt_ ULONG TitleIndex,
_In_ ULONG Type,
_In_reads_bytes_opt_(DataSize) PVOID Data,
_In_ ULONG DataSize
);
View code on GitHub#ifndef _NTZWAPI_H
_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwSetValueKey(
_In_ HANDLE KeyHandle,
_In_ PCUNICODE_STRING ValueName,
_In_opt_ ULONG TitleIndex,
_In_ ULONG Type,
_In_reads_bytes_opt_(DataSize) PVOID Data,
_In_ ULONG DataSize
);
View code on GitHub// wdm.h
NTSYSAPI NTSTATUS ZwSetValueKey(
[in] HANDLE KeyHandle,
[in] PUNICODE_STRING ValueName,
[in, optional] ULONG TitleIndex,
[in] ULONG Type,
[in, optional] PVOID Data,
[in] ULONG DataSize
);
View the official Windows Driver Kit DDI referenceNo description available.
The ZwSetValueKey routine creates or replaces a registry key's value entry.
KeyHandle [in]Handle to the registry key to write a value entry for. This handle is created by a successful call to ZwCreateKey or ZwOpenKey.
ValueName [in]Pointer to the name of the value entry for which the data is to be written. This parameter can be a NULL pointer if the value entry has no name. If a name string is specified and the given name is not unique relative to its containing key, the data for an existing value entry is replaced.
TitleIndex [in, optional]This parameter is reserved. Device and intermediate drivers should set this parameter to zero.
Type [in]One of the following system-defined types of data to write:
| Type value | Meaning |
|---|---|
| REG_BINARY | Binary data in any form. |
| REG_DWORD | A 4-byte numerical value. |
| REG_DWORD_LITTLE_ENDIAN | A 4-byte numerical value with the least significant byte at the lowest address. Identical to REG_DWORD. |
| REG_DWORD_BIG_ENDIAN | A 4-byte numerical value with the least significant byte at the highest address. |
| REG_EXPAND_SZ | A null-terminated Unicode string that contains unexpanded references to environment variables, such as "%PATH%". |
| REG_LINK | A Unicode string that names a symbolic link. This type is irrelevant to device and intermediate drivers. |
| REG_MULTI_SZ | An array of null-terminated strings, terminated by another zero. |
| REG_NONE | Data with no particular type. |
| REG_SZ | A null-terminated Unicode string. |
| REG_RESOURCE_LIST | A device driver's list of hardware resources, used by the driver or one of the physical devices it controls, in the \ResourceMap tree |
| REG_RESOURCE_REQUIREMENTS_LIST | A device driver's list of possible hardware resources it or one of the physical devices it controls can use, from which the system writes a subset into the \ResourceMap tree |
| REG_FULL_RESOURCE_DESCRIPTOR | A list of hardware resources that a physical device is using, detected and written into the \HardwareDescription tree by the system |
Device drivers should not attempt to call ZwSetValueKey to explicitly write value entries in a subkey of the \Registry...\ResourceMap key. Only the system can write value entries to the \Registry...\HardwareDescription tree.
Data [in, optional]Pointer to a caller-allocated buffer that contains the data for the value entry.
DataSize [in]Specifies the size, in bytes, of the Data buffer. If Type is REG_XXX_SZ, this value must include space for any terminating zeros.
ZwSetValueKey returns STATUS_SUCCESS if the operation succeeds. Otherwise, this routine might return one of the following values:
| Return code | Description |
|---|---|
| STATUS_ACCESS_DENIED | The caller does not have appropriate access to the registry value. |
| STATUS_INVALID_HANDLE | The handle is invalid. |
The KeyHandle passed to ZwSetValueKey must have been opened with the KEY_SET_VALUE DesiredAccess flag set for this call to succeed. For a description of possible values for DesiredAccess, see ZwCreateKey.
If the given key has no existing value entry with a name matching the given ValueName, ZwSetValueKey creates a new value entry with the given name. If a matching value entry name exists, this routine overwrites the original value entry for the given ValueName. Thus, ZwSetValueKey preserves a unique name for each value entry of any particular key. While each value entry name must be unique to its containing key, many different keys in the registry can have value entries with the same names.
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 "NtSetValueKey" instead of "ZwSetValueKey".
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 ZwSetValueKey in NT DDK or 2000 DDK for detailed description.