WdfUsbTargetPipeFormatRequestForReset, fonction (wdfusb.h)
[S’applique à KMDF et UMDF]
La méthode WdfUsbTargetPipeFormatRequestForReset génère une demande de réinitialisation pour un canal USB spécifié, mais elle n’envoie pas la requête.
Syntaxe
NTSTATUS WdfUsbTargetPipeFormatRequestForReset(
[in] WDFUSBPIPE Pipe,
[in] WDFREQUEST Request
);
Paramètres
[in] Pipe
Handle d’un objet de canal d’infrastructure obtenu en appelant WdfUsbInterfaceGetConfiguredPipe.
[in] Request
Handle d’un objet de requête d’infrastructure. Pour plus d'informations, consultez la section Notes qui suit.
Valeur retournée
WdfUsbTargetPipeFormatRequestForReset retourne la valeur d’achèvement d’E/S de la cible USB status si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :
| Code de retour | Description |
|---|---|
|
Un paramètre non valide a été détecté. |
|
La mémoire disponible était insuffisante. |
|
Le paquet de demande 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 WdfUsbTargetPipeFormatRequestForReset, suivi de WdfRequestSend, pour envoyer une demande de réinitialisation USB de manière synchrone ou asynchrone. Vous pouvez également utiliser la méthode WdfUsbTargetPipeResetSynchronously 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 réinitialisation n’est pas terminée.
Lorsqu’un pilote appelle WdfRequestSend, l’infrastructure 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.
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 WdfUsbTargetPipeFormatRequestForReset.
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 WdfUsbTargetPipeFormatRequestForReset. 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é WdfUsbTargetPipeFormatRequestForReset 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.
Les appels multiples à WdfUsbTargetPipeFormatRequestForReset 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), reformater (appeler WdfUsbTargetPipeFormatRequestForReset) et renvoyer (appeler WdfRequestSend) chaque objet de requête sans risquer une STATUS_INSUFFICIENT_RESOURCES valeur de retour à partir d’un appel ultérieur à WdfRequestCreate. Tous les appels suivants à WdfUsbTargetPipeFormatRequestForReset 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 des requêtes à chaque fois, des ressources supplémentaires peuvent être allouées.)
Pour plus d’informations sur l’obtention d’informations status après la fin d’une demande d’E/S, consultez Obtention des informations d’achèvement.
Pour plus d’informations sur la méthode WdfUsbTargetPipeFormatRequestForReset 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 réinitialisation pour un canal USB, inscrit une fonction de rappel CompletionRoutine et envoie la demande.
status = WdfUsbTargetPipeFormatRequestForReset(
pipe,
Request
);
if (!NT_SUCCESS(status)) {
goto Exit;
}
WdfRequestSetCompletionRoutine(
Request,
AbortCompletionRoutine,
pipe
);
if (WdfRequestSend(
Request,
WdfUsbTargetPipeGetIoTarget(pipe),
WDF_NO_SEND_OPTIONS
) == FALSE) {
status = WdfRequestGetStatus(Request);
goto Exit;
}
Exit:
if (!NT_SUCCESS(status)) {
WdfRequestCompleteWithInformation(
Request,
status,
0
);
}
return;
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 | <=DISPATCH_LEVEL |
| Règles de conformité DDI | DriverCreate(kmdf),KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |