IoSetCompletionRoutine function (wdm.h)
The IoSetCompletionRoutine routine registers an IoCompletion routine, which will be called when the next-lower-level driver has completed the requested operation for the given IRP.
void IoSetCompletionRoutine( PIRP Irp, PIO_COMPLETION_ROUTINE CompletionRoutine, __drv_aliasesMem PVOID Context, BOOLEAN InvokeOnSuccess, BOOLEAN InvokeOnError, BOOLEAN InvokeOnCancel );
[in] Pointer to the IRP that the driver is processing.
[in, optional] Specifies the entry point for the driver-supplied IoCompletion routine, which is called when the next-lower driver completes the packet.
[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.
[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).
[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.
[in] Specifies whether the completion routine is called if a driver or the kernel has called IoCancelIrp to cancel the IRP.
IoSetCompletionRoutine registers the specified routine to be called when the next-lower-level driver has completed the requested operation in any or all of the following ways:
- With a success status value
- With a nonsuccess status value
- By canceling the IRP
Higher-level drivers that allocate IRP's with IoAllocateIrp or IoBuildAsynchronousFsdRequest must call this routine with all InvokeOnXxx parameters set to TRUE before passing the driver-allocated IRP to IoCallDriver. When the IoCompletion routine is called with such an IRP, it must free the driver-allocated IRP and any other resources that the driver set up for the request, such as MDLs with IoBuildPartialMdl. Such a driver should return STATUS_MORE_PROCESSING_REQUIRED when it calls IoFreeIrp to forestall the I/O manager's completion processing for the driver-allocated IRP.
Non-PnP drivers that might be unloaded before their IoCompletion routines run should use IoSetCompletionRoutineEx instead.
|Minimum supported client||Available starting with Windows 2000.|
|Header||wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)|
|DDI compliance rules||CompleteRequest, CompleteRequestStatusCheck, CompletionRoutineRegistered, IoAllocateForward, IoAllocateIrpSignalEventInCompletion, IoAllocateIrpSignalEventInCompletion2, IoAllocateIrpSignalEventInCompletion3, IoAllocateIrpSignalEventInCompletionTimeout, IoBuildFsdForward, IoBuildFsdIrpSignalEventInCompletion, IoBuildFsdIrpSignalEventInCompletion2, IoBuildFsdIrpSignalEventInCompletion3, IoBuildFsdIrpSignalEventInCompletionTimeout, IoSetCompletionRoutineNonPnpDriver, LowerDriverReturn, MarkPower, MarkPowerDown, MarkQueryRelations, MarkStartDevice, PendedCompletedRequest, SignalEventInCompletion, SignalEventInCompletion2, SignalEventInCompletion3, StartDeviceWait, StartDeviceWait3, SetCompletionRoutineFromDispatch, IoFreeIrp|