ZwCreateKeyTransacted 函数 (wdm.h)

项目
02/27/2024

ZwCreateKeyTransacted 例程创建新的注册表项或打开现有注册表项，并将该注册表项与事务关联。

语法

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

参数

[out] KeyHandle

指向 HANDLE 变量的指针，例程在其中将句柄写入键。

[in] DesiredAccess

指定调用方请求的密钥的访问类型。此参数是一个 ACCESS_MASK 值。有关详细信息，请参阅 ZwCreateKey 例程的 DesiredAccess 参数的说明。

[in] ObjectAttributes

指向正在打开的键的对象属性的指针。此参数指向之前必须由 InitializeObjectAttributes 例程初始化的OBJECT_ATTRIBUTES结构。调用方必须在调用 InitializeObjectAttributes 时将注册表项的名称指定为 ObjectName 参数。如果调用方未在系统线程上下文中运行，则必须在调用 InitializeObjectAttributes 时设置 OBJ_KERNEL_HANDLE 属性。

TitleIndex

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

[in, optional] Class

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

[in] CreateOptions

指定在例程创建或打开密钥时要应用的选项。将此参数设置为零或以下一个或多个REG_OPTION_XXX 标志位的按位 OR。

CreateOptions 标志	说明
REG_OPTION_VOLATILE	计算机重启后，不会保留密钥。
REG_OPTION_NON_VOLATILE	该密钥在计算机重启后保留。
REG_OPTION_CREATE_LINK	键是符号链接。设备和中间驱动程序不使用此标志。
REG_OPTION_BACKUP_RESTORE	使用启用备份和还原操作的特殊权限打开密钥。设备和中间驱动程序不使用此标志。

[in] TransactionHandle

事务对象的句柄。若要获取此句柄，可以调用 ZwCreateTransaction 例程。或者，如果具有指向事务对象的指针，则可以提供指向 ObOpenObjectByPointer 例程的指针以获取相应的事务句柄。

[out, optional] Disposition

指向一个位置的指针，例程在其中写入以下值之一，以指示调用是创建新键还是打开了现有键。

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

如果不需要此信息，可以设置处置 = NULL 。

返回值

如果调用成功创建或打开密钥，ZwCreateKeyTransacted 将返回STATUS_SUCCESS。可能的错误返回值包括以下内容：

返回代码	说明
STATUS_INVALID_PARAMETER	ObjectAttributes 参数为 NULL 或指向无效信息，或者 CreateOptions 参数值指定无效选项。
STATUS_OBJECT_PATH_SYNTAX_BAD	对象属性中的注册表路径无效。
STATUS_OBJECT_NAME_NOT_FOUND	找不到对象属性中的注册表路径。
STATUS_ACCESS_DENIED	调用方没有打开命名注册表项句柄所需的访问权限。
STATUS_INSUFFICIENT_RESOURCES	内存分配操作失败。

注解

此例程提供调用方可以访问注册表项的句柄。此外，此例程将密钥与活动事务相关联。

不再使用 KeyHandle 指向的句柄后，驱动程序必须调用 ZwClose 例程来关闭它。

与 ZwCreateKeyTransacted 一样， ZwOpenKeyTransacted 例程将密钥与事务相关联。与 ZwCreateKeyTransacted（可以创建新密钥或打开现有项）不同， ZwOpenKeyTransacted 只能打开已存在的注册表项。

例如，在内核模式驱动程序获取事务 (句柄后，通过调用 ZwCreateTransaction) ，驱动程序可以执行一系列属于此事务的注册表操作。驱动程序可以通过提交到事务中所做的更改或通过回滚事务来关闭事务。

驱动程序成功完成属于事务的所有注册表操作后，可以调用 ZwCommitTransaction 例程来提交更改。驱动程序可以调用 ZwRollbackTransaction 例程来回滚事务。

在事务期间，如果执行该操作的系统调用满足以下任一条件，则注册表操作是事务的一部分：

调用指定事务句柄作为输入参数。例如，对 ZwCreateKeyTransacted 和 ZwOpenKeyTransacted 的 调用可以将一个或多个句柄与事务关联到注册表项。
调用指定作为输入参数的注册表项句柄，该句柄是通过调用 ZwCreateKeyTransacted 或 ZwOpenKeyTransacted 获取的，该句柄提供事务句柄。例如，对 ZwSetValueKey 例程的调用可以使用以这种方式获取的键句柄将注册表项的值设置为事务的一部分。

有关内核模式事务的详细信息，请参阅使用内核事务管理器。

对象属性中的安全描述符确定是否在以后调用例程（如访问密钥的 ZwOpenKeyTransacted）或创建密钥的例程（如 ZwCreateKeyTransacted）时授予 DesiredAccess 参数指定的访问权限。

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

有关如何在内核模式下使用注册表项的详细信息，请参阅在驱动程序中使用注册表。

要求

要求	值
最低受支持的客户端	在 Windows Vista 和更高版本的 Windows 中可用。
目标平台	通用
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 符合性规则	HwStorPortProhibitedDDI (storport) 、 PowerIrpDDis (wdm)