IWDFIoRequest2：：RetrieveOutputBuffer 方法 (wudfddi.h)

项目
03/05/2024

[警告： UMDF 2 是最新版本的 UMDF，取代了 UMDF 1。所有新的 UMDF 驱动程序都应使用 UMDF 2 编写。未向 UMDF 1 添加新功能，并且较新版本的 Windows 10 上对 UMDF 1 的支持有限。通用 Windows 驱动程序必须使用 UMDF 2。有关详细信息，请参阅使用 UMDF 入门。]

RequestRetrieveOutputBuffer 方法检索 I/O 请求的输出缓冲区。

语法

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

参数

[in] MinimumRequiredCb

驱动程序处理 I/O 请求所需的最小缓冲区大小（以字节为单位）。如果没有最小缓冲区大小，此值可以为零。

[out] Buffer

指向接收缓冲区地址的位置的指针。

[out, optional] BufferCb

指向接收缓冲区大小（以字节为单位）的位置的指针。此参数是可选的，可以为 NULL。

返回值

如果操作成功，RequestRetrieveOutputBuffer 将返回S_OK。否则，此方法可以返回以下值：

返回代码	说明
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	I/O 请求未提供输出缓冲区，或者输出缓冲区的大小小于 MinimumRequiredCb 指定的最小大小。
E_OUTOFMEMORY	内存不足，无法检索缓冲区。驱动程序应使用错误状态值完成请求。

此方法可能会返回 Winerror.h 包含的其他值之一。

注解

请求的输出缓冲区接收驱动程序提供给请求发起者的信息，例如磁盘中的数据。驱动程序可以调用 RequestRetrieveOutputBuffer 来获取读取请求或设备 I/O 控制请求的输出缓冲区，但不能为写入请求获取输出缓冲区 (因为写入请求不提供输出数据) 。

RequestRetrieveOutputBuffer 方法检索使用缓冲 I/O 或直接 I/O 方法来访问数据缓冲区的 I/O 请求的输出缓冲区。

如果 RequestRetrieveOutputBuffer 返回S_OK，驱动程序将接收地址以及输出缓冲区的大小（可选）。

驱动程序可以访问检索到的缓冲区，直到它完成 I/O 请求。

驱动程序可以调用 IWDFIoRequest2：：RetrieveOutputMemory，以创建表示缓冲区的框架内存对象，而不是调用 RequestRetrieveOutputBuffer。

有关访问 I/O 请求的数据缓冲区的详细信息，请参阅访问 UMDF-Based 驱动程序中的数据缓冲区。

示例

下面的代码示例演示串行端口驱动程序的 IQueueCallbackDeviceIoControl：：OnDeviceIoControl 回调函数的一段。代码段获取 I/O 请求的输出缓冲区，然后将波特率信息从设备传输到缓冲区。

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;
        ...
    }
    ...
}

要求

要求	值
结束支持	在 UMDF 2.0 及更高版本中不可用。
目标平台	桌面
最低 UMDF 版本	1.9
标头	wudfddi.h (包括 Wudfddi.h)
DLL	WUDFx.dll