Fonction WdfDeviceEnqueueRequest (wdfdevice.h)

Article
02/27/2024

[S’applique uniquement à KMDF]

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

Syntaxe

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

Paramètres

[in] Device

Handle d’un objet d’appareil framework.

[in] Request

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

Valeur retournée

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

Code de retour	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.

Un bogue case activée 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 demande à 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éé une. Sinon, la méthode ajoute la demande à la file d’attente par défaut de l’appareil, si le pilote en a créé une.

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 demande à la cible d’E/S du pilote.
Si le pilote n’est pas un pilote de filtre, WdfDeviceEnqueueRequest retourne STATUS_INVALID_DEVICE_REQUEST.

Pendant que WdfDeviceEnqueueRequest est en cours d’exécution, il est possible pour le pilote de recevoir et de terminer ou d’annuler la demande.

Par conséquent, si le pilote doit utiliser la demande 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 demande 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 doit être appelé à PASSIVE_LEVEL. Pour les versions 1.7 et ultérieures, WdfDeviceEnqueueRequest peut être appelé à l’adresse IRQL <= DISPATCH_LEVEL.

Exemples

L’exemple de code suivant est une fonction de rappel EvtIoInCallerContext 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 E/S est introuvable, la fonction de rappel retourne simplement la demande à l’infrastructure. Si la fonction de rappel trouve le code de contrôle d’E/S, elle prétraite la demande, puis la retourne à l’infrastructure. Si une erreur est rencontrée, la fonction de rappel termine la demande.

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

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
En-tête	wdfdevice.h (include Wdf.h)
Bibliothèque	Wdf01000.sys (consultez Gestion de version de la bibliothèque d’infrastructure.)
IRQL	<= DISPATCH_LEVEL (section Voir les remarques)
Règles de conformité DDI	DeferredRequestCompleted(kmdf),DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)

Voir aussi

WDF_REQUEST_PARAMETERS_INIT

WdfRequestComplete

WdfRequestGetParameters

Partager via