fonction USBD_SelectInterfaceUrbAllocateAndBuild (usbdlib.h)
La routine USBD_SelectInterfaceUrbAllocateAndBuild alloue et met en forme une structure URB requise pour qu’une demande sélectionne une interface ou modifie 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 dans un appel précédent à la routine USBD_CreateHandle.
[in] ConfigurationHandle
Handle retourné par la pile de pilotes USB dans la UrbSelectConfiguration.ConfigurationHandle membre de la structure URB, une fois la pile de pilotes terminée une demande de configuration sélectionnée.
InterfaceListEntry
Pointeur vers une structure USBD_INTERFACE_LIST_ENTRY allouée par l’appelant. Pour plus d’informations, consultez Remarques.
[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 terminé de l’utiliser en appelant USBD_UrbFree.
Valeur de retour
La routine retourne un code NTSTATUS. 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 |
|---|---|
|
L’appel de routine a réussi. |
|
L’appelant a passé NULL dans l’un des paramètres. |
|
Mémoire insuffisante disponible 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 sélectionnée est terminée, le pilote client reçoit un handle de configuration dans le UrbSelectConfiguration.ConfigurationHandle membre 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 une URB pour une demande d’interface de sélection pour modifier le paramètre de remplacement 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 InterfaceDescriptor membre doit pointer vers une structure USB_INTERFACE_DESCRIPTOR qui contient le descripteur d’interface avec le paramètre de remplacement à 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.
- L’interface membre doit être NULL.
Un pilote client ne peut pas modifier d’autres paramètres dans plusieurs interfaces dans une seule demande d’interface de sélection. Chaque requête cible une seule interface.
Une fois la demande d’interface sélectionnée 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 le paramètre alternatif sélectionné. Le pilote client peut obtenir ces handles de canal en inspectant le tableau pointé par le Pipes membre de USBD_INTERFACE_INFORMATIONet en stockant les handles pour les futures demandes de transfert de données.
Le pilote client peut réutiliser une URB allouée par USBD_SelectInterfaceUrbAllocateAndBuild uniquement pour une autre demande d’interface de sélection pour le même paramètre secondaire. Le pilote client ne doit pas réutiliser l’URB pour tout autre type de requête, ou pour une autre demande d’interface de sélection pour un autre paramètre. Au lieu d’allouer une nouvelle URB, la réutilisation d’une URB existante est l’approche recommandée dans certains scénarios. Considérez un périphérique audio USB doté d’une interface avec deux autres paramètres, définis pour deux exigences en bande passante. Le paramètre 0 est défini pour la bande passante zéro ; Le paramètre 1 est défini pour utiliser une certaine quantité de bande passante. Le pilote client souhaite fréquemment basculer entre les deux paramètres selon que l’appareil est en cours d’utilisation. 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) une URB pour une demande d’interface de sélection pour sélectionner le paramètre 1 lorsqu’il existe des sons à envoyer à l’appareil. Pour conserver 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.
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 |