FltPerformAsynchronousIo, fonction (fltkernel.h)

Article
02/06/2025

Un pilote minifilter appelle FltPerformAsynchronousIo pour lancer une opération d’E/S asynchrone.

Syntaxe

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

Paramètres

[in, out] CallbackData

Pointeur vers une structure de données de rappel (FLT_CALLBACK_DATA) allouée par un appel précédent à FltAllocateCallbackData. Ce paramètre est obligatoire et ne peut pas être NULL. L’appelant est chargé de libérer cette structure lorsqu’elle n’est plus nécessaire en appelant FltFreeCallbackData.

[in] CallbackRoutine

Pointeur vers une routine de rappel PFLT_COMPLETED_ASYNC_IO_CALLBACK-typée à appeler lorsque l’opération d’E/S est terminée. Remarque : Le Gestionnaire de filtre appelle cette routine après avoir appelé les routines de rappel de postopération (PFLT_POST_OPERATION_CALLBACK) de tous les pilotes minifilter dont les instances sont attachées sous l’instance de lancement (spécifiée dans le paramètre de l’instance à FltAllocateCallbackData). Ce paramètre est obligatoire et ne peut pas être NULL. Le Gestionnaire de filtre appelle toujours cette routine, même quand FltPerformAsynchronousIo échoue.

[in] CallbackContext

Le pointeur de contexte à passer au CallbackRoutine Ce paramètre est facultatif et peut être NULL.

Valeur de retour

FltPerformAsynchronousIo retourne STATUS_SUCCESS pour indiquer que l’opération d’E/S a été effectuée par le système de fichiers et la routine de rappel qui CallbackRoutine points à appeler. Sinon, elle retourne une valeur NTSTATUS appropriée, telle que l’une des suivantes :

Retourner le code	Description
STATUS_FLT_INVALID_ASYNCHRONOUS_REQUEST	IRP_MJ_CREATE les requêtes ne peuvent pas être effectuées de manière asynchrone. Il s’agit d’un code d’erreur.
STATUS_PENDING	L’opération a retourné STATUS_PENDING. Le Gestionnaire de filtre appelle la routine de rappel vers laquelle CallbackRoutine pointe vers le moment où l’opération d’E/S est terminée. Ce code indique uniquement que l’opération a été lancée.
STATUS_FLT_IO_COMPLETE	L’opération a été effectuée par la routine de rappel de préopération du pilote minifilter dont les instances sont attachées sous l’instance de lancement.

Remarques

Un pilote minifilter appelle FltPerformAsynchronousIo pour lancer une opération d’E/S asynchrone après avoir appelé FltAllocateCallbackData pour allouer une structure de données de rappel pour l’opération.

FltPerformAsynchronousIo envoie l’opération d’E/S uniquement aux instances de pilote minifilter attachées sous l’instance de lancement (spécifiée dans le paramètre Instance à FltAllocateCallbackData) et au système de fichiers. Les pilotes Minifilter attachés au-dessus de l’instance spécifiée ne reçoivent pas l’opération d’E/S.

Les pilotes minifilter ne peuvent lancer que des opérations d’E/S basées sur IRP. Ils ne peuvent pas lancer des opérations de rappel rapides d’E/S ou de filtre de système de fichiers (FSFilter).

Les pilotes minifilter doivent utiliser FltPerformAsynchronousIo uniquement pour les opérations d’E/S asynchrones pour lesquelles les routines telles que les suivantes ne peuvent pas être utilisées :

FltReadFile
FltWriteFile

IRP_MJ_CREATE les requêtes ne peuvent pas être effectuées de manière asynchrone.

La structure des données de rappel (FLT_CALLBACK_DATA) peut être libérée ou réutilisée à tout moment après la routine de rappel qui CallbackRoutine points à appeler. L’appelant peut libérer la structure des données de rappel en appelant FltFreeCallbackData ou en la préparant pour une réutilisation en appelant FltReuseCallbackData.

Note

STATUS_SUCCESS et STATUS_FLT_IO_COMPLETE indiquent que l’opération d’E/S a été terminée, mais n’indiquez pas l’état final de l’opération d’E/S. Pour déterminer l’état réel de l’opération retournée par les pilotes minifilter sous-jacents, les pilotes de filtre et le système de fichiers, le CallbackRoutine doit examiner le membre IoStatus de la structure de données de rappel reçue dans le paramètre CallbackRoutine's CallbackContext.

Étant donné que Filter Manager appelle toujours la routine de rappel vers laquelle CallbackRoutine pointe vers, même si FltPerformAsynchronousIo échoue, le pilote minifilter peut effectuer les opérations de libération ou de réutilisation directement dans la routine de rappel.

L’appelant de FltPerformAsynchronousIo peut s’exécuter au <IRQL = APC_LEVEL si l’indicateur IRP_PAGING_IO est défini dans le membre IrpFlags membre de la structure FLT_IO_PARAMETER_BLOCK pour l’opération. (Cet indicateur est valide uniquement pour les opérations IRP_MJ_READ, IRP_MJ_WRITE, IRP_MJ_QUERY_INFORMATION et IRP_MJ_SET_INFORMATION.) Sinon, l’appelant doit s’exécuter à l’PASSIVE_LEVEL IRQL.