Fonction IoSetCompletionRoutine (wdm.h)
La routine IoSetCompletionRoutine inscrit une routine IoCompletion , qui sera appelée lorsque le pilote de niveau inférieur suivant aura terminé l’opération demandée pour l’IRP donné.
Syntaxe
void IoSetCompletionRoutine(
[in] PIRP Irp,
[in, optional] PIO_COMPLETION_ROUTINE CompletionRoutine,
[in, optional] __drv_aliasesMem PVOID Context,
[in] BOOLEAN InvokeOnSuccess,
[in] BOOLEAN InvokeOnError,
[in] BOOLEAN InvokeOnCancel
);
Paramètres
[in] Irp
Pointeur vers l’IRP que le pilote traite.
[in, optional] 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 dans 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 status réussie dans la structure IO_STATUS_BLOCK de l’IRP, en fonction des résultats de la macro NT_SUCCESS (voir Utilisation des valeurs NTSTATUS).
[in] InvokeOnError
Spécifie si la routine d’achèvement est appelée si l’IRP est terminée 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 de retour
None
Remarques
Seul un pilote qui peut garantir qu’il ne sera pas déchargé avant la fin de sa routine d’achèvement peut utiliser IoSetCompletionRoutine. Sinon, le pilote doit utiliser IoSetCompletionRoutineEx, ce qui empêche le pilote de se décharger jusqu’à ce que sa routine d’achèvement s’exécute.
Cette routine définit l’adresse de transfert de la routine IoCompletion dans l’IRP donnée. Le pilote de niveau le plus bas dans une chaîne de pilotes en couches ne peut pas appeler cette routine.
IoSetCompletionRoutine inscrit la routine spécifiée à appeler lorsque le pilote de niveau inférieur suivant a effectué l’opération demandée de toutes les manières suivantes :
Avec une valeur de réussite status
Avec une valeur de status non-uccess
En annulant l’IRP
En règle générale, le bloc de status d’E/S est défini par le pilote de périphérique sous-jacent. Elle est lue, mais n’est pas modifiée par les routines IoCompletion des pilotes de niveau supérieur.
Les pilotes de niveau supérieur qui allouent des IRP avec IoAllocateIrp ou IoBuildAsynchronousFsdRequest doivent appeler cette routine avec tous les paramètres InvokeOnXxx définis sur TRUE avant de transmettre l’IRP allouée par le pilote à IoCallDriver. Lorsque la routine IoCompletion est appelée avec un tel IRP, elle doit libérer l’IRP alloué au pilote et toutes les autres ressources que le pilote a configurées pour la requête, telles que les FICHIERS MDL avec IoBuildPartialMdl. Un tel pilote doit retourner STATUS_MORE_PROCESSING_REQUIRED lorsqu’il appelle IoFreeIrp pour parer au traitement de l’achèvement du gestionnaire d’E/S pour l’IRP allouée par le pilote.
Les pilotes non PnP qui peuvent être déchargés avant l’exécution de leurs routines IoCompletion doivent utiliser IoSetCompletionRoutineEx à la place.