fonction USBD_SelectConfigUrbAllocateAndBuild (usbdlib.h)

Article
02/26/2024

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

Note 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

Poignée USBD récupérée par le pilote client lors d’un appel précédent à la routine USBD_CreateHandle .

[in] ConfigurationDescriptor

Pointeur vers une structure de USB_CONFIGURATION_DESCRIPTOR allouée à l’appelant qui contient le descripteur de configuration pour la configuration à sélectionner. En règle générale, le pilote client envoie une 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 demande récupère toutes les informations sur l’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 de structures USBD_INTERFACE_LIST_ENTRY alloué par l’appelant . La longueur du tableau dépend du nombre d’interfaces dans le descripteur de configuration. Pour plus d'informations, consultez la section Notes.

[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 retournée

La routine USBD_SelectConfigUrbAllocateAndBuild retourne un code de status NT.

Les valeurs possibles incluent, sans s’y limiter, les codes status répertoriés dans le tableau suivant.

Code de retour	Description
STATUS_SUCCESS	La demande a abouti.
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 demande.

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 supérieur au 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 sur 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 dans le tableau, définissez le membre InterfaceDescriptor sur l’adresse du descripteur d’interface qui représente la nièmeinterface dans la configuration.
Le membre InterfaceDescriptor du dernier élément doit avoir la valeur NULL.

USBD_SelectConfigUrbAllocateAndBuild effectue les tâches suivantes :

Crée un URB et le remplit avec des informations sur la configuration spécifiée, ses interfaces et ses points de terminaison, et définit le type de requête sur URB_FUNCTION_SELECT_CONFIGURATION.
Remplit une structure USBD_INTERFACE_INFORMATION dans l’interface URB pour chaque interface.
Définit le membre d’interface du nième élément du tableau USBD_INTERFACE_LIST_ENTRY fourni par l’appelant sur l’adresse de la structure 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 afin de définir la configuration spécifiée. En outre, vous pouvez utiliser le membre d’interface de chaque structure 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.

Configuration requise

Condition requise	Valeur
Client minimal 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	Desktop (Expérience utilisateur)
En-tête	usbdlib.h
Bibliothèque	Usbdex.lib
IRQL	DISPATCH_LEVEL

Voir aussi

USBD_CreateConfigurationRequestEx

USBD_CreateHandle

Partager via