IWDFIoTarget2::FormatRequestForQueryInformation method (wudfddi.h)

Article
10/21/2021

[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 FormatRequestForQueryInformation method formats an I/O request to obtain information about a file, but it does not send the request to an I/O target.

Syntax

HRESULT FormatRequestForQueryInformation(
  [in]           IWDFIoRequest              *pRequest,
  [in]           WDF_FILE_INFORMATION_CLASS InformationClass,
  [in, optional] IWDFFile                   *pFile,
  [in, optional] IWDFMemory                 *pInformationMemory,
  [in, optional] PWDFMEMORY_OFFSET          pInformationMemoryOffset
);

Parameters

[in] pRequest

A pointer to the IWDFIoRequest interface of the request object that represents the I/O request.

[in] InformationClass

A WDF_FILE_INFORMATION_CLASS-typed value that specifies the type of information to obtain.

[in, optional] pFile

A pointer to the IWDFFile interface of the file object that is associated with the I/O request. This parameter is required for local and remote I/O targets, and is optional (can be NULL) for file handle I/O targets.

[in, optional] pInformationMemory

A pointer to the IWDFMemory interface of a memory object. This object represents the output buffer, which receives the file information that the InformationClass parameter specifies. This parameter is optional and can be NULL.

[in, optional] pInformationMemoryOffset

A pointer to a WDFMEMORY_OFFSET structure that supplies optional byte offset and length values. The framework uses these values to determine the beginning address and length, within the output buffer, for the data transfer. If this pointer is NULL, the data transfer begins at the beginning of the output buffer, and the transfer size is the buffer size.

Return value

FormatRequestForQueryInformation returns S_OK if the operation succeeds. Otherwise, the method might return the following value:

Return code	Description
E_OUTOFMEMORY	The framework was unable to allocate memory.

This method might return one of the other values that Winerror.h contains.

Remarks

Use the FormatRequestForQueryInformation method, followed by the IWDFIoRequest::Send method, to send requests either synchronously or asynchronously to an I/O target.

Examples

The following code example is part of an IQueueCallbackDefaultIoHandler::OnDefaultIoHandler callback function. If the callback function receives a query information request, it sends the request to the device's default I/O target.

void
CMyQueue::OnDefaultIoHandler(
 IWDFIoQueue*  pQueue,
 IWDFIoRequest*  pRequest
    )
{
    HRESULT hr;
    IWDFDevice *pDevice;
    IWDFIoTarget *pTarget;
    IWDFFile *pFile;
    IWDFMemory *pOutMemory;
    WDF_FILE_INFORMATION_CLASS infoClass;

    //
    // Obtain the device, default I/O target, and file object.
    //
    pQueue->GetDevice(&pDevice);
    pDevice->GetDefaultIoTarget(&pTarget);
    pRequest->GetFileObject(&pFile);

    if (WdfRequestQueryInformation==pRequest->GetType())
    {
        //
        // Declare an IWDFIoRequest2 interface pointer and obtain the
        // IWDFIoRequest2 interface from the IWDFIoRequest interface.
        //
        CComQIPtr<IWDFIoRequest2> r2 = pRequest;

        // 
        // Declare an IWDFIoTarget2 interface pointer and obtain the
        // IWDFIoTarget2 interface from the IWDFIoTarget interface.
        //
        CComQIPtr<IWDFIoTarget2> target2(pTarget);

        // 
        // Get the I/O request's output buffer.
        // 
        hr = pWdfRequest2->RetrieveOutputMemory(&pOutMemory);
        if (!SUCCEEDED(hr)) goto Error;

        // 
        // Get the I/O request's parameters.
        // 
        hr = pWdfRequest2->GetQueryInformationParameters(&infoClass,
                                                         NULL);
        if (!SUCCEEDED(hr)) goto Error;

        //
        // Format a query information request and send it to the I/O target.
        //
        hr = target2->FormatRequestForQueryInformation(pRequest,
                                                       infoClass,
                                                       pFile,
                                                       pOutMemory,
                                                       NULL);
        if (!SUCCEEDED(hr)) goto Error;
        hr = pRequest->Send(pTarget,
                            WDF_REQUEST_SEND_OPTION_SYNCHRONOUS,
                            0);
    }
...
Error;
    //
    // Release objects.
    //
    SAFE_RELEASE(pDevice);
    SAFE_RELEASE(pTarget);
    SAFE_RELEASE(pFile);
    SAFE_RELEASE(pOutMemory);
}

Requirements

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