IoSetCancelRoutine

PDRIVER_CANCEL
IoSetCancelRoutine(
IN PIRP Irp,
IN PDRIVER_CANCEL CancelRoutine
);

IoSetCancelRoutine sets up a driver-supplied Cancel routine to be called if a given IRP is canceled. This routine can disable the Cancel routine currently set in an IRP.

Parameters

Irp

Points to the IRP being put into or removed from a cancelable state.

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.

Comments

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 executes at IRQL DISPATCH_LEVEL after calling IoAcquireCancelSpinLock until it releases the cancel spin lock with IoReleaseCancelSpinLock.

If the driver manages its own queue(s) of IRPs, then the driver need not hold the cancel spin lock when calling this routine. IoSetCancelSpinLock 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.