ZwCreateTransaction 函数 (wdm.h)

ZwCreateTransaction 例程创建事务对象

语法

NTSYSCALLAPI NTSTATUS ZwCreateTransaction(
  [out]          PHANDLE            TransactionHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] LPGUID             Uow,
  [in, optional] HANDLE             TmHandle,
  [in, optional] ULONG              CreateOptions,
  [in, optional] ULONG              IsolationLevel,
  [in, optional] ULONG              IsolationFlags,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PUNICODE_STRING    Description
);

参数

[out] TransactionHandle

指向调用方分配的变量的指针,如果 对 ZwCreateTransaction 的调用成功,该变量接收对新事务对象的句柄。

[in] DesiredAccess

一个ACCESS_MASK值,该值指定调用方请求对事务对象的访问权限。 除了为各种对象定义的访问权限 (请参阅 ACCESS_MASK) 之外,调用方还可以为事务对象指定以下任何标志。

访问掩码 允许调用方
TRANSACTION_COMMIT 提交事务 (请参阅 ZwCommitTransaction) 。
TRANSACTION_ENLIST 为事务创建登记 (请参阅 ZwCreateEnlistment) 。
TRANSACTION_PROPAGATE 请勿使用。
TRANSACTION_QUERY_INFORMATION 获取有关事务的信息 (请参阅 ZwQueryInformationTransaction) 。
TRANSACTION_ROLLBACK 回滚事务 (请参阅 ZwRollbackTransaction) 。
TRANSACTION_SET_INFORMATION 设置事务的信息 (请参阅 ZwSetInformationTransaction) 。
 

或者,可以指定以下一个或多个ACCESS_MASK位图。 这些位图将上表中的标志与ACCESS_MASK参考页上所述的STANDARD_RIGHTS_XXX 标志组合在一起。 还可以将这些位图与上表中的其他标志组合在一起。 下表显示了位图如何对应于特定访问权限。

权限位图 特定访问权限集
TRANSACTION_GENERIC_READ STANDARD_RIGHTS_READ、TRANSACTION_QUERY_INFORMATION 和 SYNCHRONIZE
TRANSACTION_GENERIC_WRITE STANDARD_RIGHTS_WRITE、TRANSACTION_SET_INFORMATION、TRANSACTION_COMMIT、TRANSACTION_ENLIST、TRANSACTION_ROLLBACK、TRANSACTION_PROPAGATE、TRANSACTION_SAVEPOINT和 SYNCHRONIZE
TRANSACTION_GENERIC_EXECUTE STANDARD_RIGHTS_EXECUTE、TRANSACTION_COMMIT、TRANSACTION_ROLLBACK 和 SYNCHRONIZE
TRANSACTION_ALL_ACCESS STANDARD_RIGHTS_REQUIRED、TRANSACTION_GENERIC_READ、TRANSACTION_GENERIC_WRITE和TRANSACTION_GENERIC_EXECUTE
TRANSACTION_RESOURCE_MANAGER_RIGHTS STANDARD_RIGHTS_WRITE、TRANSACTION_GENERIC_READ、TRANSACTION_SET_INFORMATION、TRANSACTION_ENLIST、TRANSACTION_ROLLBACK、TRANSACTION_PROPAGATE和 SYNCHRONIZE
 

通常,资源管理器指定TRANSACTION_RESOURCE_MANAGER_RIGHTS。

DesiredAccess 值不能为零。

[in, optional] ObjectAttributes

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

[in, optional] Uow

指向 KTM 用作新事务对象工作单元的 GUID 的指针 , (UOW) 标识符。 此参数是可选的,可以为 NULL。 如果此参数为 NULL,KTM 将生成 GUID 并将其分配给事务对象。 有关更多信息,请参见下面的“备注”部分。

[in, optional] TmHandle

事务管理器对象的句柄,该对象由以前对 ZwCreateTransactionManagerZwOpenTransactionManager 的调用获取。 KTM 将新的事务对象分配给指定的事务管理器对象。 如果此参数为 NULL,则当资源管理器为事务创建登记时,KTM 稍后会将新的事务对象分配给事务管理器。

[in, optional] CreateOptions

可选的对象创建标志。 下表包含 Ktmtypes.h 中定义的可用标志。

选项标志 含义
TRANSACTION_DO_NOT_PROMOTE 留待将来使用。

[in, optional] IsolationLevel

留待将来使用。 调用方必须将此参数设置为零。

[in, optional] IsolationFlags

保留供将来使用。 调用方应将此参数设置为零。

[in, optional] Timeout

指向超时值的指针。 如果事务尚未在此参数指定的时间前提交,KTM 将回滚该事务。 超时值以系统时间单位表示 (100 纳秒间隔) ,可以指定绝对时间或相对时间。 如果 Timeout 指向的值为负,则过期时间相对于当前系统时间。 否则,过期时间为绝对时间。 此指针是可选的,如果不希望事务具有超时值,可以为 NULL 。 如果 Timeout = NULL 或 *Timeout = 0,则事务永远不会超时。 (也可以使用 ZwSetInformationTransaction 设置超时值。)

[in, optional] Description

指向调用方提供的 UNICODE_STRING 结构的指针,该结构包含以 NULL 结尾的字符串。 字符串提供事务的说明。 KTM 存储字符串的副本,并在写入日志流的消息中包含该字符串。 最大字符串长度为MAX_TRANSACTION_DESCRIPTION_LENGTH。 此参数是可选的,可以为 NULL

返回值

如果操作成功,ZwCreateTransaction 将返回STATUS_SUCCESS。 否则,此例程可能会返回以下值之一:

返回代码 说明
STATUS_INVALID_PARAMETER
CreateOptions 参数包含无效标志、DesiredAccess 参数为零或 Description 参数的字符串太长。
STATUS_INSUFFICIENT_RESOURCES
KTM 无法 (内存) 分配系统资源。
STATUS_INVALID_ACL
安全描述符包含无效的访问控制列表 (ACL) 。
STATUS_INVALID_SID
安全描述符包含无效的安全标识符 (SID) 。
STATUS_OBJECT_NAME_EXISTS
ObjectAttributes 参数指定的对象名称已存在。
STATUS_OBJECT_NAME_INVALID
ObjectAttributes 参数指定的对象名称无效。
STATUS_ACCESS_DENIED
DesiredAccess 参数的值无效。
 

例程可能会返回其他 NTSTATUS 值

注解

调用方可以使用 Uow 参数为事务对象指定 UOW 标识符。 如果调用方未指定 UOW 标识符,KTM 将生成 GUID 并将其分配给事务对象。 调用方稍后可以通过调用 ZwQueryInformationTransaction 获取此 GUID。

通常,应让 KTM 为事务对象生成 GUID,除非你的组件与已为事务生成 UOW 标识符的另一个 TPS 组件通信。

若要关闭事务句柄,调用 ZwCreateTransaction 的 组件必须调用 ZwClose。 如果最后一个事务句柄在任何组件为事务调用 ZwCommitTransaction 之前关闭,KTM 将回滚事务。

有关事务客户端应如何使用 ZwCreateTransaction 的详细信息,请参阅 创建事务客户端

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

要求

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

另请参阅

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

UNICODE_STRING

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

ZwClose

ZwCommitTransaction

ZwCreateEnlistment

ZwCreateTransactionManager

ZwOpenTransaction

ZwOpenTransactionManager

ZwQueryInformationTransaction

ZwRollbackTransaction

ZwSetInformationTransaction