Funzione FltCbdqInitialize (fltkernel.h)

Articolo
02/06/2025

FltCbdqInitialize inizializza la tabella dispatch della coda di dati del callback di un 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 all'istanza opaca per l'istanza di 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 di inserimento fornita dal chiamante. Gestione filtri chiama questa routine per inserire la struttura dei 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-safe 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 alle 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-safe 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 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-safe 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 all'inizio 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 sulla 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-safe del driver minifilter. Questa coda deve essere stata inizializzata chiamando FltCbdqInitialize.

Irql

Puntatore a una variabile fornita dal sistema che riceve l'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. Il Gestore 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-safe 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. Gestione filtri 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-safe 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.

Osservazioni

La coda di dati di callback appena inizializzata è 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 ripristinabile chiamando FltCbdqEnable.

I driver minifiltro 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 minifiltro possono rendere le code annullabili; il sistema gestisce in modo trasparente l'annullamento di I/O per i driver minifiltri.

Le routine FltCbdqXxx possono essere usate solo per 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, utilizzare la macro FLT_IS_IRP_OPERATION.

I driver minifiltro possono usare qualsiasi implementazione interna per la coda. Gestione filtri interagisce con l'implementazione della coda del driver minifiltro esclusivamente tramite il set di routine dispatch fornite da FltCbdqInitialize.

Il sistema blocca e sblocca automaticamente la coda in base alle esigenze. I driver minifiltri non implementano alcun blocco all'interno dei loro CbdqInsertIo, CbdqRemoveIoe cbdqPeekNextIo routine.

I driver minifiltro possono usare una qualsiasi delle primitive di sincronizzazione del sistema operativo come meccanismo di blocco nel loro CbdqAcquire e routine CbdqRelease, ad esempio un blocco spin , oggetto mutexo variabile di risorsa. Si noti che se un driver minifiltro usa un blocco di selezione anziché un mutex o una risorsa per proteggere la coda, può chiamare le routine FltCbdqXxx in IRQL <= DISPATCH_LEVEL. Se si usa 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, FltCbdqRemoveIoe FltCbdqRemoveNextIo per aggiungere o rimuovere una struttura di dati di callback. Queste routine chiamano a sua volta le funzioni di callback fornite dal driver minifilter per FltCbdqInitialize.

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

Cbdq Routine	Implementazione
CbdqInsertIo	Inserire la struttura dei dati di callback specificata nella coda.
CbdqRemoveIo	Rimuovere la struttura dei dati di callback specificata dalla coda.
CbdqPeekNextIo	Questa routine dovrebbe consentire al sistema di scorrere le strutture di dati di callback con corrispondenza PeekContext nella coda. Cbd = CbdqPeekNextIo(Cbdq, NULL, PeekContext) deve restituire la prima voce corrispondente nella coda, e CbdqPeekNextIo(Cbdq, Cbd, PeekContext) devono restituire la voce corrispondente successiva dopo la struttura dei dati di callback specificata nella coda. Il driver minifilter definisce interamente 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 minifiltro possono usare qualsiasi meccanismo di blocco per bloccare la coda. Se il driver minifiltro usa la routine KeAcquireSpinLock, il driver minifiltro 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 minifiltro 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 minifiltro può usare IRQL per sbloccare il blocco di selezione chiamando KeReleaseSpinLock. In caso contrario, i driver minifilter possono ignorare il parametro irql.
CbdqCompleteCanceledIo	Questa routine deve completare un'operazione di I/O annullata. In genere, i driver minifilter possono semplicemente chiamare FltCompletePendedPreOperation(Data, FLT_PREOP_COMPLETE, NULL). I driver minifiltro non devono annullare la coda della struttura dei dati di callback. Gestione filtri chiama automaticamente il cbdqRemoveIo prima di chiamare CbdqCompleteCanceledIo.