zwOpenKeyTransacted 函数 (wdm.h)

ZwOpenKeyTransacted 例程打开现有的注册表项,并将密钥与事务相关联。

语法

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

参数

[out] KeyHandle

指向 HANDLE 变量的指针,例程将句柄写入键。

[in] DesiredAccess

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

[in] ObjectAttributes

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

[in] TransactionHandle

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

返回值

如果调用成功打开密钥,ZwOpenKeyTransacted 将返回STATUS_SUCCESS。 可能的错误返回值包括:

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

注解

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

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

如果注册表中不存在指定的键, ZwOpenKeyTransacted 将返回错误状态值,并且不提供密钥句柄。 与 ZwCreateKeyTransacted 例程不同,如果键不存在, ZwOpenKeyTransacted 例程不会创建指定的键。 ZwCreateKeyTransactedZwOpenKeyTransacted 将注册表项与事务相关联。

ZwOpenKey 例程类似于 ZwOpenKeyTransacted,但不将密钥与事务相关联。

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

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

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

  • 调用将事务句柄指定为输入参数。 例如,对 ZwCreateKeyTransactedZwOpenKeyTransacted 的调用可以将一个或多个密钥与事务相关联。
  • 该调用指定作为输入参数的注册表项句柄,该句柄是由对 ZwCreateKeyTransactedZwOpenKeyTransacted 的调用获取的。该句柄是提供给该事务句柄的。 例如,对 ZwSetValueKey 例程的调用可以使用以这种方式获取的密钥句柄将注册表项的值设置为事务的一部分。
有关内核模式事务的详细信息,请参阅 “使用内核事务管理器”。

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

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

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

要求

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

另请参阅

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

ObOpenObjectByPointer

ZwClose

ZwCommitTransaction

ZwCreateKey

ZwCreateKeyTransacted

ZwCreateTransaction

ZwOpenKey

ZwOpenKeyTransactedEx

ZwRollbackTransaction

ZwSetValueKey