WdfRequestForwardToIoQueue, fonction (wdfrequest.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfRequestForwardToIoQueue met en file d’attente une demande d’E/S dans l’une des files d’attente d’E/S du pilote appelant.

Syntaxe

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

Paramètres

[in] Request

Handle d’un objet de requête d’infrastructure.

[in] DestinationQueue

Handle d’un objet de file d’attente d’infrastructure.

Valeur retournée

WdfRequestForwardToIoQueue retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_DEVICE_REQUEST	Cette valeur est retournée si l’une des opérations suivantes se produit : Le pilote n’a pas obtenu la demande à partir d’une file d’E/S. Les files d’attente source et de destination sont identiques. Les files d’attente source et de destination n’appartiennent pas au même appareil. Le pilote n’est pas propriétaire de la demande. La demande est annulable.
STATUS_WDF_BUSY	La file d’attente de destination n’accepte pas de nouvelles demandes.

Cette méthode peut également retourner d’autres valeurs NTSTATUS.

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

Le pilote doit être propriétaire de la demande d’E/S et doit avoir obtenu la demande à partir de l’une de ses files d’E/S.

Les files d’attente source et de destination ne peuvent pas être identiques. En d’autres termes, le pilote ne peut pas appeler WdfRequestForwardToIoQueue pour renvoyer une requête à la file d’attente d’où il provient. Pour renvoyer une requête dans la même file d’attente, utilisez WdfRequestRequeue.

Les files d’attente source et de destination doivent appartenir au même appareil.

La demande ne doit pas être annulable. Si le pilote a appelé WdfRequestMarkCancelable ou WdfRequestMarkCancelableEx pour rendre la demande annulable, il doit appeler WdfRequestUnmarkCancelable avant d’appeler WdfRequestForwardToIoQueue.

Une fois que le pilote a appelé WdfRequestForwardToIoQueue, le pilote n’est pas propriétaire de la demande mise en file d’attente tant que l’infrastructure n’a pas remise la requête de la nouvelle file d’attente au pilote. Lorsque la requête se trouve dans la nouvelle file d’attente, l’infrastructure est propriétaire de la demande et peut l’annuler sans en avertir le pilote.

Avant le retour de WdfRequestForwardToIoQueue , les événements suivants peuvent se produire :

Si la file d’attente de destination était vide, l’infrastructure peut remettre la demande d’E/S reléguée à l’un des gestionnaires de requêtes de la file d’attente de destination.
Si la méthode de répartition de la file d’attente source est séquentielle ou parallèle, l’infrastructure peut envoyer une autre requête à l’un des gestionnaires de requêtes de la file d’attente source.

Pour plus d’informations sur WdfRequestForwardToIoQueue, consultez Réexécution des demandes d’E/S et Gestion des files d’attente d’E/S.

Exemples

L’exemple de code suivant est une fonction de rappel EvtIoDeviceControl de l’exemple de pilote PCIDRV . Si une demande reçue contient un code de contrôle d’E/S de IOCTL_NDISPROT_INDICATE_STATUS, le pilote appelle WdfRequestForwardToIoQueue pour déplacer la demande vers une autre file d’attente d’E/S.

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;
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfrequest.h (include Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)