WdfIoQueuePurge method

[Applies to KMDF and UMDF]

The WdfIoQueuePurge method causes the framework to stop queuing I/O requests to an I/O queue and to cancel unprocessed requests.

Syntax


VOID WdfIoQueuePurge(
  [in]            WDFQUEUE Queue,
  [in, optional]  PFN_WDF_IO_QUEUE_STATE PurgeComplete,
  [in, optional]  WDFCONTEXT Context
);

Parameters

Queue [in]

A handle to a framework queue object.

PurgeComplete [in, optional]

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

Context [in, optional]

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 WdfIoQueuePurge, the framework stops adding I/O requests to the specified queue. The framework cancels all requests that it has not delivered to the target device and calls the driver's CompletionRoutine callback function for each. The framework also attempts to cancel (by calling IoCancelIrp) any requests delivered to the target device that were not marked WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE.

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.

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

If the driver calls WdfRequestRequeue after calling WdfIoQueuePurge, the requeue attempt may succeed before the purge is complete. In versions 1.9 and earlier of KMDF, this sequence causes the operating system to crash. This problem is fixed in KMDF version 1.11 and later.

For more information about the WdfIoQueuePurge method, see Managing I/O Queues.

Examples

The following code example purges an I/O queue and does not call a callback function when all requests that were delivered to the driver have been completed or canceled.


WdfIoQueuePurge(
                ReadQueue, 
                WDF_NO_EVENT_CALLBACK, 
                WDF_NO_CONTEXT 
                );

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

<= DISPATCH_LEVEL

DDI compliance rules

ChangeQueueState, DriverCreate, EvtSurpriseRemoveNoSuspendQueue, KmdfIrql, KmdfIrql2, NoCancelFromEvtSurpriseRemove

See also

WdfIoQueueDrain
WdfIoQueuePurgeSynchronously
EvtIoQueueState

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft