IWDFIoRequest2::RetrieveOutputBuffer method

The RequestRetrieveOutputBuffer method retrieves an I/O request's output buffer.

Syntax


HRESULT RetrieveOutputBuffer(
  [in]             SIZE_T MinimumRequiredCb,
  [out]            PVOID *Buffer,
  [out, optional]  SIZE_T *BufferCb
);

Parameters

MinimumRequiredCb [in]

The minimum buffer size, in bytes, that the driver needs to process the I/O request. This value can be zero if there is no minimum buffer size.

Buffer [out]

A pointer to a location that receives the buffer's address.

BufferCb [out, optional]

A pointer to a location that receives the buffer's size, in bytes. This parameter is optional and can be NULL.

Return value

RequestRetrieveOutputBuffer 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, or the size of the output buffer is less than the minimum size that MinimumRequiredCb specifies.

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 output buffer receives information, such as data from a disk, that the driver provides to the originator of the request. Your driver can call RequestRetrieveOutputBuffer 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 RequestRetrieveOutputBuffer 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 RequestRetrieveOutputBuffer returns S_OK, the driver receives the address and, optionally, the size of the output buffer.

The driver can access the retrieved buffer until it completes the I/O request.

Instead of calling RequestRetrieveOutputBuffer, the driver can call IWDFIoRequest2::RetrieveOutputMemory, which creates a framework memory object that represents the buffer.

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 a segment of a serial port driver's IQueueCallbackDeviceIoControl::OnDeviceIoControl callback function. The code segment obtains the I/O request's output buffer and then transfers baud rate information from the device to the buffer.


VOID
STDMETHODCALLTYPE
  CMyQueue::OnDeviceIoControl(
    __in IWDFIoQueue *pWdfQueue,
    __in IWDFIoRequest *pWdfRequest,
    __in ULONG ControlCode,
    __in SIZE_T InputBufferSizeInBytes,
    __in SIZE_T OutputBufferSizeInBytes
    )
{
    HRESULT hr;
    //
    // Declare an IWDFIoRequest2 interface pointer and obtain the
    // IWDFIoRequest2 interface from the IWDFIoRequest interface.
    //
    CComQIPtr<IWDFIoRequest2> r2 = pWdfRequest;

    switch (ControlCode)
    {
        case IOCTL_SERIAL_GET_BAUD_RATE:
        {
            SERIAL_BAUD_RATE *pBaudRateBuffer;
            hr = pWdfRequest2->RetrieveOutputBuffer(sizeof(SERIAL_BAUD_RATE),
                                                    (PVOID*) &pBaudRateBuffer,
                                                    NULL);
            if (SUCCEEDED(hr))
                  {
                      RtlZeroMemory(pBaudRateBuffer, sizeof(SERIAL_BAUD_RATE));
                      pBaudRateBuffer->BaudRate = m_Device->GetBaudRate();
                      reqCompletionInfo = sizeof(SERIAL_BAUD_RATE);
                  }
            
        }
        break;
        ...
    }
    ...
}

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::RetrieveInputMemory
IWDFIoRequest2::RetrieveOutputMemory

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft