WdfIoQueueDrainSynchronously method

[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

Queue [in]

A handle to a framework queue object.

Return value

None.

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

Remarks

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

Minimum KMDF version

1.0

Minimum UMDF version

2.0

Header

Wdfio.h (include Wdf.h)

Library

Wdf01000.sys (KMDF);
WUDFx02000.dll (UMDF)

IRQL

PASSIVE_LEVEL

DDI compliance rules

ChangeQueueState, DriverCreate, EvtSurpriseRemoveNoSuspendQueue, KmdfIrql, KmdfIrql2, NoCancelFromEvtSurpriseRemove

See also

WdfIoQueueDrain

 

 

Send comments about this topic to Microsoft

Afficher:
© 2014 Microsoft