Interpretando relatórios HID

Artigo
06/15/2023

Esta seção descreve como aplicativos de modo de usuário e drivers de modo kernel usam as rotinas de suporte do HidP_XxxHIDClass 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 dimensionado.
HidP_GetUsageValue Retorna um valor não dimensionado em um formato sem sinal 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 é grande o suficiente para manter a matriz de valor de uso. O tamanho necessário em bytes é o produto dos membros BitSize e ReportCount da estrutura de HIDP_VALUE_CAPS da matriz de valor de uso, arredondado para cima até o byte mais próximo.

Extraindo usos de botão definidos como ON

Para extrair os usos 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 definida 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 zero o buffer usado para retornar a matriz de usos de botão. 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 igual a zero, a rotina retornará o número de todos os usos de botão no relatório.

O tamanho do buffer necessário, em bytes, é o seguinte:

(Para HidP_GetButtons) O valor retornado por HidP_MaxUsageListLength times sizeof(USAGE)
(Para HidP_GetButtonsEx) O valor retornado por HidP_MaxUsageListLength times sizeof(USAGE_AND_PAGE)

Depois que um aplicativo ou driver tiver usado essas rotinas para obter informações sobre quais botões estão atualmente definidos como ON, ele poderá determinar a diferença entre o estado atual e o estado anterior dos botões chamando uma das rotinas de suporte hidclass a seguir. Essas rotinas retornam a diferença entre duas matrizes de informações de uso:

Extraindo e definindo dados de controle por índices de dados

Para 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 particularmente úteis para um aplicativo ou driver que fornece um serviço de "valor agregado". Por exemplo, uma que fornece uma interface personalizada para todos os controles compatíveis com um dispositivo HIDClass. O Microsoft DirectInput é um exemplo.

Chamando essas rotinas, um aplicativo ou driver pode obter e definir com mais eficiência todos os valores em um relatório. Por exemplo, para obter todos os dados de valor por seus usos hid , ele precisa chamar HidP_GetUsageValue para cada uso. No entanto, 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 em Matrizes de Funcionalidade de Botão e Matrizes de Capacidade de Valor de uma coleção para identificar os 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 HID por índices de dados

Para 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:

Chamando essas rotinas, um aplicativo ou driver pode obter e definir com mais eficiência todos os valores em um relatório. Por exemplo, para obter todos os dados de valor por seus usos hid, ele precisa chamar HidP_GetUsageValue para cada uso. No entanto, 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 em Matrizes de Funcionalidade 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 HID

Compartilhar via