IoSetCompletionRoutineEx

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

VOID 
  IoSetCompletionRoutineEx(
    IN PDEVICE_OBJECT  DeviceObject,
    IN PIRP  Irp,
    IN PIO_COMPLETION_ROUTINE  CompletionRoutine,
    IN 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 wants to track.

CompletionRoutine

Specifies the entry point for the driver-supplied IoCompletion routine to be called when the next-lower driver completes the packet.

Context

Pointer to a driver-determined context to pass to the IoCompletion routine.

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 (defined in ntdef.h).

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.

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Comments

This routine is only available on Windows XP and later.

The behavior of IoSetCompletionRoutineEx is the same as IoSetCompletionRoutine, except that it guarantees that a non-Plug and Play driver is not unloaded before the IoCompletion routine executes.

See Also

IO_STACK_LOCATION, IoCompletion, IoAllocateIrp, IoBuildAsynchronousFsdRequest, IRP, IoBuildPartialMdl, IoFreeIrp, IoSetCompletionRoutine