FltCbdqInitialize 函式 (fltkernel.h)

發行項
02/26/2024

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
      );

卡里克

迷你篩選驅動程式取消安全回呼數據佇列的指標。此佇列必須透過呼叫 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
      );

卡里克

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

Cbd

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

[in] CbdqPeekNextIo

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

卡里克

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

Cbd

回呼數據結構的指標，標記佇列中的位置，以開始搜尋 與 PeekContext 的相符專案。如果其為 NULL，搜尋就會從佇列的前端開始。

PeekContext

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

[in] CbdqAcquire

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

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

卡里克

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

Irql

接收目前 IRQL 之系統提供之變數的指標。相同的變數會傳遞至對應的 「對應的」的「快取」版本 例程。

[in] CbdqRelease

呼叫端提供的釋放佇列鎖定回呼例程的指標。篩選管理員會呼叫此例程，以釋放其透過呼叫對應 之「AzureQAcquire 」例程取得的鎖定。此例程宣告如下：

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

卡里克

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

Irql

接收目前 IRQL 做為 Irql 參數的相同系統提供的變數，該變數會接收對應至對應的 回應的回應式的回應。Acquire 例程。

[in] CbdqCompleteCanceledIo

呼叫端提供的取消例程的指標。篩選管理員會呼叫此例程，以向迷你篩選驅動程式發出訊號，以完成已取消的 I/O 作業。此例程宣告如下：

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

卡里克

迷你篩選驅動程式取消安全回呼數據佇列的指標。此佇列必須透過呼叫 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 驅動程式不會在其 其「Azure AzureInsertIo」、 「建議程式」、「建議程式」和 「AzureqPeekNextIo 例程」內實作任何鎖定。

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

迷你篩選驅動程式不會直接操作佇列。相反地，它會呼叫 FltCbdqInsertIo、 FltCbdqRemoveIo 和 FltCbdqRemoveNextIo 來新增或移除回呼數據結構。這些例程會接著呼叫 Minifilter 驅動程式提供給 FltCbdqInitialize 的回呼函式。

迷你篩選驅動程式應該實作佇列例程，如下所示。

卡里克例程	實作
其為一個位置	將指定的回呼數據結構插入佇列中。
儲存資源	從佇列中移除指定的回呼數據結構。
在#2012年1月	此例程應該允許系統迴圈查看佇列中具有相符 PeekContext 的回呼數據結構。 Cbd = ( (的 ( (的 (，PeekContext) 應該會傳回佇列中的第一個相符專案，而在佇列中指定回呼數據結構之後，) (應傳回下一個相符專案。迷你篩選驅動程式會完全定義 PeekContext 的意義，並在回呼數據結構符合 PeekContext 值時定義。
卡里克文	此例程應該鎖定佇列，讓其他線程無法存取佇列。迷你篩選驅動程式可以使用任何鎖定機制來鎖定佇列。如果迷你篩選驅動程式使用 KeAcquireSpinLock 例程，迷你篩選驅動程式可以使用例程的 Irql 參數所指向的記憶體位置來儲存 IRQL。否則，迷你篩選驅動程式可以忽略該參數。
此為一元	此例程應該會解除鎖定由其所建立的佇列。如果迷你篩選驅動程式使用微調鎖定，並在其 Irql 參數中傳回一個 IrQL 值，則系統會在一個參數的 Irql 參數中傳遞該值，而該值會傳回至一個類型為一文。迷你篩選驅動程式可以使用 IRQL 來解除鎖定微調鎖定，方法是呼叫 KeReleaseSpinLock。否則，迷你篩選驅動程式可以忽略 Irql 參數。
其類型為一般	此例程應該會完成已取消的 I/O 作業。一般而言，迷你篩選驅動程式只能呼叫 FltCompletePendedPreOperation (Data、FLT_PREOP_COMPLETE、 NULL) 。 Minifilter 驅動程式不需要取消佇列回呼數據結構 -- 篩選管理員會在呼叫此佇列的一個個的回應器RemoveIo 之前，先自動呼叫佇列的一個類型。