IWDFIoRequest2::RetrieveInputMemory-Methode (wudfddi.h)

Artikel
08/08/2023

[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 in neueren 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 RetrieveInputMemory-Methode ruft die IWDFMemory-Schnittstelle eines Frameworkspeicherobjekts ab, das den Eingabepuffer einer E/A-Anforderung darstellt.

Syntax

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

Parameter

[out] Memory

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

Rückgabewert

RetrieveInputMemory 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 Ausgabepuffer 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 Eingabepuffer einer Anforderung enthält Informationen, z. B. Daten, die auf einen Datenträger geschrieben werden sollen, die der Absender der Anforderung bereitgestellt hat. Ihr Treiber kann RetrieveInputMemory aufrufen, um den Eingabepuffer für eine Schreibanforderung oder eine Geräte-E/A-Steuerungsanforderung zu erhalten, aber nicht für eine Leseanforderung (da Leseanforderungen keine Eingabedaten bereitstellen).

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

Wenn RetrieveInputMemory S_OK zurückgibt, empfängt der Treiber einen Zeiger auf die IWDFMemory-Schnittstelle eines UMDF-Speicherobjekts, das den Eingabepuffer 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 abschließt, muss er IWDFMemory::Release aufrufen.

Anstatt RetrieveInputMemory aufzurufen, kann der Treiber IWDFIoRequest2::RetrieveInputBuffer 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 IQueueCallbackWrite::OnWrite-Rückruffunktion die IWDFMemory-Schnittstelle des Frameworkspeicherobjekts abrufen kann, das den Eingabepuffer einer Schreibanforderung darstellt. Im Beispiel wird die Schreibanforderung dann formatiert und an ein USB-E/A-Ziel gesendet.

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

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