USBD_SelectInterfaceUrbAllocateAndBuild, fonction (usbdlib.h)
La routine USBD_SelectInterfaceUrbAllocateAndBuild alloue et met en forme une structure URB requise pour une demande de sélection d’une interface ou de modification de son autre paramètre.
Syntaxe
NTSTATUS USBD_SelectInterfaceUrbAllocateAndBuild(
[in] USBD_HANDLE USBDHandle,
[in] USBD_CONFIGURATION_HANDLE ConfigurationHandle,
PUSBD_INTERFACE_LIST_ENTRY InterfaceListEntry,
[out] PURB *Urb
);
Paramètres
[in] USBDHandle
Handle USBD récupéré par le pilote client lors d’un appel précédent à la routine USBD_CreateHandle .
[in] ConfigurationHandle
Handle retourné par la pile de pilotes USB dans le membre UrbSelectConfiguration.ConfigurationHandle de la structure URB , une fois que la pile de pilotes a terminé une demande select-configuration.
InterfaceListEntry
Pointeur vers une structure de USBD_INTERFACE_LIST_ENTRY allouée par l’appelant. Pour plus d'informations, consultez la section Notes.
[out] Urb
Pointeur vers une structure URB qui reçoit l’URB allouée par USBD_SelectInterfaceUrbAllocateAndBuild. Le pilote client doit libérer l’URB lorsque le pilote a fini de l’utiliser en appelant USBD_UrbFree.
Valeur retournée
La routine retourne un code NTSTATUS. Les valeurs possibles incluent, sans s’y limiter, les codes status répertoriés dans le tableau suivant.
| Code de retour | Description |
|---|---|
|
L’appel de routine a réussi. |
|
L’appelant a passé la valeur NULL dans l’un des paramètres. |
|
Mémoire insuffisante pour terminer l’appel. |
Remarques
Le pilote client doit appeler la routine USBD_SelectInterfaceUrbAllocateAndBuild après avoir sélectionné une configuration dans l’appareil. Une fois qu’une demande de configuration de sélection est terminée, le pilote client reçoit un handle de configuration dans le membre UrbSelectConfiguration.ConfigurationHandle de l’URB. Ce handle doit être spécifié dans le paramètre ConfigurationHandle de USBD_SelectInterfaceUrbAllocateAndBuild.
Un pilote client appelle USBD_SelectInterfaceUrbAllocateAndBuild pour allouer et générer un URB pour une demande de sélection d’interface afin de modifier l’autre paramètre d’une interface, dans la configuration sélectionnée. Dans l’appel à USBD_SelectInterfaceUrbAllocateAndBuild, le pilote client doit allouer et fournir un pointeur vers une structure USBD_INTERFACE_LIST_ENTRY . Le pilote client doit définir les membres de la structure comme suit :
- Le membre InterfaceDescriptor doit pointer vers une structure USB_INTERFACE_DESCRIPTOR qui contient le descripteur d’interface avec l’autre paramètre à sélectionner. Le descripteur d’interface a été obtenu dans une demande précédente pour obtenir un descripteur de configuration et les descripteurs d’interface et de point de terminaison associés.
- Le membre Interface doit être NULL.
Un pilote client ne peut pas modifier d’autres paramètres dans plusieurs interfaces dans une seule demande select-interface. Chaque requête ne cible qu’une seule interface.
Une fois la demande d’interface de sélection terminée, la pile de pilotes USB remplit USBD_INTERFACE_INFORMATION avec des informations sur les canaux ouverts pour les points de terminaison définis dans l’autre paramètre sélectionné. Le pilote client peut obtenir ces handles de canal en inspectant le tableau pointé par le membre Pipes de USBD_INTERFACE_INFORMATION, et stocker les handles pour les demandes de transfert de données futures.
Le pilote client peut réutiliser un URB alloué par USBD_SelectInterfaceUrbAllocateAndBuild uniquement pour une autre demande d’interface de sélection pour le même autre paramètre. Le pilote client ne doit pas réutiliser l’URB pour un autre type de demande ou pour une autre demande d’interface de sélection pour un autre paramètre. Au lieu d’allouer un nouvel URB, la réutilisation d’un URB existant est l’approche recommandée dans certains scénarios. Prenons l’exemple d’un périphérique audio USB qui a une interface avec deux paramètres alternatifs, définis pour deux exigences de bande passante. Le paramètre 0 est défini pour zéro bande passante ; Le paramètre 1 est défini pour utiliser une certaine quantité de bande passante. Le pilote client souhaite basculer fréquemment entre les deux paramètres selon que l’appareil est en cours d’utilisation ou non. Pour implémenter ce scénario, le pilote client peut allouer deux URB pour les demandes d’interface de sélection, une par paramètre. Le pilote client peut utiliser (et réutiliser) un URB pour une demande de sélection d’interface pour sélectionner le paramètre 1 lorsqu’il y a des sons à envoyer à l’appareil. Pour économiser la bande passante en l’absence de sons, le pilote client peut utiliser (et réutiliser) l’autre URB pour basculer vers le paramètre 0. Cette implémentation empêche le pilote client d’allouer des URB pour chacune de ces demandes d’interface de sélection, chaque fois que le pilote doit modifier le paramètre.
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 |