KsRemoveIrpFromCancelableQueue function (ks.h)

Article
02/22/2024

The KsRemoveIrpFromCancelableQueue function pops the next noncanceled IRP from the specified queue that can be canceled and removes its cancel status. The function searches the list until an IRP is found that has a cancel routine or until the end of the list is reached. The function minimizes the use of the cancel spin lock by using the provided spin lock to synchronize access in most cases. The function may be called at IRQ level DISPATCH_LEVEL or lower.

Syntax

KSDDKAPI PIRP KsRemoveIrpFromCancelableQueue(
  [in, out] PLIST_ENTRY             QueueHead,
  [in]      PKSPIN_LOCK             SpinLock,
  [in]      KSLIST_ENTRY_LOCATION   ListLocation,
  [in]      KSIRP_REMOVAL_OPERATION RemovalOperation
);

Parameters

[in, out] QueueHead

Points to the head of the queue from which to remove the IRP.

[in] SpinLock

Points to driver's spin lock for queue access.

[in] ListLocation

Indicates whether this IRP should come from the beginning or end of the queue.

[in] RemovalOperation

Specifies whether the IRP is removed from the list or just acquired by setting the cancel function to NULL. If it is only acquired, the IRP must be later released with KsReleaseIrpOnCancelableQueue or completely removed with KsRemoveSpecificIrpFromCancelableQueue.

Return value

The KsRemoveIrpFromCancelableQueue function returns the next noncanceled IRP on the list, or it returns NULL if none is found or if an IRP that has not already been acquired cannot be found.

Remarks

These enumerations are used in the previous parameters to control where the IRP is removed from and how.

typedef enum {
    KsListEntryTail,
    KsListEntryHead
} KSLIST_ENTRY_LOCATION;

typedef enum {
    KsAcquireOnly,
    KsAcquireAndRemove
} KSIRP_REMOVAL_OPERATION;

Requirements

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