IWDFIoRequest2::RetrieveOutputMemory-Methode (wudfddi.h)

Artikel
03/01/2024

[Warnung: UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. UMDF 1 werden keine neuen Features hinzugefügt, und die Unterstützung für UMDF 1 für neuere Versionen von Windows 10 ist eingeschränkt. Universelle Windows-Treiber müssen UMDF 2 verwenden. Weitere Informationen finden Sie unter Erste Schritte mit UMDF.]

Die RetrieveOutputMemory-Methode ruft die IWDFMemory-Schnittstelle eines Frameworkspeicherobjekts ab, das den Ausgabepuffer einer E/A-Anforderung darstellt.

Syntax

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

Parameter

[out] Memory

Die Adresse eines Speicherorts, der einen Zeiger auf die IWDFMemory-Schnittstelle eines UMDF-Speicherobjekts empfängt.

Rückgabewert

RetrieveOutputMemory gibt S_OK zurück, wenn der Vorgang erfolgreich ist. Andernfalls kann diese Methode den folgenden Wert zurückgeben:

Rückgabecode	Beschreibung
HRESULT_FROM_WIN32 (ERROR_INSUFFICIENT_BUFFER)	Die E/A-Anforderung hat keinen Eingabepuffer bereitgestellt.
E_OUTOFMEMORY	Zum Abrufen des Puffers ist nicht genügend Arbeitsspeicher verfügbar. Der Treiber sollte die Anforderung mit einem Fehler status Wert abschließen.

Diese Methode gibt möglicherweise einen der anderen Werte zurück, die Winerror.h enthält.

Hinweise

Der Ausgabepuffer einer Anforderung empfängt Informationen, z. B. Daten von einem Datenträger, die der Treiber dem Absender der Anforderung zur Verfügung stellt. Ihr Treiber kann RetrieveOutputMemory aufrufen, um den Ausgabepuffer für eine Leseanforderung oder eine Geräte-E/A-Steuerungsanforderung abzurufen, aber nicht für eine Schreibanforderung (da Schreibanforderungen keine Ausgabedaten bereitstellen).

Die RetrieveOutputMemory-Methode ruft den Ausgabepuffer für E/A-Anforderungen ab, die die gepufferte E/A - oder direkte E/A-Methode für den Zugriff auf Datenpuffer verwenden.

Wenn RetrieveOutputMemory S_OK zurückgibt, empfängt der Treiber einen Zeiger auf die IWDFMemory-Schnittstelle eines UMDF-Speicherobjekts, das den Ausgabepuffer darstellt. Um auf den Puffer zuzugreifen, muss der Treiber IWDFMemory::GetDataBuffer aufrufen.

Der Treiber kann auf das abgerufene Frameworkspeicherobjekt zugreifen, bis er die E/A-Anforderung abgeschlossen hat. Bevor der Treiber die E/A-Anforderung abgeschlossen hat, muss er IWDFMemory::Release aufrufen.

Anstatt RetrieveOutputMemory aufzurufen, kann der Treiber IWDFIoRequest2::RetrieveOutputBuffer aufrufen, wodurch die Adresse und Länge des Puffers abgerufen wird.

Weitere Informationen zum Zugreifen auf die Datenpuffer einer E/A-Anforderung finden Sie unter Zugreifen auf Datenpuffer in UMDF-Based-Treibern.

Beispiele

Das folgende Codebeispiel zeigt, wie eine IQueueCallbackRead::OnRead-Rückruffunktion die IWDFMemory-Schnittstelle des Frameworkspeicherobjekts abrufen kann, das den Ausgabepuffer einer Leseanforderung darstellt. Im Beispiel wird dann die Leseanforderung formatiert und an ein USB-E/A-Ziel gesendet.

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

Anforderungen

Anforderung	Wert
Ende des Supports	In UMDF 2.0 und höher nicht verfügbar.
Zielplattform	Desktop
UMDF-Mindestversion	1.9
Kopfzeile	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll