FltCbdqInitialize 関数 (fltkernel.h)

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

FltCbdqInitialize は、ミニフィルタードライバーのコールバックデータキューディスパッチテーブルを初期化します。

構文

NTSTATUS FLTAPI FltCbdqInitialize(
  [in]      PFLT_INSTANCE                                 Instance,
  [in, out] PFLT_CALLBACK_DATA_QUEUE                      Cbdq,
  [in]      PFLT_CALLBACK_DATA_QUEUE_INSERT_IO            CbdqInsertIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_REMOVE_IO            CbdqRemoveIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_PEEK_NEXT_IO         CbdqPeekNextIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_ACQUIRE              CbdqAcquire,
  [in]      PFLT_CALLBACK_DATA_QUEUE_RELEASE              CbdqRelease,
  [in]      PFLT_CALLBACK_DATA_QUEUE_COMPLETE_CANCELED_IO CbdqCompleteCanceledIo
);

パラメーター

[in] Instance

コールバックデータキューを初期化するインスタンスの不透明なインスタンスポインター。

[in, out] Cbdq

ミニフィルタードライバーによって割り当てられたコールバックデータキューへのポインター。

[in] CbdqInsertIo

呼び出し元が指定した挿入コールバックルーチンへのポインター。 Filter Manager は、このルーチンを呼び出して、指定されたコールバックデータ構造をキューに挿入します。このルーチンは、次のように宣言されています。

typedef NTSTATUS
(*PFLT_CALLBACK_DATA_QUEUE_INSERT_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_ PFLT_CALLBACK_DATA Cbd,
      _In_opt_ PVOID InsertContext
      );

Cbdq

ミニフィルタードライバーの cancel-safe コールバックデータキューへのポインター。このキューは 、FltCbdqInitialize を呼び出して初期化されている必要があります。

Cbd

キューに挿入されるコールバックデータ構造へのポインター。

InsertContext

InsertContext パラメーターとして FltCbdqInsertIo に渡されたコンテキスト情報ポインター。

[in] CbdqRemoveIo

呼び出し元から提供された削除コールバックルーチンへのポインター。 Filter Manager は、このルーチンを呼び出して、指定されたコールバックデータ構造をキューから削除します。このルーチンは、次のように宣言されています。

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_REMOVE_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_ PFLT_CALLBACK_DATA Cbd
      );

Cbdq

Cbd

キューから削除するコールバックデータ構造へのポインター。

[in] CbdqPeekNextIo

呼び出し元から提供されたピークコールバックルーチンへのポインター。 Filter Manager は、この関数を呼び出して、キュー内の PeekContext に一致する次の I/O 操作へのポインターを取得します。または、 Cbd が NULL の場合は、キュー内の最初に一致する I/O 操作へのポインターを取得します。ミニフィルタードライバーは、 PeekContext の意味を完全に定義し、I/O 操作が特定の PeekContext と一致するタイミングを定義します。このルーチンは、次のように宣言されています。

typedef PFLT_CALLBACK_DATA
(*PFLT_CALLBACK_DATA_QUEUE_PEEK_NEXT_IO)(
      _In_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_opt_ PFLT_CALLBACK_DATA Cbd,
      _In_opt_ PVOID PeekContext
      );

Cbdq

Cbd

PeekContext との一致の検索を開始するキュー内の位置を示すコールバックデータ構造へのポインター。 Cbd が NULL の場合、検索はキューの先頭から開始されます。

PeekContext

PeekContext パラメーターとして FltCbdqRemoveNextIo に渡されたコンテキスト情報ポインター。

[in] CbdqAcquire

呼び出し元から提供された取得キューロックコールバックルーチンへのポインター。フィルターマネージャーは、このルーチンを呼び出して、キューに対するロックを取得してから、キューに項目を挿入または削除します。このルーチンは、次のように宣言されています。

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_ACQUIRE)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _Out_opt_ PKIRQL Irql
      );

Cbdq

Irql

現在の IRQL を受け取るシステム提供の変数へのポインター。同じ変数が、対応する CbdqRelease ルーチンに渡されます。

[in] CbdqRelease

呼び出し元が指定したリリースキューロックコールバックルーチンへのポインター。フィルターマネージャーは、このルーチンを呼び出して、対応する CbdqAcquire ルーチンを呼び出して取得したロックを解放します。このルーチンは、次のように宣言されています。

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_RELEASE)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_opt_ KIRQL Irql
      );

Cbdq

Irql

現在の IRQL を、対応する CbdqAcquire ルーチンに Irql パラメーターとして受け取ったのと同じシステム提供の変数。

[in] CbdqCompleteCanceledIo

呼び出し元から提供されたキャンセルルーチンへのポインター。フィルターマネージャーは、このルーチンを呼び出して、取り消された I/O 操作を完了するようにミニフィルタードライバーに通知します。このルーチンは、次のように宣言されています。

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_COMPLETE_CANCELED_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _Inout_ PFLT_CALLBACK_DATA Cbd
      );

Cbdq

Cbd

取り消された I/O 操作のコールバックデータ構造へのポインター。

戻り値

FltCbdqInitialize は、STATUS_SUCCESSまたは適切な NTSTATUS 値を返します。

注釈

新しく初期化されたコールバックデータキューは有効な状態です。つまり、コールバックデータ構造項目をキューに挿入できます。キューを無効にするには、 FltCbdqDisable を呼び出し、 FltCbdqEnable を呼び出して再度有効にします。

ミニフィルタードライバーは 、FltCbdqXxx ルーチンを使用して、IRP ベースの I/O 操作のコールバックデータキューを実装できます。これらのルーチンを使用することで、ミニフィルタードライバーはキューをキャンセルセーフにすることができます。システムは、ミニフィルタードライバーの I/O 取り消しを透過的に処理します。

FltCbdqXxx ルーチンは、IRP ベースの I/O 操作にのみ使用できます。指定されたコールバックデータ構造が IRP ベースの I/O 操作を表すかどうかを確認するには、 FLT_IS_IRP_OPERATION マクロを使用します。

ミニフィルタードライバーは、キューに対して任意の内部実装を使用できます。フィルターマネージャーは、 FltCbdqInitialize によって提供されるディスパッチルーチンのセットを介してのみミニフィルタードライバーのキューの実装と対話します。

システムは、必要に応じてキューを自動的にロックおよびロック解除します。ミニフィルタードライバーは、 CbdqInsertIo、 CbdqRemoveIo、 および CbdqPeekNextIo ルーチン内にロックを実装しません。

ミニフィルタードライバーは、スピンロック、ミューテックスオブジェクト、リソース変数など、CbdqAcquire ルーチンと CbdqRelease ルーチンのロックメカニズムとして、オペレーティングシステムの同期プリミティブのいずれかを使用できます。ミニフィルタードライバーがミューテックスまたはリソースではなくスピンロックを使用してキューを保護する場合、IRQL <= DISPATCH_LEVEL で FltCbdqXxx ルーチンを呼び出すことができることに注意してください。ミューテックスまたはリソースを使用する場合、ミニフィルタードライバーは、FltCbdqInitialize を除くこれらのルーチンのいずれかを呼び出すときに、IRQL <= APC_LEVELで実行されている必要があります。

ミニフィルタードライバーは、キューを直接操作しません。代わりに、 FltCbdqInsertIo、 FltCbdqRemoveIo、および FltCbdqRemoveNextIo を呼び出して、コールバックデータ構造を追加または削除します。これらのルーチンは、ミニフィルタードライバーが FltCbdqInitialize に提供したコールバック関数を呼び出します。

ミニフィルタードライバーは、次のようにキュールーチンを実装する必要があります。

Cbdq ルーチン	実装
CbdqInsertIo	指定したコールバックデータ構造をキューに挿入します。
CbdqRemoveIo	指定したコールバックデータ構造をキューから削除します。
CbdqPeekNextIo	このルーチンを使用すると、キュー内の PeekContext に一致するコールバックデータ構造をシステムがループ処理できるようになります。 Cbd = CbdqPeekNextIo(Cbdq, NULL, PeekContext) はキュー内の最初の一致するエントリを返す必要があり、 CbdqPeekNextIo(Cbdq, Cbd, PeekContext) は、キュー内の指定されたコールバックデータ構造の後に次の一致するエントリを返す必要があります。ミニフィルタードライバーは、 PeekContext の意味を完全に定義し、コールバックデータ構造が PeekContext 値と一致するタイミングを定義します。
CbdqAcquire	このルーチンは、他のスレッドがキューにアクセスできないようにキューをロックする必要があります。ミニフィルタードライバーは、任意のロックメカニズムを使用してキューをロックできます。ミニフィルタードライバーが KeAcquireSpinLock ルーチンを使用する場合、ミニフィルタードライバーは、ルーチンの Irql パラメーターによって指されるメモリ位置を使用して IRQL を格納できます。それ以外の場合、ミニフィルタードライバーはそのパラメーターを無視できます。
CbdqRelease	このルーチンは、 CbdqAcquire によって作成されたキューのロックを解除する必要があります。ミニフィルタードライバーがスピンロックを使用し、CbdqAcquire の Irql パラメーターで IRQL 値を返した場合、システムはその値を CbdqRelease の Irql パラメーターに渡します。ミニフィルタードライバーは、IRQL を使用して、KeReleaseSpinLock を呼び出してスピンロックのロックを解除できます。それ以外の場合、ミニフィルタードライバーは Irql パラメーターを無視できます。
CbdqCompleteCanceledIo	このルーチンは、取り消された I/O 操作を完了する必要があります。通常、ミニフィルタードライバーは FltCompletePendedPreOperation(Data, FLT_PREOP_COMPLETE, NULL) を呼び出すことができます。ミニフィルタードライバーでは、コールバックデータ構造をデキューする必要はありません。フィルターマネージャーは、CbdqCompleteCanceledIo を呼び出す前に、キューの CbdqRemoveIo を自動的に呼び出します。