función USBD_SelectInterfaceUrbAllocateAndBuild (usbdlib.h)
La rutina USBD_SelectInterfaceUrbAllocateAndBuild asigna y da formato a una estructura de 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 de la UrbSelectConfiguration.ConfigurationHandle miembro del URB estructura, 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 Comentarios.
[out] Urb
Puntero a una estructura de URB de 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 de rutina se realizó correctamente. |
|
El autor de la llamada pasó NULL en cualquiera de los parámetros. |
|
Memoria insuficiente disponible para completar la llamada. |
Observaciones
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 de cliente recibe un identificador de configuración en el UrbSelectConfiguration.ConfigurationHandle miembro del URB. Ese identificador debe especificarse en el parámetro configurationHandle de USBD_SelectInterfaceUrbAllocateAndBuild.
Un controlador cliente llama a USBD_SelectInterfaceUrbAllocateAndBuild para asignar y compilar 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 de 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 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 de debe ser NULL.
Un controlador cliente no puede cambiar la configuración alternativa en varias interfaces en una sola 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 Canalizaciones miembro de USBD_INTERFACE_INFORMATIONy 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 reutilizar el URB para cualquier otro tipo de solicitud o para otra solicitud select-interface 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 cero ancho de banda; 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 select-interface para seleccionar Configuración 1 cuando hay sonidos para enviar al dispositivo. Para conservar el 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 | Valor |
|---|---|
| cliente mínimo admitido | Requiere WDK para Windows 8. Tiene como destino Windows Vista y versiones posteriores del sistema operativo Windows. |
| de la plataforma de destino de | Escritorio |
| encabezado de | usbdlib.h |
| biblioteca de | Usbdex.lib |
| irQL | DISPATCH_LEVEL |