Fonction IoSetCompletionRoutineEx (wdm.h)
La routine IoSetCompletionRoutineEx enregistre une routine IoCompletion , qui est appelée lorsque le pilote de niveau inférieur suivant a terminé l’opération demandée pour l’IRP donné.
Syntaxe
NTSTATUS IoSetCompletionRoutineEx(
[in] PDEVICE_OBJECT DeviceObject,
[in] PIRP Irp,
[in] PIO_COMPLETION_ROUTINE CompletionRoutine,
[in, optional] PVOID Context,
[in] BOOLEAN InvokeOnSuccess,
[in] BOOLEAN InvokeOnError,
[in] BOOLEAN InvokeOnCancel
);
Paramètres
[in] DeviceObject
Pointeur vers l’objet de périphérique du pilote.
[in] Irp
Pointeur vers l’IRP que le pilote traite.
[in] CompletionRoutine
Spécifie le point d’entrée pour la routine IoCompletion fournie par le pilote, qui est appelée lorsque le pilote inférieur suivant termine le paquet.
[in, optional] Context
Pointeur vers un contexte déterminé par le pilote à passer à la routine IoCompletion . Les informations de contexte doivent être stockées dans la mémoire non paginée, car la routine IoCompletion est appelée à IRQL <= DISPATCH_LEVEL.
[in] InvokeOnSuccess
Spécifie si la routine d’achèvement est appelée si l’IRP est terminée avec une valeur de réussite status dans la structure de IO_STATUS_BLOCK de l’IRP, en fonction des résultats de la macro NT_SUCCESS (voir Utilisation de valeurs NTSTATUS).
[in] InvokeOnError
Spécifie si la routine d’achèvement est appelée si l’IRP est terminé avec une valeur de status non-réussite dans la structure IO_STATUS_BLOCK de l’IRP.
[in] InvokeOnCancel
Spécifie si la routine d’achèvement est appelée si un pilote ou le noyau a appelé IoCancelIrp pour annuler l’IRP.
Valeur retournée
Cette routine retourne STATUS_SUCCESS en cas de réussite ou STATUS_INSUFFICIENT_RESOURCES si la mémoire est insuffisante pour l’opération.
Remarques
Contrairement à IoSetCompletionRoutine, la routine IoSetCompletionRoutineEx retourne une valeur NTSTATUS. Le pilote doit case activée cette valeur pour déterminer si la routine IoCompletion a été correctement inscrite. Si la routine IoCompletion est correctement inscrite, IoSetCompletionRoutineEx alloue la mémoire qui reste allouée jusqu’à ce que la routine IoCompletion s’exécute. Les pilotes doivent s’assurer que leur routine IoCompletion s’exécute en appelant IoCallDriver ; sinon, le noyau fuit la mémoire.
La routine IoCompletion doit appartenir au pilote qui possède l’objet d’appareil pointé par DeviceObject. Cette exigence empêche le déchargement de la routine IoCompletion avant son retour.
Le comportement d’IoSetCompletionRoutineEx est le même que la routine IoSetCompletionRoutine , sauf que :
IoSetCompletionRoutineEx garantit qu’un pilote non Plug-and-Play n’est pas déchargé avant l’exécution de la routine IoCompletion.
IoSetCompletionRoutineEx est une routine qui retourne une valeur NTSTATUS.