[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.
VOID WdfIoQueueDrain( _In_ WDFQUEUE Queue, _In_opt_ PFN_WDF_IO_QUEUE_STATE DrainComplete, _In_opt_ WDFCONTEXT Context );
A handle to a framework queue object.
A pointer to a driver-supplied EvtIoQueueState callback function. This parameter is optional and can be NULL.
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.
A bug check occurs if the driver supplies an invalid object handle.
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.
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.
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 );
|Minimum KMDF version||1.0|
|Minimum UMDF version||2.0|
|Header||wdfio.h (include Wdf.h)|
|Library||Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)|
|DDI compliance rules||ChangeQueueState, DriverCreate, EvtSurpriseRemoveNoSuspendQueue, KmdfIrql, KmdfIrql2, NoCancelFromEvtSurpriseRemove|