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.
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 );
- DeviceObject [in]
Pointer to the driver's device object.
- Irp [in]
Pointer to the IRP that the driver is processing.
- CompletionRoutine [in]
Specifies the entry point for the driver-supplied IoCompletion routine, which is called when the next-lower driver completes the packet.
- Context [in, optional]
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 [in]
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 [in]
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 [in]
Specifies whether the completion routine is called if a driver or the kernel has called IoCancelIrp to cancel the IRP.
This routine returns STATUS_SUCCESS on success, or STATUS_INSUFFICIENT_RESOURCES if insufficient memory is available for the operation.
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.