TmCreateEnlistment 関数 (wdm.h)

[アーティクル]
08/08/2023

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

リソースマネージャーオブジェクトへのポインター。このポインターを取得するには、コンポーネントで ObReferenceObjectByHandle を呼び出し、前に ZwCreateResourceManager または ZwOpenResourceManager を呼び出したオブジェクトハンドルを指定する必要があります。

[in] Transaction

トランザクションオブジェクトへのポインター。このポインターを取得するには、コンポーネントで ObReferenceObjectByHandle を呼び出し、前に ZwCreateTransaction または ZwOpenTransaction を呼び出したオブジェクトハンドルを指定する必要があります。 KTM は、呼び出し元のリソースマネージャーが処理しているトランザクションの一覧にこのトランザクションを追加します。

[in, optional] CreateOptions

参加オプションフラグ。次の表に、使用可能なフラグのみを示します。

CreateOptions フラグ	意味
ENLISTMENT_SUPERIOR	呼び出し元は、指定されたトランザクションの上位のトランザクションマネージャーとして参加しています。

このパラメーターは省略可能であり、0 にすることができます。

[in] NotificationMask

Ktmtypes.h で定義されているTRANSACTION_NOTIFY_XXX 値のビットごとの OR。このマスク値は、KTM が呼び出し元に送信するトランザクション通知の種類を指定します。

[in, optional] EnlistmentKey

参加リストを一意に識別する呼び出し元定義情報へのポインター。リソースマネージャーは、 ZwGetNotificationResourceManager を呼び出すとき、または KTM が ResourceManagerNotification コールバックルーチンを呼び出すときに、このポインターを受け取ります。リソースマネージャーは、 TmReferenceEnlistmentKey と TmDereferenceEnlistmentKey を呼び出すことによって、このキーの参照カウントを維持できます。このパラメーターは省略可能であり、 NULL にすることができます。

戻り値

TmCreateEnlistment は、操作が成功した場合にSTATUS_SUCCESSを返します。それ以外の場合、このルーチンは次のいずれかの値を返す可能性があります。

リターンコード	説明
STATUS_INVALID_PARAMETER	CreateOptions パラメーターまたは NotificationMask パラメーターの値が無効であるか、または TRANSACTION パラメーターで指定されたトランザクションが KTM で見つかりませんでした。
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 ルーチンのポインターベースのバージョンです。

Zw Xxx ルーチンの代わりに KTM の TmXxx ルーチンを使用する場合の詳細については、「TmXxx ルーチンの使用」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows Vista 以降のオペレーティングシステムバージョンで使用できます。
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL