tmCreateEnlistment 函式 (wdm.h)

發行項
02/27/2024

TmCreateEnlistment 例程會為交易建立新的登記物件。

語法

NTSTATUS TmCreateEnlistment(
  [out]          PHANDLE            EnlistmentHandle,
  [in]           KPROCESSOR_MODE    PreviousMode,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           POBJECT_ATTRIBUTES ObjectAttributes,
  [in]           PRKRESOURCEMANAGER ResourceManager,
  [in]           PKTRANSACTION      Transaction,
  [in, optional] ULONG              CreateOptions,
  [in]           NOTIFICATION_MASK  NotificationMask,
  [in, optional] PVOID              EnlistmentKey
);

參數

[out] EnlistmentHandle

呼叫端配置變數的指標，如果 呼叫TmCreateEnlistment 成功，就會接收新登記物件的句柄。

[in] PreviousMode

將使用登記句柄來存取登記對象的進程處理器模式。此值必須是 UserMode 或 KernelMode。

[in] DesiredAccess

ACCESS_MASK值，指定呼叫端對登記物件的要求存取權。如需此參數的詳細資訊，請參閱 ZwCreateEnlistment的 DesiredAccess 參數描述。

[in] ObjectAttributes

指定物件名稱和其他屬性之OBJECT_ATTRIBUTES 結構的指標。使用 InitializeObjectAttributes 例程來初始化這個結構。如果呼叫端未在系統線程內容中執行，它必須在呼叫 InitializeObjectAttributes 時設定OBJ_KERNEL_HANDLE屬性。這個參數是選擇性的，而且可以是 NULL。

[in] ResourceManager

Resource Manager 物件的指標。若要取得此指標，您的元件必須呼叫 ObReferenceObjectByHandle ，並提供先前呼叫 ZwCreateResourceManager 或 ZwOpenResourceManager 的物件句柄。

[in] Transaction

交易物件的指標。若要取得此指標，您的元件必須呼叫 ObReferenceObjectByHandle ，並提供先前呼叫 ZwCreateTransaction 或 ZwOpenTransaction 的物件句柄。 KTM 會將此交易新增至呼叫資源管理員正在處理的交易清單。

[in, optional] CreateOptions

登記選項旗標。下表包含唯一可用的旗標。

CreateOptions 旗標	意義
ENLISTMENT_SUPERIOR	呼叫端會登記為指定交易的上層交易管理員。

這個參數是選擇性的，而且可以是零。

[in] NotificationMask

Ktmtypes.h 中定義的TRANSACTION_NOTIFY_XXX 值的位 OR。此遮罩值會指定 KTM 傳送給呼叫端的交易通知類型。

[in, optional] EnlistmentKey

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

傳回值

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

傳回碼	Description
STATUS_INVALID_PARAMETER	CreateOptions 或 NotificationMask 參數的值無效，或 KTM 找不到 Transaction 參數指定的交易。
STATUS_INSUFFICIENT_RESOURCES	記憶體配置失敗。
STATUS_TRANSACTIONMANAGER_NOT_ONLINE	登記失敗，因為 KTM 或資源管理員未處於操作狀態。
STATUS_TRANSACTION_NOT_ACTIVE	登記失敗，因為 Transaction 參數指定的交易不是作用中。
STATUS_TRANSACTION_SUPERIOR_EXISTS	呼叫端嘗試註冊為上層交易管理員，但已存在上層登記。
STATUS_TM_VOLATILE	呼叫端正嘗試註冊為上層交易管理員，但呼叫端的資源管理員對象在相關聯的交易管理員物件不變動時是變動的。
STATUS_ACCESS_DENIED	DesiredAccess 參數的值無效。

例程可能會傳回其他 NTSTATUS值。

備註

TmCreateEnlistment 例程是以指標為基礎的 ZwCreateEnlistment 例程版本。

如需何時使用 KTM 的 TmXxx 例程而非 Zw Xxx 例程的資訊，請參閱使用 TmXxx例程。

規格需求

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