IWDFIoRequest2::RetrieveOutputMemory method (wudfddi.h)

[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 RetrieveOutputMemory method retrieves the IWDFMemory interface of a framework memory object that represents an I/O request's output buffer.

Syntax

HRESULT RetrieveOutputMemory(
  [out] IWDFMemory **Memory
);

Parameters

[out] Memory

The address of a location that receives a pointer to the IWDFMemory interface of a UMDF memory object.

Return value

RetrieveOutputMemory returns S_OK if the operation succeeds. Otherwise, this method can return the following value:

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

Remarks

A request's output buffer receives information, such as data from a disk, that the driver provides to the originator of the request. Your driver can call RetrieveOutputMemory to obtain the output buffer for a read request or a device I/O control request, but not for a write request (because write requests do not provide output data).

The RetrieveOutputMemory method retrieves the output buffer for I/O requests that use the buffered I/O or direct I/O method for accessing data buffers.

If RetrieveOutputMemory returns S_OK, the driver receives a pointer to the IWDFMemory interface of a UMDF memory object that represents the output buffer. To access the buffer, the driver must call IWDFMemory::GetDataBuffer.

The driver can access the retrieved framework memory object until it completes the I/O request. Before the driver completes the I/O request, it must call IWDFMemory::Release.

Instead of calling RetrieveOutputMemory, the driver can call IWDFIoRequest2::RetrieveOutputBuffer, which retrieves the buffer's address and length.

For more information about accessing an I/O request's data buffers, see Accessing Data Buffers in UMDF-Based Drivers.

Examples

The following code example shows how an IQueueCallbackRead::OnRead callback function can obtain the IWDFMemory interface of the framework memory object that represents a read request's output buffer. The example then formats and sends the read request to a USB I/O target.

VOID
STDMETHODCALLTYPE
  CMyQueue::OnRead(
     __in IWDFIoQueue *pWdfQueue,
     __in IWDFIoRequest *pWdfRequest,
     __in SIZE_T BytesToRead
     )
{
    HRESULT hr = S_OK;
    IWDFMemory * pOutputMemory = NULL;

    //
    // Declare an IWDFIoRequest2 interface pointer and obtain the
    // IWDFIoRequest2 interface from the IWDFIoRequest interface.
    //
    CComQIPtr<IWDFIoRequest2> r2 = pWdfRequest;

    r2->RetrieveOutputMemory(&pOutputMemory);
    if (FAILED(hr)) goto Exit;

    hr = m_Device->GetInputPipe()->FormatRequestForRead(pWdfRequest,
                                                        NULL,
                                                        pOutputMemory,
                                                        NULL,
                                                        NULL);
Exit:
    if (FAILED(hr))
    {
        pWdfRequest->Complete(hr);
    }
    else
    {
        ForwardFormattedRequest(pWdfRequest, m_Device->GetInputPipe());
    }
    SAFE_RELEASE(pOutputMemory);
    return;
}

Requirements

See also

IWDFIoRequest2

IWDFIoRequest2::RetrieveInputBuffer

IWDFIoRequest2::RetrieveInputMemory

IWDFIoRequest2::RetrieveOutputBuffer

IWDFIoRequest::GetInputMemory

IWDFIoRequest::GetOutputMemory