ZwCreateEnlistment 函式 (wdm.h)

發行項
02/29/2024

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	執行非上層資源管理員執行的作業 (請參閱 ZwRollbackEnlistment、 ZwPreprepareComplete、 ZwPrepareComplete、 ZwCommitComplete、 ZwRollbackComplete、 ZwSinglePhaseReject、 ZwReadOnlyEnlistment) 。
ENLISTMENT_SUPERIOR_RIGHTS	執行上層交易管理員必須執行的作業 (請參閱 ZwPrepareEnlistment、 ZwPrepareEnlistment、 ZwCommitEnlistment) 。

或者，您可以指定下列一或多個 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

呼叫者資源管理員物件的句柄，由先前呼叫 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 中定義的TRANSACTION_NOTIFY_XXX 值的位 OR。此遮罩會指定 KTM 傳送給呼叫端的交易通知類型。

[in, optional] EnlistmentKey

可唯一識別登記之呼叫端定義資訊的指標。當資源管理員呼叫 ZwGetNotificationResourceManager 或 KTM 呼叫 ResourceManagerNotification 回呼例程時，資源管理員會收到此指標。資源管理員可以呼叫 TmReferenceEnlistmentKey 和 TmDereferenceEnlistmentKey來維護此索引鍵的參考計數。此參數是選擇性的，可以是 NULL。

傳回值

如果作業成功，ZwCreateEnlistment 會傳回STATUS_SUCCESS。否則，此例程可能會傳回下列其中一個值：

傳回碼	Description
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 和建立進階交易管理員。

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

規格需求

需求	值
最低支援的用戶端	適用於 Windows Vista 和更新版本的作業系統版本。
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 合規性規則	HwStorPortProhibitedDDIs (storport) 、 PowerIrpDDis (wdm)