zwCreateKey 函数 (wdm.h)

ZwCreateKey 例程创建新的注册表项或打开现有注册表项。

语法

NTSYSAPI NTSTATUS ZwCreateKey(
  [out]           PHANDLE            KeyHandle,
  [in]            ACCESS_MASK        DesiredAccess,
  [in]            POBJECT_ATTRIBUTES ObjectAttributes,
                  ULONG              TitleIndex,
  [in, optional]  PUNICODE_STRING    Class,
  [in]            ULONG              CreateOptions,
  [out, optional] PULONG             Disposition
);

参数

[out] KeyHandle

指向接收键句柄的 HANDLE 变量的指针。

[in] DesiredAccess

指定一个 ACCESS_MASK 值,该值确定对对象的请求访问权限。 除了为所有类型的对象定义的访问权限之外, (ACCESS_MASK ) ,调用方还可以指定以下一个或多个特定于对象目录的访问权限:

DesiredAccess 标志 允许调用方执行此操作
KEY_QUERY_VALUE 读取键值。
KEY_SET_VALUE 写入键值。
KEY_CREATE_SUB_KEY 为密钥创建子项。
KEY_ENUMERATE_SUB_KEYS 读取密钥的子项。
KEY_CREATE_LINK 创建指向密钥的符号链接。 设备和中间驱动程序不使用此标志。
KEY_NOTIFY 当密钥的名称、值或属性发生更改时,请求接收通知。 有关详细信息,请参阅 ZwNotifyChangeKey
 

调用方还可以指定下列常量之一,该常量结合了多个ACCESS_MASK标志。

返回的常量 由这些ACCESS_MASK标志组成
KEY_READ STANDARD_RIGHTS_READ、KEY_QUERY_VALUE、KEY_ENUMERATE_SUB_KEYS和KEY_NOTIFY
KEY_WRITE STANDARD_RIGHTS_WRITE、KEY_SET_VALUE和KEY_CREATE_SUB_KEY
KEY_EXECUTE 与KEY_READ相同。
KEY_ALL_ACCESS STANDARD_RIGHTS_ALL、KEY_QUERY_VALUE、KEY_SET_VALUE、KEY_CREATE_SUB_KEY、KEY_ENUMERATE_SUB_KEYS、KEY_NOTIFY和KEY_CREATE_LINK

[in] ObjectAttributes

指向指定对象名称和其他属性 的OBJECT_ATTRIBUTES 结构的指针。 使用 InitializeObjectAttributes 初始化此结构。 如果调用方未在系统线程上下文中运行,则必须在调用 InitializeObjectAttributes 时设置OBJ_KERNEL_HANDLE属性。

TitleIndex

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

[in, optional] Class

指向包含键的对象类的 Unicode 字符串的指针。 此信息由配置管理器使用。

[in] CreateOptions

指定创建或打开键时要应用的选项,指定为以下标志的兼容组合。

CreateOptions 标志 说明
REG_OPTION_VOLATILE 重新启动系统时不会保留密钥。
REG_OPTION_NON_VOLATILE 重新启动系统时会保留密钥。
REG_OPTION_CREATE_LINK 新创建的密钥是符号链接。 设备和中间驱动程序不使用此标志。
REG_OPTION_BACKUP_RESTORE 应使用允许备份和还原操作的特殊特权创建或打开密钥。 设备和中间驱动程序不使用此标志。

[out, optional] Disposition

指向接收一个值的变量的指针,该值指示是创建新键还是打开现有键。

处置 说明
REG_CREATED_NEW_KEY 创建了一个新密钥。
REG_OPENED_EXISTING_KEY 已打开现有密钥。

返回值

ZwCreateKey 在成功时返回STATUS_SUCCESS,或者在失败时返回相应的 NTSTATUS 错误代码。

注解

ZwCreateKey 提供调用方可用于操作注册表项的句柄。 有关详细信息,请参阅 在驱动程序中使用注册表

当 KeyHandle 指向的句柄不再使用后,驱动程序必须调用 ZwClose 将其关闭。

可通过两种替代方法指定要使用 ZwCreateKey 创建或打开的文件的名称:

  1. 作为完全限定的路径名,在输入 ObjectAttributesObjectName 成员中提供。 注册表项的路径名称以 \Registry 开头。
  2. 作为相对于另一个注册表项的路径名称,由输入 ObjectAttributesRootDirectory 成员中的句柄表示。
如果 ObjectAttributes 指定的键不存在,则例程会尝试创建密钥。 为使此尝试成功,新密钥必须是 RootDirectory 引用的密钥的直接子项, 并且 RootDirectory 引用的密钥必须已打开才能KEY_CREATE_SUB_KEY访问。

如果指定的键已存在,则会打开,并且其值不会以任何方式受到影响。

创建密钥时 ObjectAttributes 指定的安全属性确定是否在后续调用 ZwCreateKeyZwOpenKey 时授予指定的 DesiredAccess

如果调用方未在系统线程上下文中运行,则必须确保创建的任何句柄都是专用句柄。 否则,该句柄可由运行驱动程序的上下文的进程访问。 有关详细信息,请参阅 对象句柄

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

注意 如果在用户模式下调用此函数,则应使用名称“NtCreateKey”而不是“ZwCreateKey”。
 
Windows 内核中的 NtCreateKey 例程不能直接访问内核模式驱动程序。

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

要求

   
最低受支持的客户端 从 Windows 2000 开始可用。
目标平台 通用
标头 wdm.h(包括 Wdm.h、Ntddk.h、Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 符合性规则 HwStorPortProhibitedDDIs (storport) IrqlZwPassive (wdm) PowerIrpDDis (wdm ) 、 ZwRegistryCreate (storport) 、ZwRegistryCreate (storport ) , ZwRegistryCreate (wdm) ZwRegistryOpen (wdm)

另请参阅

ACCESS_MASK

InitializeObjectAttributes

使用本机系统服务例程的 Nt 和 Zw 版本

ZwClose

ZwDeleteKey

ZwEnumerateKey

ZwEnumerateValueKey

ZwFlushKey

ZwNotifyChangeKey

ZwOpenKey

ZwQueryValueKey

ZwSetValueKey