fonction USBD_SelectConfigUrbAllocateAndBuild (usbdlib.h)

Article
02/07/2025

La routine USBD_SelectConfigUrbAllocateAndBuild alloue et met en forme une structure URB requise pour sélectionner une configuration pour un périphérique USB.

Remarque dans Windows 8, USBD_SelectConfigUrbAllocateAndBuild remplace USBD_CreateConfigurationRequestEx et USBD_CreateConfigurationRequest.

Syntaxe

NTSTATUS USBD_SelectConfigUrbAllocateAndBuild(
  [in]  USBD_HANDLE                   USBDHandle,
  [in]  PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor,
  [in]  PUSBD_INTERFACE_LIST_ENTRY    InterfaceList,
  [out] PURB                          *Urb
);

Paramètres

[in] USBDHandle

Handle USBD récupéré par le pilote client dans un appel précédent à la routine USBD_CreateHandle.

[in] ConfigurationDescriptor

Pointeur vers une structure USB_CONFIGURATION_DESCRIPTOR allouée par l’appelant qui contient le descripteur de configuration à sélectionner. En règle générale, le pilote client envoie un URB du type URB_FUNCTION_GET_DESCRIPTOR_FROM_DEVICE (voir _URB_CONTROL_DESCRIPTOR_REQUEST) pour récupérer des informations sur les configurations, les interfaces, les points de terminaison, le fournisseur et les descripteurs spécifiques à la classe à partir d’un périphérique USB. Lorsque le pilote client spécifie USB_CONFIGURATION_DESCRIPTOR_TYPE comme type de descripteur, la requête récupère toutes les informations d’appareil dans une structure USB_CONFIGURATION_DESCRIPTOR. Le pilote transmet ensuite le pointeur reçu à la structure USB_CONFIGURATION_DESCRIPTOR dans le paramètre ConfigurationDescriptor.

[in] InterfaceList

Pointeur vers le premier élément d’un tableau alloué par l’appelant de structures USBD_INTERFACE_LIST_ENTRY. La longueur du tableau dépend du nombre d’interfaces dans le descripteur de configuration. Pour plus d’informations, consultez Remarques.

[out] Urb

Pointeur vers une structure URB qui reçoit l’URB allouée par USBD_SelectConfigUrbAllocateAndBuild. Le pilote client doit libérer l’URB lorsque le pilote a terminé de l’utiliser en appelant USBD_UrbFree.

Valeur de retour

La routine USBD_SelectConfigUrbAllocateAndBuild retourne un code d’état NT.

Les valeurs possibles incluent, mais ne sont pas limitées à, les codes d’état répertoriés dans le tableau suivant.

Retourner le code	Description
STATUS_SUCCESS	La demande a réussi.
STATUS_INVALID_PARAMETER	L’appelant a passé une valeur de paramètre non valide. USBDHandle ou Urb a la valeur NULL.
STATUS_INSUFFICIENT_RESOURCES	Mémoire insuffisante disponible pour terminer la requête.

Remarques

Avant d’appeler USBD_SelectConfigUrbAllocateAndBuild, le pilote client doit effectuer les tâches suivantes :

Obtenez le nombre d’interfaces dans la configuration. Ces informations sont contenues dans le membre bNumInterfaces de la structure USB_CONFIGURATION_DESCRIPTOR pointée par ConfigurationDescriptor.
Créez un tableau de structures USBD_INTERFACE_LIST_ENTRY. Le nombre d’éléments dans le tableau doit être un plus que le nombre d’interfaces. Initialisez le tableau en appelant RtlZeroMemory.
Obtenez un descripteur d’interface pour chaque interface (ou son autre paramètre) dans la configuration. Vous pouvez obtenir ces descripteurs d’interface en appelant USBD_ParseConfigurationDescriptorEx.
Pour chaque élément (à l’exception du dernier élément) dans le tableau, définissez le membre InterfaceDescriptor à l’adresse d’un descripteur d’interface. Pour le premier élément du tableau, définissez le membre InterfaceDescriptor sur l’adresse du descripteur d’interface qui représente la première interface de la configuration. De même, pour le nième élément du tableau, définissez le membre InterfaceDescriptor sur l’adresse du descripteur d’interface qui représente l'nième interface de la configuration.
Le InterfaceDescriptor membre du dernier élément doit avoir la valeur NULL.

USBD_SelectConfigUrbAllocateAndBuild effectue les tâches suivantes :

Crée une URB et la remplit avec des informations sur la configuration spécifiée, ses interfaces et points de terminaison, et définit le type de requête sur URB_FUNCTION_SELECT_CONFIGURATION.
Remplit une structure USBD_INTERFACE_INFORMATION dans l’URB pour chaque interface.
Définit le membre interface du nième élément du tableau USBD_INTERFACE_LIST_ENTRY fourni par l’appelant à l’adresse de la structure de USBD_INTERFACE_INFORMATION correspondante dans l’URB.

Vous pouvez utiliser le pointeur reçu vers la structure URB pour envoyer une demande de configuration de sélection à la pile de pilotes USB pour définir la configuration spécifiée. En outre, vous pouvez utiliser l’interface membre de chaque structure de USBD_INTERFACE_INFORMATION dans le tableau pour obtenir des informations sur l’interface. Dans chaque structure USBD_INTERFACE_INFORMATION, le membre pipes est un tableau de structures USBD_PIPE_INFORMATION. Chaque structure USBD_PIPE_INFORMATION contient des informations sur les canaux ouverts (par la pile de pilotes USB) pour les points de terminaison de cette interface. Vous pouvez obtenir des handles de canal à partir du tableau et les stocker pour les demandes d’E/S futures sur l’appareil.

Exigences

Exigence	Valeur
client minimum pris en charge	Nécessite WDK pour Windows 8. Cible Windows Vista et les versions ultérieures du système d’exploitation Windows.
plateforme cible	Bureau
d’en-tête	usbdlib.h
bibliothèque	Usbdex.lib
IRQL	DISPATCH_LEVEL

Voir aussi

USBD_CreateConfigurationRequestEx

USBD_CreateHandle

Partager via