IoSetCancelRoutine function (wdm.h)
The IoSetCancelRoutine routine sets up a driver-supplied Cancel routine to be called if a given IRP is canceled.
Syntax
PDRIVER_CANCEL IoSetCancelRoutine(
[in] PIRP Irp,
[in] PDRIVER_CANCEL CancelRoutine
);
Parameters
[in] Irp
Pointer to the IRP being put into or removed from a cancelable state.
[in] CancelRoutine
Specifies the entry point of the caller-supplied Cancel routine to be called if the specified IRP is canceled or is NULL if the given IRP is being removed from the cancelable state. This routine is declared as follows:
VOID
(*PDRIVER_CANCEL)(
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp
);
Return value
IoSetCancelRoutine returns the previous value of Irp->CancelRoutine. If no Cancel routine was previously set, or if IRP cancellation is already in progress, IoSetCancelRoutine returns NULL.
Remarks
This routine can disable the Cancel routine currently set in an IRP.
A driver must hold the system cancel spin lock when calling this routine if the driver uses the I/O manager-supplied device queue in the device object. The driver runs at IRQL = DISPATCH_LEVEL after calling IoAcquireCancelSpinLock until it releases the cancel spin lock with IoReleaseCancelSpinLock.
If the driver manages its own queues of IRPs, then the driver need not hold the cancel spin lock when calling this routine. IoSetCancelRoutine uses an interlocked exchange intrinsic to set the address of the Cancel routine as an atomic operation. Reduced usage of the cancel spin lock can improve driver performance and overall system performance.
Driver Cancel routines are called at IRQL = DISPATCH_LEVEL with the cancel spin lock held. The Cancel routine must release the cancel spin lock before it returns control.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Desktop |
| Header | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | DISPATCH_LEVEL (see Remarks section) |
| DDI compliance rules | IrpCancelField(wdm), StartIoCancel(wdm) |