Fonction IoSetCompletionRoutine (wdm.h)

Article
08/08/2023

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.

Configuration requise

Condition requise	Valeur
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	IRQL <= DISPATCH_LEVEL
Règles de conformité DDI	CompleteRequest(wdm), CompleteRequestStatusCheck(wdm), CompletionRoutineRegistered(wdm), IoAllocateForward(wdm), IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm), IoAllocateIrpSignalEventInCompletion3(wdm), IoAllocateIrpSignalEventInCompletionTimeout(wdm), IoBuildFsdForward(wdm), IoBuildFsdIrpSignalEventInCompletion(wdm), IoBuildFsdIrpSignalEventInCompletion2(wdm), IoBuildFsdIrpSignalEventInCompletion3(wdm), IoBuildFsdIrpSignalEventInCompletionTimeout(wdm), IoFreeIrp(storport), IoSetCompletionRoutineNonPnpDriver(wdm), LowerDriverReturn(wdm), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PendedCompletedRequest(wdm), SetCompletionRoutineFromDispatch(kmdf), SignalEventInCompletion(wdm), SignalEventInCompletion2(wdm), SignalEventInCompletion3(wdm), StartDeviceWait(wdm), StartDeviceWait3(wdm)