WdfIoQueueDrainSynchronously function (wdfio.h)

[Applies to KMDF and UMDF]

The WdfIoQueueDrainSynchronously 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. The method returns after all requests are completed or canceled.

Syntax

void WdfIoQueueDrainSynchronously(
  [in] WDFQUEUE Queue
);

Parameters

[in] Queue

A handle to a framework queue object.

Return value

None

Remarks

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

After a driver calls WdfIoQueueDrainSynchronously, 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.

The driver should not call another method that changes queue state, such as WdfIoQueuePurge or WdfIoQueueStart, before the call to WdfIoQueueDrainSynchronously has returned.

As a best practice, you should only call WdfIoQueueDrainSynchronously when you are certain that the queue's pending I/O requests will complete in a timely fashion. Otherwise, use WdfIoQueuePurgeSynchronously. 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.

Do not call WdfIoQueueDrainSynchronously from the following queue object event callback functions, regardless of the queue with which the event callback function is associated:

EvtIoDefault EvtIoDeviceControl EvtIoInternalDeviceControl EvtIoRead EvtIoWrite

Examples

The following code example drains an I/O queue.

WdfIoQueueDrainSynchronously(queue);

Requirements

See also

WdfIoQueueDrain