IWDFIoRequest2：：RetrieveOutputMemory 方法（wudfddi.h）

發行項
02/07/2025

[警告： 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 介面之 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，驅動程式會收到代表輸出緩衝區之 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