ZwOpenKeyTransactedEx 函数 (wdm.h)

项目
02/27/2024

ZwOpenKeyTransactedEx 例程打开现有注册表项，并将该注册表项与事务相关联。

语法

NTSYSAPI NTSTATUS ZwOpenKeyTransactedEx(
  [out] PHANDLE            KeyHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  ULONG              OpenOptions,
  [in]  HANDLE             TransactionHandle
);

参数

[out] KeyHandle

指向 HANDLE 变量的指针，例程将句柄写入到该变量中。

[in] DesiredAccess

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

[in] ObjectAttributes

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

[in] OpenOptions

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

OpenOptions 标志	说明
REG_OPTION_OPEN_LINK	键是符号链接。设备和中间驱动程序不使用此标志。
REG_OPTION_BACKUP_RESTORE	应使用允许备份和还原操作的特殊权限打开密钥。设备和中间驱动程序不使用此标志。

[in] TransactionHandle

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

返回值

如果调用成功打开密钥，ZwOpenKeyTransactedEx 将返回STATUS_SUCCESS。可能的错误返回值包括：

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

注解

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

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

如果注册表中不存在指定的项， 则 ZwOpenKeyTransactedEx 将返回错误状态值，并且不提供键句柄。与 ZwCreateKeyTransacted 例程不同， ZwOpenKeyTransactedEx 例程不会创建指定的键（如果该键不存在）。 ZwCreateKeyTransacted 和 ZwOpenKeyTransactedEx 将注册表项与事务相关联。

ZwOpenKeyEx 例程类似于 ZwOpenKeyTransactedEx，但不会将密钥与事务相关联。

ZwOpenKeyTransacted 例程类似于 ZwOpenKeyTransactedEx，但不接受 OpenOptions 参数。 ZwOpenKeyTransactedEx 的 OpenOptions 参数使调用方能够打开作为符号链接的密钥，或打开用于备份和还原操作的密钥。调用将 OpenOptions 参数设置为零的 ZwOpenKeyTransactedEx 等效于对 ZwOpenKeyTransacted 的调用。

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

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

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

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

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

ZwOpenKeyTransactedEx 忽略 ObjectAttributes 参数指向的结构中的安全信息。

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

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

要求

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