WdfIoQueueReadyNotify method

[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

Queue [in]

A handle to a framework queue object.

QueueReady [in, optional]

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

Context [in, optional]

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 codeDescription
STATUS_INVALID_PARAMETER

The driver supplied an invalid handle.

STATUS_INVALID_DEVICE_REQUEST

This value is returned if one of the following occurs:

 

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.

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

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, KmdfIrql, KmdfIrql2

See also

WdfIoQueueRetrieveNextRequest
WdfIoQueueRetrieveRequestByFileObject
WDF_IO_QUEUE_CONFIG
EvtIoQueueState

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft