NtCreateTransaction 函数 （wdm.h）
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位图。 这些位图将上表中的标志与STANDARD_RIGHTS_XXX 标志组合在 ACCESS_MASK 参考页上。 还可以将这些位图与上表中的其他标志组合在一起。 下表显示了位图如何对应于特定的访问权限。
| Rights bitmap | 特定访问权限集 |
|---|---|
| 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 用作新事务对象的工作单位（UOW）标识符 的 GUID 的指针。 此参数是可选的，可以 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 纳秒间隔）表示，可以指定绝对时间或相对时间。 如果 超时 指向的值为负值，则过期时间相对于当前系统时间。 否则，过期时间是绝对的。 此指针是可选的，如果不希望事务具有超时值，则可以 NULL。 如果 Timeout = NULL 或 *Timeout = 0，则事务永远不会超时。（也可以使用 ZwSetInformationTransaction 设置超时值。
[in, optional] Description
指向调用方提供的 UNICODE_STRING 结构的指针，该结构包含 NULL 终止的字符串。 该字符串提供事务的说明。 KTM 存储字符串的副本，并在写入日志流的消息中包含字符串。 最大字符串长度为MAX_TRANSACTION_DESCRIPTION_LENGTH。 此参数是可选的，可以 NULL。
返回值
ZwCreateTransaction 如果作成功，则返回STATUS_SUCCESS。 否则，此例程可能会返回以下值之一：
| 返回代码 | 描述 |
|---|---|
|
CreateOptions 参数包含无效标志、DesiredAccess 参数为零，或者 说明 参数的字符串太长。 |
|
KTM 无法分配系统资源（通常是内存）。 |
|
安全描述符包含无效的访问控制列表（ACL）。 |
|
安全描述符包含无效的安全标识符（SID）。 |
|
ObjectAttributes 参数指定的对象名称已存在。 |
|
ObjectAttributes 参数指定的对象名称无效。 |
|
DesiredAccess 参数的值无效。 |
例程可能会 返回其他NTSTATUS 值。
言论
调用方可以使用 Uow 参数为事务对象指定 UOW 标识符。 如果调用方未指定 UOW 标识符，KTM 将生成 GUID 并将其分配给事务对象。 调用方稍后可以通过调用 ZwQueryInformationTransaction来获取此 GUID。
通常，应让 KTM 为事务对象生成 GUID，除非组件与已为事务生成 UOW 标识符的另一个 TPS 组件通信。
若要关闭事务句柄，调用 ZwCreateTransaction 的组件必须调用 ZwClose。 如果在任何组件调用 ZwCommitTransaction 事务之前关闭最后一个事务句柄，KTM 将回滚事务。
若要详细了解事务客户端如何使用 ZwCreateTransaction，请参阅 创建事务客户端。
对于内核模式驱动程序的调用，NtXxx 和 ZwXxx 版本的 Windows 本机系统服务例程的行为方式可能以不同的方式处理和解释输入参数。 有关 NtXxx 与 ZwXxx 例程之间的关系的详细信息，请参阅 使用 Nt 和 Zw 版本的本机系统服务例程。
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | 在 Windows Vista 和更高版本的作系统版本中可用。 |
| 目标平台 | 普遍 |
| 标头 | wdm.h （包括 Wdm.h、Ntddk.h、Ntifs.h） |
| 库 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI 符合性规则 | HwStorPortProhibitedDDI、PowerIrpDDis |