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 创建或打开的文件的名称：
作为完全限定的路径名，在输入 ObjectAttributes 的 ObjectName 成员中提供。 注册表项的路径名以 \Registry 开头。
作为相对于另一个注册表项的路径名，由输入 ObjectAttributes 的 RootDirectory 成员中的句柄表示。
如果 ObjectAttributes 指定的键不存在，则例程将尝试创建密钥。 若要成功尝试，新密钥必须是 RootDirectory 引用的密钥的直接子项，并且 RootDirectory 引用的密钥必须已打开才能KEY_CREATE_SUB_KEY访问。
如果指定的键已存在，则会打开它，并且其值不会以任何方式受到影响。
创建密钥时由 ObjectAttributs 指定的安全属性确定是否在后续调用 ZwCreateKey 和 ZwOpenKey 时授予指定的 DesiredAccess。
如果调用方未在系统线程上下文中运行，它必须确保它创建的任何句柄都是专用句柄。 否则，运行驱动程序的上下文的进程可以访问句柄。 有关详细信息，请参阅 对象句柄。
有关使用注册表项的详细信息，请参阅 在驱动程序中使用注册表。
如果在用户模式下调用此函数，则应使用名称“NtCreateKey”而不是“ZwCreateKey”。
内核模式驱动程序无法直接访问 Windows 内核中的 NtCreateKey 例程。
对于来自内核模式驱动程序的调用，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 (wdm) |