WdfIoQueueReadyNotify function (wdfio.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfIoQueueReadyNotify method registers (or deregisters) an event callback function that the framework calls each time a specified I/O queue that was previously empty receives one or more I/O requests.

Syntax

NTSTATUS WdfIoQueueReadyNotify(
  [in]           WDFQUEUE               Queue,
  [in, optional] PFN_WDF_IO_QUEUE_STATE QueueReady,
  [in, optional] WDFCONTEXT             Context
);

Parameters

[in] Queue

A handle to a framework queue object.

[in, optional] QueueReady

A pointer to a driver-supplied EvtIoQueueState callback function, if the driver is registering for ready notification, or NULL if the driver is deregistering.

[in, optional] Context

An untyped pointer to driver-supplied context information that the framework passes to the EvtIoQueueState callback function, if the driver is registering for ready notification, or NULL if the driver is deregistering.

Return value

WdfIoQueueReadyNotify returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return one of the following values:

Return code	Description
STATUS_INVALID_PARAMETER	The driver supplied an invalid handle.
STATUS_INVALID_DEVICE_REQUEST	This value is returned if one of the following occurs: The DispatchType member of the specified I/O queue's WDF_IO_QUEUE_CONFIG structure is not WdfIoQueueDispatchManual. The driver had previously called WdfIoQueueReadyNotify and registered an EvtIoQueueState callback function. The driver is attempting to deregister its notification callback function, but a callback function is not registered or the driver has not called WdfIoQueueStop or WdfIoQueueStopSynchronously.

Return code

Description

STATUS_INVALID_PARAMETER

The driver supplied an invalid handle.

STATUS_INVALID_DEVICE_REQUEST

This value is returned if one of the following occurs:

The DispatchType member of the specified I/O queue's WDF_IO_QUEUE_CONFIG structure is not WdfIoQueueDispatchManual.
The driver had previously called WdfIoQueueReadyNotify and registered an EvtIoQueueState callback function.
The driver is attempting to deregister its notification callback function, but a callback function is not registered or the driver has not called WdfIoQueueStop or WdfIoQueueStopSynchronously.

This method also might return other NTSTATUS values.

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

Remarks

After a driver has called WdfIoQueueReadyNotify to register a EvtIoQueueState callback function, the framework calls the callback function each time the specified queue's state changes from empty to non-empty. Specifically, the framework calls EvtIoQueueState when a request arrives on an empty queue, even if the driver still owns previously delivered requests from the queue that it has not yet completed. You can modify the IRQL at which the callback runs by specifying ExecutionLevel in WDF_OBJECT_ATTRIBUTES at queue creation time. For more info, see the Remarks section ofEVT_WDF_IO_QUEUE_STATE.

The framework does not call EvtIoQueueState while the specified queue is stopped. When the queue starts, the framework calls EvtIoQueueState if the queue is non-empty.

Your driver can call WdfIoQueueReadyNotify only for I/O queues that use the manual dispatching method.

The EvtIoQueueState callback function typically calls WdfIoQueueRetrieveNextRequest or WdfIoQueueRetrieveRequestByFileObject in a loop to retrieve all of the requests that have arrived since the last time the callback function executed.

To stop the framework from calling the EvtIoQueueState callback function, the driver must call WdfIoQueueReadyNotify again with the QueueReady parameter set to NULL. However, the driver must first call WdfIoQueueStop or WdfIoQueueStopSynchronously to stop the I/O queue. The driver can subsequently call WdfIoQueueStart to restart the queue.

When a driver calls WdfIoQueueReadyNotify to register a EvtIoQueueState callback function, it is possible for the framework to call the callback function before WdfIoQueueReadyNotify returns.

For more information about the WdfIoQueueReadyNotify method, see Dispatching Methods for I/O Requests.

Examples

The following code example registers a driver's EvtIoQueueReady function, so that this function will be called when the specified I/O queue receives an I/O request.

Status = WdfIoQueueReadyNotify(
                               ReadQueue,
                               EvtIoQueueReady,
                               myQueueContext
                               );

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