Funzione FltCbdqInitialize (fltkernel.h)

Articolo
08/07/2023

FltCbdqInitialize inizializza una tabella di invio dei dati di callback del driver minifilter.

Sintassi

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

Parametri

[in] Instance

Puntatore istanza opaca per l'istanza la cui coda di dati di callback deve essere inizializzata.

[in, out] Cbdq

Puntatore a una coda di dati di callback allocata dal driver minifilter.

[in] CbdqInsertIo

Puntatore a una routine di callback fornita dal chiamante. Gestione filtri chiama questa routine per inserire la struttura di dati di callback specificata nella coda. Questa routine viene dichiarata come segue:

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

Cbdq

Puntatore alla coda dei dati di callback annulla-sicura del driver minifilter. Questa coda deve essere stata inizializzata chiamando FltCbdqInitialize.

Cbd

Puntatore alla struttura dei dati di callback da inserire nella coda.

InsertContext

Puntatore informazioni di contesto passato come parametro InsertContext a FltCbdqInsertIo.

[in] CbdqRemoveIo

Puntatore a una routine di callback fornita dal chiamante. Gestione filtri chiama questa routine per rimuovere la struttura dei dati di callback specificata dalla coda. Questa routine viene dichiarata come segue:

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

Cbdq

Puntatore alla coda dei dati di callback annulla-sicura del driver minifilter. Questa coda deve essere stata inizializzata chiamando FltCbdqInitialize.

Cbd

Puntatore alla struttura dei dati di callback da rimuovere dalla coda.

[in] CbdqPeekNextIo

Puntatore a una routine di callback fornita dal chiamante. Gestione filtri chiama questa funzione per ottenere un puntatore alla successiva operazione di I/O corrispondente a PeekContext nella coda; oppure, se Cbd è NULL, per ottenere un puntatore alla prima operazione di I/O corrispondente nella coda. Il driver minifilter definisce interamente il significato di PeekContext e definisce quando un'operazione di I/O corrisponde a un determinato PeekContext. Questa routine viene dichiarata come segue:

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

Puntatore alla coda dei dati di callback annulla-sicura del driver minifilter. Questa coda deve essere stata inizializzata chiamando FltCbdqInitialize.

Cbd

Puntatore alla struttura dei dati di callback che contrassegna la posizione nella coda per iniziare a cercare una corrispondenza con PeekContext. Se Cbd è NULL, la ricerca inizia alla testa della coda.

PeekContext

Puntatore alle informazioni di contesto passato come parametro PeekContext a FltCbdqRemoveNextIo.

[in] CbdqAcquire

Puntatore a una routine di callback di blocco della coda fornita dal chiamante. Gestione filtri chiama questa routine per acquisire il blocco nella coda prima di tentare di inserire o rimuovere un elemento dalla coda. Questa routine viene dichiarata come segue:

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

Cbdq

Puntatore alla coda dei dati di callback annulla-sicura del driver minifilter. Questa coda deve essere stata inizializzata chiamando FltCbdqInitialize.

Irql

Puntatore a una variabile fornita dal sistema che riceve l'oggetto IRQL corrente. La stessa variabile viene passata alla routine CbdqRelease corrispondente.

[in] CbdqRelease

Puntatore a una routine di callback di blocco della coda di rilascio fornita dal chiamante. Gestione filtri chiama questa routine per rilasciare il blocco ottenuto chiamando la routine cbdqAcquire corrispondente. Questa routine viene dichiarata come segue:

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

Cbdq

Puntatore alla coda dei dati di callback annulla-sicura del driver minifilter. Questa coda deve essere stata inizializzata chiamando FltCbdqInitialize.

Irql

La stessa variabile fornita dal sistema che ha ricevuto l'IRQL corrente come parametro Irql alla routine cbdqAcquire corrispondente.

[in] CbdqCompleteCanceledIo

Puntatore a una routine di annullamento fornita dal chiamante. Filter Manager chiama questa routine per segnalare al driver minifilter di completare un'operazione di I/O annullata. Questa routine viene dichiarata come segue:

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

Cbdq

Puntatore alla coda dei dati di callback annulla-sicura del driver minifilter. Questa coda deve essere stata inizializzata chiamando FltCbdqInitialize.

Cbd

Puntatore alla struttura dei dati di callback per l'operazione di I/O annullata.

Valore restituito

FltCbdqInitialize restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato.

Commenti

La coda di dati di callback appena inizializzata si trova nello stato abilitato, il che significa che gli elementi della struttura dei dati di callback possono essere inseriti nella coda. La coda può essere disabilitata chiamando FltCbdqDisable e reenable chiamando FltCbdqEnable.

I driver minifilter possono usare le routine FltCbdqXxx per implementare una coda di dati di callback per le operazioni di I/O basate su IRP. Usando queste routine, i driver minifilter possono rendere le code annullate; il sistema gestisce in modo trasparente l'annullamento di I/O per i driver minifilter.

Le routine FltCbdqXxx possono essere usate solo per le operazioni di I/O basate su IRP. Per determinare se una determinata struttura di dati di callback rappresenta un'operazione di I/O basata su IRP, usare la macro FLT_IS_IRP_OPERATION .

I driver minifilter possono usare qualsiasi implementazione interna per la coda. Filter Manager interagisce con l'implementazione della coda del driver minifilter esclusivamente tramite il set di routine di invio fornite da FltCbdqInitialize.

Il sistema blocca automaticamente e sblocca la coda in base alle esigenze. I driver minifilter non implementano alcun blocco all'interno delle loro routine CbdqInsertIo, CbdqRemoveIo e CbdqPeekNextIo.

I driver minifilter possono usare una delle primitive di sincronizzazione del sistema operativo come meccanismo di blocco nelle routine CbdqAcquire e CbdqRelease , ad esempio un blocco spin, un oggetto mutex o una variabile di risorse. Si noti che se un driver minifilter usa un blocco di rotazione anziché un mutex o una risorsa per proteggere la coda, può chiamare le routine FltCbdqXxx in IRQL <= DISPATCH_LEVEL. Se viene usato un mutex o una risorsa, il driver minifilter deve essere in esecuzione in IRQL <= APC_LEVEL quando chiama una di queste routine tranne FltCbdqInitialize.

Il driver minifilter non modifica direttamente la coda. Chiama invece FltCbdqInsertIo, FltCbdqRemoveIo e FltCbdqRemoveNextIo per aggiungere o rimuovere una struttura di dati di callback. Queste routine a sua volta chiamano le funzioni di callback fornite dal driver minifilter a FltCbdqInitialize.

I driver minifilter devono implementare le routine della coda come indicato di seguito.

Cbdq Routine	Implementazione
CbdqInsertIo	Inserire la struttura di dati di callback specificata nella coda.
CbdqRemoveIo	Rimuovere la struttura dei dati di callback specificata dalla coda.
CbdqPeekNextIo	Questa routine deve consentire al sistema di eseguire il ciclo attraverso le strutture di dati di callback con la corrispondenza di PeekContext nella coda. Cbd = CbdqPeekNextIo(Cbdq, NULL, PeekContext) deve restituire la prima voce corrispondente nella coda e CbdqPeekNextIo(Cbdq, Cbd, PeekContext) dovrebbe restituire la voce corrispondente successiva dopo la struttura dei dati di callback specificata nella coda. Il driver minifilter definisce completamente il significato di PeekContext e definisce quando una struttura di dati di callback corrisponde a un valore PeekContext .
CbdqAcquire	Questa routine deve bloccare la coda in modo che nessun altro thread possa accedervi. I driver minifilter possono usare qualsiasi meccanismo di blocco per bloccare la coda. Se il driver minifilter usa la routine KeAcquireSpinLock , il driver minifilter può usare la posizione di memoria a cui punta il parametro Irql della routine per archiviare irQL. In caso contrario, i driver minifilter possono ignorare tale parametro.
CbdqRelease	Questa routine dovrebbe sbloccare la coda creata da CbdqAcquire. Se il driver minifilter ha usato un blocco spin e ha restituito il valore IRQL nel parametro Irql di CbdqAcquire, il sistema passa tale valore nel parametro Irql di CbdqRelease. Il driver minifilter può usare IRQL per sbloccare il blocco di spin chiamando KeReleaseSpinLock. In caso contrario, i driver minifilter possono ignorare il parametro Irql .
CbdqCompleteCanceledIo	Questa routine deve completare un'operazione di I/O annullata. Normalmente, i driver minifilter possono semplicemente chiamare FltCompletePendedPreOperation(Data, FLT_PREOP_COMPLETE, NULL). I driver minifilter non devono dequeuere la struttura dei dati di callback, ovvero Filter Manager chiama automaticamente il CbdqRemoveIo della coda prima di chiamare CbdqCompleteCanceledIo.