função USBD_SelectInterfaceUrbAllocateAndBuild (usbdlib.h)
A rotina USBD_SelectInterfaceUrbAllocateAndBuild aloca e formata uma estrutura URB necessária para uma solicitação selecionar uma interface ou alterar sua configuração alternativa.
Sintaxe
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 pelo driver cliente em uma chamada anterior para a rotina de USBD_CreateHandle.
[in] ConfigurationHandle
Identificador retornado pela pilha de driver USB no UrbSelectConfiguration.ConfigurationHandle membro da estrutura URB, após a pilha de driver concluir uma solicitação de configuração de seleção.
InterfaceListEntry
Ponteiro para uma estrutura de USBD_INTERFACE_LIST_ENTRY alocada pelo chamador. Para obter mais informações, consulte Comentários.
[out] Urb
Ponteiro para uma estrutura URB que recebe a URB alocada por USBD_SelectInterfaceUrbAllocateAndBuild. O driver cliente deve liberar o URB quando o driver terminar de usá-lo chamando USBD_UrbFree.
Valor de retorno
A rotina retorna um código NTSTATUS. Os valores possíveis incluem, mas não se limitam a, os códigos de status listados na tabela a seguir.
| Código de retorno | Descrição |
|---|---|
|
A chamada de rotina foi bem-sucedida. |
|
O chamador passou NULL em qualquer um dos parâmetros. |
|
Memória insuficiente disponível para concluir a chamada. |
Observações
O driver cliente deve chamar a rotina de USBD_SelectInterfaceUrbAllocateAndBuild depois de selecionar uma configuração no dispositivo. Depois que uma solicitação de configuração selecionada for concluída, o driver cliente receberá um identificador de configuração no UrbSelectConfiguration.ConfigurationHandle membro da URB. Esse identificador deve ser especificado no parâmetro ConfigurationHandle de USBD_SelectInterfaceUrbAllocateAndBuild.
Um driver cliente chama USBD_SelectInterfaceUrbAllocateAndBuild para alocar e criar um URB para uma solicitação select-interface para alterar a configuração alternativa de uma interface, na configuração selecionada. Na chamada para USBD_SelectInterfaceUrbAllocateAndBuild, o driver cliente deve alocar e fornecer um ponteiro para uma estrutura USBD_INTERFACE_LIST_ENTRY. O driver cliente deve definir os membros da estrutura da seguinte maneira:
- O membro InterfaceDescriptor deve apontar para uma estrutura de USB_INTERFACE_DESCRIPTOR que contenha o descritor de interface com a configuração alternativa a ser selecionada. O descritor de interface foi obtido em uma solicitação anterior para obter um descritor de configuração e os descritores de interface e ponto de extremidade associados.
- O membro interface deve ser NULL.
Um driver cliente não pode alterar as configurações alternativas em várias interfaces em uma única solicitação de interface de seleção. Cada solicitação tem como destino apenas uma interface.
Depois que a solicitação select-interface for concluída, a pilha de driver USB preencherá USBD_INTERFACE_INFORMATION com informações sobre pipes abertos para pontos de extremidade definidos na configuração alternativa selecionada. O driver cliente pode obter essas alças de pipe inspecionando a matriz apontada pelo Pipes membro do USBD_INTERFACE_INFORMATIONe armazenar os identificadores para solicitações futuras de transferência de dados.
O driver cliente pode reutilizar um URB alocado por USBD_SelectInterfaceUrbAllocateAndBuild apenas para outra solicitação select-interface para a mesma configuração alternativa. O driver cliente não deve reutilizar o URB para qualquer outro tipo de solicitação ou para outra solicitação select-interface para uma configuração alternativa diferente. Em vez de alocar um novo URB, reutilize um URB existente é a abordagem preferencial em determinados cenários. Considere um dispositivo de áudio USB que tenha uma interface com duas configurações alternativas, definidas para dois requisitos de largura de banda. A configuração 0 é definida para largura de banda zero; A configuração 1 é definida para usar uma determinada quantidade de largura de banda. O driver cliente deseja alternar frequentemente entre as duas configurações, dependendo se o dispositivo está em uso. Para implementar esse cenário, o driver cliente pode alocar dois URBs para solicitações select-interface, uma por configuração. O driver cliente pode usar (e reutilizar) um URB para uma solicitação select-interface para selecionar a Configuração 1 quando houver sons a serem enviados para o dispositivo. Para conservar a largura de banda quando não houver sons, o driver cliente pode usar (e reutilizar) o outro URB para alternar para a Configuração 0. Essa implementação impede que o driver cliente aloque URBs para cada uma dessas solicitações de select-interface, sempre que o driver precisa alterar a configuração.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Requer WDK para Windows 8. Direciona o Windows Vista e versões posteriores do sistema operacional Windows. |
| da Plataforma de Destino | Área de trabalho |
| cabeçalho | usbdlib.h |
| biblioteca | Usbdex.lib |
| IRQL | DISPATCH_LEVEL |