Funzione FltAllocateCallbackData (fltkernel.h)

Articolo
02/06/2025

FltAllocateCallbackData alloca una struttura di dati di callback che un driver minifilter può usare per avviare una richiesta di I/O.

Sintassi

NTSTATUS FLTAPI FltAllocateCallbackData(
  [in]           PFLT_INSTANCE      Instance,
  [in, optional] PFILE_OBJECT       FileObject,
  [out]          PFLT_CALLBACK_DATA *RetNewCallbackData
);

Parametri

[in] Instance

Puntatore a istanze opache per l'istanza del driver minifilter che avvia l'operazione di I/O. Questo parametro è obbligatorio e non può essere NULL.

[in, optional] FileObject

Puntatore all'oggetto file da usare nell'operazione di I/O. Questo parametro è facoltativo e può essere NULL.

[out] RetNewCallbackData

Puntatore a una variabile allocata dal chiamante che riceve l'indirizzo della struttura di dati di callback appena allocati (FLT_CALLBACK_DATA).

Valore restituito

FltAllocateCallbackData restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio:

Codice restituito	Descrizione
STATUS_INSUFFICIENT_RESOURCES	FltAllocateCallbackData rilevato un errore di allocazione del pool durante il tentativo di allocare la struttura dei dati di callback. Si tratta di un codice di errore.

Osservazioni

Un driver minifilter può chiamare FltAllocateCallbackData per allocare una struttura di dati di callback (FLT_CALLBACK_DATA) per un'operazione di I/O avviata dal driver minifilter.

Nota Routine FltAllocateCallbackData non alloca tutta la memoria necessaria per una richiesta di I/O successiva. Se una richiesta di I/O, ad esempio FltPerformSynchronousIo o FltPerformAsynchronousIo, richiede memoria aggiuntiva per alcune strutture, la richiesta potrebbe riscontrare un'allocazione di memoria. La routine FltAllocateCallbackDataEx può essere utilizzata per evitare questo potenziale problema preallocando la memoria per ulteriori strutture da utilizzare in una richiesta di I/O. Se si verifica un problema di allocazione della memoria per la struttura di RetNewCallbackData o altre strutture necessarie, è possibile risolvere il problema al momento dell'allocazione dei dati di callback.

Le strutture dei dati di callback vengono allocate dal pool non di paging.

Dopo aver inizializzato i parametri della struttura dei dati di callback restituita da FltAllocateCallbackData, il chiamante avvia l'operazione di I/O passando la struttura a FltPerformSynchronousIo o FltPerformAsynchronousIo. Queste routine inviano l'operazione di I/O solo alle istanze del driver minifilter collegate sotto l'istanza di avvio (specificata nel parametro instance di) e al file system. I driver minifilter collegati sopra l'istanza specificata non ricevono l'operazione di I/O.

I driver minifiltro possono avviare solo operazioni di I/O basate su IRP. Non possono avviare operazioni di callback di I/O o file system veloci (FSFilter).

I driver minifilter devono usare FltAllocateCallbackData, FltPerformAsynchronousIoe FltPerformSynchronousIo solo per le operazioni di I/O per le quali non è possibile usare routine come le seguenti:

FltClose

FltCreateFile

FltQueryVolumeInformation

fltReadFile

FltSetVolumeInformation

FltTagFile

FltUntagFile

FltWriteFile

Quando la struttura dei dati di callback allocata da FltAllocateCallbackData non è più necessaria, il chiamante è responsabile della liberazione chiamando FltFreeCallbackData.