IoCsqRemoveNextIrp function (wdm.h)

Article
02/25/2022

The IoCsqRemoveNextIrp routine removes the next matching IRP in the queue.

Syntax

PIRP IoCsqRemoveNextIrp(
  [in, out]      PIO_CSQ Csq,
  [in, optional] PVOID   PeekContext
);

Parameters

[in, out] Csq

Pointer to the driver's dispatch table for cancel-safe IRP queues. The dispatch table must be initialized by IoCsqInitialize.

[in, optional] PeekContext

A pointer to a driver-defined context value. IoCsqRemoveNextIrp passes this parameter to the driver's CsqPeekNextIrp routine. For more information, see the following Remarks section.

Return value

This routine returns a pointer to the next matching IRP in the queue, or NULL if no more IRPs are available. The routine only returns IRPs that have not yet been canceled.

Remarks

IoCsqRemoveNextIrp uses the queue's dispatch routines to remove the IRP. The IoCsqRemoveNextIrp routine:

Calls the queue's CsqAcquireLock routine to lock the queue.
Calls the queue's CsqPeekNextIrp routine to find the next matching IRP in the queue. IoCsqRemoveNextIrp passes the value of the PeekContext parameter as the PeekContext parameter of CsqPeekNextIrp. CsqPeekNextIrp returns a pointer to the next matching IRP, or NULL if there is no matching IRP.
If the return value of CsqPeekNextIrp is non-NULL, IoCsqRemoveNextIrp calls the queue's CsqRemoveIrp routine to remove the IRP.
Calls the queue's CsqReleaseLock routine to unlock the queue.

For more information, see Cancel-Safe IRP Queues.

Note that IoCsqXxx routines use the DriverContext[3] member of the IRP to hold IRP context information. Drivers that use these routines to queue IRPs must leave that member unused.

Callers of IoCsqRemoveNextIrp must be running at an IRQL <= DISPATCH_LEVEL. The driver's callback routines must work correctly at that IRQL.

Requirements

Requirement	Value
Minimum supported client	Available in Windows XP and later versions of Windows. Drivers that must also work on Windows 2000 and Windows 98/Me can instead link to Csq.lib to use the routine.
Target Platform	Universal
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL (see Remarks section)