WdfRequestForwardToIoQueue-Funktion (wdfrequest.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

Die WdfRequestForwardToIoQueue Methode stellt eine E/A-Anforderung in eine der E/A-Warteschlangen des aufrufenden Treibers um.

Syntax

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

Parameter

[in] Request

Ein Handle zu einem Framework-Anforderungsobjekt.

[in] DestinationQueue

Ein Handle zu einem 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 Aktionen auftritt: Der Treiber hat die Anforderung nicht aus einer E/A-Warteschlange abgerufen. Die Quell- und Zielwarteschlangen sind identisch. Die Quell- und Zielwarteschlangen gehören nicht zum gleichen Gerät. Der Treiber besitzt die Anforderung nicht. Die Anforderung kann abgebrochen werden.
STATUS_WDF_BUSY	Die Zielwarteschlange akzeptiert keine neuen Anforderungen.

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

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

Bemerkungen

Der Treiber muss eine eigene der E/A-Anforderung und die Anforderung aus einer der E/A-Warteschlangen erhalten haben.

Die Quell- und Zielwarteschlangen können nicht identisch sein. Mit anderen Worten, der Treiber kann WdfRequestForwardToIoQueue aufrufen, um eine Anforderung an die Warteschlange zurückzugeben, von der sie 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. Wenn der Treiber WdfRequestMarkCancelable oder WdfRequestMarkCancelableEx aufgerufen hat, um die Anforderung abzubrechen, muss er WdfRequestUnmarkCancelable aufrufen, bevor WdfRequestForwardToIoQueueaufgerufen wird.

Nachdem der Treiber WdfRequestForwardToIoQueueaufgerufen hat, besitzt der Treiber nicht die erneut abgefragte Anforderung, bis 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 abgefragte E/A-Anforderung an eine der Anforderungshandler der Zielwarteschlangeliefern.
Wenn die Dispatching-Methode der Quellwarteschlange sequenziell oder parallel ist, kann das Framework eine weitere Anforderung an einen der Anforderungshandler der Quellwarteschlange übermitteln.

Weitere Informationen zu WdfRequestForwardToIoQueuefinden Sie unter Requeuing I/O Requests und Managing I/O Queues.

Beispiele

Das folgende Codebeispiel ist ein EvtIoDeviceControl Rückruffunktion aus dem PCIDRV Beispieltreiber. Wenn eine empfangene Anforderung einen E/A-Steuerungscode von 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-	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	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrq, KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)