IWDFIoRequest2：：RetrieveOutputMemory 方法 (wudfddi.h)

项目
03/05/2024

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

RetrieveOutputMemory 方法检索表示 I/O 请求输出缓冲区的框架内存对象的 IWDFMemory 接口。

语法

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

参数

[out] Memory

接收指向 UMDF 内存对象的 IWDFMemory 接口的指针的位置的地址。

返回值

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

返回代码	说明
HRESULT_FROM_WIN32 (ERROR_INSUFFICIENT_BUFFER)	I/O 请求未提供输入缓冲区。
E_OUTOFMEMORY	内存不足，无法检索缓冲区。驱动程序应使用错误状态值完成请求。

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

注解

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

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

如果 RetrieveOutputMemory 返回S_OK，驱动程序将收到指向表示输出缓冲区的 UMDF 内存对象的 IWDFMemory 接口的指针。若要访问缓冲区，驱动程序必须调用 IWDFMemory：：GetDataBuffer。

驱动程序可以访问检索到的框架内存对象，直到它完成 I/O 请求。在驱动程序完成 I/O 请求之前，它必须调用 IWDFMemory：：Release。

驱动程序可以调用 IWDFIoRequest2：：RetrieveOutputBuffer，以检索缓冲区的地址和长度，而不是调用 RetrieveOutputMemory。

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

示例

下面的代码示例演示 IQueueCallbackRead：：OnRead 回调函数如何获取表示读取请求输出缓冲区的框架内存对象的 IWDFMemory 接口。然后，该示例格式化读取请求并将其发送到 USB I/O 目标。

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

要求

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