IoSetCancelRoutine

The IoSetCancelRoutine routine sets up a driver-supplied Cancel routine to be called if a given IRP is canceled.

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

Parameters

Irp

Pointer 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. If no Cancel routine was previously set, or if IRP cancellation is already in progress, IoSetCancelRoutine returns NULL.

Headers

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

Comments

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 executes 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.

See Also

IoAcquireCancelSpinLock, IoReleaseCancelSpinLock