função WinUsb_ControlTransfer (winusb.h)

Artigo
08/27/2023

A função WinUsb_ControlTransfer transmite dados de controle sobre um ponto de extremidade de controle padrão.

Sintaxe

BOOL WinUsb_ControlTransfer(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            WINUSB_SETUP_PACKET     SetupPacket,
  [out]           PUCHAR                  Buffer,
  [in]            ULONG                   BufferLength,
  [out, optional] PULONG                  LengthTransferred,
  [in, optional]  LPOVERLAPPED            Overlapped
);

Parâmetros

[in] InterfaceHandle

Um identificador opaco para uma interface na configuração selecionada.

Para especificar o destinatário de uma solicitação de controle como o dispositivo inteiro ou a primeira interface, use o identificador retornado por WinUsb_Initialize. Para todas as outras interfaces, obtenha o identificador para a interface de destino chamando WinUsb_GetAssociatedInterface e chame WinUsb_ControlTransfer especificando o identificador de interface obtido.

[in] SetupPacket

O pacote de configuração de 8 bytes do tipo WINUSB_SETUP_PACKET.

[out] Buffer

Um buffer alocado pelo chamador que contém os dados a serem transferidos. O comprimento desse buffer não deve exceder 4 KB.

[in] BufferLength

O número de bytes a serem transferidos, sem incluir o pacote de instalação. Esse número deve ser menor ou igual ao tamanho, em bytes, de Buffer.

[out, optional] LengthTransferred

Um ponteiro para uma variável ULONG que recebe o número real de bytes transferidos. Se o aplicativo não espera que nenhum dado seja transferido durante a fase de dados (BufferLength é zero), LengthTransferred poderá ser NULL.

[in, optional] Overlapped

Um ponteiro opcional para uma estrutura OVERLAPPED , que é usada para operações assíncronas. Se esse parâmetro for especificado, WinUsb_ControlTransfer retornará imediatamente e o evento será sinalizado quando a operação for concluída. Se Sobreposto não for fornecido, a função WinUsb_ControlTransfer transferirá dados de forma síncrona.

Retornar valor

WinUsb_ControlTransferretornará 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 um dos seguintes códigos de erro.

Código de retorno	Descrição
ERROR_INVALID_HANDLE	O chamador passou NULL no parâmetro InterfaceHandle .
ERROR_NOT_ENOUGH_MEMORY	Indica que não há memória suficiente para executar a operação.

Comentários

Uma solicitação de controle sempre é enviada pelo host para o ponto de extremidade padrão de um dispositivo USB, mas o destinatário da solicitação pode ser todo o dispositivo, uma interface ou um ponto de extremidade na configuração alternativa selecionada. Na chamada WinUsb_ControlTransfer , o aplicativo deve indicar o destinatário por meio de dois parâmetros: InterfaceHandle e SetupPacket.

Se o destinatário de uma solicitação de controle for todo o dispositivo, a primeira interface ou qualquer ponto de extremidade nessa interface, o aplicativo deverá usar o identificador retornado por WinUsb_Initialize. Se o destinatário for qualquer outra interface ou seu ponto de extremidade, o aplicativo deverá obter o identificador WinUSB associado à interface de destino chamando WinUsb_GetAssociatedInterface e, em seguida, chamar WinUsb_ControlTransfer especificando o identificador de interface obtido.

De acordo com a Seção 9.3 da especificação USB oficial, o token de instalação de uma transferência de controle contém informações sobre a solicitação. Para um aplicativo WinUSB, esse token de instalação é descrito usando a estrutura WINUSB_SETUP_PACKET .

Dentro do token de instalação, os campos bmRequestType e wIndex são usados para indicar o destinatário da solicitação. Esses campos correspondem aos membros RequestType e Index de WINUSB_SETUP_PACKET, respectivamente.

Os dois bits mais baixos de RequestType indicam o destinatário da solicitação. O destinatário pode ser o dispositivo, uma interface, um ponto de extremidade ou outro (para solicitação de fornecedor). Dependendo do destinatário, o byte inferior de Index indica o índice definido pelo dispositivo do destinatário. O valor de Index depende do tipo de solicitação. Por exemplo, para solicitações de controle padrão, o valor é 0 ou indica a interface ou o número do ponto de extremidade. Para determinados tipos de solicitações padrão, como uma solicitação GET_DESCRIPTOR para obter um descritor de cadeia de caracteres, o valor Index indica a ID da linguagem.

Se o destinatário for o dispositivo, o aplicativo deverá definir os valores RequestType e Index . Os dois bits mais baixos do valor RequestType devem ser 0. O byte inferior do valor index depende do tipo de solicitação. O InterfaceHandle deve ser o identificador WinUSB retornado por WinUsb_Initialize.

Se o destinatário da solicitação for uma interface, o aplicativo deverá definir os dois bits mais baixos de RequestType como 0x01. O aplicativo não é necessário para definir o byte inferior de Index para qualquer tipo de solicitação. Para solicitações padrão, de classe e de fornecedor, Winusb.sys define o valor como o número de interface da interface de destino. O InterfaceHandle deve ser associado à interface de destino. O aplicativo pode obter esse identificador chamando WinUsb_GetAssociatedInterface.

Se o destinatário for um ponto de extremidade, o aplicativo deverá definir os dois bits mais baixos de RequestType como 0x02 e byte inferior de Index para o endereço do ponto de extremidade. Nesse caso, InterfaceHandle está associado à interface que contém o ponto de extremidade. O aplicativo pode obter esse identificador chamando WinUsb_GetAssociatedInterface.