structure _URB_BULK_OR_INTERRUPT_TRANSFER (usb.h)

Article
08/07/2023

La structure _URB_BULK_OR_INTERRUPT_TRANSFER est utilisée par les pilotes clients USB pour envoyer ou recevoir des données sur un canal en bloc ou sur un canal d’interruption.

Syntaxe

struct _URB_BULK_OR_INTERRUPT_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;
};

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_BULK_OR_INTERRUPT_TRANSFER et Hdr.Length doit avoir la valeur sizeof(_URB_BULK_OR_INTERRUPT_TRANSFER).

PipeHandle

Spécifie un handle opaque pour le canal de bloc ou d’interruption. Le pilote du contrôleur hôte retourne ce handle lorsque le pilote client sélectionne la configuration de l’appareil avec un URB de type URB_FUNCTION_SELECT_CONFIGURATION ou lorsque le pilote client modifie les paramètres d’une interface avec un 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. La définition de cet indicateur équivaut à effacer l’indicateur USBD_TRANSFER_DIRECTION_IN.
USBD_SHORT_TRANSFER_OK	Est défini pour indiquer au contrôleur hôte de ne pas renvoyer d’erreur lorsqu’il reçoit un paquet de l’appareil inférieur à 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 wMaxPacketSize de la structure USB_ENDPOINT_DESCRIPTOR (descripteur de point de terminaison). Lorsque le contrôleur hôte reçoit un paquet plus court que wMaxPacketSize sur un point de terminaison en bloc ou une interruption, le contrôleur hôte cesse immédiatement de demander des données à partir du point de terminaison et termine le transfert. Si l’indicateur USBD_SHORT_TRANSFER_OK n’est pas défini, le contrôleur hôte termine le transfert avec une erreur. Cet indicateur ne doit pas être défini, sauf si USBD_TRANSFER_DIRECTION_IN est également défini. Note Sur les contrôleurs hôtes EHCI, USBD_SHORT_TRANSFER_OK est ignoré pour les points de terminaison en bloc et d’interruption. Le transfert de paquets courts sur les contrôleurs EHCI n’entraîne pas de condition d’erreur. Sur les contrôleurs hôtes UHCI et OHCI, si USBD_SHORT_TRANSFER_OK n’est pas défini pour un transfert en bloc ou une interruption, un transfert de paquets court arrête le point de terminaison et un code d’erreur est retourné pour le transfert. Le pilote client doit reprendre le point de terminaison en soumettant une demande de URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL avant d’envoyer une demande de transfert au point de terminaison.

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. La définition de cet indicateur équivaut à effacer l’indicateur USBD_TRANSFER_DIRECTION_IN.

USBD_SHORT_TRANSFER_OK

Est défini pour indiquer au contrôleur hôte de ne pas renvoyer d’erreur lorsqu’il reçoit un paquet de l’appareil inférieur à 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 wMaxPacketSize de la structure USB_ENDPOINT_DESCRIPTOR (descripteur de point de terminaison). Lorsque le contrôleur hôte reçoit un paquet plus court que wMaxPacketSize sur un point de terminaison en bloc ou une interruption, le contrôleur hôte cesse immédiatement de demander des données à partir du point de terminaison et termine le transfert. Si l’indicateur USBD_SHORT_TRANSFER_OK n’est pas défini, le contrôleur hôte termine le transfert avec une erreur.

Cet indicateur ne doit pas être défini, sauf si USBD_TRANSFER_DIRECTION_IN est également défini. Note Sur les contrôleurs hôtes EHCI, USBD_SHORT_TRANSFER_OK est ignoré pour les points de terminaison en bloc et d’interruption. Le transfert de paquets courts sur les contrôleurs EHCI n’entraîne pas de condition d’erreur.

Sur les contrôleurs hôtes UHCI et OHCI, si USBD_SHORT_TRANSFER_OK n’est pas défini pour un transfert en bloc ou une interruption, un transfert de paquets court arrête le point de terminaison et un code d’erreur est retourné pour le transfert. Le pilote client doit reprendre le point de terminaison en soumettant une demande de URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL avant d’envoyer une demande de transfert au point de terminaison.

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 est NULL si un MDL est fourni 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 contiendra 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 pour le transfert vers l’appareil.

TransferBufferMDL

Pointeur vers un 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 contiendra 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 pour le transfert 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.

Remarques

Les pilotes peuvent utiliser la routine de service UsbBuildInterruptOrBulkTransferRequest pour mettre en forme cet URB. Les mémoires tampons spécifiées dans TransferBuffer ou décrites dans TransferBufferMDL doivent être non modifiables.

Dans un URB, les paramètres TransferBuffer et TransferBufferMDL peuvent être des valeurs non NULL, en même temps. Dans ce cas, la mémoire tampon de transfert et le MDL pointé vers TransferBuffer et TransferBufferMDL doivent pointer vers la même mémoire tampon.

Le pilote de bus USB traite cet URB à DISPATCH_LEVEL.

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