função USBD_SelectConfigUrbAllocateAndBuild (usbdlib.h)

Artigo
02/07/2025

A rotina USBD_SelectConfigUrbAllocateAndBuild aloca e formata uma estrutura de URB necessária para selecionar uma configuração para um dispositivo USB.

Observação no Windows 8, USBD_SelectConfigUrbAllocateAndBuild substitui USBD_CreateConfigurationRequestEx e USBD_CreateConfigurationRequest.

Sintaxe

NTSTATUS USBD_SelectConfigUrbAllocateAndBuild(
  [in]  USBD_HANDLE                   USBDHandle,
  [in]  PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor,
  [in]  PUSBD_INTERFACE_LIST_ENTRY    InterfaceList,
  [out] PURB                          *Urb
);

Parâmetros

[in] USBDHandle

Identificador USBD recuperado pelo driver cliente em uma chamada anterior para a rotina de USBD_CreateHandle.

[in] ConfigurationDescriptor

Ponteiro para uma estrutura de USB_CONFIGURATION_DESCRIPTOR alocada pelo chamador que contém o descritor de configuração para a configuração a ser selecionada. Normalmente, o driver cliente envia um URB do tipo URB_FUNCTION_GET_DESCRIPTOR_FROM_DEVICE (consulte _URB_CONTROL_DESCRIPTOR_REQUEST) para recuperar informações sobre configurações, interfaces, pontos de extremidade, o fornecedor e descritores específicos de classe de um dispositivo USB. Quando o driver cliente especifica USB_CONFIGURATION_DESCRIPTOR_TYPE como o tipo de descritor, a solicitação recupera todas as informações do dispositivo em uma estrutura USB_CONFIGURATION_DESCRIPTOR. Em seguida, o driver passa o ponteiro recebido para a estrutura de USB_CONFIGURATION_DESCRIPTOR no parâmetro ConfigurationDescriptor.

[in] InterfaceList

Ponteiro para o primeiro elemento de uma matriz alocada por chamador de estruturas de USBD_INTERFACE_LIST_ENTRY. O comprimento da matriz depende do número de interfaces no descritor de configuração. Para obter mais informações, consulte Comentários.

[out] Urb

Ponteiro para uma estrutura URB que recebe o URB alocado por USBD_SelectConfigUrbAllocateAndBuild. O driver cliente deve liberar o URB quando o driver terminar de usá-lo chamando USBD_UrbFree.

Valor de retorno

A rotina de USBD_SelectConfigUrbAllocateAndBuild retorna um código de status NT.

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
STATUS_SUCCESS	A solicitação foi bem-sucedida.
STATUS_INVALID_PARAMETER	O chamador passou um valor de parâmetro inválido. USBDHandle ou Urb é NULL.
STATUS_INSUFFICIENT_RESOURCES	Memória insuficiente disponível para concluir a solicitação.

Observações

Antes de chamar USBD_SelectConfigUrbAllocateAndBuild, o driver cliente deve executar as seguintes tarefas:

Obtenha o número de interfaces na configuração. Essas informações estão contidas no membro bNumInterfaces da estrutura USB_CONFIGURATION_DESCRIPTOR apontada pelo ConfigurationDescriptor.
Crie uma matriz de estruturas de USBD_INTERFACE_LIST_ENTRY. O número de elementos na matriz deve ser um a mais do que o número de interfaces. Inicialize a matriz chamando RtlZeroMemory.
Obtenha um descritor de interface para cada interface (ou sua configuração alternativa) na configuração. Você pode obter esses descritores de interface chamando USBD_ParseConfigurationDescriptorEx.
Para cada elemento (exceto o último elemento) na matriz, defina o membro InterfaceDescriptor para o endereço de um descritor de interface. Para o primeiro elemento na matriz, defina o membro InterfaceDescriptor para o endereço do descritor de interface que representa a primeira interface na configuração. Da mesma forma para o elemento nth na matriz, defina o membro InterfaceDescriptor para o endereço do descritor de interface que representa o ninterface th na configuração.
O InterfaceDescriptor membro do último elemento deve ser definido como NULL.

USBD_SelectConfigUrbAllocateAndBuild executa as seguintes tarefas:

Cria um URB e o preenche com informações sobre a configuração especificada, suas interfaces e pontos de extremidade e define o tipo de solicitação como URB_FUNCTION_SELECT_CONFIGURATION.
Preenche uma estrutura USBD_INTERFACE_INFORMATION na URB para cada interface.
Define o membro interface do elemento nda matriz de USBD_INTERFACE_LIST_ENTRY fornecida pelo chamador para o endereço da estrutura de USBD_INTERFACE_INFORMATION correspondente na URB.

Você pode usar o ponteiro recebido para a estrutura URB para enviar uma solicitação de configuração selecionada para a pilha de driver USB para definir a configuração especificada. Além disso, você pode usar o Interface membro de cada estrutura USBD_INTERFACE_INFORMATION na matriz para obter informações sobre a interface. Dentro de cada estrutura USBD_INTERFACE_INFORMATION, o membro pipes é uma matriz de estruturas USBD_PIPE_INFORMATION. Cada estrutura USBD_PIPE_INFORMATION contém informações sobre os pipes abertos (pela pilha do driver USB) para os pontos de extremidade nessa interface. Você pode obter identificadores de pipe da matriz e armazená-los para futuras solicitações de E/S para o dispositivo.

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

Consulte também

USBD_CreateConfigurationRequestEx

USBD_CreateHandle

Compartilhar via