ZwCreateEnlistment 関数 (wdm.h)

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

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、ZwPrePrepareEnlistment、ZwCommitEnlistment を参照)。

または、次の ACCESS_MASK ビットマップの 1 つ以上を指定することもできます。これらのビットマップは、前の表のフラグと、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	呼び出し元は、指定されたトランザクションの上位のトランザクションマネージャーとして参加しています。

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

[in] NotificationMask

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

[in, optional] EnlistmentKey

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

戻り値

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

リターンコード	説明
STATUS_INVALID_HANDLE	オブジェクトハンドルが無効です。
STATUS_INVALID_PARAMETER	CreateOptions または NotificationMask パラメーターの値が無効であるか、または TRANSACTIONHandle パラメーターで指定されたトランザクションが KTM で見つかりませんでした。
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 バージョン間の関係の詳細については、「Using Nt and Zw Versions of the Native System Services Routines」を参照してください。

要件

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