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
事务管理器对象的句柄，该对象由以前对 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。 否则，此例程可能会返回以下值之一：
| 返回代码 | 说明 |
|---|---|
|
CreateOptions 参数包含无效标志、DesiredAccess 参数为零或 Description 参数的字符串太长。 |
|
KTM 无法 (内存) 分配系统资源。 |
|
安全描述符包含无效的访问控制列表 (ACL) 。 |
|
安全描述符包含无效的安全标识符 (SID) 。 |
|
ObjectAttributes 参数指定的对象名称已存在。 |
|
ObjectAttributes 参数指定的对象名称无效。 |
|
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 (storport) ， PowerIrpDDis (wdm) |