NtCreateEnlistment 函式（wdm.h）

發行項
02/07/2025

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

呼叫端 Resource Manager 物件的句柄，先前呼叫 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。否則，此例程可能會傳回下列其中一個值：

傳回碼	描述
STATUS_INVALID_HANDLE	物件句柄無效。
STATUS_INVALID_PARAMETER	CreateOptions 或 NotificationMask 參數的值無效，或 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 參數將唯一值指派給每個登記，例如數據結構的指標，其中包含登記的相關信息。例如，如果資源管理員將登記物件的句柄儲存在結構中，則資源管理員可以執行下列動作：

呼叫 ZwGetNotificationResourceManager 以取得通知。
從 TRANSACTION_NOTIFICATION 結構取得登記索引鍵值。
使用登記索引鍵來尋找儲存的登記物件句柄。
呼叫需要登記句柄做為輸入的例程，例如 ZwCommitComplete 或 ZwRollbackComplete。

如需 ZwCreateEnlistment的詳細資訊，請參閱建立 Resource Manager 和建立進階交易管理員。

對於內核模式驅動程式的呼叫，NtXxx 和 ZwXxx 版本的 Windows 原生系統服務例程，在處理和解譯輸入參數的方式上可能會有不同的行為。如需 nt NtXxx 與 ZwXxx 例程之間關聯性的詳細資訊，請參閱使用 Nt 和 Zw 版本的原生系統服務例程。

要求

要求	價值
最低支援的用戶端	適用於 Windows Vista 和更新版本的作系統版本。
目標平臺	普遍
標頭	wdm.h （包括 Wdm.h、Ntddk.h、Ntifs.h）
連結庫	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 合規性規則	HwStorPortProhibitedDDIs， PowerIrpDDis