IWDFIoRequest2::RetrieveOutputBuffer-Methode (wudfddi.h)

Artikel
02/27/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 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 RequestRetrieveOutputBuffer-Methode ruft den Ausgabepuffer einer E/A-Anforderung ab.

Syntax

HRESULT RetrieveOutputBuffer(
  [in]            SIZE_T MinimumRequiredCb,
  [out]           PVOID  *Buffer,
  [out, optional] SIZE_T *BufferCb
);

Parameter

[in] MinimumRequiredCb

Die minimale Puffergröße in Bytes, die der Treiber zum Verarbeiten der E/A-Anforderung benötigt. Dieser Wert kann null sein, wenn keine Mindestpuffergröße vorhanden ist.

[out] Buffer

Ein Zeiger auf einen Speicherort, der die Adresse des Puffers empfängt.

[out, optional] BufferCb

Ein Zeiger auf einen Speicherort, der die Größe des Puffers in Bytes empfängt. Dieser Parameter ist optional und kann NULL sein.

Rückgabewert

RequestRetrieveOutputBuffer 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, oder die Größe des Ausgabepuffers ist kleiner als die von MinimumRequiredCb festgelegte Mindestgröße.
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 RequestRetrieveOutputBuffer 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 RequestRetrieveOutputBuffer-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 RequestRetrieveOutputBuffer S_OK zurückgibt, erhält der Treiber die Adresse und optional die Größe des Ausgabepuffers.

Der Treiber kann auf den abgerufenen Puffer zugreifen, bis er die E/A-Anforderung abgeschlossen hat.

Anstatt RequestRetrieveOutputBuffer aufzurufen, kann der Treiber IWDFIoRequest2::RetrieveOutputMemory aufrufen, wodurch ein Frameworkspeicherobjekt erstellt wird, das den Puffer darstellt.

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 ein Segment der Rückruffunktion IQueueCallbackDeviceIoControl::OnDeviceIoControl eines Seriellen Porttreibers. Das Codesegment ruft den Ausgabepuffer der E/A-Anforderung ab und überträgt dann Baudrateninformationen vom Gerät an den Puffer.

VOID
STDMETHODCALLTYPE
  CMyQueue::OnDeviceIoControl(
    __in IWDFIoQueue *pWdfQueue,
    __in IWDFIoRequest *pWdfRequest,
    __in ULONG ControlCode,
    __in SIZE_T InputBufferSizeInBytes,
    __in SIZE_T OutputBufferSizeInBytes
    )
{
    HRESULT hr;
    //
    // Declare an IWDFIoRequest2 interface pointer and obtain the
    // IWDFIoRequest2 interface from the IWDFIoRequest interface.
    //
    CComQIPtr<IWDFIoRequest2> r2 = pWdfRequest;

    switch (ControlCode)
    {
        case IOCTL_SERIAL_GET_BAUD_RATE:
        {
            SERIAL_BAUD_RATE *pBaudRateBuffer;
            hr = pWdfRequest2->RetrieveOutputBuffer(sizeof(SERIAL_BAUD_RATE),
                                                    (PVOID*) &pBaudRateBuffer,
                                                    NULL);
            if (SUCCEEDED(hr))
                  {
                      RtlZeroMemory(pBaudRateBuffer, sizeof(SERIAL_BAUD_RATE));
                      pBaudRateBuffer->BaudRate = m_Device->GetBaudRate();
                      reqCompletionInfo = sizeof(SERIAL_BAUD_RATE);
                  }
            
        }
        break;
        ...
    }
    ...
}

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