WdfDeviceEnqueueRequest, fonction (wdfdevice.h)

Article
02/07/2025

[S’applique uniquement à KMDF]

La méthode WdfDeviceEnqueueRequest remet une requête d’E/S spécifiée à l’infrastructure, afin que l’infrastructure puisse ensuite ajouter la requête à l’une des files d’attente d’E/S créées par le pilote pour l’appareil spécifié.

Syntaxe

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

Paramètres

[in] Device

Handle vers un objet d’appareil framework.

[in] Request

Handle vers un objet de requête de framework.

Valeur de retour

Si l’opération réussit, la méthode retourne STATUS_SUCCESS. Les valeurs de retour supplémentaires sont les suivantes :

Retourner le code	Description
STATUS_INSUFFICIENT_RESOURCES	La quantité de mémoire disponible est faible.
STATUS_INVALID_DEVICE_REQUEST	Le pilote n’a pas créé de files d’attente d’E/S pour l’appareil, et le pilote n’est pas un pilote de filtre.
STATUS_WDF_BUSY	La file d’attente d’E/S de l’appareil n’accepte pas les demandes.

La méthode peut retourner d’autres valeurs NTSTATUS .

Une vérification de bogue se produit si le pilote fournit un handle d’objet non valide.

Remarques

Votre pilote peut appeler WdfDeviceEnqueueRequest uniquement à partir d’une fonction de rappel EvtIoInCallerContext.

La méthode WdfDeviceEnqueueRequest ajoute la requête à la file d’attente d’E/S spécifique au type de requête du pilote pour l’appareil, si le pilote en a créé un. Sinon, la méthode ajoute la requête à la file d’attente par défaut de l’appareil, si le pilote en a créé un.

Si le pilote n’a pas créé de files d’attente d’E/S pour l’appareil, WdfDeviceEnqueueRequest effectue les opérations suivantes :

Si le pilote est un pilote de filtre, WdfDeviceEnqueueRequest envoie la requête à la cible d’E/S du pilote.
Si le pilote n’est pas un pilote de filtre, WdfDeviceEnqueueRequest retourne STATUS_INVALID_DEVICE_REQUEST.

Bien que WdfDeviceEnqueueRequest s’exécute, il est possible que le pilote reçoive et termine ou annule la demande.

Par conséquent, si le pilote doit utiliser la requête ou son contexte après avoir appelé WdfDeviceEnqueueRequest, il doit prendre une référence sur la demande avant d’appeler WdfDeviceEnqueueRequest.

Pour ce faire, le pilote peut appeler WdfObjectReference avant, puis WdfObjectDereference après l’appel à WdfDeviceEnqueueRequest. Le pilote doit déréférencer la requête avant de quitter EvtIoInCallerContext.

Pour plus d’informations sur la méthode WdfDeviceEnqueueRequest, consultez Gestion des files d’attente d’E/S.

Pour les versions 1.0 et 1.5 de KMDF, WdfDeviceEnqueueRequest doivent être appelées à PASSIVE_LEVEL. Pour les versions 1.7 et ultérieures, WdfDeviceEnqueueRequest peuvent être appelées au <IRQL = DISPATCH_LEVEL.

Exemples

L’exemple de code suivant est un EvtIoInCallerContext fonction de rappel qui recherche les requêtes qui contiennent le code de contrôle d’E/S personnalisé, IOCTL_NONPNP_METHOD_NEITHER. Si le code de contrôle d’E/S est introuvable, la fonction de rappel retourne simplement la requête au framework. Si la fonction de rappel trouve le code de contrôle d’E/S, elle préprocesse la requête, puis la retourne à l’infrastructure. Si une erreur se produit, la fonction de rappel termine la requête.

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

Exigences

Exigence	Valeur
plateforme cible	Universel
version minimale de KMDF	1.0
d’en-tête	wdfdevice.h (include Wdf.h)
bibliothèque	Wdf01000.sys (voir Versioning de la bibliothèque Framework.)
IRQL	<= DISPATCH_LEVEL (voir la section Remarques)
règles de conformité DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), Km, KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)

Voir aussi

WDF_REQUEST_PARAMETERS_INIT

WdfRequestComplete

WdfRequestGetParameters

Partager via