NtCreateEnlistment 函数 （wdm.h）
ZwCreateEnlistment 例程为事务创建新的 登记对象。
语法
__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateEnlistment(
[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 | 执行非高级资源管理器执行的作（请参阅 ZwRollbackEnlistment、ZwPrepareComplete、ZwPrepareComplete、ZwCommitComplete、ZwRollbackComplete、ZwSinglePhaseReject、ZwReadOnlyEnlistment）。 |
| ENLISTMENT_SUPERIOR_RIGHTS | 执行 高级事务管理器 必须执行的作（请参阅 ZwPrepareEnlistment、ZwPrepareEnlistment、ZwCommitEnlistment）。 |
或者，可以指定以下一个或多个 ACCESS_MASK 位图。 这些位图将上表中的标志与STANDARD_RIGHTS_XXX 标志组合在 ACCESS_MASK 参考页上。 还可以将这些位图与上表中的其他标志组合在一起。 下表显示了位图如何对应于特定的访问权限。
| 通用访问权限 | 特定访问权限集 |
|---|---|
| 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
调用方 资源管理器对象 的句柄，该对象是由上一次调用 ZwCreateResourceManager 或 ZwOpenResourceManager获取的。
[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 中定义的按位 OR TRANSACTION_NOTIFY_XXX 值。 此掩码指定 KTM 发送到调用方 事务通知的类型。
[in, optional] EnlistmentKey
指向唯一标识登记的调用方定义信息的指针。 当资源管理器调用 ZwGetNotificationResourceManager 或 KTM 调用 ResourceManagerNotification 回调例程时，该指针将接收此指针。 资源管理器可以通过调用 TmReferenceEnlistmentKey 和 TmDereferenceEnlistmentKey来维护此密钥的引用计数。 此参数是可选的，可以 NULL。
返回值
如果作成功，ZwCreateEnlistment 将返回STATUS_SUCCESS。 否则，此例程可能会返回以下值之一：
| 返回代码 | 描述 |
|---|---|
|
对象句柄无效。 |
|
CreateOptions 或 NotificationMask 参数的值无效，或者 KTM 找不到 TransactionHandle 参数指定的事务。 |
|
内存分配失败。 |
|
登记失败，因为 KTM 或资源管理器未处于作状态。 |
|
登记失败，因为 TransactionHandle 参数指定的事务未处于活动状态。 |
|
调用方尝试注册为高级事务管理器，但已存在 高级事务管理器。 |
|
调用方正尝试注册为高级事务管理器，但调用方的资源管理器对象 易失性，而关联的事务管理器对象不可变。 |
|
DesiredAccess 参数的值无效。 |
例程可能会 返回其他NTSTATUS 值。
言论
资源管理器调用 ZwCreateEnlistment 以在事务中登记。
不上级的资源管理器必须在其访问掩码中包含ENLISTMENT_SUBORDINATE_RIGHTS标志。
高级事务管理器 必须在访问掩码中包含ENLISTMENT_SUPERIOR_RIGHTS标志。 通常，高级事务管理器包含调用 ZwRollbackEnlistment的代码，因此还必须包含ENLISTMENT_SUBORDINATE_RIGHTS标志。
调用 ZwCreateEnlistment 的资源管理器最终必须调用 ZwClose 才能关闭对象句柄。
资源管理器可以使用 EnlistmentKey 参数为每个登记分配唯一值，例如指向包含登记信息的数据结构的指针。 例如，如果资源管理器将登记对象的句柄存储在结构中，则资源管理器可以执行以下作：
- 调用 ZwGetNotificationResourceManager 以获取通知。
- 从 TRANSACTION_NOTIFICATION 结构中获取登记键值。
- 使用登记键查找存储的登记对象句柄。
- 调用需要登记句柄的例程，例如 ZwCommitComplete 或 ZwRollbackComplete。
对于内核模式驱动程序的调用，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 |