Fonction FltPerformAsynchronousIo (fltkernel.h)

Article
08/07/2023

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 quand elle n’est plus nécessaire en appelant FltFreeCallbackData.

[in] CallbackRoutine

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

[in] CallbackContext

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

Valeur retournée

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

Code de retour	Description
STATUS_FLT_INVALID_ASYNCHRONOUS_REQUEST	IRP_MJ_CREATE demandes ne peuvent pas être effectuées de manière asynchrone. Il s’agit d’un code d’erreur.
STATUS_PENDING	Opération retournée STATUS_PENDING. Le Gestionnaire de filtres appelle la routine de rappel vers laquelle CallbackRoutine pointe lorsque 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é terminée par la routine de rappel de préopération du pilote minifilter dont les instances sont attachées sous la instance de lancement.

Remarques

Un pilote minifilter appelle FltPerformAsynchronousIo pour lancer une opération d’E/S asynchrone après avoir appelé FltAllocateCallbackData afin d’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 la 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 la instance spécifiée ne reçoivent pas l’opération d’E/S.

Les pilotes Minifilter peuvent uniquement lancer des opérations d’E/S basées sur IRP. Ils ne peuvent pas lancer d’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 des routines telles que les suivantes ne peuvent pas être utilisées :

IRP_MJ_CREATE demandes ne peuvent pas être effectuées de manière asynchrone.

La structure de données de rappel (FLT_CALLBACK_DATA) peut être libérée ou réutilisée à tout moment après l’appel de la routine de rappel vers laquelle callbackRoutine pointe. L’appelant peut libérer la structure de données de rappel en appelant FltFreeCallbackData ou la préparer à la réutiliser en appelant FltReuseCallbackData.

Notes

STATUS_SUCCESS et STATUS_FLT_IO_COMPLETE indiquent que l’opération d’E/S a été effectuée, mais n’indiquent pas la status finale de l’opération d’E/S. Pour déterminer l’opération réelle status retournées 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 CallbackContext de CallbackRoutine.

Étant donné que le Gestionnaire de filtres appelle toujours la routine de rappel vers laquelle CallbackRoutine pointe, même en cas d’échec de FltPerformAsynchronousIo , 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 sur IRQL <= APC_LEVEL si l’indicateur IRP_PAGING_IO est défini dans le membre IrpFlags de la structure FLT_IO_PARAMETER_BLOCK de l’opération. (Cet indicateur n’est valide que 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 sur irQL PASSIVE_LEVEL.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	fltkernel.h (inclure Fltkernel.h)
Bibliothèque	FltMgr.lib
DLL	Fltmgr.sys
IRQL	Consultez la section Notes.