WdfUsbTargetDeviceFormatRequestForControlTransfer, fonction (wdfusb.h)

  • Article

[S’applique à KMDF et UMDF]

La méthode WdfUsbTargetDeviceFormatRequestForControlTransfer génère une demande de transfert de contrôle USB, mais elle n’envoie pas la requête.

Syntaxe

NTSTATUS WdfUsbTargetDeviceFormatRequestForControlTransfer(
  [in]           WDFUSBDEVICE                  UsbDevice,
  [in]           WDFREQUEST                    Request,
  [in]           PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
  [in, optional] WDFMEMORY                     TransferMemory,
  [in, optional] PWDFMEMORY_OFFSET             TransferOffset
);

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.

[in] SetupPacket

Pointeur vers une structure de WDF_USB_CONTROL_SETUP_PACKET allouée à l’appelant qui décrit le transfert de contrôle.

[in, optional] TransferMemory

Handle vers un objet de mémoire d’infrastructure qui décrit une mémoire tampon d’entrée ou de sortie, en fonction de la commande spécifique à l’appareil. Ce pointeur est facultatif et peut être NULL. Pour plus d'informations, consultez la section Notes qui suit.

[in, optional] TransferOffset

Pointeur vers une structure de WDFMEMORY_OFFSET allouée par l’appelant qui fournit des valeurs facultatives de décalage d’octets et de longueur. L’infrastructure utilise ces valeurs pour déterminer l’adresse et la longueur de début, dans la mémoire tampon spécifiée par TransferMemory . Si ce pointeur a la valeur NULL, l’infrastructure utilise la mémoire tampon entière.

Valeur retournée

WdfUsbTargetDeviceFormatRequestForControlTransfer 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_PARAMETER
 Un paramètre non valide a été détecté.
STATUS_INSUFFICIENT_RESOURCES
 La mémoire disponible était insuffisante.
STATUS_INVALID_DEVICE_REQUEST
 Un descripteur de mémoire non valide a été spécifié ou la demande d’E/S spécifiée était déjà mise en file d’attente vers une cible d’E/S.
 

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 WdfUsbTargetDeviceFormatRequestForControlTransfer, suivi de WdfRequestSend, pour envoyer une demande de transfert de contrôle USB de manière synchrone ou asynchrone. Vous pouvez également utiliser la méthode WdfUsbTargetDeviceSendControlTransferSynchronously pour envoyer une requête de manière synchrone.

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. Dans les deux cas, l’infrastructure nécessite un objet de requête et, selon le type de transfert de contrôle, peut-être un espace de mémoire tampon.

Pour transférer une demande d’E/S reçue par votre pilote dans une file d’attente d’E/S :

  1. Spécifiez le handle de la requête reçue pour le paramètre Request de la méthode WdfUsbTargetDeviceFormatRequestForControlTransfer.
  2. Utilisez la mémoire tampon d’entrée ou de sortie de la requête reçue pour le paramètre TransferMemory .

    Le pilote doit appeler WdfRequestRetrieveInputMemory ou WdfRequestRetrieveOutputMemory pour obtenir un handle pour un objet de mémoire du framework qui représente la mémoire tampon d’entrée ou de sortie de la requête, et utiliser ce handle comme valeur pour TransferMemory.

Pour créer une demande d’E/S et une nouvelle mémoire tampon :
  1. Créez un objet de requête et fournissez son handle pour le paramètre Request de la méthode WdfUsbTargetDeviceFormatRequestForControlTransfer.

    Appelez WdfRequestCreate pour préallouer un ou plusieurs objets de requête. Vous pouvez réutiliser ces objets 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.

  2. Fournissez de l’espace tampon et fournissez le handle de la mémoire tampon pour le paramètre TransferMemory de la méthode WdfUsbTargetDeviceFormatRequestForControlTransfer.

    Votre pilote doit spécifier cet espace de mémoire tampon en tant que handle WDFMEMORY pour la mémoire gérée par l’infrastructure. Votre pilote peut effectuer l’une des opérations suivantes :

    Notez que si votre pilote appelle WdfRequestRetrieveInputMemory ou WdfRequestRetrieveOutputMemory et transmet le handle de mémoire à WdfUsbTargetDeviceFormatRequestForControlTransfer, le pilote ne doit pas terminer la requête d’E/S reçue tant qu’il n’a pas supprimé, réutilisé ou reformaté le nouvel objet de requête créé par le pilote. (WdfUsbTargetDeviceFormatRequestForControlTransfer incrémente le nombre de références de l’objet mémoire. La suppression, la réutilisation ou la reformatage d’un objet de requête décrémentent le nombre de références de l’objet mémoire.)
Après avoir appelé WdfUsbTargetDeviceFormatRequestForControlTransfer pour mettre en forme une requête d’E/S, le pilote doit appeler WdfRequestSend pour envoyer la demande (de manière synchrone ou asynchrone) à une cible d’E/S.

Les appels multiples à WdfUsbTargetDeviceFormatRequestForControlTransfer 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 WdfUsbTargetDeviceFormatRequestForControlTransfer) 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 à WdfUsbTargetDeviceFormatRequestForControlTransfer 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.)

L’infrastructure définit l’indicateur USBD_SHORT_TRANSFER_OK dans son URB interne. La définition de cet indicateur permet au dernier paquet d’un transfert de données d’être inférieur à la taille maximale du paquet.

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

Exemples

L’exemple de code suivant crée un objet de requête et un objet mémoire, puis initialise une structure WDF_USB_CONTROL_SETUP_PACKET pour un transfert de contrôle « get status ». Ensuite, l’exemple appelle WdfUsbTargetDeviceFormatRequestForControlTransfer pour mettre en forme la requête. Ensuite, l’exemple définit une fonction de rappel CompletionRoutine et envoie la requête à une cible d’E/S.

WDF_USB_CONTROL_SETUP_PACKET packet;
NTSTATUS status;
WDF_OBJECT_ATTRIBUTES attributes;
WDFMEMORY memHandle;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);

status = WdfRequestCreate(
                          &attributes,
                          WdfUsbTargetDeviceGetIoTarget(
                              UsbTargetDevice,
                              &request
                              )
                          );
if (!NT_SUCCESS(status)){
    return status;
}

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = request;
status = WdfMemoryCreate(
                         &attributes,
                         NonPagedPool,
                         0,
                         sizeof(USHORT),
                         &memHandle,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return status;
}

WDF_USB_CONTROL_SETUP_PACKET_INIT_GET_STATUS(
                                             &packet,
                                             BmRequestToDevice,
                                             0
                                             );
status = WdfUsbTargetDeviceFormatRequestForControlTransfer(
                         UsbTargetDevice,
                         request,
                         &packet,
                         memHandle,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return status;
}
WdfRequestSetCompletionRoutine(
                               request,
                               MyCompletionRoutine,
                               NULL
                               );
if (WdfRequestSend(
                   request,
                   WdfUsbTargetDeviceGetIoTarget(UsbTargetDevice),
                   NULL
                   ) == FALSE) {
    status = WdfRequestGetStatus(request);
}

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

WDF_USB_CONTROL_SETUP_PACKET

WDF_USB_CONTROL_SETUP_PACKET_INIT_GET_STATUS

WdfUsbTargetDeviceSendControlTransferSynchronously