structure _URB_CONTROL_TRANSFER (usb.h)

Article
08/07/2023

La structure _URB_CONTROL_TRANSFER est utilisée par les pilotes clients USB pour transférer des données vers ou à partir d’un canal de contrôle.

Syntaxe

struct _URB_CONTROL_TRANSFER {
  struct _URB_HEADER   Hdr;
  USBD_PIPE_HANDLE     PipeHandle;
  ULONG                TransferFlags;
  ULONG                TransferBufferLength;
  PVOID                TransferBuffer;
  PMDL                 TransferBufferMDL;
  struct _URB          *UrbLink;
  struct _URB_HCD_AREA hca;
  UCHAR                SetupPacket[8];
};

Membres

Hdr

Pointeur vers une structure de _URB_HEADER qui spécifie les informations d’en-tête URB. Hdr.Function doit être URB_FUNCTION_CONTROL_TRANSFER, et Hdr.Length doit être sizeof(_URB_CONTROL_TRANSFER).

PipeHandle

Handle pour le canal de contrôle.

Si target est le point de terminaison de contrôle par défaut, PipeHandle doit avoir la valeur NULL. Dans ce cas, les TransferFlags doivent contenir l’indicateur USBD_DEFAULT_PIPE_TRANSFER.

Si target est un point de terminaison de contrôle autre que celui par défaut, PipeHandle spécifie un handle opaque pour le canal de contrôle. Le pilote du contrôleur hôte retourne ce handle quand le pilote client sélectionne la configuration du périphérique avec un URB de type URB_FUNCTION_SELECT_CONFIGURATION ou quand le pilote client modifie les paramètres d’une interface avec une interface URB de type URB_FUNCTION_SELECT_INTERFACE.

TransferFlags

Spécifie zéro, un ou une combinaison des indicateurs suivants :

Valeur	Signification
USBD_TRANSFER_DIRECTION_IN	Est défini pour demander des données à partir d’un appareil. Pour transférer des données vers un appareil, cet indicateur doit être clair.
USBD_TRANSFER_DIRECTION_OUT	Est défini pour transférer des données vers un appareil. Définir cet indicateur revient à effacer l’indicateur USBD_TRANSFER_DIRECTION_IN.
USBD_SHORT_TRANSFER_OK	Est défini pour indiquer au contrôleur hôte de ne pas retourner d’erreur lorsqu’il reçoit un paquet de l’appareil qui est plus court que la taille de paquet maximale pour le point de terminaison. La taille maximale du paquet pour le point de terminaison est signalée dans le membre bMaxPacketSize0 de la structure USB_DEVICE_DESCRIPTOR (descripteur d’appareil) pour le point de terminaison de contrôle par défaut. Pour un point de terminaison de contrôle autre que celui par défaut, la taille maximale du paquet est définie dans le membre wMaxPacketSize de la structure USB_ENDPOINT_DESCRIPTOR (descripteur de point de terminaison). Lorsque le contrôleur hôte reçoit un paquet dont la longueur est inférieure à la valeur wMaxPacketSize sur un point de terminaison de contrôle, le comportement est le suivant en fonction du type de contrôleur hôte : Sur les contrôleurs hôtes EHCI, le contrôleur hôte passe immédiatement à la phase de status du transfert de contrôle. Le transfert se termine correctement, que USBD_SHORT_TRANSFER_OK soit défini ou non. Sur les contrôleurs hôtes UHCI et OHCI, si USBD_SHORT_TRANSFER_OK est défini, le contrôleur hôte passe à la phase de status. Si USBD_SHORT_TRANSFER_OK n’est pas défini, le contrôleur hôte abandonne les phases de données et de status du transfert de contrôle et le transfert se termine avec une erreur.
USBD_DEFAULT_PIPE_TRANSFER	Est défini pour indiquer au contrôleur hôte d’effectuer un transfert de contrôle sur le canal de contrôle par défaut. Cela permet à l’appelant d’envoyer des commandes au canal de contrôle par défaut sans spécifier explicitement le handle de canal.

TransferBufferLength

Spécifie la longueur, en octets, de la mémoire tampon spécifiée dans TransferBuffer ou décrite dans TransferBufferMDL. Le pilote du contrôleur hôte retourne le nombre d’octets envoyés ou lus à partir du canal dans ce membre.

TransferBuffer

Pointeur vers une mémoire tampon résidente pour le transfert ou a la valeur NULL si une MDL est fournie dans TransferBufferMDL. Le contenu de cette mémoire tampon dépend de la valeur de TransferFlags. Si USBD_TRANSFER_DIRECTION_IN est spécifié, cette mémoire tampon contient les données lues à partir de l’appareil au retour du pilote du contrôleur hôte. Sinon, cette mémoire tampon contient des données fournies par le pilote à transférer vers l’appareil.

TransferBufferMDL

Pointeur vers une MDL qui décrit une mémoire tampon résidente ou a la valeur NULL si une mémoire tampon est fournie dans TransferBuffer. Le contenu de la mémoire tampon dépend de la valeur de TransferFlags. Si USBD_TRANSFER_DIRECTION_IN est spécifié, la mémoire tampon décrite contient les données lues à partir de l’appareil au retour du pilote du contrôleur hôte. Sinon, la mémoire tampon contient des données fournies par le pilote à transférer vers l’appareil. Cette MDL doit être allouée à partir d’un pool non paginé.

UrbLink

Réservé. Ne pas utiliser.

hca

Réservé. Ne pas utiliser.

SetupPacket[8]

Spécifie un paquet de configuration de requête défini par USB. Le format d’un paquet de configuration de requête USB se trouve dans la spécification du cœur USB.

Remarques

La structure URB_CONTROL_TRANSFER_EX est identique à URB_CONTROL_TRANSFER, à ceci près qu’elle fournit une valeur de délai d’expiration dans le champ Délai d’expiration .

Les membres réservés de cette structure doivent être traités comme opaques et sont réservés à l’utilisation du système.