ZwSetValueKey 函数 (wdm.h)

项目
02/27/2024

ZwSetValueKey 例程创建或替换注册表项的值项。

语法

NTSYSAPI NTSTATUS ZwSetValueKey(
  [in]           HANDLE          KeyHandle,
  [in]           PUNICODE_STRING ValueName,
  [in, optional] ULONG           TitleIndex,
  [in]           ULONG           Type,
  [in, optional] PVOID           Data,
  [in]           ULONG           DataSize
);

参数

[in] KeyHandle

要为其写入值项的注册表项的句柄。此句柄是通过成功调用 ZwCreateKey 或 ZwOpenKey 创建的。

[in] ValueName

指向要为其写入数据的值条目的名称的指针。如果值条目没有名称，此参数可以是 NULL 指针。如果指定了名称字符串，并且给定的名称相对于其包含键不是唯一的，则会替换现有值条目的数据。

[in, optional] TitleIndex

此参数为保留参数。设备和中间驱动程序应将此参数设置为零。

[in] Type

要写入的以下系统定义数据类型之一：

类型值	含义
REG_BINARY	任意格式的二进制数据。
REG_DWORD	一个 4 字节的数值。
REG_DWORD_LITTLE_ENDIAN	一个 4 字节数值，其最低地址处的最小有效字节。与 REG_DWORD 相同。
REG_DWORD_BIG_ENDIAN	一个 4 字节数值，其最高地址处的最小有效字节。
REG_EXPAND_SZ	一个以 null 结尾的 Unicode 字符串，包含对环境变量（如“%PATH%”）的未扩展引用。
REG_LINK	一个 Unicode 字符串，用于命名符号链接。此类型与设备和中间驱动程序无关。
REG_MULTI_SZ	以 null 结尾的字符串的数组，以另一个零结尾。
REG_NONE	没有特定类型的数据。
REG_SZ	以 Null 值结束的 Unicode 字符串。
REG_RESOURCE_LIST	设备驱动程序的硬件资源列表，由驱动程序或其控制的物理设备之一在 \ResourceMap 树中使用
REG_RESOURCE_REQUIREMENTS_LIST	设备驱动程序的可能硬件资源列表或它控制的物理设备之一可以使用，系统从中将子集写入 \ResourceMap 树
REG_FULL_RESOURCE_DESCRIPTOR	物理设备正在使用、检测到并写入到 \HardwareDescription 树中的硬件资源列表

设备驱动程序不应尝试调用 ZwSetValueKey 以在 \Registry...\ResourceMap 键的子项中显式写入值条目。只有系统才能将值条目写入 \Registry...\HardwareDescription 树。

[in, optional] Data

指向调用方分配的缓冲区的指针，该缓冲区包含值条目的数据。

[in] DataSize

指定数据缓冲区的大小（以字节为单位）。如果 Type REG_XXX_SZ，则此值必须包含任何终止零的空间。

返回值

如果操作成功，ZwSetValueKey 将返回STATUS_SUCCESS。否则，此例程可能会返回以下值之一：

返回代码	说明
STATUS_ACCESS_DENIED	调用方对注册表值没有适当的访问权限。
STATUS_INVALID_HANDLE	该句柄无效。

注解

传递给 ZwSetValueKey 的 KeyHandle 必须已打开并设置了 KEY_SET_VALUE DesiredAccess 标志，此调用才能成功。有关 DesiredAccess 的可能值的说明，请参阅 ZwCreateKey。

如果给定键没有现有值条目，其名称与给定 ValueName 匹配， 则 ZwSetValueKey 会创建一个具有给定名称的新值条目。如果存在匹配的值条目名称，则此例程将覆盖给定 ValueName 的原始值项。因此， ZwSetValueKey 保留任何特定键的每个值条目的唯一名称。虽然每个值项名称对于其包含项必须是唯一的，但注册表中的许多不同键可以具有具有相同名称的值项。

有关使用注册表项的详细信息，请参阅在驱动程序中使用注册表。

如果在用户模式下调用此函数，则应使用名称“NtSetValueKey”而不是“ZwSetValueKey”。

对于来自内核模式驱动程序的调用，Windows 本机系统服务例程的 NtXxx 和 ZwXxx 版本在处理和解释输入参数的方式上的行为可能有所不同。有关例程的 NtXxx 和 ZwXxx 版本之间的关系的详细信息，请参阅使用本机系统服务例程的 Nt 和 Zw 版本。

要求

要求	值
目标平台	通用
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 符合性规则	HwStorPortProhibitedDDI (storport) 、 IrqlZwPassive (wdm) 、 PowerIrpDDis (wdm) 、 ZwRegistryCreate (storport) 、ZwRegistryCreate (storport) ， ZwRegistryCreate (wdm) 、 ZwRegistryOpen (storport) 、ZwRegistryOpen (storport) 、 ZwRegistryOpen (wdm)