função WinUsb_Initialize (winusb.h)

Artigo
03/13/2024

A função WinUsb_Initialize cria um identificador WinUSB para o dispositivo especificado por um identificador de arquivo.

Sintaxe

BOOL WinUsb_Initialize(
  [in]  HANDLE                   DeviceHandle,
  [out] PWINUSB_INTERFACE_HANDLE InterfaceHandle
);

Parâmetros

[in] DeviceHandle

O identificador para o dispositivo que CreateFile retornou. O WinUSB usa E/S sobreposta, portanto, FILE_FLAG_OVERLAPPED deve ser especificado no parâmetro dwFlagsAndAttributes da chamada CreateFile para DeviceHandle ter as características necessárias para que WinUsb_Initialize funcionem corretamente.

[out] InterfaceHandle

Recebe um identificador opaco para a primeira interface (padrão) no dispositivo. Esse identificador é exigido por outras rotinas do WinUSB que executam operações na interface padrão. Para liberar o identificador, chame a função WinUSB_Free .

Retornar valor

WinUsb_Initializeretornará TRUE se a operação for bem-sucedida. Caso contrário, essa rotina retornará FALSE e o chamador poderá recuperar o erro registrado chamando GetLastError.

GetLastError pode retornar o código de erro a seguir.

Código de retorno	Descrição
ERROR_INVALID_HANDLE	O chamador passou NULL ou um identificador inválido no parâmetro DeviceHandle ; FILE_FLAG_OVERLAPPED não foi definido no identificador de arquivo.
ERROR_NOT_ENOUGH_MEMORY	Indica que não há memória suficiente para executar a operação.
ERROR_BAD_DEVICE	Indica que o descritor de interface padrão não pôde ser encontrado para o dispositivo.

Comentários

Quando WinUsb_Initialize é chamado, as configurações de política da interface são redefinidas para os valores padrão.

A chamada WinUsb_Initialize consulta a pilha USB subjacente para vários descritores e aloca memória suficiente para armazenar os dados do descritor recuperado.

WinUsb_Initialize primeiro recupera o descritor de dispositivo e, em seguida, obtém o descritor de configuração associado. No descritor de configuração, a chamada deriva os descritores de interface associados e os armazena em uma matriz. As interfaces na matriz são identificadas por índices baseados em zero. Um valor de índice 0 indica a primeira interface (a interface padrão), um valor de 1 indica a segunda interface associada e assim por diante. WinUsb_Initialize analisa o descritor de interface padrão para os descritores de ponto de extremidade e armazena em cache informações como os pipes associados ou dados específicos do estado. O identificador recebido no parâmetro InterfaceHandle é um ponteiro para o bloco de memória alocado para a primeira interface na matriz.

Se um aplicativo quiser usar outra interface no dispositivo, ele deverá chamar WinUsb_GetAssociatedInterface, especificar o índice da interface e recuperar um identificador para o bloco de memória alocado para a interface especificada.