structure _URB_HEADER (usb.h)

Article
02/07/2025

La structure _URB_HEADER est utilisée par les pilotes clients USB pour fournir des informations de base sur la demande 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 cette 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. Si elle est définie, 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. Si elle est définie, l’URB est utilisé avec _URB_SELECT_INTERFACE comme structure de données.

URB_FUNCTION_ABORT_PIPE

Indique que toutes les demandes en attente d’un canal doivent être annulées. Si elle est définie, l’URB est utilisé avec _URB_PIPE_REQUEST comme structure de données. Cette demande à usage général permet à un client d’annuler 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 la fin de toutes les demandes en attente. N'pas supposez que l’achèvement de la demande d’abandon implique que toutes les autres demandes en attente se 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. N’utilisez pas. Si vous spécifiez cette fonction avec une requête URB, la requête é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. N’utilisez pas. 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. N’utilisez pas. Si vous l’utilisez avec une requête URB, la requête échoue et le système signale une erreur.

URB_FUNCTION_GET_CURRENT_FRAME_NUMBER

Demande le numéro d’image actuel du pilote du contrôleur hôte. Si elle est définie, 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. Si elle est définie, 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. Si elle est définie, 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 les données d’un canal en bloc ou d’un canal d’interruption ou vers un canal en bloc. Si elle est définie, 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 MDL chaînés. Si elle est définie, 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 dans 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 de MDL chaînés, consultez Comment envoyer des dll MDL chaînées«>Comment envoyer des DLL chaînées.

URB_FUNCTION_ISOCH_TRANSFER

Transfère des données vers ou depuis un canal isochrone. Si elle est définie, 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 à partir d’un canal isochrone à l’aide de MDL chaînés. Si elle est définie, 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 dans 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 de MDL chaînés, consultez Comment envoyer des dll MDL chaînées«>Comment 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é. Si elle est définie, cette URB est utilisée avec _URB_PIPE_REQUEST.

Note

Cette URB remplace URB_FUNCTION_RESET_PIPE.

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

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

Deuxièmement, le pilote de bus USB réinitialise les données côté hôte, comme requis par la spécification USB. Le périphérique USB doit réinitialiser le bouton bascule des 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 des données côté hôte. Si l’appareil ne réinitialise pas le bouton bascule de données quand il doit, le pilote client peut compenser ce défaut en ne réinitialisant pas le bouton bascule des 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 la séquence 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 la prochaine URB mise en file d’attente.

Après une réinitialisation du canal, les transferts reprendnt avec la prochaine URB mise 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 du côté hôte d’un canal. Si elle est définie, cette URB est utilisée avec _URB_PIPE_REQUEST comme structure de données.

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

Les codes d’état suivants sont importants et ont la signification indiquée :

USBD_STATUS_INVALID_PIPE_HANDLE

Le PipeHandle n’est pas valide

USBD_STATUS_ERROR_BUSY

Le point de terminaison a des transferts actifs en attente.

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.

Disponible dans Windows XP et les systèmes d’exploitation 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 isochrones, cette 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 des données sur le 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 efface 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 désactivant la condition de blocage 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 des 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.

Si elle est définie, l’URB est utilisé avec _URB_PIPE_REQUEST comme structure de données.

Cette fonction URB doit être envoyée à PASSIVE_LEVEL

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

URB_FUNCTION_GET_DESCRIPTOR_FROM_DEVICE

Récupère le descripteur d’appareil à partir d’un périphérique USB spécifique. Si elle est définie, 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. Si elle est définie, 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. Si elle est définie, 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. Si elle est définie, 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. Si elle est définie, 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. Si elle est définie, 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. Si elle est définie, 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 l’appareil sur un périphérique USB. Si elle est définie, 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. Si elle est définie, 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. Si elle est définie, 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. Si elle est définie, 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. Si elle est définie, l’URB est utilisé avec _URB_CONTROL_FEATURE_REQUEST comme structure de données.

URB_FUNCTION_GET_STATUS_FROM_DEVICE

Récupère l’état d’un appareil USB. Si elle est définie, l’URB est utilisé avec _URB_CONTROL_GET_STATUS_REQUEST comme structure de données.

URB_FUNCTION_GET_STATUS_FROM_INTERFACE

Récupère l’état d’une interface sur un périphérique USB. Si elle est définie, l’URB est utilisé avec _URB_CONTROL_GET_STATUS_REQUEST comme structure de données.

URB_FUNCTION_GET_STATUS_FROM_ENDPOINT

Récupère l’état d’un point de terminaison pour une interface sur un périphérique USB. Si elle est définie, l’URB est utilisé avec _URB_CONTROL_GET_STATUS_REQUEST comme structure de données.

URB_FUNCTION_GET_STATUS_FROM_OTHER

Récupère l’état d’une cible définie par l’appareil sur un appareil USB. Si elle est définie, l’URB est utilisé avec _URB_CONTROL_GET_STATUS_REQUEST comme structure de données.

URB_FUNCTION_VENDOR_DEVICE

Envoie une commande spécifique au fournisseur à un périphérique USB. Si elle est définie, 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. Si elle est définie, 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. Si elle est définie, 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. Si elle est définie, 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. Si elle est définie, 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. Si elle est définie, 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. Si elle est définie, 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 l’appareil sur un périphérique USB. Si elle est définie, 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. Si elle est définie, 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. Si elle est définie, 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. Si elle est définie, 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. Si elle est définie, 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. Si elle est définie, 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 des flux dans le point de terminaison en bloc spécifié. Si elle est définie, 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’une demande URB pour une requête open-stream, consultez Comment ouvrir et fermer des flux statiques dans un point de terminaison en bloc USB.

URB_FUNCTION_CLOSE_STATIC_STREAMS

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

Status

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

UsbdDeviceHandle

Réservé. N’utilisez pas.

UsbdFlags

Réservé. N’utilisez pas.

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 courantes sur chaque requête adressée 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 à une utilisation système.