zwCreateEnlistment 函数 (wdm.h)

ZwCreateEnlistment 例程为事务创建新的登记对象

语法

NTSYSCALLAPI NTSTATUS ZwCreateEnlistment(
  [out]          PHANDLE            EnlistmentHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           HANDLE             ResourceManagerHandle,
  [in]           HANDLE             TransactionHandle,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] ULONG              CreateOptions,
  [in]           NOTIFICATION_MASK  NotificationMask,
  [in, optional] PVOID              EnlistmentKey
);

参数

[out] EnlistmentHandle

指向调用方分配的变量的指针,如果 对 ZwCreateEnlistment 的 调用成功,该变量接收新登记对象的句柄。

[in] DesiredAccess

一个 ACCESS_MASK 值,该值指定调用方对登记对象的请求访问权限。 除了为各种对象定义的访问权限 (查看 ACCESS_MASK) 之外,调用方还可以为登记对象指定以下任何访问权限标志:

ACCESS_MASK标志 允许调用方
ENLISTMENT_QUERY_INFORMATION 有关登记 (的查询信息,请参阅 ZwQueryInformationEnlistment) 。
ENLISTMENT_SET_INFORMATION 设置登记信息 (请参阅 ZwSetInformationEnlistment) 。
ENLISTMENT_RECOVER 恢复登记 (请参阅 ZwRecoverEnlistment) 。
ENLISTMENT_SUBORDINATE_RIGHTS 执行非高级资源管理器执行的操作 (请参阅 ZwRollbackEnlistmentZwPrepareCompleteZwPrepareCompleteZwCommitCompleteZwRollbackCompleteZwSinglePhaseRejectZwReadOnlyEnlistment) 。
ENLISTMENT_SUPERIOR_RIGHTS 执行 高级事务管理器 必须执行的操作 (请参阅 ZwPrepareEnlistmentZwPrepareEnlistmentZwCommitEnlistment) 。
 

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

通用访问权限 特定访问权限集
ENLISTMENT_GENERIC_READ STANDARD_RIGHTS_READ和ENLISTMENT_QUERY_INFORMATION
ENLISTMENT_GENERIC_WRITE STANDARD_RIGHTS_WRITE、ENLISTMENT_SET_INFORMATION、ENLISTMENT_RECOVER、ENLISTMENT_REFERENCE、ENLISTMENT_SUBORDINATE_RIGHTS和ENLISTMENT_SUPERIOR_RIGHTS
ENLISTMENT_GENERIC_EXECUTE STANDARD_RIGHTS_EXECUTE、ENLISTMENT_RECOVER、ENLISTMENT_SUBORDINATE_RIGHTS 和 ENLISTMENT_SUPERIOR_RIGHTS
ENLISTMENT_ALL_ACCESS STANDARD_RIGHTS_REQUIRED、ENLISTMENT_GENERIC_READ、ENLISTMENT_GENERIC_WRITE和ENLISTMENT_GENERIC_EXECUTE

[in] ResourceManagerHandle

调用方 资源管理器对象的 句柄,该对象是通过上一次调用 ZwCreateResourceManagerZwOpenResourceManager 获取的

[in] TransactionHandle

事务对象的句柄,该 柄是通过对 ZwCreateTransaction 或 ZwOpenTransaction 的先前调用获取 。 KTM 将此事务添加到调用资源管理器正在处理的事务列表中。

[in, optional] ObjectAttributes

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

[in, optional] CreateOptions

登记选项标志。 下表包含唯一可用的标志。

CreateOptions 标志 含义
ENLISTMENT_SUPERIOR 调用方将登记为指定 事务的上级事务管理器
 

此参数是可选的,可以为零。

[in] NotificationMask

Ktmtypes.h 中定义的TRANSACTION_NOTIFY_XXX 值的按位 OR。 此掩码指定 KTM 发送给调用方 的交易通知 的类型。

[in, optional] EnlistmentKey

指向调用方定义的信息的指针,该信息唯一标识登记。 资源管理器在调用 ZwGetNotificationResourceManager 或 KTM 调用 ResourceManagerNotification 回调例程时接收此指针。 资源管理器可以通过调用 TmReferenceEnlistmentKeyTmDereferenceEnlistmentKey 来维护此密钥的引用计数。 此参数是可选的,可以为 NULL

返回值

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

返回代码 说明
STATUS_INVALID_HANDLE
对象句柄无效。
STATUS_INVALID_PARAMETER
CreateOptionsNotificationMask 参数的值无效,或者 KTM 找不到 TransactionHandle 参数指定的事务。
STATUS_INSUFFICIENT_RESOURCES
内存分配失败。
STATUS_TRANSACTIONMANAGER_NOT_ONLINE
登记失败,因为 KTM 或资源管理器未处于操作状态。
STATUS_TRANSACTION_NOT_ACTIVE
登记失败,因为 TransactionHandle 参数指定的事务未处于活动状态。
STATUS_TRANSACTION_SUPERIOR_EXISTS
调用方尝试注册为高级事务管理器,但 已存在高级事务管理器
STATUS_TM_VOLATILE
调用方尝试注册为高级事务管理器,但调用方的资源管理器对象是 可变 的,而关联的事务管理器对象不是可变的。
STATUS_ACCESS_DENIED
DesiredAccess 参数的值无效。
 

例程可能会返回其他 NTSTATUS 值

注解

资源管理器调用 ZwCreateEnlistment 在事务中登记。

非高级资源管理器必须在其访问掩码中包含 ENLISTMENT_SUBORDINATE_RIGHTS 标志。

高级事务管理器 必须在其访问掩码中包含 ENLISTMENT_SUPERIOR_RIGHTS 标志。 通常,高级事务管理器包含调用 ZwRollbackEnlistment 的代码,因此它还必须包含 ENLISTMENT_SUBORDINATE_RIGHTS 标志。

调用 ZwCreateEnlistment 的资源管理器最终必须调用 ZwClose 以关闭对象句柄。

资源管理器可以使用 EnlistmentKey 参数为每个登记分配唯一值,例如指向包含登记相关信息的数据结构的指针。 例如,如果资源管理器将登记对象的句柄存储在 结构中,则资源管理器可以执行以下操作:

  1. 调用 ZwGetNotificationResourceManager 以获取通知。
  2. TRANSACTION_NOTIFICATION 结构中获取登记键值。
  3. 使用登记键查找存储的登记对象句柄。
  4. 调用需要登记句柄作为输入的例程,例如 ZwCommitCompleteZwRollbackComplete
有关 ZwCreateEnlistment 的详细信息,请参阅创建资源管理器创建高级事务管理器

对于来自内核模式驱动程序的调用,Windows Native System Services 例程的 NtXxxZwXxx 版本在处理和解释输入参数的方式上的行为可能有所不同。 有关例程的 NtXxxZwXxx 版本之间的关系的详细信息,请参阅 使用本机系统服务例程的 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)

另请参阅

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

TRANSACTION_NOTIFICATION

使用本机系统服务例程的 Nt 和 Zw 版本

ZwClose

ZwCommitComplete

ZwCommitEnlistment

ZwCreateResourceManager

ZwCreateTransaction

ZwGetNotificationResourceManager

ZwOpenEnlistment

ZwOpenResourceManager

ZwOpenTransaction

ZwPrepareComplete

ZwPrepareEnlistment

ZwPrepareComplete

ZwPrepareEnlistment

ZwQueryInformationEnlistment

ZwReadOnlyEnlistment

ZwRecoverEnlistment

ZwRollbackComplete

ZwRollbackEnlistment

ZwSetInformationEnlistment

ZwSinglePhaseReject