IWDFIoRequest2::RetrieveInputMemory method

The RetrieveInputMemory method retrieves the IWDFMemory interface of a framework memory object that represents an I/O request's input buffer.

Syntax


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

Parameters

Memory [out]

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

Return value

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

Return codeDescription
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)

The I/O request did not provide an output buffer.

E_OUTOFMEMORY

Not enough memory is available to retrieve the buffer. The driver should complete the request with an error status value.

 

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

Remarks

A request's input buffer contains information, such as data to be written to a disk, that the originator of the request supplied. Your driver can call RetrieveInputMemory to obtain the input buffer for a write request or a device I/O control request, but not for a read request (because read requests do not provide input data).

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

If RetrieveInputMemory returns S_OK, the driver receives a pointer to the IWDFMemory interface of a UMDF memory object that represents the input 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 RetrieveInputMemory, the driver can call IWDFIoRequest2::RetrieveInputBuffer, 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 IQueueCallbackWrite::OnWrite callback function can obtain the IWDFMemory interface of the framework memory object that represents a write request's input buffer. The example then formats and sends the write request to a USB I/O target.


VOID
STDMETHODCALLTYPE
  CMyQueue::OnWrite(
    __in IWDFIoQueue *pWdfQueue,
    __in IWDFIoRequest *pWdfRequest,
    __in SIZE_T BytesToWrite
    )
{
    HRESULT hr = S_OK;
    IWDFMemory * pInputMemory = NULL;
    IWDFUsbTargetPipe * pOutputPipe = m_Device->GetOutputPipe();
    //
    // Declare an IWDFIoRequest2 interface pointer and obtain the
    // IWDFIoRequest2 interface from the IWDFIoRequest interface.
    //
    CComQIPtr<IWDFIoRequest2> r2 = pWdfRequest;

    hr = r2->RetrieveInputMemory(&pInputMemory);
    if (FAILED(hr)) goto Exit;

    hr = pOutputPipe->FormatRequestForWrite(
                                           pWdfRequest,
                                           NULL, //pFile
                                           pInputMemory,
                                           NULL, //Memory offset
                                           NULL  //DeviceOffset
                                           );
Exit:
    if (FAILED(hr))
    {
        pWdfRequest->Complete(hr);
    }
    else
    {
        ForwardFormattedRequest(pWdfRequest, pOutputPipe);
    }
    SAFE_RELEASE(pInputMemory);
 return;
}

Requirements

End of support

Unavailable in UMDF 2.0 and later.

Minimum UMDF version

1.9

Header

Wudfddi.h (include Wudfddi.h)

DLL

WUDFx.dll

See also

IWDFIoRequest2
IWDFIoRequest::GetInputMemory
IWDFIoRequest::GetOutputMemory
IWDFIoRequest2::RetrieveInputBuffer
IWDFIoRequest2::RetrieveOutputBuffer
IWDFIoRequest2::RetrieveOutputMemory

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft