IWDFIoQueue::RetrieveNextRequestByFileObject method (wudfddi.h)

Article
08/12/2022

Warning

UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.

The RetrieveNextRequestByFileObject method retrieves from an I/O queue the next I/O request whose file object matches the specified file object.

Syntax

HRESULT RetrieveNextRequestByFileObject(
  [in]  IWDFFile      *pFile,
  [out] IWDFIoRequest **ppRequest
);

Parameters

[in] pFile

A pointer to the IWDFFile interface for the file object that is used to retrieve the next I/O request whose file object matches this supplied file object.

[out] ppRequest

A pointer to a buffer that receives a pointer to the IWDFIoRequest interface for the next request object whose file object matches the supplied file object, or receives NULL if the queue is empty or if the next request is not found.

Return value

RetrieveNextRequestByFileObject returns one of the following values:

Return code	Description
S_OK	The next I/O request was successfully retrieved from the I/O queue.
HRESULT_FROM_NT(STATUS_WDF_PAUSED)	The queue is not dispatching requests. This situation occurs if the device undergoes a power state transition and all of the queues are stopped from dispatching requests or if the driver explicitly called IWDFIoQueue::Stop to stop dispatching requests. This situation can also occur if the driver attempts to remove a request from a manual queue that is power managed and that is powered down or if the queue is paused.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	No requests were in the queue.
HRESULT_FROM_NT(STATUS_INVALID_DEVICE_STATE)	The call was made to retrieve the request from a parallel queue.

RetrieveNextRequestByFileObject might also return other HRESULT values.

Remarks

If a driver configures an I/O queue for manual dispatching of I/O requests, the driver can call the RetrieveNextRequestByFileObject method to obtain the next request whose file object matches the supplied file object from the queue. For more information about manually dispatching I/O requests, see Configuring Dispatch Mode for an I/O Queue.

If multiple I/O requests whose file objects match the file object that the pFile parameter points to exist in the I/O queue, the first I/O request is returned.

Examples

For a code example of how to use the RetrieveNextRequestByFileObject method, see IWDFIoQueue::RetrieveNextRequest.

Requirements

Requirement	Value
End of support	Unavailable in UMDF 2.0 and later.
Target Platform	Desktop
Minimum UMDF version	1.5
Header	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll

Share via