WdfRequestRetrieveOutputBuffer-Funktion (wdfrequest.h)

[Gilt für KMDF und UMDF]

Die WdfRequestRetrieveOutputBuffer-Methode ruft den Ausgabepuffer einer E/A-Anforderung ab.

Syntax

NTSTATUS WdfRequestRetrieveOutputBuffer(
  [in]            WDFREQUEST Request,
  [in]            size_t     MinimumRequiredSize,
  [out]           PVOID      *Buffer,
  [out, optional] size_t     *Length
);

Parameter

[in] Request

Ein Handle für ein Frameworkanforderungsobjekt.

[in] MinimumRequiredSize

Die minimale Puffergröße in Bytes, die der Treiber zum Verarbeiten der E/A-Anforderung benötigt.

[out] Buffer

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

[out, optional] Length

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

WdfRequestRetrieveOutputBuffer gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

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 WdfRequestRetrieveOutputBuffer 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 WdfRequestRetrieveOutputBuffer-Methode ruft den Ausgabepuffer für E/A-Anforderungen ab, die die gepufferte E/A-Methode oder die direkte E/A-Methode für den Zugriff auf Datenpuffer verwenden. Wenn der E/A-Steuerungscode der Anforderung IRP_MJ_INTERNAL_DEVICE_CONTROL ist oder die Anforderung von einem anderen Kernelmodustreiber stammt, unterstützt WdfRequestRetrieveOutputBuffer auch E/A-Anforderungen, die weder gepufferte noch direkte E/A verwenden.

Wenn WdfRequestRetrieveOutputBuffer STATUS_SUCCESS 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 die E/A-Anforderung abgeschlossen hat, die der Request-Parameter darstellt.

Anstatt WdfRequestRetrieveOutputBuffer aufzurufen, kann der Treiber WdfRequestRetrieveOutputMemory aufrufen, wodurch ein Frameworkspeicherobjekt erstellt wird, das den Puffer darstellt.

Weitere Informationen zu WdfRequestRetrieveOutputBuffer finden Sie unter Zugreifen auf Datenpuffer in Framework-Based Drivers.

Beispiele

Das folgende Codebeispiel ist Teil einer EvtIoDeviceControl-Rückruffunktion . In diesem Beispiel wird der Konfigurationsdeskriptor eines USB-Geräts abgerufen und der Deskriptor im Ausgabepuffer der E/A-Anforderung platziert.

VOID
MyEvtIoDeviceControl(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  OutputBufferLength,
    IN size_t  InputBufferLength,
    IN ULONG  IoControlCode    
    )
{
    WDFDEVICE  device;
    PDEVICE_CONTEXT  pDevContext;
    size_t  bytesReturned = 0;
    NTSTATUS  status;

    device = WdfIoQueueGetDevice(Queue);
    //
    // GetDeviceContext is a driver-defined function 
    // to retrieve device object context space.
    //
    pDevContext = GetDeviceContext(device);

    switch(IoControlCode) {

      case IOCTL_OSRUSBFX2_GET_CONFIG_DESCRIPTOR: {
 
        PUSB_CONFIGURATION_DESCRIPTOR  configurationDescriptor = NULL;
        USHORT  requiredSize;

        //
        // First, get the size of the USB configuration descriptor.
        //
        status = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                                pDevContext->UsbDevice,
                                                NULL,
                                                &requiredSize
                                                );
        if (status == STATUS_BUFFER_TOO_SMALL) {
            break;
        }

        //
        // Get the buffer. Make sure the buffer is big
        // enough to hold the configuration descriptor.
        //
        status = WdfRequestRetrieveOutputBuffer(
                                                Request, 
                                                (size_t)requiredSize,
                                                &configurationDescriptor,
                                                NULL
                                                );
        if(!NT_SUCCESS(status)){
            break;
        }
        //
        // Now get the config descriptor.
        //
        status = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                                pDevContext->UsbDevice,
                                                configurationDescriptor,
                                                &requiredSize
                                                );
        if (!NT_SUCCESS(status)) {
            break;
        }

        bytesReturned = requiredSize;
      }
        break;
...
    (Other case statements removed.)
...
    default:
        status = STATUS_INVALID_DEVICE_REQUEST;
        break;
    }
    //
    // Complete the request.
    //
    WdfRequestCompleteWithInformation(
                                      Request,
                                      status,
                                      bytesReturned
                                      );
    return;
}

Anforderungen

Weitere Informationen

WdfRequestRetrieveInputBuffer

WdfRequestRetrieveOutputMemory