función USBD_SelectInterfaceUrbAllocateAndBuild (usbdlib.h)
La rutina USBD_SelectInterfaceUrbAllocateAndBuild asigna y da formato a una estructura URB necesaria para que una solicitud seleccione una interfaz o cambie su configuración alternativa.
Sintaxis
NTSTATUS USBD_SelectInterfaceUrbAllocateAndBuild(
[in] USBD_HANDLE USBDHandle,
[in] USBD_CONFIGURATION_HANDLE ConfigurationHandle,
PUSBD_INTERFACE_LIST_ENTRY InterfaceListEntry,
[out] PURB *Urb
);
Parámetros
[in] USBDHandle
Identificador USBD recuperado por el controlador cliente en una llamada anterior a la rutina USBD_CreateHandle .
[in] ConfigurationHandle
Identificador devuelto por la pila de controladores USB en el miembro UrbSelectConfiguration.ConfigurationHandle de la estructura URB , después de que la pila del controlador complete una solicitud de configuración de selección.
InterfaceListEntry
Puntero a una estructura de USBD_INTERFACE_LIST_ENTRY asignada por el autor de la llamada. Para obtener más información, vea la sección Comentarios.
[out] Urb
Puntero a una estructura URB que recibe el URB asignado por USBD_SelectInterfaceUrbAllocateAndBuild. El controlador cliente debe liberar el URB cuando el controlador haya terminado de usarlo llamando a USBD_UrbFree.
Valor devuelto
La rutina devuelve un código NTSTATUS. Entre los valores posibles se incluyen, entre otros, los códigos de estado enumerados en la tabla siguiente.
| Código devuelto | Descripción |
|---|---|
|
La llamada rutinaria se realizó correctamente. |
|
El llamador pasó NULL en cualquiera de los parámetros. |
|
Memoria insuficiente disponible para completar la llamada. |
Comentarios
El controlador cliente debe llamar a la rutina USBD_SelectInterfaceUrbAllocateAndBuild después de seleccionar una configuración en el dispositivo. Una vez completada una solicitud de selección de configuración, el controlador cliente recibe un identificador de configuración en el miembro UrbSelectConfiguration.ConfigurationHandle del URB. Ese identificador debe especificarse en el parámetro ConfigurationHandle de USBD_SelectInterfaceUrbAllocateAndBuild.
Un controlador cliente llama a USBD_SelectInterfaceUrbAllocateAndBuild para asignar y crear un URB para una solicitud de interfaz de selección para cambiar la configuración alternativa de una interfaz, en la configuración seleccionada. En la llamada a USBD_SelectInterfaceUrbAllocateAndBuild, el controlador cliente debe asignar y proporcionar un puntero a una estructura USBD_INTERFACE_LIST_ENTRY . El controlador cliente debe establecer los miembros de la estructura de la siguiente manera:
- El miembro InterfaceDescriptor debe apuntar a una estructura de USB_INTERFACE_DESCRIPTOR que contenga el descriptor de interfaz con la configuración alternativa que se va a seleccionar. El descriptor de interfaz se obtuvo en una solicitud anterior para obtener un descriptor de configuración y los descriptores de interfaz y punto de conexión asociados.
- El miembro Interface debe ser NULL.
Un controlador cliente no puede cambiar la configuración alternativa en varias interfaces en una única solicitud de interfaz de selección. Cada solicitud tiene como destino solo una interfaz.
Una vez completada la solicitud select-interface, la pila del controlador USB rellena USBD_INTERFACE_INFORMATION con información sobre las canalizaciones abiertas para los puntos de conexión definidos en la configuración alternativa seleccionada. El controlador cliente puede obtener esos identificadores de canalización inspeccionando la matriz a la que apunta el miembro Pipes de USBD_INTERFACE_INFORMATION y almacena los identificadores para futuras solicitudes de transferencia de datos.
El controlador cliente puede reutilizar un URB asignado por USBD_SelectInterfaceUrbAllocateAndBuild solo para otra solicitud de interfaz de selección para la misma configuración alternativa. El controlador cliente no debe volver a usar el URB para cualquier otro tipo de solicitud o para otra solicitud de interfaz de selección para una configuración alternativa diferente. En lugar de asignar un nuevo URB, reutilizar un URB existente es el enfoque preferido en determinados escenarios. Considere un dispositivo de audio USB que tenga una interfaz con dos configuraciones alternativas, definidas para dos requisitos de ancho de banda. El valor 0 se define para el ancho de banda cero; El valor 1 se define para usar una determinada cantidad de ancho de banda. El controlador cliente quiere cambiar con frecuencia entre las dos configuraciones en función de si el dispositivo está en uso. Para implementar este escenario, el controlador de cliente puede asignar dos direcciones URL para solicitudes de interfaz de selección, una por configuración. El controlador cliente puede usar (y reutilizar) un URB para una solicitud de interfaz de selección para seleccionar Configuración 1 cuando hay sonidos para enviar al dispositivo. Para ahorrar ancho de banda cuando no hay sonidos, el controlador cliente puede usar (y reutilizar) el otro URB para cambiar a Configuración 0. Esta implementación impide que el controlador cliente asigne direcciones URL para cada una de esas solicitudes de interfaz de selección, cada vez que el controlador necesite cambiar la configuración.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Requiere WDK para Windows 8. Tiene como destino Windows Vista y versiones posteriores del sistema operativo Windows. |
| Plataforma de destino | Escritorio |
| Encabezado | usbdlib.h |
| Library | Usbdex.lib |
| IRQL | DISPATCH_LEVEL |