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 | 執行非上層資源管理員執行的作業 (請參閱 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 |
|---|---|
|
物件句柄無效。 |
|
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。
對於核心模式驅動程式的呼叫，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) |