IWDFIoRequest2：：RetrieveInputMemory 方法 (wudfddi.h)

發行項
03/01/2024

[警告： UMDF 2 是最新版的 UMDF，並取代 UMDF 1。所有新的 UMDF 驅動程式都應該使用 UMDF 2 來撰寫。未將新功能新增至 UMDF 1，而且較新版本的 Windows 10 上不支援 UMDF 1。通用 Windows 驅動程式必須使用 UMDF 2。如需詳細資訊，請參閱使用 UMDF 使用者入門。]

RetrieveInputMemory 方法會擷取架構記憶體物件的 IWDFMemory 介面，此介面代表 I/O 要求的輸入緩衝區。

語法

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

參數

[out] Memory

接收 UMDF記憶體物件之IWDFMemory 介面指標的位置位址。

傳回值

如果作業成功，RetrieveInputMemory 會傳回S_OK。否則，此方法可以傳回下列值：

傳回碼	Description
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	I/O 要求未提供輸出緩衝區。
E_OUTOFMEMORY	沒有足夠的記憶體可用來擷取緩衝區。驅動程式應該會以錯誤狀態值完成要求。

這個方法可能會傳回 Winerror.h 包含的其他其中一個值。

備註

要求的輸入緩衝區包含資訊，例如要寫入磁碟的數據，而要求提供的來源者。您的驅動程式可以呼叫 RetrieveInputMemory 來取得寫入要求或裝置 I/O 控制要求的輸入緩衝區，但不適用於讀取要求 (，因為讀取要求不提供輸入數據) 。

RetrieveInputMemory 方法會擷取 I/O 要求的輸入緩衝區，這些要求會使用緩衝 I/O 或直接 I/O 方法來存取數據緩衝區。

如果 RetrieveInputMemory 傳回S_OK，驅動程式會接收代表輸入緩衝區之 UMDF 記憶體物件的 IWDFMemory 介面指標。若要存取緩衝區，驅動程式必須呼叫 IWDFMemory：：GetDataBuffer。

驅動程式可以存取擷取的架構記憶體物件，直到完成 I/O 要求為止。驅動程式完成 I/O 要求之前，它必須呼叫 IWDFMemory：：Release。

驅動程式可以呼叫 IWDFIoRequest2：：RetrieveInputBuffer 來擷取緩衝區的地址和長度，而不是呼叫 RetrieveInputMemory。

如需存取 I/O 要求數據緩衝區的詳細資訊，請參閱存取 UMDF-Based 驅動程式中的數據緩衝區。

範例

下列程式代碼範例示範 IQueueCallbackWrite：：OnWrite 回呼函式如何取得架構記憶體物件的 IWDFMemory 介面，該介面代表寫入要求的輸入緩衝區。然後，此範例會將寫入要求格式化並傳送至USB I/O目標。

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

規格需求

需求	值
終止支援	UMDF 2.0 和更新版本中無法使用。
目標平台	桌面
最低UMDF版本	1.9
標頭	wudfddi.h (包括 Wudfddi.h)
Dll	WUDFx.dll