ntCreateTransaction 函数 (wdm.h)

项目
03/14/2023

ZwCreateTransaction 例程创建事务对象。

语法

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateTransaction(
  [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

事务管理器对象的句柄，该对象由以前对 ZwCreateTransactionManager 或 ZwOpenTransactionManager 的调用获取。 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 例程的 NtXxx 和 ZwXxx 版本在处理和解释输入参数的方式上的行为可能有所不同。有关例程的 NtXxx 和 ZwXxx 版本之间的关系的详细信息，请参阅使用本机系统服务例程的 Nt 和 Zw 版本。

要求

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