WdfUsbTargetPipeResetSynchronously, fonction (wdfusb.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfUsbTargetPipeResetSynchronously génère une demande de réinitialisation et l’envoie de manière synchrone à un canal USB spécifié.

Syntaxe

NTSTATUS WdfUsbTargetPipeResetSynchronously(
  [in]           WDFUSBPIPE                Pipe,
  [in, optional] WDFREQUEST                Request,
  [in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions
);

Paramètres

[in] Pipe

Handle vers un objet de canal d’infrastructure obtenu en appelant WdfUsbInterfaceGetConfiguredPipe.

[in, optional] Request

Handle pour un objet de requête d’infrastructure. Ce paramètre est facultatif et peut être NULL. Pour plus d'informations, consultez la section Notes qui suit.

[in, optional] RequestOptions

Pointeur vers une structure de WDF_REQUEST_SEND_OPTIONS allouée par l’appelant qui spécifie des options pour la demande. Ce pointeur est facultatif et peut être NULL. Pour plus d'informations, consultez la section Notes qui suit.

Valeur retournée

WdfUsbTargetPipeResetSynchronously retourne la valeur d’achèvement status de la cible d’E/S USB si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INFO_LENGTH_MISMATCH	La taille de la structure WDF_REQUEST_SEND_OPTIONS spécifiée par le paramètre RequestOptions était incorrecte.
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.
STATUS_INSUFFICIENT_RESOURCES	La mémoire disponible était insuffisante.
STATUS_INVALID_DEVICE_REQUEST	L’IRQL de l’appelant n’a pas été PASSIVE_LEVEL, ou la demande d’E/S que le paramètre Request spécifié a déjà été mise en file d’attente vers une cible d’E/S.
STATUS_IO_TIMEOUT	Le pilote a fourni une valeur de délai d’attente et la demande n’a pas été effectuée dans le délai imparti.
STATUS_REQUEST_NOT_ACCEPTED	Le paquet de demandes d’E/S (IRP) que représente le paramètre Request ne fournit pas suffisamment de structures IO_STACK_LOCATION pour permettre au pilote de transférer la requête.

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 la méthode WdfUsbTargetPipeResetSynchronously pour envoyer une demande de réinitialisation USB de manière synchrone. Pour envoyer de telles demandes de manière asynchrone, utilisez WdfUsbTargetPipeFormatRequestForReset, suivi de WdfRequestSend.

Avant que le framework ne réinitialise le canal USB de la cible d’E/S, il annule toutes les demandes d’E/S qui restent dans la file d’attente de 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 WdfUsbTargetPipeResetSynchronously n’est pas retourné.

Le pilote doit appeler WdfIoTargetStop avant d’appeler WdfUsbTargetPipeResetSynchronously. Une fois que WdfUsbTargetPipeResetSynchronously est retourné, le pilote peut appeler WdfIoTargetStart.

Lorsqu’un pilote appelle WdfUsbTargetPipeResetSynchronously, le framework envoie une requête URB_FUNCTION_RESET_PIPE à la cible d’E/S. Pour plus d’informations sur la réinitialisation d’un canal USB, consultez la spécification USB.

La méthode WdfUsbTargetPipeResetSynchronously ne retourne pas tant que la demande n’est pas terminée, sauf si le pilote fournit une valeur de délai d’attente dans la structure WDF_REQUEST_SEND_OPTIONS vers laquelle pointe le paramètre RequestOptions , ou si une erreur est détecté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 WdfUsbTargetPipeResetSynchronously.

Pour créer et envoyer une nouvelle demande, fournissez un handle de requête NULL pour le paramètre Request , ou créez un objet de requête et fournissez son handle :

Si vous fournissez un handle de requête NULL , l’infrastructure utilise un objet de requête interne. Cette technique est simple à utiliser, mais le pilote ne peut pas annuler la demande.
Si vous appelez WdfRequestCreate pour créer un ou plusieurs objets de requête, vous pouvez réutiliser ces objets de requête en appelant WdfRequestReuse. Cette technique permet à la fonction de rappel EvtDriverDeviceAdd de votre pilote de préallouer des objets de requête pour un appareil. En outre, un autre thread de pilote peut appeler WdfRequestCancelSentRequest pour annuler la demande, si nécessaire.

Votre pilote peut spécifier un paramètre RequestOptions non NULL, que le pilote fournisse un paramètre non NULL ou un paramètre de requêteNULL. Vous pouvez, par exemple, utiliser le paramètre RequestOptions pour spécifier une valeur de délai d’attente.

Pour plus d’informations sur l’obtention d’informations status après la fin d’une demande d’E/S, consultez Obtention d’informations d’achèvement.

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

Exemples

L’exemple de code suivant envoie une demande de réinitialisation au canal d’un périphérique USB.

NTSTATUS  status;

status = WdfUsbTargetPipeResetSynchronously(
                                            Pipe, 
                                            WDF_NO_HANDLE,
                                            NULL
                                            );

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfusb.h (inclure Wdfusb.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestForUrbXrb(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Voir aussi

WdfObjectDereference

WdfRequestCancelSentRequest

WdfRequestSend

WdfUsbTargetPipeAbortSynchronously

Partager via