ntCreateTransactionManager 函数 (wdm.h)

项目
02/29/2024

ZwCreateTransactionManager 例程创建新的事务管理器对象。

语法

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateTransactionManager(
  [out]          PHANDLE            TmHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] PUNICODE_STRING    LogFileName,
  [in, optional] ULONG              CreateOptions,
  [in, optional] ULONG              CommitStrength
);

参数

[out] TmHandle

指向调用方分配的变量的指针，该变量接收新的事务管理器对象的句柄。

[in] DesiredAccess

一个 ACCESS_MASK 值，该值指定调用方对事务管理器对象的请求访问权限。除了为各种对象定义的访问权限 (查看 ACCESS_MASK) 之外，调用方还可以为事务管理器对象指定以下任一访问权限标志。

ACCESS_MASK标志	允许调用方
TRANSACTIONMANAGER_CREATE_RM	创建资源管理器 (请参阅 ZwCreateResourceManager) 。
TRANSACTIONMANAGER_QUERY_INFORMATION	获取有关事务管理器的信息 (请参阅 ZwQueryInformationTransactionManager 和 ZwEnumerateTransactionObject) 。 ZwOpenResourceManager、ZwCreateTransaction 和 ZwOpenTransaction.)
TRANSACTIONMANAGER_RECOVER	恢复事务管理器 (请参阅 ZwRecoverTransactionManager 和 ZwRollforwardTransactionManager) 。
TRANSACTIONMANAGER_RENAME	未使用。
TRANSACTIONMANAGER_SET_INFORMATION	未使用。

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

权限位图	特定访问权限集
TRANSACTIONMANAGER_GENERIC_READ	STANDARD_RIGHTS_READ和TRANSACTIONMANAGER_QUERY_INFORMATION
TRANSACTIONMANAGER_GENERIC_WRITE	STANDARD_RIGHTS_WRITE、TRANSACTIONMANAGER_SET_INFORMATION、TRANSACTIONMANAGER_RECOVER、TRANSACTIONMANAGER_RENAME和TRANSACTIONMANAGER_CREATE_RM
TRANSACTIONMANAGER_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE
TRANSACTIONMANAGER_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED、TRANSACTIONMANAGER_GENERIC_READ、TRANSACTIONMANAGER_GENERIC_WRITE和TRANSACTIONMANAGER_GENERIC_EXECUTE

[in, optional] ObjectAttributes

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

[in, optional] LogFileName

指向 UNICODE_STRING 结构的指针，该结构包含要与事务管理器对象关联的 CLFS 日志文件流的路径和文件名。如果TRANSACTION_MANAGER_VOLATILE CreateOptions 参数，此参数必须为 NULL。否则，此参数必须为非 NULL。有关更多信息，请参见下面的“备注”部分。

[in, optional] CreateOptions

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

选项标志	含义
TRANSACTION_MANAGER_VOLATILE	事务管理器对象将是可变的。因此，它不使用日志文件。
TRANSACTION_MANAGER_COMMIT_DEFAULT	仅限内部使用。
TRANSACTION_MANAGER_COMMIT_SYSTEM_VOLUME	仅限内部使用。
TRANSACTION_MANAGER_COMMIT_SYSTEM_HIVES	仅限内部使用。
TRANSACTION_MANAGER_COMMIT_LOWEST	仅限内部使用。
TRANSACTION_MANAGER_CORRUPT_FOR_RECOVERY	仅限内部使用。
TRANSACTION_MANAGER_CORRUPT_FOR_PROGRESS	仅限内部使用。

[in, optional] CommitStrength

保留供将来使用。此参数必须为零。

返回值

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

返回代码	说明
STATUS_INVALID_PARAMETER	输入参数的值无效。
STATUS_INSUFFICIENT_RESOURCES	KTM 无法 (内存) 分配系统资源。
STATUS_LOG_CORRUPTION_DETECTED	KTM 在创建或打开日志文件时遇到错误。
STATUS_INVALID_ACL	安全描述符包含无效的访问控制列表 (ACL) 。
STATUS_INVALID_SID	安全描述符包含无效的安全标识符 (SID) 。
STATUS_OBJECT_NAME_EXISTS	ObjectAttributes 参数指定的对象名称已存在。
STATUS_OBJECT_NAME_COLLISION	操作系统检测到重复的对象名称。此错误可能指示日志流已被使用。
STATUS_OBJECT_NAME_INVALID	ObjectAttributes 参数指定的对象名称无效。
STATUS_ACCESS_DENIED	DesiredAccess 参数的值无效。

例程可能会返回其他 NTSTATUS 值。

注解

如果 LogFileName 参数指定的日志文件流不存在，KTM 会调用 CLFS 来创建流。如果流已存在，KTM 会调用 CLFS 以打开流。

TPS 组件在调用 ZwCreateTransactionManager 后必须调用 ZwRecoverTransactionManager

如果 TPS 组件在 CreateOptions 参数中指定TRANSACTION_MANAGER_VOLATILE标志，则与事务管理器对象关联的所有资源管理器在调用 ZwCreateResourceManager 时都必须指定RESOURCE_MANAGER_VOLATILE标志。

调用 ZwCreateTransactionManager 的 TPS 组件最终必须调用 ZwClose 以关闭对象句柄。

有关如何使用 ZwCreateTransactionManager 的详细信息，请参阅创建资源管理器。

NtCreateTransactionManager 和 ZwCreateTransactionManager 是同一 Windows 本机系统服务例程的两个版本。

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

要求

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