WdfUsbTargetDeviceFormatRequestForCyclePort, fonction (wdfusb.h)

Article
08/08/2023

[S’applique à KMDF uniquement]

La méthode WdfUsbTargetDeviceFormatRequestForCyclePort génère une demande de cycle d’alimentation pour le port auquel un appareil spécifié est attaché, mais elle n’envoie pas la demande.

Syntaxe

NTSTATUS WdfUsbTargetDeviceFormatRequestForCyclePort(
  [in] WDFUSBDEVICE UsbDevice,
  [in] WDFREQUEST   Request
);

Paramètres

[in] UsbDevice

Handle pour un objet de périphérique USB obtenu à partir d’un appel précédent à WdfUsbTargetDeviceCreateWithParameters.

[in] Request

Handle pour un objet de requête d’infrastructure. Pour plus d'informations, consultez la section Notes qui suit.

Valeur retournée

WdfUsbTargetDeviceFormatRequestForCyclePort 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_STATE	Le périphérique USB de l’appareil n’était pas disponible.
STATUS_INSUFFICIENT_RESOURCES	La mémoire disponible était insuffisante.

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

Utilisez WdfUsbTargetDeviceFormatRequestForCyclePort, suivi de WdfRequestSend, pour envoyer une demande de cycle d’alimentation de manière synchrone ou asynchrone. Vous pouvez également utiliser la méthode WdfUsbTargetDeviceCyclePortSynchronously pour envoyer une requête de manière synchrone.

Avant d’appeler WdfRequestSend, le pilote doit appeler WdfIoTargetStop et il doit terminer ou annuler toutes les demandes d’E/S qu’il a envoyées à la cible d’E/S. Le pilote ne doit pas envoyer de demandes d’E/S supplémentaires à la cible d’E/S tant que la demande de cycle n’est pas terminée.

Vous pouvez transférer une demande d’E/S que votre pilote a reçue dans une file d’attente d’E/S, ou vous pouvez créer et envoyer une nouvelle demande.

Pour transférer une demande d’E/S reçue par votre pilote dans une file d’attente d’E/S, spécifiez le handle de la demande reçue pour le paramètre Request de la méthode WdfUsbTargetDeviceFormatRequestForCyclePort.

Pour créer une demande d’E/S, appelez WdfRequestCreate pour préallouer un objet de requête. Fournissez le handle de requête pour le paramètre Request de la méthode WdfUsbTargetDeviceFormatRequestForCyclePort. Vous pouvez réutiliser l’objet de requête en appelant WdfRequestReuse. La fonction de rappel EvtDriverDeviceAdd de votre pilote peut préallouer des objets de requête pour un appareil.

Après avoir appelé WdfUsbTargetDeviceFormatRequestForCyclePort pour mettre en forme une requête d’E/S, le pilote doit appeler WdfRequestSend pour envoyer la requête (de manière synchrone ou asynchrone) à une cible d’E/S. Cet appel à WdfRequestSend doit être effectué à l’adresse IRQL = PASSIVE_LEVEL.

Les appels multiples à WdfUsbTargetDeviceFormatRequestForCyclePort qui utilisent la même requête ne provoquent pas d’allocations de ressources supplémentaires. Par conséquent, pour réduire le risque que WdfRequestCreate retourne STATUS_INSUFFICIENT_RESOURCES, la fonction de rappel EvtDriverDeviceAdd de votre pilote peut appeler WdfRequestCreate pour préallouer un ou plusieurs objets de requête pour un appareil. Le pilote peut ensuite réutiliser (appeler WdfRequestReuse), reformat (appeler WdfUsbTargetDeviceFormatRequestForCyclePort) et renvoyer (appeler WdfRequestSend) chaque objet de requête sans risquer une valeur de retour STATUS_INSUFFICIENT_RESOURCES d’un appel ultérieur à WdfRequestCreate. Tous les appels suivants à WdfUsbTargetDeviceFormatRequestForCyclePort pour l’objet de requête réutilisé retournent STATUS_SUCCESS, si les valeurs de paramètre ne changent pas. (Si le pilote n’appelle pas la même méthode de mise en forme de requête à chaque fois, des ressources supplémentaires peuvent être allouées.)

Pour plus d’informations sur la méthode WdfUsbTargetDeviceFormatRequestForCyclePort et les cibles d’E/S USB, consultez Cibles d’E/S USB.

Exemples

L’exemple de code suivant met en forme une demande de cycle d’alimentation, inscrit une fonction de rappel CompletionRoutine et envoie la demande à une cible d’E/S.

status = WdfUsbTargetDeviceFormatRequestForCyclePort(
                                            UsbDevice,
                                            request
                                            );
if (!NT_SUCCESS(status)){
    return status;
}
WdfRequestSetCompletionRoutine(
                               request,
                               MyCompletionRoutine,
                               NULL
                               );

if (WdfRequestSend(
                   request,
                   WdfUsbTargetDeviceGetIoTarget(UsbDevice),
                   NULL
                   ) == FALSE) {
    status = WdfRequestGetStatus(request);
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
En-tête	wdfusb.h (inclure Wdfusb.h)
Bibliothèque	Wdf01000.sys (consultez Gestion des versions de la bibliothèque d’infrastructure).)
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)