Função USBD_SelectConfigUrbAllocateAndBuild (usbdlib.h)

  • Artigo

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

Nota Em 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, fornecedor e descritores específicos de classe de um dispositivo USB. Quando o driver do 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 USB_CONFIGURATION_DESCRIPTOR no parâmetro ConfigurationDescriptor .

[in] InterfaceList

Ponteiro para o primeiro elemento de uma matriz alocada pelo 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.

Retornar valor

A rotina 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.

Comentários

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

  1. Obtenha o número de interfaces na configuração. Essas informações estão contidas no membro bNumInterfaces da estrutura USB_CONFIGURATION_DESCRIPTOR apontada por ConfigurationDescriptor.
  2. Crie uma matriz de estruturas 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.
  3. 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.
  4. Para cada elemento (exceto o último elemento) na matriz, defina o membro InterfaceDescriptor como o endereço de um descritor de interface. Para o primeiro elemento na matriz, defina o membro InterfaceDescriptor como o endereço do descritor de interface que representa a primeira interface na configuração. Da mesma forma para o nth elemento na matriz, defina o membro InterfaceDescriptor como o endereço do descritor de interface que representa a nth interface na configuração.
  5. O membro InterfaceDescriptor 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 nºelemento da 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 select-configuration para a pilha de driver USB para definir a configuração especificada. Além disso, você pode usar o membro Interface 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 de driver USB) para os pontos de extremidade nessa interface. Você pode obter identificadores de pipe da matriz e armazená-los para solicitações de E/S futuras para o dispositivo.

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_CreateConfigurationRequestEx

USBD_CreateHandle