fonction WinUsb_ControlTransfer (winusb.h)

Article
03/04/2024

La fonction WinUsb_ControlTransfer transmet les données de contrôle sur un point de terminaison de contrôle par défaut.

Syntaxe

BOOL WinUsb_ControlTransfer(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            WINUSB_SETUP_PACKET     SetupPacket,
  [out]           PUCHAR                  Buffer,
  [in]            ULONG                   BufferLength,
  [out, optional] PULONG                  LengthTransferred,
  [in, optional]  LPOVERLAPPED            Overlapped
);

Paramètres

[in] InterfaceHandle

Handle opaque pour une interface dans la configuration sélectionnée.

Pour spécifier le destinataire d’une demande de contrôle comme l’ensemble de l’appareil ou la première interface, utilisez le handle retourné par WinUsb_Initialize. Pour toutes les autres interfaces, obtenez le handle de l’interface cible en appelant WinUsb_GetAssociatedInterface, puis appelez WinUsb_ControlTransfer en spécifiant le handle d’interface obtenu.

[in] SetupPacket

Paquet d’installation de 8 octets de type WINUSB_SETUP_PACKET.

[out] Buffer

Mémoire tampon allouée à l’appelant qui contient les données à transférer. La longueur de cette mémoire tampon ne doit pas dépasser 4 Ko.

[in] BufferLength

Nombre d’octets à transférer, sans inclure le paquet d’installation. Ce nombre doit être inférieur ou égal à la taille, en octets, de La mémoire tampon.

[out, optional] LengthTransferred

Pointeur vers une variable ULONG qui reçoit le nombre réel d’octets transférés. Si l’application ne s’attend pas à ce que des données soient transférées pendant la phase de données (BufferLength est égal à zéro), LengthTransferred peut avoir la valeur NULL.

[in, optional] Overlapped

Pointeur facultatif vers une structure CHEVAUCHEMENT , qui est utilisé pour les opérations asynchrones. Si ce paramètre est spécifié, WinUsb_ControlTransfer retourne immédiatement et l’événement est signalé lorsque l’opération est terminée. Si le chevauchement n’est pas fourni, la fonction WinUsb_ControlTransfer transfère les données de manière synchrone.

Valeur retournée

WinUsb_ControlTransfer retourne TRUE si l’opération réussit. Sinon, cette routine retourne FALSE et l’appelant peut récupérer l’erreur journalisée en appelant GetLastError.

GetLastError peut retourner l’un des codes d’erreur suivants.

Code de retour	Description
ERROR_INVALID_HANDLE	L’appelant a passé la valeur NULL dans le paramètre InterfaceHandle .
ERROR_NOT_ENOUGH_MEMORY	Indique que la mémoire est insuffisante pour effectuer l’opération.

Remarques

Une demande de contrôle est toujours envoyée par l’hôte au point de terminaison par défaut d’un périphérique USB, mais le destinataire de la demande peut être l’appareil entier, une interface ou un point de terminaison dans l’autre paramètre sélectionné. Dans l’appel WinUsb_ControlTransfer , l’application doit indiquer le destinataire via deux paramètres : InterfaceHandle et SetupPacket.

Si le destinataire d’une demande de contrôle est l’appareil entier, la première interface ou tout point de terminaison de cette interface, l’application doit utiliser le handle retourné par WinUsb_Initialize. Si le destinataire est une autre interface ou son point de terminaison, l’application doit obtenir le handle WinUSB associé à l’interface cible en appelant WinUsb_GetAssociatedInterface, puis appeler WinUsb_ControlTransfer en spécifiant le handle d’interface obtenu.

Conformément à la section 9.3 de la spécification USB officielle, le jeton d’installation d’un transfert de contrôle contient des informations sur la demande. Pour une application WinUSB, ce jeton d’installation est décrit à l’aide de la structure WINUSB_SETUP_PACKET .

Dans le jeton d’installation, les champs bmRequestType et wIndex sont utilisés pour indiquer le destinataire de la demande. Ces champs correspondent respectivement aux membres RequestType et Index de WINUSB_SETUP_PACKET.

Les deux bits les plus bas de RequestType indiquent le destinataire de la demande. Le destinataire peut être l’appareil, une interface, un point de terminaison ou autre (pour une demande du fournisseur). Selon le destinataire, l’octet inférieur de Index indique l’index défini par l’appareil du destinataire. La valeur d’Index dépend du type de requête. Par exemple, pour les demandes de contrôle standard, la valeur est 0 ou indique le numéro d’interface ou de point de terminaison. Pour certains types de requêtes standard, comme une demande de GET_DESCRIPTOR d’obtention d’un descripteur de chaîne, la valeur Index indique l’ID de langue.

Si le destinataire est l’appareil, l’application doit définir les valeurs RequestType et Index . Les deux bits les plus bas de la valeur RequestType doivent être 0. L’octet inférieur de la valeur d’index dépend du type de requête. InterfaceHandle doit être le handle WinUSB retourné par WinUsb_Initialize.

Si le destinataire de la requête est une interface, l’application doit définir les deux bits les plus bas de RequestType sur 0x01. L’application n’est pas tenue de définir l’octet inférieur d’Index pour n’importe quel type de requête. Pour les demandes standard, de classe et de fournisseur, Winusb.sys définit la valeur sur le numéro d’interface de l’interface cible. InterfaceHandle doit être associé à l’interface cible. L’application peut obtenir ce handle en appelant WinUsb_GetAssociatedInterface.

Si le destinataire est un point de terminaison, l’application doit définir les deux bits de RequestType les plus bas sur 0x02 et l’octet inférieur d’Index à l’adresse du point de terminaison. Dans ce cas, InterfaceHandle est associé à l’interface qui contient le point de terminaison. L’application peut obtenir ce handle en appelant WinUsb_GetAssociatedInterface.