WdfIoQueueReadyNotify function (wdfio.h)

[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:

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

See also

EvtIoQueueState

WDF_IO_QUEUE_CONFIG

WdfIoQueueRetrieveNextRequest

WdfIoQueueRetrieveRequestByFileObject