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)

See also

IoAcquireCancelSpinLock

IoReleaseCancelSpinLock