Export (0) Print
Expand All
Expand Minimize

IoSetCancelRoutine routine

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

Irp [in]

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

CancelRoutine [in]

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

Version

Available starting with Windows 2000.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

Ntoskrnl.lib

IRQL

DISPATCH_LEVEL (see Remarks section)

DDI compliance rules

IrpCancelField, StartIoCancel

See also

IoAcquireCancelSpinLock
IoReleaseCancelSpinLock

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft