tmCreateEnlistment 函数 (wdm.h)
TmCreateEnlistment 例程为事务创建新的登记对象。
语法
NTSTATUS TmCreateEnlistment(
[out] PHANDLE EnlistmentHandle,
[in] KPROCESSOR_MODE PreviousMode,
[in] ACCESS_MASK DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[in] PRKRESOURCEMANAGER ResourceManager,
[in] PKTRANSACTION Transaction,
[in, optional] ULONG CreateOptions,
[in] NOTIFICATION_MASK NotificationMask,
[in, optional] PVOID EnlistmentKey
);
参数
[out] EnlistmentHandle
指向调用方分配的变量的指针，如果 对 TmCreateEnlistment 的 调用成功，该变量接收新登记对象的句柄。
[in] PreviousMode
将使用登记句柄访问登记对象的进程的处理器模式。 此值必须是 UserMode 或 KernelMode。
[in] DesiredAccess
一个 ACCESS_MASK 值，该值指定调用方对登记对象的请求访问权限。 有关此参数的详细信息，请参阅 ZwCreateEnlistment 的 DesiredAccess 参数的说明。
[in] ObjectAttributes
指向 OBJECT_ATTRIBUTES 结构的指针，该结构指定对象名称和其他属性。 使用 InitializeObjectAttributes 例程初始化此结构。 如果调用方未在系统线程上下文中运行，则必须在调用 InitializeObjectAttributes 时设置 OBJ_KERNEL_HANDLE 属性。 此参数是可选的，可以为 NULL。
[in] ResourceManager
指向 资源管理器对象的指针。 若要获取此指针，组件必须调用 ObReferenceObjectByHandle 并提供先前对 ZwCreateResourceManager 或 ZwOpenResourceManager 的调用提供的对象句柄。
[in] Transaction
指向 事务对象的指针。 若要获取此指针，组件必须调用 ObReferenceObjectByHandle 并提供先前对 ZwCreateTransaction 或 ZwOpenTransaction 的调用提供的对象句柄。 KTM 将此事务添加到调用资源管理器正在处理的事务列表中。
[in, optional] CreateOptions
登记选项标志。 下表包含唯一可用的标志。
| CreateOptions 标志 | 含义 |
|---|---|
| ENLISTMENT_SUPERIOR | 调用方将登记为指定 事务的上级事务管理器 。 |
此参数是可选的，可以为零。
[in] NotificationMask
Ktmtypes.h 中定义的TRANSACTION_NOTIFY_XXX 值的按位 OR。 此掩码值指定 KTM 向调用方发送 的事务通知 的类型。
[in, optional] EnlistmentKey
指向调用方定义的信息的指针，该信息唯一标识登记。 资源管理器在调用 ZwGetNotificationResourceManager 或 KTM 调用 ResourceManagerNotification 回调例程时接收此指针。 资源管理器可以通过调用 TmReferenceEnlistmentKey 和 TmDereferenceEnlistmentKey 来维护此密钥的引用计数。 此参数是可选的，可以为 NULL。
返回值
如果操作成功，TmCreateEnlistment 将返回STATUS_SUCCESS。 否则，此例程可能会返回以下值之一：
| 返回代码 | 说明 |
|---|---|
|
CreateOptions 或 NotificationMask 参数的值无效，或者 KTM 找不到 Transaction 参数指定的事务。 |
|
内存分配失败。 |
|
登记失败，因为 KTM 或资源管理器未处于操作状态。 |
|
由于 Transaction 参数指定的事务未处于活动状态，登记失败。 |
|
调用方尝试注册为 高级事务管理器 ，但已存在高级登记。 |
|
调用方尝试注册为高级事务管理器，但调用方的资源管理器对象是 可变 的，而关联的事务管理器对象不是可变的。 |
|
DesiredAccess 参数的值无效。 |
例程可能会返回其他 NTSTATUS 值。
注解
TmCreateEnlistment 例程是 ZwCreateEnlistment 例程的基于指针的版本。
有关何时使用 KTM 的 TmXxx 例程而不是 ZwXxx 例程的信息，请参阅 使用 TmXxx 例程。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | 在 Windows Vista 和更高版本的操作系统版本中可用。 |
| 目标平台 | 通用 |
| 标头 | wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h） |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |