Interpretando relatórios de HID
Este artigo explica como aplicativos de modo de usuário e drivers de modo kernel usam as rotinas de suporte HIDClass HidP_Xxx para interpretar dados de controle contidos em um relatório de 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 dimensionado.
- HidP_GetUsageValue Retorna um valor não dimensionado em um formato não assinado ou um valor dimensionado que está fora de seu intervalo Normal.
- HidP_GetUsageValueArray Retorna uma matriz de valor de uso.
Para usar HidP_GetUsageValueArray aplicativos e drivers devem alocar um buffer inicializado por zero, que seja suficientemente grande para manter a matriz de valor de uso. O tamanho necessário em bytes é o produto dos membros BitSize e ReportCount da estrutura HIDP_VALUE_CAPS da matriz 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 uso de todos os botões, em uma página de uso especificada, que estão definidos como ON.
- HidP_GetButtonsEx (ou HidP_GetUsagesEx) Retorna a página de uso e a ID de uso de todos os botões definidos como ON.
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 usos de botão em uma página de uso especificada no relatório. Se o aplicativo ou driver especificar uma página de uso de zero, a rotina retornará o número de todos os usos 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 vezes 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 ON, ele pode identificar a diferença entre o estado atual e 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:
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. O 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 seus usos de HID, ele precisa 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 usos de HID.
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 Define um valor assinado e dimensionado em um relatório.
- HidP_SetUsageValue Define um valor em um relatório.
- HidP_SetUsageValueArray Define 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:
- HidP_SetButtons (ou HidP_SetUsages) Define um conjunto especificado de botões como ON (1).
- HidP_UnsetButtons (ou HidP_UnsetUsages) Define um conjunto especificado de botões como OFF (zero).
Extraindo e definindo dados de controle de HID 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. O 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 seus usos de HID, ele precisa 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 usos de HID.