Interpretando relatórios de HID

Este artigo descreve como aplicativos em modo de usuário e drivers em modo kernel usam as rotinas de suporte HIDClass, como HidP_Xxx, para interpretar dados de controle em um relatório HID.

Extraindo dados de valor especificando seu uso

Para extrair dados de valor de um relatório HID, um aplicativo ou driver pode usar uma das seguintes rotinas de suporte HID:

  • HidP_GetScaledUsageValue Retorna um valor assinado e escalado.
  • HidP_GetUsageValue Retorna um valor não escalonado em um formato não assinado ou um valor escalonado que está fora do seu intervalo normal.
  • HidP_GetUsageValueArray retorna uma matriz de valor de uso.

Para usar HidP_GetUsageValueArray, aplicativos e drivers devem alocar um buffer inicializado a zero, que seja suficientemente grande para conter o array de valores de uso. O tamanho necessário em bytes é o produto dos membros BitSize e ReportCount da estrutura HIDP_VALUE_CAPS do array de valores de uso, arredondado para o byte mais próximo.

Extraindo usos de botões definidos como ON

Para fazer a extração de usos de HID de botões definidos como ON (1), aplicativos e drivers chamam uma das seguintes rotinas de suporte HID:

  • HidP_GetButtons (ou HidP_GetUsages) Retorna a ID de utilização de todos os botões em uma página de uso especificada que estão ativados.
  • HidP_GetButtonsEx (ou HidP_GetUsagesEx) retorna a página de uso e a ID de uso de todos os botões que estão definidos como ATIVADO.

Essas rotinas retornam uma matriz de todas as informações de uso para todos os botões que estão atualmente definidos como ON. Implicitamente, os botões cujo uso não é retornado por essas rotinas são definidos como OFF (zero).

Para chamar essas rotinas, os aplicativos e drivers devem, primeiro, alocar e inicializar o buffer destinado a retornar a matriz de usos dos botões. Um aplicativo ou driver chama HidP_MaxUsageListLength para determinar o número de usagens de botões em uma página de usagem especificada no relatório. Se o aplicativo ou driver especificar uma página de uso de zero, a rotina retornará o número de todas as usagens de botão no relatório.

O tamanho obrigatório do buffer, em bytes, é:

  • (Para HidP_GetButtons) O valor retornado por HidP_MaxUsageListLength vezes sizeof(USAGE)
  • (Para HidP_GetButtonsEx) O valor retornado por HidP_MaxUsageListLength multiplicado por sizeof(USAGE_AND_PAGE)

Após um aplicativo ou driver utilizar essas rotinas para obter informações sobre quais botões estão atualmente definidos como ligados, ele pode determinar a diferença entre o estado atual e o estado anterior dos botões chamando uma das seguintes rotinas de suporte HIDClass. Essas rotinas retornam a diferença entre duas matrizes de informações de uso:

  • HidP_UsageListDifference
  • HidP_UsageAndPageListDifference

Definindo dados de valor especificando seu uso

Um aplicativo ou driver pode definir um valor em um relatório HID inicializado corretamente chamando uma das seguintes rotinas de suporte HID:

  • HidP_SetScaledUsageValue Configura um valor assinado e escalado em um relatório.
  • HidP_SetUsageValue Define um valor em um relatório.
  • HidP_SetUsageValueArray configura uma matriz de valor de uso em um relatório.

Definindo o estado do botão especificando seu uso

Um aplicativo ou driver pode definir o estado dos botões em um relatório HID inicializado corretamente chamando uma das seguintes rotinas de suporte HIDClass:

Extraindo e definindo dados de controle por índices de dados

A fim de usar índices de dados para extrair e definir dados de controle em um relatório HID, um aplicativo ou driver pode usar as seguintes rotinas de suporte HIDClass:

Essas rotinas são úteis para um aplicativo ou driver que oferece um serviço de "valor agregado". Por exemplo, um que oferece uma interface personalizada para todos os controles compatíveis com um dispositivo HIDClass. Microsoft DirectInput é um exemplo.

Um aplicativo ou driver que chama essas rotinas pode obter e definir, de forma mais eficiente, todos os valores em um relatório. Por exemplo, para obter todos os dados de valor por meio de seus usos HID, é necessário chamar HidP_GetUsageValue para cada uso. Porém, para obter todos os dados de valor por índice de dados, ele só precisa chamar HidP_GetData uma vez.

Um aplicativo ou driver usa os índices de dados especificados nas Matrizes de Capacidade de Botão e Matrizes de Capacidade de Valor de uma coleção para identificar os usos de HID.

Confira também

  • Inicializando relatórios de HID
  • Last updated on