IWDFIoRequest2::RetrieveOutputBuffer-Methode (wudfddi.h)

Artikel
02/07/2025

[Warnung: UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. Es werden keine neuen Features zu UMDF 1 hinzugefügt, und es gibt eingeschränkte Unterstützung für UMDF 1 für neuere Versionen von Windows 10. 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 für die Verarbeitung der E/A-Anforderung benötigt. Dieser Wert kann null sein, wenn keine minimale Puffergröße vorhanden ist.

[out] Buffer

Ein Zeiger auf eine Position, die die Adresse des Puffers empfängt.

[out, optional] BufferCb

Ein Zeiger auf eine Position, die die Größe des Puffers in Byte empfängt. Dieser Parameter ist optional und kann NULL-werden.

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 Mindestgröße, die MinimumRequiredCb- angibt.
E_OUTOFMEMORY	Nicht genügend Arbeitsspeicher zum Abrufen des Puffers verfügbar. Der Treiber sollte die Anforderung mit einem Fehlerstatuswert abschließen.

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

Bemerkungen

Der Ausgabepuffer einer Anforderung empfängt Informationen, z. B. Daten von einem Datenträger, die der Treiber dem Absender der Anforderung bereitstellt. Ihr Treiber kann RequestRetrieveOutputBuffer- aufrufen, um den Ausgabepuffer für eine Leseanforderung oder eine Geräte-E/A-Steuerelementanforderung 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 gepufferten E/A- oder direkten E/A--Methode für den Zugriff auf Datenpuffer verwenden.

Wenn RequestRetrieveOutputBuffer S_OK zurückgibt, empfängt der Treiber die Adresse und optional die Größe des Ausgabepuffers.

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

Anstatt RequestRetrieveOutputBuffer-aufzurufen, kann der Treiber IWDFIoRequest2::RetrieveOutputMemoryaufrufen, 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 Drivers.

Beispiele

Das folgende Codebeispiel zeigt ein Segment der IQueueCallbackDeviceIoControl::OnDeviceIoControl Rückruffunktion eines seriellen Porttreibers. Das Codesegment ruft den Ausgabepuffer der E/A-Anforderung ab und überträgt dann Baudrateinformationen 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
Mindest-UMDF-Version	1.9
Header-	wudfddi.h (include Wudfddi.h)
DLL-	WUDFx.dll