Funzione FltAllocateCallbackData (fltkernel.h)

Articolo
08/07/2023

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 istanza opaca 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 a oggetti 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 nuova struttura di callback (FLT_CALLBACK_DATA).

Valore restituito

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

Codice restituito	Descrizione
STATUS_INSUFFICIENT_RESOURCES	FltAllocateCallbackData ha 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.

Commenti

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

Nota La routine FltAllocateCallbackData non alloca tutta la memoria che potrebbe essere richiesta da 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 usata per evitare questo potenziale problema preallocando la memoria per altre strutture da usare in una richiesta di I/O. Se si verifica un problema di allocazione della memoria per la struttura RetNewCallbackData o altre strutture necessarie, può essere gestito al punto di allocazione dei dati di callback.

Le strutture di dati di callback vengono allocate dal pool non a pagina.

Dopo aver inizializzato i parametri della struttura dei dati di callback restituito 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 associate sotto l'istanza di avvio (specificata nel parametro Istanza ) e al file system. I driver minifilter collegati sopra l'istanza specificata non ricevono l'operazione di I/O.

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

I driver minifilter devono usare FltAllocateCallbackData, FltPerformAsynchronousIo e FltPerformSynchronousIo solo per le operazioni di I/O per cui 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 per liberarlo chiamando FltFreeCallbackData.