FltSetTransactionContext 関数 (fltkernel.h)

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

FltSetTransactionContext ルーチンは、トランザクションにコンテキストを設定します。

構文

NTSTATUS FLTAPI FltSetTransactionContext(
  [in]            PFLT_INSTANCE             Instance,
  [in]            PKTRANSACTION             Transaction,
  [in]            FLT_SET_CONTEXT_OPERATION Operation,
  [in]            PFLT_CONTEXT              NewContext,
  [out, optional] PFLT_CONTEXT              *OldContext
);

パラメーター

[in] Instance

呼び出し元の不透明なインスタンスポインター。

[in] Transaction

コンテキストが設定されているトランザクションの不透明なトランザクションポインター。

[in] Operation

実行する操作の詳細を指定するフラグ。このパラメーターは、次のいずれかである必要があります。

フラグ	説明
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	Transaction パラメーターが指すトランザクションに対してコンテキストが既に設定されている場合、FltSetTransactionContext は NewContext パラメーターが指すコンテキストに置き換えられます。それ以外の場合は、 NewContext パラメーターによって指されるコンテキストが、 Transaction パラメーターによって指されるトランザクションのコンテキストとして設定されます。
FLT_SET_CONTEXT_KEEP_IF_EXISTS	Transaction パラメーターが指すトランザクションに対してコンテキストが既に設定されている場合、FltSetTransactionContext はSTATUS_FLT_CONTEXT_ALREADY_DEFINEDを返し、既存のコンテキストを置き換えたり、参照カウントをインクリメントしたりしません。コンテキストがまだ設定されていない場合、このルーチンは、NewContext パラメーターが指すコンテキストを Transaction パラメーターが指すトランザクションのコンテキストとして設定し、参照カウントをインクリメントします。

フラグ

説明

FLT_SET_CONTEXT_REPLACE_IF_EXISTS

Transaction パラメーターが指すトランザクションに対してコンテキストが既に設定されている場合、FltSetTransactionContext は NewContext パラメーターが指すコンテキストに置き換えられます。それ以外の場合は、 NewContext パラメーターによって指されるコンテキストが、 Transaction パラメーターによって指されるトランザクションのコンテキストとして設定されます。

FLT_SET_CONTEXT_KEEP_IF_EXISTS

Transaction パラメーターが指すトランザクションに対してコンテキストが既に設定されている場合、FltSetTransactionContext はSTATUS_FLT_CONTEXT_ALREADY_DEFINEDを返し、既存のコンテキストを置き換えたり、参照カウントをインクリメントしたりしません。コンテキストがまだ設定されていない場合、このルーチンは 、NewContext パラメーターが指すコンテキストを Transaction パラメーターが指すトランザクションのコンテキストとして設定し、参照カウントをインクリメントします。

[in] NewContext

トランザクションに設定する新しいコンテキストへのポインター。このパラメーターは必須であり、 NULL にすることはできません。

[out, optional] OldContext

既存のトランザクションコンテキストのアドレスを受け取る呼び出し元によって割り当てられた変数へのポインター (既に設定されている場合)。このパラメーターは省略可能であり、 NULL にすることができます。このパラメーターの詳細については、次の「解説」セクションを参照してください。

戻り値

FltSetTransactionContext は 、次のいずれかのSTATUS_SUCCESSまたは適切な NTSTATUS 値を返します。

リターンコード	説明
STATUS_FLT_CONTEXT_ALREADY_DEFINED	Operation パラメーターにFLT_SET_CONTEXT_KEEP_IF_EXISTSが指定されている場合、このエラーコードはコンテキストがトランザクションに既にアタッチされていることを示します。特定のミニフィルタードライバーのトランザクションにアタッチできるコンテキストは 1 つだけです。
STATUS_FLT_CONTEXT_ALREADY_LINKED	NewContext パラメーターが指すコンテキストは、オブジェクトに既にリンクされています。言い換えると、このエラーコードは、FltSetXxxコンテキストルーチンの以前の呼び出しが成功したため、NewContext が既に使用されていることを示します。
STATUS_FLT_DELETING_OBJECT
Instance パラメーターで指定されたインスタンスが破棄されています。これはエラーコードです。
STATUS_INVALID_PARAMETER	無効なパラメーターが渡されました。たとえば、 NewContext パラメーターが有効なトランザクションコンテキストを指していないか、 Operation パラメーターに無効な値が指定されています。これはエラーコードです。

注釈

コンテキストの詳細については、「ミニフィルターコンテキストについて」を参照してください。

ミニフィルタードライバーは 、FltSetTransactionContext を呼び出して、トランザクションにコンテキストをアタッチするか、既存のトランザクションコンテキストを削除または置換します。ミニフィルタードライバーは、特定のトランザクションに 1 つのコンテキストのみをアタッチできます。

参照カウント

FltSetTransactionContext が成功した場合:

NewContext の参照カウントがインクリメントされます。 NewContext が不要になった場合、ミニフィルターは FltReleaseContext を呼び出して参照カウントをデクリメントする必要があります。

FltSetTransactionContext が失敗した場合は、それ以外の場合:

NewContext の参照カウントは変更されません。
OldContext が NULL ではなく、NULL_CONTEXTを指していない場合、OldContext は現在トランザクションに関連付けられているコンテキストへの参照ポインターです。 FltSetTransactionContext を呼び出すフィルターは、コンテキストポインターが不要になった場合にも、OldContext に対して FltReleaseContext を呼び出す必要があります。

成功に関係なく:

FltSetTransactionContext を呼び出すフィルターは、FltAllocateContext によってインクリメントされた NewContext オブジェクトの参照カウントをデクリメントするために FltReleaseContext を呼び出す必要があります。

詳細については、「コンテキストの参照」を参照してください。

その他のコンテキスト操作

詳細については、「コンテキストの設定」および「コンテキストの解放」を参照してください。

新しいコンテキストを割り当てるには、 FltAllocateContext を呼び出します。

トランザクションコンテキストを取得するには、 FltGetTransactionContext を呼び出します。

トランザクションコンテキストを削除するには、 FltDeleteTransactionContext または FltDeleteContext を呼び出します。

要件

要件	値
サポートされている最小のクライアント	Windows Vista 以降のオペレーティングシステムで使用可能でサポートされています。
対象プラットフォーム	ユニバーサル
Header	fltkernel.h (Fltkernel.h を含む)
Library	FltMgr.lib
[DLL]	FltMgr.sys
IRQL	<= APC_LEVEL。