Fonction IoSetCompletionRoutineEx (wdm.h)

Article
03/08/2023

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.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Règles de conformité DDI	CompleteRequest(wdm),CompleteRequestStatusCheck(wdm), CompletionRoutineRegistered(wdm), HwStorPortProhibitedDDDIs(storport), IoAllocateForward(wdm), IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm), IoAllocateIrpSignalEventInCompletion3(wdm), IoAllocateIrpSignalEventInCompletionTimeout(wdm), IoBuildFsdForward(wdm), IoBuildFsdIrpSignalEventInCompletion(wdm), IoBuildFsdIrpSignalEventInCompletion2(wdm), IoBuildFsdIrpSignalEventInCompletion3(wdm), IoBuildFsdIrpSignalEventInCompletionTimeout(wdm), IoSetCompletionExCompleteIrp(wdm),IoSetCompletionRoutineExCheck(wdm), IoSetCompletionRoutineExCheckDeviceObject(wdm), LowerDriverReturn(wdm), MarkPower(wdm), MarkPowerDown(wdm) , MarkQueryRelations(wdm), MarkStartDevice(wdm), PendedCompletedRequestEx(wdm), SetCompletionRoutineFromDispatch(kmdf), SignalEventInCompletion(wdm), SignalEventInCompletion2(wdm), SignalEventInCompletion3(wdm), StartDeviceWait2(wdm), StartDeviceWait4(wdm)