WdfIoQueueGetState function (wdfio.h)

Article
02/22/2024

[Applies to KMDF and UMDF]

The WdfIoQueueGetState method returns the status of a specified I/O queue.

Syntax

WDF_IO_QUEUE_STATE WdfIoQueueGetState(
  [in]            WDFQUEUE Queue,
  [out, optional] PULONG   QueueRequests,
  [out, optional] PULONG   DriverRequests
);

Parameters

[in] Queue

A handle to a framework queue object.

[out, optional] QueueRequests

A pointer to a location that receives the number of I/O requests that are currently in the I/O queue and have not been delivered to the driver. This pointer is optional and can be NULL.

[out, optional] DriverRequests

A pointer to a location that receives the number of I/O requests that have been delivered to the driver but that the driver has not completed or canceled. This pointer is optional and can be NULL.

Return value

WdfIoQueueGetState returns a WDF_IO_QUEUE_STATE-typed value, which can contain the bitwise OR of several WDF_IO_QUEUE_STATE enumerators.

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

Remarks

After calling WdfIoQueueGetState, your driver can pass the received state value to the following functions, which are defined in Wdfio.h:

WDF_IO_QUEUE_DRAINED, which returns TRUE if the queue is drained.
WDF_IO_QUEUE_IDLE, which returns TRUE if the queue is idle.
WDF_IO_QUEUE_PURGED, which returns TRUE if the queue is purged.
WDF_IO_QUEUE_READY, which returns TRUE if the queue is ready.
WDF_IO_QUEUE_STOPPED, which returns TRUE if the queue is stopped.

If your driver uses the framework's automatic synchronization, the I/O queue's status will not change between the time that the WdfIoQueueGetState method obtains status information from the framework and the time that the method returns. Otherwise the queue's status might change before the WdfIoQueueGetState method returns.

For more information about the WdfIoQueueGetState method, see Obtaining I/O Queue Properties.

Examples

The following code example is a routine that returns TRUE if a specified I/O queue is idle.

BOOLEAN
IsQueueIdle(
    IN WDFQUEUE Queue
    )
{
    WDF_IO_QUEUE_STATE queueStatus;
    queueStatus = WdfIoQueueGetState(
                                     Queue,
                                     NULL,
                                     NULL
                                     );
    return (WDF_IO_QUEUE_IDLE(queueStatus)) ? TRUE : FALSE;
}

Requirements

Requirement	Value
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	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Share via