Interprétation des rapports HID

Article
06/15/2023

Cette section décrit comment les applications en mode utilisateur et les pilotes en mode noyau utilisent le HidP_XxxHIDClass prennent en charge les routines pour interpréter les données de contrôle dans un rapport HID.

Extraction de données de valeur en spécifiant leur utilisation

Pour extraire des données de valeur d’un rapport HID, une application ou un pilote peut utiliser l’une des routines de prise en charge HID suivantes :

HidP_GetScaledUsageValue Retourne une valeur signée et mise à l’échelle.
HidP_GetUsageValue Retourne une valeur non mise à l’échelle dans un format non signé ou une valeur mise à l’échelle qui est hors de sa plage Normale.
HidP_GetUsageValueArray Retourne un tableau de valeurs d’utilisation.

Pour utiliser HidP_GetUsageValueArray les applications et les pilotes doivent allouer une mémoire tampon à initialisation zéro, qui est suffisamment grande pour contenir le tableau de valeurs d’utilisation. La taille requise en octets est le produit des membres BitSize et ReportCount de la structure HIDP_VALUE_CAPS du tableau de valeurs d’utilisation, arrondis à l’octet le plus proche.

Extraction des utilisations des boutons définies sur ON

Pour extraire les utilisations HID des boutons définis sur ON (1), les applications et les pilotes appellent l’une des routines de prise en charge HID suivantes :

HidP_GetButtons (ou HidP_GetUsages) Retourne l’ID d’utilisation de tous les boutons d’une page d’utilisation spécifiée qui sont définis sur ACTIVÉ.
HidP_GetButtonsEx (ou HidP_GetUsagesEx) Retourne la page d’utilisation et l’ID d’utilisation de tous les boutons définis sur ACTIVÉ.

Ces routines retournent un tableau de toutes les informations d’utilisation pour tous les boutons actuellement définis sur ACTIVÉ. Implicitement, les boutons dont l’utilisation n’est pas retournée par ces routines sont définis sur OFF (zéro).

Pour appeler ces routines, les applications et les pilotes doivent d’abord allouer et zéro initialiser la mémoire tampon utilisée pour retourner le tableau des utilisations des boutons. Une application ou un pilote appelle HidP_MaxUsageListLength pour déterminer le nombre d’utilisations de boutons dans une page d’utilisation spécifiée dans le rapport. Si l’application ou le pilote spécifie une page d’utilisation de zéro, la routine retourne le nombre de toutes les utilisations de bouton dans le rapport.

La taille de mémoire tampon requise, en octets, est la suivante :

(Pour HidP_GetButtons) Valeur retournée par HidP_MaxUsageListLength times sizeof(UTILISATION)
(Pour HidP_GetButtonsEx) Valeur retournée par HidP_MaxUsageListLength fois sizeof(USAGE_AND_PAGE)

Une fois qu’une application ou un pilote a utilisé ces routines pour obtenir des informations sur les boutons actuellement définis sur ACTIVÉ, il peut déterminer la différence entre l’état actuel et l’état précédent des boutons en appelant l’une des routines de prise en charge HIDClass suivantes. Ces routines retournent la différence entre deux tableaux d’informations d’utilisation :

Extraction et définition de données de contrôle par index de données

Pour utiliser des index de données pour extraire et définir des données de contrôle dans un rapport HID, une application ou un pilote peut utiliser les routines de prise en charge HIDClass suivantes :

Ces routines sont particulièrement utiles pour une application ou un pilote qui fournit un service « à valeur ajoutée ». Par exemple, un qui fournit une interface personnalisée à tous les contrôles pris en charge par un appareil HIDClass. Microsoft DirectInput en est un exemple.

En appelant ces routines, une application ou un pilote peut obtenir et définir plus efficacement toutes les valeurs d’un rapport. Par exemple, pour obtenir toutes les données de valeur par leurs utilisations HID , il doit appeler HidP_GetUsageValue pour chaque utilisation. Toutefois, pour obtenir toutes les données de valeur par index de données, il ne doit appeler HidP_GetData qu’une seule fois.

Une application ou un pilote utilise les index de données spécifiés dans les tableaux de capacité de bouton et les tableaux de capacité de valeur d’une collection pour identifier les utilisations HID.

Définition des données de valeur en spécifiant leur utilisation

Une application ou un pilote peut définir une valeur dans un rapport HID correctement initialisé en appelant l’une des routines de prise en charge HID suivantes :

HidP_SetScaledUsageValue Définit une valeur signée et mise à l’échelle dans un rapport.
HidP_SetUsageValue Définit une valeur dans un rapport.
HidP_SetUsageValueArray Définit un tableau de valeurs d’utilisation dans un rapport.

Définition de l’état du bouton en spécifiant son utilisation

Une application ou un pilote peut définir l’état des boutons dans un rapport HID correctement initialisé en appelant l’une des routines de prise en charge HIDClass suivantes :

HidP_SetButtons (ou HidP_SetUsages) Définit un ensemble de boutons spécifié sur ON (1).
HidP_UnsetButtons (ou HidP_UnsetUsages) Définit un ensemble de boutons spécifié sur OFF (zéro).

Extraction et définition des données de contrôle HID par index de données

En appelant ces routines, une application ou un pilote peut obtenir et définir plus efficacement toutes les valeurs d’un rapport. Par exemple, pour obtenir toutes les données de valeur par leurs utilisations HID, il doit appeler HidP_GetUsageValue pour chaque utilisation. Toutefois, pour obtenir toutes les données de valeur par index de données, il ne doit appeler HidP_GetData qu’une seule fois.

Voir aussi

Initialisation des rapports HID

Partager via