structure _URB_HEADER (usb.h)

Article
08/07/2023

La structure _URB_HEADER est utilisée par les pilotes clients USB pour fournir des informations de base sur la requête envoyée au pilote du contrôleur hôte.

Syntaxe

struct _URB_HEADER {
  USHORT      Length;
  USHORT      Function;
  USBD_STATUS Status;
  PVOID       UsbdDeviceHandle;
  ULONG       UsbdFlags;
};

Membres

Length

Spécifie la longueur, en octets, de l’URB. Pour les requêtes URB qui utilisent des structures de données autres que _URB_HEADER, ce membre doit être défini sur la longueur de la structure de requête URB entière, et non sur la taille _URB_HEADER.

Function

Spécifie un code numérique indiquant l’opération demandée pour cet URB. L’une des valeurs suivantes doit être définie :

URB_FUNCTION_SELECT_CONFIGURATION

Indique au pilote du contrôleur hôte qu’une configuration doit être sélectionnée. S’il est défini, l’URB est utilisé avec URB_SELECT_CONFIGURATION comme structure de données.

URB_FUNCTION_SELECT_INTERFACE

Indique au pilote du contrôleur hôte qu’un autre paramètre d’interface est sélectionné pour une interface. S’il est défini, l’URB est utilisé avec _URB_SELECT_INTERFACE comme structure de données.

URB_FUNCTION_ABORT_PIPE

Indique que toutes les demandes en suspens pour un canal doivent être annulées. S’il est défini, l’URB est utilisé avec _URB_PIPE_REQUEST comme structure de données. Cette demande à usage général permet à un client d’annuler tous les transferts en attente pour le canal spécifié. L’état du canal et l’état du point de terminaison ne sont pas affectés. La demande d’abandon peut se terminer avant que toutes les demandes en suspens ne soient terminées. Ne partez pas du principe que l’achèvement de la demande d’abandon implique que toutes les autres demandes en suspens sont terminées.

URB_FUNCTION_TAKE_FRAME_LENGTH_CONTROL

Cette fonction URB est déconseillée dans les systèmes d’exploitation Windows 2000 et ultérieurs et n’est pas prise en charge par Microsoft. Ne pas utiliser. Si vous spécifiez cette fonction avec une requête URB, la demande échoue et le système signale une erreur.

URB_FUNCTION_RELEASE_FRAME_LENGTH_CONTROL

URB_FUNCTION_GET_FRAME_LENGTH

Cette fonction URB est déconseillée dans les systèmes d’exploitation Windows 2000 et ultérieurs et n’est pas prise en charge par Microsoft. Ne pas utiliser. Si vous utilisez cette fonction avec une requête URB, la requête échoue et le système signale une erreur.

URB_FUNCTION_SET_FRAME_LENGTH

Cette fonction URB est déconseillée dans les systèmes d’exploitation Windows 2000 et ultérieurs et n’est pas prise en charge par Microsoft. Ne pas utiliser. Si vous l’utilisez avec une requête URB, la demande échoue et le système signale une erreur.

URB_FUNCTION_GET_CURRENT_FRAME_NUMBER

Demande le numéro d’image actuel à partir du pilote du contrôleur hôte. S’il est défini, l’URB est utilisé avec _URB_GET_CURRENT_FRAME_NUMBER comme structure de données.

URB_FUNCTION_CONTROL_TRANSFER

Transfère des données vers ou depuis un canal de contrôle. S’il est défini, l’URB est utilisé avec _URB_CONTROL_TRANSFER comme structure de données.

URB_FUNCTION_CONTROL_TRANSFER_EX

Transfère des données vers ou depuis un canal de contrôle sans limite de temps spécifiée par une valeur de délai d’expiration. S’il est défini, l’URB est utilisé avec URB_CONTROL_TRANSFER_EX comme structure de données.

Disponible dans Windows Vista et les systèmes d’exploitation ultérieurs.

URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER

Transfère des données à partir d’un canal en bloc ou d’un canal d’interruption ou vers un canal en bloc. S’il est défini, l’URB est utilisé avec _URB_BULK_OR_INTERRUPT_TRANSFER comme structure de données.

URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER_USING_CHAINED_MDL

Transfère des données vers et à partir d’un canal en bloc ou d’un canal d’interruption, à l’aide de dll MDL chaînées. S’il est défini, l’URB est utilisé avec _URB_BULK_OR_INTERRUPT_TRANSFER comme structure de données. Le pilote client doit définir le membre TransferBufferMDL sur la première structure MDL de la chaîne qui contient la mémoire tampon de transfert. La pile de pilotes USB ignore le membre TransferBuffer lors du traitement de cet URB.

Disponible dans Windows 8. Pour plus d’informations sur l’utilisation des DLL chaînées, consultez Guide pratique pour envoyer des DLL chaînées.>

URB_FUNCTION_ISOCH_TRANSFER

Transfère des données vers ou à partir d’un canal isochronieux. S’il est défini, l’URB est utilisé avec _URB_ISOCH_TRANSFER comme structure de données.

URB_FUNCTION_ISOCH_TRANSFER_USING_CHAINED_MDL

Transfère des données vers ou depuis un canal isochronisé à l’aide de MDL chaînées. S’il est défini, l’URB est utilisé avec _URB_ISOCH_TRANSFER comme structure de données. Le pilote client doit définir le membre TransferBufferMDL sur le premier MDL de la chaîne qui contient la mémoire tampon de transfert. La pile de pilotes USB ignore le membre TransferBuffer lors du traitement de cet URB.

Disponible dans Windows 8. Pour plus d’informations sur l’utilisation des DLL chaînées, consultez Guide pratique pour envoyer des DLL chaînées.>

URB_FUNCTION_RESET_PIPE

Voir URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL.

URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL

Réinitialise le canal indiqué. S’il est défini, cet URB est utilisé avec _URB_PIPE_REQUEST.

Notes

Cet URB remplace URB_FUNCTION_RESET_PIPE.

Le pilote de bus effectue trois tâches en réponse à cet URB :

Tout d’abord, pour tous les canaux à l’exception des canaux isochronieux, cette URB envoie une demande CLEAR_FEATURE pour effacer la fonctionnalité ENDPOINT_HALT de l’appareil.

Deuxièmement, le pilote de bus USB réinitialise le bouton bascule de données côté hôte, comme requis par la spécification USB. Le périphérique USB doit réinitialiser le bouton bascule de données côté appareil lorsque le pilote de bus efface sa fonctionnalité de ENDPOINT_HALT. Étant donné que certains appareils non conformes ne prennent pas en charge cette fonctionnalité, Microsoft fournit les deux URI supplémentaires : URB_FUNCTION_SYNC_CLEAR_STALL et URB_FUNCTION_SYNC_RESET_PIPE. Ceux-ci permettent aux pilotes clients d’effacer la fonctionnalité de ENDPOINT_HALT sur l’appareil ou de réinitialiser le canal côté hôte, respectivement, sans affecter le bouton bascule de données côté hôte. Si l’appareil ne réinitialise pas le bouton bascule de données comme il le doit, le pilote client peut compenser ce défaut en ne réinitialisant pas le bouton bascule de données côté hôte. Si le bouton bascule de données est réinitialisé côté hôte, mais pas côté appareil, les paquets sortent de l’ordre et l’appareil peut supprimer des paquets.

Troisièmement, une fois que le pilote de bus a correctement réinitialisé le canal, il reprend les transferts avec l’URB suivant mis en file d’attente.

Après une réinitialisation de canal, les transferts reprennent avec l’URB suivant mis en file d’attente.

Il n’est pas nécessaire d’effacer une condition d’arrêt sur un canal de contrôle par défaut. Le canal de contrôle par défaut doit toujours accepter les paquets d’installation. Par conséquent, s’il s’arrête, la pile USB efface automatiquement la condition d’arrêt. Le pilote client n’a pas besoin d’effectuer une action spéciale pour effacer la condition d’arrêt sur un canal par défaut.

Tous les transferts doivent être abandonnés ou annulés avant de tenter de réinitialiser le canal.

Cette URB doit être envoyée à PASSIVE_LEVEL.

URB_FUNCTION_SYNC_RESET_PIPE

Efface la condition d’arrêt côté hôte d’un canal. S’il est défini, cet URB est utilisé avec _URB_PIPE_REQUEST comme structure de données.

Cet URB permet à un client d’effacer l’état arrêté d’un canal sans réinitialiser le bouton bascule de données et sans effacer la condition de blocage du point de terminaison (ENDPOINT_HALT de fonctionnalité). Pour effacer une condition d’arrêt sur le canal, réinitialisez le bouton bascule de données côté hôte et effacez un décrochage sur l’appareil avec une seule opération, utilisez URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL.

Les codes status suivants sont importants et ont la signification indiquée :

USBD_STATUS_INVALID_PIPE_HANDLE

PipeHandle n’est pas valide

USBD_STATUS_ERROR_BUSY

Le point de terminaison a des transferts actifs en attente.

Il n’est pas nécessaire d’effacer une condition d’arrêt sur un canal de contrôle par défaut. Le canal de contrôle par défaut doit toujours accepter les paquets d’installation. Ainsi, s’il s’arrête, la pile USB efface automatiquement la condition d’arrêt. Le pilote client n’a pas besoin d’effectuer une action spéciale pour effacer la condition d’arrêt sur un canal par défaut.

Tous les transferts doivent être abandonnés ou annulés avant de tenter de réinitialiser le canal.

Cet URB doit être envoyé à PASSIVE_LEVEL.

Disponible dans les systèmes d’exploitation Windows XP et ultérieurs.

URB_FUNCTION_SYNC_CLEAR_STALL

Efface la condition de blocage sur le point de terminaison. Pour tous les canaux à l’exception des canaux isochroneuses, cet URB envoie une demande de CLEAR_FEATURE pour effacer la fonctionnalité de ENDPOINT_HALT de l’appareil. Toutefois, contrairement à la fonction RB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL, cette fonction URB ne réinitialise pas le bouton bascule de données côté hôte du canal. La spécification USB exige que les appareils réinitialisent le bouton bascule des données côté appareil une fois que le client a effacé la fonctionnalité de ENDPOINT_HALT de l’appareil, mais certains appareils non conformes ne réinitialisent pas correctement leurs données. Les pilotes clients qui gèrent ces appareils peuvent compenser ce défaut en effaçant l’état de décrochage directement avec URB_FUNCTION_SYNC_CLEAR_STALL au lieu de réinitialiser le canal avec URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL. URB_FUNCTION_SYNC_CLEAR_STALL efface une condition de blocage sur l’appareil sans réinitialiser le bouton bascule de données côté hôte. Cela empêche un appareil non conforme d’interpréter le paquet suivant comme une retransmission et de supprimer le paquet.

S’il est défini, l’URB est utilisé avec _URB_PIPE_REQUEST comme structure de données.

Cette fonction URB doit être envoyée à PASSIVE_LEVEL

Disponible dans les systèmes d’exploitation Windows XP et ultérieurs.

URB_FUNCTION_GET_DESCRIPTOR_FROM_DEVICE

Récupère le descripteur d’appareil à partir d’un périphérique USB spécifique. S’il est défini, l’URB est utilisé avec _URB_CONTROL_DESCRIPTOR_REQUEST comme structure de données.

URB_FUNCTION_GET_DESCRIPTOR_FROM_ENDPOINT

Récupère le descripteur à partir d’un point de terminaison sur une interface pour un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_DESCRIPTOR_REQUEST comme structure de données.

URB_FUNCTION_SET_DESCRIPTOR_TO_DEVICE

Définit un descripteur d’appareil sur un appareil. S’il est défini, l’URB est utilisé avec _URB_CONTROL_DESCRIPTOR_REQUEST comme structure de données.

URB_FUNCTION_SET_DESCRIPTOR_TO_ENDPOINT

Définit un descripteur de point de terminaison sur un point de terminaison pour une interface. S’il est défini, l’URB est utilisé avec _URB_CONTROL_DESCRIPTOR_REQUEST comme structure de données.

URB_FUNCTION_SET_FEATURE_TO_DEVICE

Définit une fonctionnalité définie par USB sur un appareil. S’il est défini, l’URB est utilisé avec _URB_CONTROL_FEATURE_REQUEST comme structure de données.

URB_FUNCTION_SET_FEATURE_TO_INTERFACE

Définit une fonctionnalité définie par USB sur une interface pour un appareil. S’il est défini, l’URB est utilisé avec _URB_CONTROL_FEATURE_REQUEST comme structure de données.

URB_FUNCTION_SET_FEATURE_TO_ENDPOINT

Définit une fonctionnalité définie par USB sur un point de terminaison pour une interface sur un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_FEATURE_REQUEST comme structure de données.

URB_FUNCTION_SET_FEATURE_TO_OTHER

Définit une fonctionnalité définie par USB sur une cible définie par le périphérique sur un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_FEATURE_REQUEST comme structure de données.

URB_FUNCTION_CLEAR_FEATURE_TO_DEVICE

Efface une fonctionnalité définie par USB sur un appareil. S’il est défini, l’URB est utilisé avec _URB_CONTROL_FEATURE_REQUEST comme structure de données.

URB_FUNCTION_CLEAR_FEATURE_TO_INTERFACE

Efface une fonctionnalité définie par USB sur une interface pour un appareil. S’il est défini, l’URB est utilisé avec _URB_CONTROL_FEATURE_REQUEST comme structure de données.

URB_FUNCTION_CLEAR_FEATURE_TO_ENDPOINT

Efface une fonctionnalité définie par USB sur un point de terminaison, pour une interface, sur un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_FEATURE_REQUEST comme structure de données.

URB_FUNCTION_CLEAR_FEATURE_TO_OTHER

Efface une fonctionnalité définie par USB sur une cible définie par un appareil sur un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_FEATURE_REQUEST comme structure de données.

URB_FUNCTION_GET_STATUS_FROM_DEVICE

Récupère status à partir d’un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_GET_STATUS_REQUEST comme structure de données.

URB_FUNCTION_GET_STATUS_FROM_INTERFACE

Récupère status d’une interface sur un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_GET_STATUS_REQUEST comme structure de données.

URB_FUNCTION_GET_STATUS_FROM_ENDPOINT

Récupère status à partir d’un point de terminaison pour une interface sur un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_GET_STATUS_REQUEST comme structure de données.

URB_FUNCTION_GET_STATUS_FROM_OTHER

Récupère status d’une cible définie par l’appareil sur un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_GET_STATUS_REQUEST comme structure de données.

URB_FUNCTION_VENDOR_DEVICE

Envoie une commande propre au fournisseur à un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_VENDOR_OR_CLASS_REQUEST comme structure de données.

URB_FUNCTION_VENDOR_INTERFACE

Envoie une commande spécifique au fournisseur pour une interface sur un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_VENDOR_OR_CLASS_REQUEST comme structure de données.

URB_FUNCTION_VENDOR_ENDPOINT

Envoie une commande spécifique au fournisseur pour un point de terminaison sur une interface sur un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_VENDOR_OR_CLASS_REQUEST comme structure de données.

URB_FUNCTION_VENDOR_OTHER

Envoie une commande spécifique au fournisseur à une cible définie par l’appareil sur un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_VENDOR_OR_CLASS_REQUEST comme structure de données.

URB_FUNCTION_CLASS_DEVICE

Envoie une commande spécifique à une classe définie par USB à un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_VENDOR_OR_CLASS_REQUEST comme structure de données.

URB_FUNCTION_CLASS_INTERFACE

Envoie une commande spécifique à une classe définie par USB à une interface sur un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_VENDOR_OR_CLASS_REQUEST comme structure de données.

URB_FUNCTION_CLASS_ENDPOINT

Envoie une commande spécifique à une classe définie par USB à un point de terminaison, sur une interface, sur un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_VENDOR_OR_CLASS_REQUEST comme structure de données.

URB_FUNCTION_CLASS_OTHER

Envoie une commande spécifique à une classe définie par USB à une cible définie par le périphérique sur un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_VENDOR_OR_CLASS_REQUEST comme structure de données.

URB_FUNCTION_GET_CONFIGURATION

Récupère la configuration actuelle sur un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_GET_CONFIGURATION_REQUEST comme structure de données.

URB_FUNCTION_GET_INTERFACE

Récupère les paramètres actuels d’une interface sur un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_GET_INTERFACE_REQUEST comme structure de données.

Disponible dans Windows 2000 et Windows Vista et les systèmes d’exploitation ultérieurs. Non disponible dans Windows XP.

URB_FUNCTION_GET_DESCRIPTOR_FROM_INTERFACE

Récupère le descripteur à partir d’une interface pour un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_DESCRIPTOR_REQUEST comme structure de données.

URB_FUNCTION_SET_DESCRIPTOR_TO_INTERFACE

Définit un descripteur pour une interface sur un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_CONTROL_DESCRIPTOR_REQUEST comme structure de données.

URB_FUNCTION_GET_MS_FEATURE_DESCRIPTOR

Récupère un descripteur de fonctionnalité de système d’exploitation Microsoft à partir d’un périphérique USB ou d’une interface sur un périphérique USB. S’il est défini, l’URB est utilisé avec _URB_OS_FEATURE_DESCRIPTOR_REQUEST comme structure de données.

Disponible dans les systèmes d’exploitation Windows XP et ultérieurs.

URB_FUNCTION_OPEN_STATIC_STREAMS

Ouvre les flux dans le point de terminaison en bloc spécifié. S’il est défini, l’URB est utilisé avec _URB_OPEN_STATIC_STREAMS comme structure de données.

Disponible dans Windows 8. Pour plus d’informations sur la mise en forme d’un URB pour une demande de flux ouvert, consultez How to Open and Close Static Streams in a USB Bulk Endpoint.

URB_FUNCTION_CLOSE_STATIC_STREAMS

Ferme tous les flux ouverts dans le point de terminaison en bloc spécifié. S’il est défini, l’URB est utilisé avec _URB_PIPE_REQUEST comme structure de données.

Disponible dans Windows 8. Pour plus d’informations sur la mise en forme d’un URB pour une demande de flux ouvert, consultez How to Open and Close Static Streams in a USB Bulk Endpoint.

Status

Contient un code USBD_STATUS_XXX au retour du pilote du contrôleur hôte.

UsbdDeviceHandle

Réservé. Ne pas utiliser.

UsbdFlags

Réservé. Ne pas utiliser.

Remarques

La structure _URB_HEADER est membre de toutes les requêtes USB qui font partie de la structure URB. La structure _URB_HEADER est utilisée pour fournir des informations communes sur chaque requête au pilote du contrôleur hôte.

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