IoSetCompletionRoutineEx function

The IoSetCompletionRoutineEx routine registers an IoCompletion routine, which is called when the next-lower-level driver has completed the requested operation for the given IRP.

Syntax

NTSTATUS IoSetCompletionRoutineEx(
  _In_     PDEVICE_OBJECT         DeviceObject,
  _In_     PIRP                   Irp,
  _In_     PIO_COMPLETION_ROUTINE CompletionRoutine,
  _In_opt_ PVOID                  Context,
  _In_     BOOLEAN                InvokeOnSuccess,
  _In_     BOOLEAN                InvokeOnError,
  _In_     BOOLEAN                InvokeOnCancel
);

Parameters

DeviceObject

Pointer to the driver's device object.

Irp

Pointer to the IRP that the driver is processing.

CompletionRoutine

Specifies the entry point for the driver-supplied IoCompletion routine, which is called when the next-lower driver completes the packet.

Context

Pointer to a driver-determined context to pass to the IoCompletion routine. Context information must be stored in nonpaged memory, because the IoCompletion routine is called at IRQL <= DISPATCH_LEVEL.

InvokeOnSuccess

Specifies whether the completion routine is called if the IRP is completed with a success status value in the IRP's IO_STATUS_BLOCK structure, based on results of the NT_SUCCESS macro (see Using NTSTATUS values).

InvokeOnError

Specifies whether the completion routine is called if the IRP is completed with a nonsuccess status value in the IRP's IO_STATUS_BLOCK structure.

InvokeOnCancel

Specifies whether the completion routine is called if a driver or the kernel has called IoCancelIrp to cancel the IRP.

Return Value

This routine returns STATUS_SUCCESS on success, or STATUS_INSUFFICIENT_RESOURCES if insufficient memory is available for the operation.

Remarks

Note Unlike IoSetCompletionRoutine, the IoSetCompletionRoutineEx routine returns an NTSTATUS value. The driver must check this value to determine if the IoCompletion routine was successfully registered. If the IoCompletion routine is successfully registered, IoSetCompletionRoutineEx allocates memory that remains allocated until the IoCompletion routine executes. Drivers must ensure that their IoCompletion routine executes by calling IoCallDriver; otherwise, the kernel will leak memory.
The IoCompletion routine must belong to the driver that owns the device object pointed to by DeviceObject. This requirement prevents the IoCompletion routine from being unloaded before it returns.

The behavior of IoSetCompletionRoutineEx is the same as the IoSetCompletionRoutine routine, except that:

  • IoSetCompletionRoutineEx guarantees that a non-Plug and Play driver is not unloaded before the IoCompletion routine runs.
  • IoSetCompletionRoutineEx is a routine that returns an NTSTATUS value.

Requirements

   
Windows version Available starting with Windows XP.
Target Platform Universal
Header wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL "<= DISPATCH_LEVEL"
DDI compliance rules CompleteRequest, CompleteRequestStatusCheck, CompletionRoutineRegistered, IoAllocateForward, IoAllocateIrpSignalEventInCompletion, IoAllocateIrpSignalEventInCompletion2, IoAllocateIrpSignalEventInCompletion3, IoAllocateIrpSignalEventInCompletionTimeout, IoBuildFsdForward, IoBuildFsdIrpSignalEventInCompletion, IoBuildFsdIrpSignalEventInCompletion2, IoBuildFsdIrpSignalEventInCompletion3, IoBuildFsdIrpSignalEventInCompletionTimeout, IoSetCompletionExCompleteIrp, IoSetCompletionRoutineExCheck, IoSetCompletionRoutineExCheckDeviceObject, LowerDriverReturn, MarkPower, MarkPowerDown, MarkQueryRelations, MarkStartDevice, PendedCompletedRequestEx, SignalEventInCompletion, SignalEventInCompletion2, SignalEventInCompletion3, StartDeviceWait2, StartDeviceWait4, SetCompletionRoutineFromDispatch, HwStorPortProhibitedDDIs

See Also

IO_STACK_LOCATION

IoBuildPartialMdl

IRP

IoBuildAsynchronousFsdRequest

IoCompletion

IoAllocateIrp

IoSetCompletionRoutine

IoFreeIrp

Send comments about this topic to Microsoft