Funzione FltPerformAsynchronousIo (fltkernel.h)

Articolo
02/29/2024

Un driver minifilter chiama FltPerformAsynchronousIo per avviare un'operazione di I/O asincrona.

Sintassi

NTSTATUS FLTAPI FltPerformAsynchronousIo(
  [in, out] PFLT_CALLBACK_DATA               CallbackData,
  [in]      PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
  [in]      PVOID                            CallbackContext
);

Parametri

[in, out] CallbackData

Puntatore a una struttura di dati di callback (FLT_CALLBACK_DATA) allocata da una chiamata precedente a FltAllocateCallbackData. Questo parametro è obbligatorio e non può essere NULL. Il chiamante è responsabile della liberazione di questa struttura quando non è più necessaria chiamando FltFreeCallbackData.

[in] CallbackRoutine

Puntatore a una routine di callback tipizzata PFLT_COMPLETED_ASYNC_IO_CALLBACK da chiamare al termine dell'operazione di I/O. Nota: Gestione filtri chiama questa routine dopo che chiama le routine di callback di postoperazione (PFLT_POST_OPERATION_CALLBACK) di qualsiasi driver minifilter le cui istanze sono collegate sotto l'istanza di avvio (specificata nel parametro Instance a FltAllocateCallbackData). Questo parametro è obbligatorio e non può essere NULL. Gestione filtri chiama sempre questa routine, anche quando FltPerformAsynchronousIo ha esito negativo.

[in] CallbackContext

Puntatore di contesto da passare a CallbackRoutine Questo parametro è facoltativo e può essere NULL.

Valore restituito

FltPerformAsynchronousIo restituisce STATUS_SUCCESS per indicare che l'operazione di I/O è stata completata dal file system e la routine di callback a cui punta CallbackRoutine è stata chiamata. In caso contrario, restituisce un valore NTSTATUS appropriato, ad esempio uno dei seguenti:

Codice restituito	Descrizione
STATUS_FLT_INVALID_ASYNCHRONOUS_REQUEST	IRP_MJ_CREATE richieste non possono essere eseguite in modo asincrono. Si tratta di un codice di errore.
STATUS_PENDING	L'operazione ha restituito STATUS_PENDING. Gestione filtri chiamerà la routine di callback a cui CallbackRoutine punta al completamento dell'operazione di I/O. Questo codice indica solo che l'operazione è stata avviata.
STATUS_FLT_IO_COMPLETE	L'operazione è stata completata dalla routine di callback di preoperazione del driver minifilter le cui istanze sono collegate sotto l'istanza di avvio.

Commenti

Un driver minifilter chiama FltPerformAsynchronousIo per avviare un'operazione di I/O asincrona dopo aver chiamato FltAllocateCallbackData per allocare una struttura di dati di callback per l'operazione.

FltPerformAsynchronousIo invia l'operazione di I/O solo alle istanze del driver minifilter collegate sotto l'istanza di avvio (specificata nel parametro Instance a FltAllocateCallbackData) 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 veloci (FSFilter).

I driver minifilter devono usare FltPerformAsynchronousIo solo per le operazioni di I/O asincrone per le quali non è possibile usare routine come le seguenti:

IRP_MJ_CREATE richieste non possono essere eseguite in modo asincrono.

La struttura dei dati di callback (FLT_CALLBACK_DATA) può essere liberata o riutilizzata in qualsiasi momento dopo la chiamata della routine di callback a cui callbackRoutine punta. Il chiamante può liberare la struttura dei dati di callback chiamando FltFreeCallbackData o preparandola per il riutilizzo chiamando FltReuseCallbackData.

Nota

STATUS_SUCCESS e STATUS_FLT_IO_COMPLETE indicano che l'operazione di I/O è stata completata, ma non indica lo stato finale dell'operazione di I/O. Per determinare lo stato effettivo dell'operazione restituito dai driver minifilter sottostanti, dai driver di filtro e dal file system, callbackRoutine deve esaminare il membro IoStatus della struttura dei dati di callback ricevuta nel parametro CallbackContext di CallbackRoutine.

Poiché Gestione filtri chiama sempre la routine di callback a cui CallbackRoutine punta, anche quando FltPerformAsynchronousIo ha esito negativo, il driver minifilter può eseguire le operazioni di liberamento o riutilizzo direttamente nella routine di callback.

Il chiamante di FltPerformAsynchronousIo può essere eseguito in IRQL <= APC_LEVEL se il flag IRP_PAGING_IO è impostato nel membro IrpFlags della struttura FLT_IO_PARAMETER_BLOCK per l'operazione. Questo flag è valido solo per le operazioni di IRP_MJ_READ, IRP_MJ_WRITE, IRP_MJ_QUERY_INFORMATION e IRP_MJ_SET_INFORMATION. In caso contrario, il chiamante deve essere in esecuzione in irQL PASSIVE_LEVEL.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	fltkernel.h (include Fltkernel.h)
Libreria	FltMgr.lib
DLL	Fltmgr.sys
IRQL	Vedere la sezione Osservazioni.