WdfIoQueueDrain function

[Applies to KMDF and UMDF]

The WdfIoQueueDrain method causes the framework to stop queuing I/O requests to an I/O queue, while allowing already-queued requests to be delivered and processed.

Syntax

void WdfIoQueueDrain(
  WDFQUEUE               Queue,
  PFN_WDF_IO_QUEUE_STATE DrainComplete,
  WDFCONTEXT             Context
);

Parameters

Queue

A handle to a framework queue object.

DrainComplete

A pointer to a driver-supplied EvtIoQueueState callback function. This parameter is optional and can be NULL.

Context

An untyped pointer to driver-supplied context information that the framework passes to the EvtIoQueueState callback function. This parameter is optional and can be NULL.

Return Value

None.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

After a driver calls WdfIoQueueDrain, the framework stops adding I/O requests to the specified queue. If the framework receives additional requests for the queue, it completes them with a completion status value of STATUS_INVALID_DEVICE_STATE.

If the driver supplies an EvtIoQueueState callback function, the framework calls it after all requests that were delivered to the driver have been completed or canceled.

The driver should not call another method that changes queue state, such as WdfIoQueuePurge or WdfIoQueueStart, before the framework has called EvtIoQueueState.

If a driver specifies NULL for DrainComplete, the driver can call another state changing operation before requests are completed.

As a best practice, you should only call WdfIoQueueDrain when you are certain that the queue's pending I/O requests will complete in a timely fashion. Otherwise, use WdfIoQueuePurge. For more information, see Managing I/O Queues.

After a driver has drained an I/O queue, it can restart the queue by calling WdfIoQueueStart.

Examples

The following code example drains an I/O queue and calls a driver's EvtIoQueueDrainComplete function when all requests that were delivered to the driver have been completed or canceled.

WdfIoQueueDrain(
                Queue,
                EvtIoQueueDrainComplete,
                (WDFCONTEXT) myQueueContext
                );

Requirements

   
Target Platform Universal
Minimum KMDF version 1.0
Minimum UMDF version 2.0
Header wdfio.h (include Wdf.h)
Library Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL "<= DISPATCH_LEVEL"
DDI compliance rules ChangeQueueState, DriverCreate, EvtSurpriseRemoveNoSuspendQueue, KmdfIrql, KmdfIrql2, NoCancelFromEvtSurpriseRemove

See Also

EvtIoQueueState

WdfIoQueueDrainSynchronously

WdfIoQueuePurge