ZwSetValueKey

The ZwSetValueKey routine replaces or creates a value entry for a key in the registry.

NTSTATUS 
  ZwSetValueKey(
    IN HANDLE  KeyHandle,
    IN PUNICODE_STRING  ValueName,
    IN ULONG  TitleIndex  OPTIONAL,
    IN ULONG  Type,
    IN PVOID  Data,
    IN ULONG  DataSize
    );

Parameters

KeyHandle

Handle to the key for which a value entry is to be written in the registry. This handle is created by a successful call to ZwCreateKey or ZwOpenKey.

ValueName

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

Reserved. Device and intermediate drivers should set this parameter to zero.

Type

Specifies the type of the data to be written for ValueName. System-defined types include the following.

REG_XXX Type	Value
REG_BINARY	Binary data in any form
REG_DWORD	A 4-byte numerical value
REG_DWORD_LITTLE_ENDIAN	A 4-byte numerical value whose least significant byte is at the lowest address, which is identical to type REG_DWORD
REG_DWORD_BIG_ENDIAN	A 4-byte numerical value whose least significant byte is at the highest address
REG_EXPAND_SZ	A zero-terminated Unicode string, containing unexpanded references to environment variables, such as "%PATH%"
REG_LINK	A Unicode string naming a symbolic link; this type is irrelevant to device and intermediate drivers.
REG_MULTI_SZ	An array of zero-terminated strings, terminated by another zero
REG_NONE	Data with no particular type
REG_SZ	A zero-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 need not, and should not attempt to, call ZwSetValueKey directly to write value entries in a subkey of the \Registry..\ResourceMap key. Only the system can write value entries to the \Registry..\HardwareDescription tree.

Data

Pointer to a caller-allocated buffer containing the data for the value entry.

DataSize

Specifies the size in bytes of the Data buffer. If Type is any of the REG_XXX_SZ, this value must include the terminating zero(s).

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Return Value

ZwSetValueKey returns an NTSTATUS value. Possible return values include:

STATUS_SUCCESS
STATUS_ACCESS_DENIED
STATUS_INVALID_HANDLE

Comments

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.

Callers of ZwSetValueKey must be running at IRQL = PASSIVE_LEVEL.

See Also

HalAssignSlotResources, IoAssignResources, IoQueryDeviceDescription, IoReportResourceUsage, ZwClose, ZwCreateKey, ZwFlushKey, ZwOpenKey