WdfRequestRetrieveOutputMemory-Funktion (wdfrequest.h)

[Gilt für KMDF und UMDF]

Die WdfRequestRetrieveOutputMemory Methode ruft ein Handle zu einem Framework-Speicherobjekt ab, das den Ausgabepuffer einer E/A-Anforderung darstellt.

Syntax

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

Parameter

[in] Request

Ein Handle zu einem Framework-Anforderungsobjekt.

[out] Memory

Ein Zeiger auf eine Position, die ein Handle zu einem Framework-Speicherobjekt 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 gepuffert noch direkte E/A-. Weitere Informationen zu unterstützten Methoden für den Zugriff auf Datenpuffer finden Sie im folgenden Abschnitt "Hinweise".
STATUS_INTERNAL_ERROR	Die Anforderung wurde bereits abgeschlossen.
STATUS_BUFFER_TOO_SMALL	Die Länge des Ausgabepuffers ist null.
STATUS_INSUFFICIENT_RESOURCES	Es ist nicht genügend Arbeitsspeicher vorhanden.

 

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

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 WdfRequestRetrieveOutputMemory- 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 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-Steuercode der Anforderung IRP_MJ_INTERNAL_DEVICE_CONTROList oder die Anforderung von einem anderen Kernelmodustreiber stammt, unterstützt WdfRequestRetrieveOutputMemory auch E/A-Anforderungen, die weder gepuffert noch direkte E/A-verwenden.

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

Der Treiber kann auf das abgerufene Framework-Speicherobjekt zugreifen, bis die E/A-Anforderung abgeschlossen, die der parameter Request darstellt.

Anstatt WdfRequestRetrieveOutputMemoryaufzurufen, kann der Treiber WdfRequestRetrieveOutputBufferaufrufen, wodurch die Adresse und Länge des Puffers abgerufen wird.

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

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. Anschließend wird die Leseanforderung an ein USB-E/A-Ziel formatiert und 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-	Universal
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Header-	wdfrequest.h (include Wdf.h)
Library	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)-

Siehe auch

WdfMemoryGetBuffer-

WdfRequestRetrieveInputMemory

WdfRequestRetrieveOutputBuffer