WdfRequestRetrieveInputMemory-Funktion (wdfrequest.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

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

Syntax

NTSTATUS WdfRequestRetrieveInputMemory(
  [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

WdfRequestRetrieveInputMemory 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 Eingabepuffers 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 Eingabepuffer einer Anforderung enthält Informationen, z. B. Daten, die auf einen Datenträger geschrieben werden sollen, die vom Absender der Anforderung bereitgestellt wurden. Ihr Treiber kann WdfRequestRetrieveInputMemory aufrufen, um den Eingabepuffer für eine Schreibanforderung oder eine Geräte-E/A-Steuerungsanforderung abzurufen, aber nicht für eine Leseanforderung (da Leseanforderungen keine Eingabedaten bereitstellen).

Die WdfRequestRetrieveInputMemory-Methode ruft den Eingabepuffer 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 WdfRequestRetrieveInputMemory auch E/A-Anforderungen, die weder gepufferte noch direkte E/A verwenden.

Wenn WdfRequestRetrieveInputMemory STATUS_SUCCESS zurückgibt, empfängt der Treiber ein Handle für ein Frameworkspeicherobjekt, das den Eingabepuffer 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 WdfRequestRetrieveInputMemory aufzurufen, kann der Treiber WdfRequestRetrieveInputBuffer aufrufen, wodurch die Adresse und Länge des Puffers abgerufen wird.

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

Beispiele

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

VOID 
MyEvtIoWrite(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    NTSTATUS  status;
    WDFUSBPIPE  pipe;
    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->BulkWritePipe;

    //
    // Get input memory.
    //
    status = WdfRequestRetrieveInputMemory(
                                           Request,
                                           &reqMemory
                                           );
    if(!NT_SUCCESS(status)){
        goto Exit;
    }

    //
    // Format the request.
    //
    status = WdfUsbTargetPipeFormatRequestForWrite(
                                          pipe,
                                          Request,
                                          reqMemory,
                                          NULL
                                          );
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }
    WdfRequestSetCompletionRoutine(
                                   Request,
                                   EvtRequestWriteCompletionRoutine,
                                   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), InputBufferAPI(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MemAfterReqCompletedIntIoctl(kmdf), MemAfterReqCompletedIntIoctlA(kmdf), MemAfterReqCompletedIoctl(kmdf), MemAfterReqCompletedIoctlA(kmdf), MemAfterReqCompletedRead(kmdf), MemAfterReqCompletedWrite(kmdf) , MemAfterReqCompletedWriteA(kmdf)

Weitere Informationen

WdfMemoryGetBuffer

WdfRequestRetrieveInputBuffer

WdfRequestRetrieveOutputMemory

Freigeben über