FltCbdqInitialize 函式（fltkernel.h）

發行項
02/06/2025

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

呼叫端提供的插入回呼例程指標。篩選管理員會呼叫這個例程，將指定的回呼數據結構插入佇列中。此例程宣告如下：

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

Cbdq

迷你篩選驅動程式取消安全回呼數據佇列的指標。呼叫 fltCbdqInitialize ，此佇列必須已初始化。

Cbd

要插入佇列之回呼數據結構的指標。

InsertContext

傳遞為 InsertContext 參數的內容資訊指標，FltCbdqInsertIo。

[in] CbdqRemoveIo

呼叫端提供的移除回呼例程的指標。篩選管理員會呼叫此例程，以從佇列中移除指定的回呼數據結構。此例程宣告如下：

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

Cbdq

迷你篩選驅動程式取消安全回呼數據佇列的指標。呼叫 fltCbdqInitialize ，此佇列必須已初始化。

Cbd

要從佇列中移除之回呼數據結構的指標。

[in] CbdqPeekNextIo

呼叫端提供的查看回呼例程的指標。篩選管理員會呼叫此函式，以取得佇列中 PeekContext 下一個 I/O 作業的指標;或者，如果 CbdNULL，以取得佇列中第一個相符 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

迷你篩選驅動程式取消安全回呼數據佇列的指標。呼叫 fltCbdqInitialize ，此佇列必須已初始化。

Cbd

回呼數據結構的指標，標記佇列中的位置，以開始搜尋符合專案，PeekContext。如果 CbdNULL，則搜尋會從佇列的前端開始。

PeekContext

傳遞為 PeekContext 參數至 FltCbdqRemoveNextIo的內容資訊指標。

[in] CbdqAcquire

呼叫端提供的取得佇列鎖定回呼例程的指標。篩選管理員會呼叫此例程，以取得佇列上的鎖定，然後再嘗試插入或移除佇列中的專案。此例程宣告如下：

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

Cbdq

迷你篩選驅動程式取消安全回呼數據佇列的指標。呼叫 fltCbdqInitialize ，此佇列必須已初始化。

Irql

接收目前 IRQL 之系統提供的變數指標。相同的變數會傳遞至對應的 CbdqRelease 例程。

[in] CbdqRelease

呼叫端提供的發行佇列鎖定回呼例程的指標。篩選管理員會呼叫此例程，藉由呼叫對應的 CbdqAcquire 例程來釋放其取得的鎖定。此例程宣告如下：

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

Cbdq

迷你篩選驅動程式取消安全回呼數據佇列的指標。呼叫 fltCbdqInitialize ，此佇列必須已初始化。

Irql

接收目前 IRQL 做為 Irql 參數的相同系統提供變數，CbdqAcquire 例程。

[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

迷你篩選驅動程式取消安全回呼數據佇列的指標。呼叫 fltCbdqInitialize ，此佇列必須已初始化。

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所提供的一組分派例程，與小型篩選驅動程式的佇列實作互動。

系統會視需要自動鎖定和解除鎖定佇列。 Minifilter 驅動程式不會在其 CbdqInsertIo內實作任何鎖定、CbdqRemoveIo，以及 CbdqPeekNextIo 例程。

小型篩選驅動程式可以使用任何作系統的同步處理基本類型作為其 CbdqAcquire 中的鎖定機制，以及 CbdqRelease 例程，例如微調鎖定、mutex 物件或資源變數。請注意，如果迷你篩選驅動程式使用微調鎖定，而不是 mutex 或資源來保護佇列，它可以在 IRQL <= DISPATCH_LEVEL 呼叫 FltCbdqXxx 例程。如果使用 mutex 或資源，小型篩選驅動程式必須在 IRQL <= APC_LEVEL執行，但 FltCbdqInitialize除外。

迷你篩選驅動程式不會直接作佇列。相反地，它會呼叫 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。