Compartir a través de


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
STATUS_SUCCESS
La llamada rutinaria se realizó correctamente.
STATUS_INVALID_PARAMETER
El llamador pasó NULL en cualquiera de los parámetros.
STATUS_INSUFFICIENT_RESOURCES
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.
USBD_SelectInterfaceUrbAllocateAndBuild asigna una estructura URB y la rellena con información sobre la configuración de interfaz especificada y los puntos de conexión. La rutina también asigna una estructura de USBD_INTERFACE_INFORMATION . Los miembros de la estructura (excepto la información de canalización) se rellenan en función del descriptor de interfaz especificado. USBD_SelectInterfaceUrbAllocateAndBuild establece el miembro Interface de USBD_INTERFACE_LIST_ENTRY en la dirección de USBD_INTERFACE_INFORMATION en el URB. El controlador cliente puede enviar este URB a la pila de controladores USB para seleccionar una configuración alternativa en la interfaz.

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

Consulte también

USBD_CreateHandle

USBD_SelectConfigUrbAllocateAndBuild