WdfRequestForwardToIoQueue-Funktion (wdfrequest.h)

Artikel
02/27/2024

[Gilt für KMDF und UMDF]

Die WdfRequestForwardToIoQueue-Methode stellt eine E/A-Anforderung erneut an eine der E/A-Warteschlangen des aufrufenden Treibers aus.

Syntax

NTSTATUS WdfRequestForwardToIoQueue(
  [in] WDFREQUEST Request,
  [in] WDFQUEUE   DestinationQueue
);

Parameter

[in] Request

Ein Handle für ein Frameworkanforderungsobjekt.

[in] DestinationQueue

Ein Handle für ein Framework-Warteschlangenobjekt.

Rückgabewert

WdfRequestForwardToIoQueue 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_DEVICE_REQUEST	Dieser Wert wird zurückgegeben, wenn einer der folgenden Fehler auftritt: Der Treiber hat die Anforderung nicht aus einer E/A-Warteschlange abgerufen. Quell- und Zielwarteschlangen sind identisch. Die Quell- und Zielwarteschlangen gehören nicht zum gleichen Gerät. Der Treiber ist nicht Besitzer der Anforderung. Die Anforderung kann abgebrochen werden.
STATUS_WDF_BUSY	Die Zielwarteschlange akzeptiert keine neuen Anforderungen.

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

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

Hinweise

Der Treiber muss besitzer der E/A-Anforderung sein und die Anforderung aus einer seiner E/A-Warteschlangen abgerufen haben.

Quell- und Zielwarteschlangen können nicht identisch sein. Anders ausgedrückt: Der Treiber kann WdfRequestForwardToIoQueue nicht aufrufen, um eine Anforderung an die Warteschlange zurückzugeben, aus der er stammt. Verwenden Sie WdfRequestRequeue, um eine Anforderung erneut an dieselbe Warteschlange zu stellen.

Sowohl die Quell- als auch die Zielwarteschlange müssen zum gleichen Gerät gehören.

Die Anforderung darf nicht abgebrochen werden können. Wenn der Treiber WdfRequestMarkCancelable oder WdfRequestMarkCancelableEx aufgerufen hat, um die Anforderung abzubrechen, muss er WdfRequestUnmarkCancelable aufrufen, bevor WdfRequestForwardToIoQueue aufgerufen wird.

Nachdem der Treiber WdfRequestForwardToIoQueue aufgerufen hat, besitzt der Treiber die erneut warteschlangenierte Anforderung erst, wenn das Framework die Anforderung aus der neuen Warteschlange an den Treiber übermittelt. Während sich die Anforderung in der neuen Warteschlange befindet, besitzt das Framework die Anforderung und kann sie abbrechen, ohne den Treiber zu benachrichtigen.

Bevor WdfRequestForwardToIoQueue zurückgibt, können die folgenden Ereignisse auftreten:

Wenn die Zielwarteschlange leer war, kann das Framework die erneut in die Warteschlange stehenden E/A-Anforderungen an einen der Anforderungshandler der Zielwarteschlange übermitteln.
Wenn die Verteilungsmethode der Quellwarteschlange sequenziell oder parallel ist, kann das Framework eine weitere Anforderung an einen der Anforderungshandler der Quellwarteschlange übermitteln.

Weitere Informationen zu WdfRequestForwardToIoQueue finden Sie unter Wiederherstellen von E/A-Anforderungen und Verwalten von E/A-Warteschlangen.

Beispiele

Das folgende Codebeispiel ist eine EvtIoDeviceControl-Rückruffunktion aus dem PCIDRV-Beispieltreiber . Wenn eine empfangene Anforderung den E/A-Steuerungscode IOCTL_NDISPROT_INDICATE_STATUS enthält, ruft der Treiber WdfRequestForwardToIoQueue auf, um die Anforderung in eine andere E/A-Warteschlange zu verschieben.

VOID
PciDrvEvtIoDeviceControl(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  OutputBufferLength,
    IN size_t  InputBufferLength,
    IN ULONG  IoControlCode
    )
{
    NTSTATUS  status= STATUS_SUCCESS;
    PFDO_DATA  fdoData = NULL;
    WDFDEVICE  hDevice;
    WDF_REQUEST_PARAMETERS  params;

    UNREFERENCED_PARAMETER(OutputBufferLength);
    UNREFERENCED_PARAMETER(InputBufferLength);

    hDevice = WdfIoQueueGetDevice(Queue);
    fdoData = FdoGetData(hDevice);

    WDF_REQUEST_PARAMETERS_INIT(&params);
    WdfRequestGetParameters(
                            Request,
                            &params
                            );

    switch (IoControlCode)
    {
        case IOCTL_NDISPROT_QUERY_OID_VALUE:
            NICHandleQueryOidRequest(
                                     Queue,
                                     Request,
                                     &params
                                     );
            break;

        case IOCTL_NDISPROT_SET_OID_VALUE:
            NICHandleSetOidRequest(
                                   Queue,
                                   Request,
                                   &params
                                   );
            break;

        case IOCTL_NDISPROT_INDICATE_STATUS:
            status = WdfRequestForwardToIoQueue(
                                                Request,
                                                fdoData->PendingIoctlQueue
                                                );
            if(!NT_SUCCESS(status)){
                WdfRequestComplete(
                                   Request,
                                   status
                                   );
                break;
            }
            break;

        default:
            WdfRequestComplete(
                               Request,
                               STATUS_INVALID_DEVICE_REQUEST
                               );
            break;
    }
    return;
}

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfrequest.h (include Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)