Função USBD_SelectInterfaceUrbAllocateAndBuild (usbdlib.h)

A rotina USBD_SelectInterfaceUrbAllocateAndBuild aloca e formata uma estrutura URB necessária para que uma solicitação selecione uma interface ou altere 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 membro UrbSelectConfiguration.ConfigurationHandle da estrutura URB , depois que a pilha de driver conclui uma solicitação select-configuration.

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 o URB alocado por USBD_SelectInterfaceUrbAllocateAndBuild. O driver do cliente deve liberar o URB quando o driver terminar de usá-lo chamando USBD_UrbFree.

Retornar valor

A rotina retorna um código NTSTATUS. Os valores possíveis incluem, mas não se limitam a, os códigos status listados na tabela a seguir.

Código de retorno	Descrição
STATUS_SUCCESS	A chamada de rotina foi bem-sucedida.
STATUS_INVALID_PARAMETER	O chamador passou NULL em qualquer um dos parâmetros.
STATUS_INSUFFICIENT_RESOURCES	Memória insuficiente disponível para concluir a chamada.

Comentários

O driver do cliente deve chamar a rotina de USBD_SelectInterfaceUrbAllocateAndBuild depois de selecionar uma configuração no dispositivo. Depois que uma solicitação select-configuration for concluída, o driver do cliente receberá um identificador de configuração no membro UrbSelectConfiguration.ConfigurationHandle da URB. Esse identificador deve ser especificado no parâmetro ConfigurationHandle de USBD_SelectInterfaceUrbAllocateAndBuild.

Um driver de 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 do cliente deve definir os membros da estrutura da seguinte maneira:

• O membro InterfaceDescriptor deve apontar para uma estrutura USB_INTERFACE_DESCRIPTOR que contém 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.

USBD_SelectInterfaceUrbAllocateAndBuild aloca uma estrutura URB e a preenche com informações sobre a configuração de interface especificada e os pontos de extremidade. A rotina também aloca uma estrutura de USBD_INTERFACE_INFORMATION . Os membros da estrutura (exceto as informações de pipe) são preenchidos com base no descritor de interface especificado. USBD_SelectInterfaceUrbAllocateAndBuild define o membro interface de USBD_INTERFACE_LIST_ENTRY para o endereço de USBD_INTERFACE_INFORMATION na URB. O driver cliente pode enviar esse URB para a pilha do driver USB para selecionar uma configuração alternativa na interface.

Um driver de cliente não pode alterar configurações alternativas em várias interfaces em uma única solicitação select-interface. Cada solicitação tem como destino apenas uma interface.

Depois que a solicitação select-interface for concluída, a pilha do 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 membro pipes de USBD_INTERFACE_INFORMATION e armazenando os identificadores para solicitações futuras de transferência de dados.

O driver do cliente pode reutilizar um URB alocado por USBD_SelectInterfaceUrbAllocateAndBuild apenas para outra solicitação select-interface para a mesma configuração alternativa. O driver do 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, reutilizando 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 com frequência entre as duas configurações, dependendo se o dispositivo está em uso. Para implementar esse cenário, o driver do 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 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 do cliente pode usar (e reutilizar) o outro URB para alternar para a Configuração 0. Essa implementação impede que o driver do cliente aloque URBs para cada uma dessas solicitações select-interface sempre que o driver precisar alterar a configuração.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Requer WDK para Windows 8. Tem como destino o Windows Vista e versões posteriores do sistema operacional Windows.
Plataforma de Destino	Área de Trabalho
Cabeçalho	usbdlib.h
Biblioteca	Usbdex.lib
IRQL	DISPATCH_LEVEL

Confira também

USBD_CreateHandle

USBD_SelectConfigUrbAllocateAndBuild