WdfRequestRetrieveOutputMemory-Funktion (wdfrequest.h)

[Gilt für KMDF und UMDF]

Die WdfRequestRetrieveOutputMemory-Methode ruft ein Handle für ein Frameworkspeicherobjekt ab, das den Ausgabepuffer einer E/A-Anforderung darstellt.

Syntax

NTSTATUS WdfRequestRetrieveOutputMemory(
  [in]  WDFREQUEST Request,
  [out] WDFMEMORY  *Memory
);

Parameter

[in] Request

Ein Handle für ein Frameworkanforderungsobjekt.

[out] Memory

Ein Zeiger auf einen Speicherort, der ein Handle für ein Frameworkspeicherobjekt empfängt.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Ein Eingabeparameter ist ungültig.
STATUS_INVALID_DEVICE_REQUEST	Der Anforderungstyp ist ungültig, oder die Anforderung verwendet weder gepufferte noch direkte E/A. Weitere Informationen zu unterstützten Methoden für den Zugriff auf Datenpuffer finden Sie im folgenden Abschnitt Mit Anmerkungen.
STATUS_INTERNAL_ERROR	Die Anforderung wurde bereits abgeschlossen.
STATUS_BUFFER_TOO_SMALL	Die Länge des Ausgabepuffers ist 0.
STATUS_INSUFFICIENT_RESOURCES	Es ist nicht genügend Arbeitsspeicher vorhanden.

 

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 WdfRequestRetrieveOutputMemory 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 WdfRequestRetrieveOutputMemory-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 WdfRequestRetrieveOutputMemory auch E/A-Anforderungen, die weder gepufferte noch direkte E/A verwenden.

Wenn WdfRequestRetrieveOutputMemory STATUS_SUCCESS zurückgibt, empfängt der Treiber ein Handle für ein Frameworkspeicherobjekt, das den Ausgabepuffer darstellt. Um auf den Puffer zuzugreifen, muss der Treiber WdfMemoryGetBuffer aufrufen.

Der Treiber kann auf das abgerufene Frameworkspeicherobjekt zugreifen, bis er die E/A-Anforderung abgeschlossen hat, die der Request-Parameter darstellt.

Anstatt WdfRequestRetrieveOutputMemory aufzurufen, kann der Treiber WdfRequestRetrieveOutputBuffer aufrufen, wodurch die Adresse und Länge des Puffers abgerufen wird.

Weitere Informationen zu WdfRequestRetrieveOutputMemory finden Sie unter Zugreifen auf Datenpuffer in Framework-Based Treibern.

Beispiele

Das folgende Codebeispiel zeigt, wie eine EvtIoRead-Rückruffunktion ein Handle für das Framework-Speicherobjekt abrufen kann, das den Ausgabepuffer einer Leseanforderung darstellt. Im Beispiel wird dann die Leseanforderung formatiert und an ein USB-E/A-Ziel gesendet.

VOID 
MyEvtIoRead(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    WDFUSBPIPE  pipe;
    NTSTATUS  status;
    WDFMEMORY  reqMemory;
    PDEVICE_CONTEXT  pDeviceContext;

    //
    // The driver previously stored a pipe handle in 
    // the device object's context space.
    //
    pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
    pipe = pDeviceContext->BulkReadPipe;

    //
    // Get output memory.
    //
    status = WdfRequestRetrieveOutputMemory(
                                            Request,
                                            &reqMemory
                                            );
    if(!NT_SUCCESS(status)){
        goto Exit;
    }
    //
    // Format the request.
    //
    status = WdfUsbTargetPipeFormatRequestForRead(
                                           pipe,
                                           Request,
                                           reqMemory,
                                           NULL
                                           ); 
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }
    WdfRequestSetCompletionRoutine(
                                   Request,
                                   EvtRequestReadCompletionRoutine,
                                   pipe
                                   );
    //
    // Send the request.
    //
    if (WdfRequestSend(
                       Request,
                       WdfUsbTargetPipeGetIoTarget(pipe),
                       WDF_NO_SEND_OPTIONS
                       ) == FALSE) {
        status = WdfRequestGetStatus(Request);
        goto Exit;
    }
Exit:
    //
    // Complete the request now if an error occurred.
    //
    if (!NT_SUCCESS(status)) {
        WdfRequestCompleteWithInformation(
                                          Request,
                                          status,
                                          0
                                          );
    }
    return;
}

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfrequest.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MemAfterReqCompletedIntIoctl(kmdf), MemAfterReqCompletedIntIoctlA(kmdf), MemAfterReqCompletedIoctl(kmdf), MemAfterReqCompletedIoctlA(kmdf), MemAfterReqCompletedRead(kmdf), MemAfterReqCompletedReadA(kmdf), MemAfterReqCompletedWrite(kmdf), OutputBufferAPI(kmdf)

Weitere Informationen

WdfMemoryGetBuffer

WdfRequestRetrieveInputMemory

WdfRequestRetrieveOutputBuffer