WdfDeviceEnqueueRequest-Funktion (wdfdevice.h)

Artikel
02/27/2024

[Gilt nur für KMDF]

Die WdfDeviceEnqueueRequest-Methode übermittelt eine angegebene E/A-Anforderung an das Framework, sodass das Framework die Anforderung anschließend einer der E/A-Warteschlangen hinzufügen kann, die der Treiber für das angegebene Gerät erstellt hat.

Syntax

NTSTATUS WdfDeviceEnqueueRequest(
  [in] WDFDEVICE  Device,
  [in] WDFREQUEST Request
);

Parameter

[in] Device

Ein Handle für ein Framework-Geräteobjekt.

[in] Request

Ein Handle für ein Frameworkanforderungsobjekt.

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt die Methode STATUS_SUCCESS zurück. Weitere Rückgabewerte sind:

Rückgabecode	Beschreibung
STATUS_INSUFFICIENT_RESOURCES	Die Menge des verfügbaren Arbeitsspeichers ist gering.
STATUS_INVALID_DEVICE_REQUEST	Der Treiber hat keine E/A-Warteschlangen für das Gerät erstellt, und der Treiber ist kein Filtertreiber.
STATUS_WDF_BUSY	Die E/A-Warteschlange des Geräts akzeptiert keine Anforderungen.

Die -Methode gibt möglicherweise andere NTSTATUS-Werte zurück.

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

Hinweise

Ihr Treiber kann WdfDeviceEnqueueRequest nur über eine EvtIoInCallerContext-Rückruffunktion aufrufen.

Die WdfDeviceEnqueueRequest-Methode fügt die Anforderung der anforderungstypspezifischen E/A-Warteschlange des Treibers für das Gerät hinzu, sofern der Treiber eine solche erstellt hat. Andernfalls fügt die -Methode die Anforderung der Standardwarteschlange des Geräts hinzu, wenn der Treiber eine erstellt hat.

Wenn der Treiber keine E/A-Warteschlangen für das Gerät erstellt hat, führt WdfDeviceEnqueueRequest folgendes aus:

Wenn der Treiber ein Filtertreiber ist, sendet WdfDeviceEnqueueRequest die Anforderung an das E/A-Ziel des Treibers.
Wenn der Treiber kein Filtertreiber ist, gibt WdfDeviceEnqueueRequest STATUS_INVALID_DEVICE_REQUEST zurück.

Während WdfDeviceEnqueueRequest ausgeführt wird, ist es möglich, dass der Treiber die Anforderung empfängt und abschließt oder abbricht.

Wenn der Treiber daher die Anforderung oder ihren Kontext nach dem Aufrufen von WdfDeviceEnqueueRequest verwenden muss, sollte er vor dem Aufrufen von WdfDeviceEnqueueRequest einen Verweis auf die Anforderung benötigen.

Dazu kann der Treiber WdfObjectReference vor und dann WdfObjectDereference nach dem Aufruf von WdfDeviceEnqueueRequest aufrufen. Der Treiber muss die Anforderung ableiten, bevor EvtIoInCallerContext beendet wird.

Weitere Informationen zur WdfDeviceEnqueueRequest-Methode finden Sie unter Verwalten von E/A-Warteschlangen.

Für die Versionen 1.0 und 1.5 von KMDF muss WdfDeviceEnqueueRequest unter PASSIVE_LEVEL aufgerufen werden. Ab Version 1.7 kann WdfDeviceEnqueueRequest unter IRQL <= DISPATCH_LEVEL aufgerufen werden.

Beispiele

Das folgende Codebeispiel ist eine EvtIoInCallerContext-Rückruffunktion , die nach Anforderungen sucht, die den benutzerdefinierten E/A-Steuerungscode enthalten, IOCTL_NONPNP_METHOD_NEITHER. Wenn der E/A-Steuerelementcode nicht gefunden wird, gibt die Rückruffunktion einfach die Anforderung an das Framework zurück. Wenn die Rückruffunktion den E/A-Steuerelementcode findet, verarbeitet sie die Anforderung vor und gibt ihn dann an das Framework zurück. Wenn ein Fehler auftritt, schließt die Rückruffunktion die Anforderung ab.

VOID
MyEvtDeviceIoInCallerContext(
    IN WDFDEVICE  Device,
    IN WDFREQUEST Request
    )
{
    NTSTATUS  status = STATUS_SUCCESS;
    WDF_REQUEST_PARAMETERS  params;

    WDF_REQUEST_PARAMETERS_INIT(&params);
    WdfRequestGetParameters(
                            Request,
                            &params
                            );
    if(!(params.Type == WdfRequestTypeDeviceControl &&
         params.Parameters.DeviceIoControl.IoControlCode == IOCTL_NONPNP_METHOD_NEITHER)) {
        status = WdfDeviceEnqueueRequest(
                                         Device,
                                         Request
                                         );
        if(!NT_SUCCESS(status)) {
            goto End;
        }
        return;
    }
    //
    // Found a match for the control code. Preprocess the request, and then
    // return the request to the framework.
    //

    //...(Preprocess the request here.)

    status = WdfDeviceEnqueueRequest(
                                     Device,
                                     Request
                                     );
    if(!NT_SUCCESS(status)) {
        goto End;
    }
    return;
End:
    WdfRequestComplete(
                       Request,
                       status
                       );
    return;
}

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
Kopfzeile	wdfdevice.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (siehe Versionierung der Frameworkbibliothek.)
IRQL	<= DISPATCH_LEVEL (Siehe Abschnitt "Hinweise")
DDI-Complianceregeln	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)

Weitere Informationen

WDF_REQUEST_PARAMETERS_INIT

WdfRequestComplete

WdfRequestGetParameters

Freigeben über