Edit

KsAddIrpToCancelableQueue function (ks.h)

  • Article

The KsAddIrpToCancelableQueue function adds an IRP to a queue of cancelable IRPs, thus allowing the IRP to be canceled. If the IRP had been previously set to a canceled state, the KsAddIrpToCancelableQueue function completes the canceling of that IRP.

Syntax

KSDDKAPI VOID KsAddIrpToCancelableQueue(
  [in, out]      PLIST_ENTRY           QueueHead,
  [in]           PKSPIN_LOCK           SpinLock,
  [in]           PIRP                  Irp,
  [in]           KSLIST_ENTRY_LOCATION ListLocation,
  [in, optional] PDRIVER_CANCEL        DriverCancel
);

Parameters

[in, out] QueueHead

Specifies the driver-allocated storage for the head of the queue on which to add the IRP.

[in] SpinLock

Points to driver's spin lock for queue access to the queue specified at QueueHead. A copy of this pointer is kept in the IRP's KSQUEUE_SPINLOCK_IRP_STORAGE(Irp) for use by the cancel routine, if necessary.

[in] Irp

Specifies the IRP to add to the queue specified at QueueHead.

[in] ListLocation

Indicates whether this IRP should be placed at the beginning or end of the queue. This value must be KsListEntryTail or KsListEntryHead.

[in, optional] DriverCancel

Optional parameter that specifies a driver-supplied cancel routine to use. If this is NULL, the standard KsCancelRoutine is used.

Return value

None

Remarks

If the IRP has been put into a cancel state when this routine is called, KsAddIrpToCancelableQueue will immediately call the cancel routine specified at DriverCancel, or if no routine was specified at DriverCancel the default streaming cancel routine is called.

The KsAddIrpToCancelableQueue function allows IRPs to be canceled even before being placed on a cancel list, or when being moved from one list to another. This function can be called at IRQ level DISPATCH_LEVEL or lower unless the driver-allocated queue and all entries in the queue are system-resident or allocated from resident storage.

The function does not use the cancel spin lock to add items to the list. Access to the list is synchronized using the provided spin lock and relies on atomic operations on Irp->CancelRoutine.

Requirements

Requirement Value
Target Platform Universal
Header ks.h (include Ks.h)
Library Ks.lib