WdfUsbTargetPipeFormatRequestForAbort, fonction (wdfusb.h)

[S’applique à KMDF et UMDF]

La méthode WdfUsbTargetPipeFormatRequestForAbort génère une demande d’abandon pour un canal USB spécifié, mais elle n’envoie pas la requête.

Syntaxe

NTSTATUS WdfUsbTargetPipeFormatRequestForAbort(
  [in] WDFUSBPIPE Pipe,
  [in] WDFREQUEST Request
);

Paramètres

[in] Pipe

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

[in] Request

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

Valeur retournée

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

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.
STATUS_INSUFFICIENT_RESOURCES	La mémoire disponible était insuffisante.
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 WdfUsbTargetPipeFormatRequestForAbort, suivi de WdfRequestSend, pour envoyer une demande d’abandon USB de manière synchrone ou asynchrone. Vous pouvez également utiliser la méthode WdfUsbTargetPipeAbortSynchronously pour envoyer une requête de manière synchrone.

Une demande d’abandon USB entraîne l’annulation par la cible d’E/S du pilote de toutes les demandes d’E/S qui ont été envoyées à un canal. Lorsqu’un pilote appelle WdfRequestSend, le framework envoie une requête URB_FUNCTION_ABORT_PIPE à la cible d’E/S. Pour plus d’informations sur l’annulation d’opérations sur un canal USB (également appelée « abandon d’un canal »), 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 requête reçue pour le paramètre Request de la méthode WdfUsbTargetPipeFormatRequestForAbort.

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 WdfUsbTargetPipeFormatRequestForAbort. 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é WdfUsbTargetPipeFormatRequestForAbort 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 à WdfUsbTargetPipeFormatRequestForAbort 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 WdfUsbTargetPipeFormatRequestForAbort) 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 à WdfUsbTargetPipeFormatRequestForAbort 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 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 WdfUsbTargetPipeFormatRequestForAbort et les cibles d’E/S USB, consultez Cibles d’E/S USB.

Exemples

L’exemple de code suivant met en forme une demande d’abandon pour un canal USB, inscrit une fonction de rappel CompletionRoutine et envoie la requête.

status = WdfUsbTargetPipeFormatRequestForAbort(
                                               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)

Voir aussi

WdfUsbInterfaceGetConfiguredPipe