WdfIoQueueReadyNotify - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
// wdfio.h
NTSTATUS WdfIoQueueReadyNotify(
[in] WDFQUEUE Queue,
[in, optional] PFN_WDF_IO_QUEUE_STATE QueueReady,
[in, optional] WDFCONTEXT Context
);
View the official Windows Driver Kit DDI referenceNo description available.
[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.
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.
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. |
This method also might return other NTSTATUS values.
A bug check occurs if the driver supplies an invalid object handle.
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.
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
);
WdfIoQueueRetrieveRequestByFileObject