Interprétation des rapports HID

Cet article décrit comment les applications en mode utilisateur et les pilotes en mode noyau utilisent les routines de prise en charge HidP_XxxHIDClass 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 support HID suivantes :

• HidP_GetScaledUsageValue Renvoie une valeur signée et mise à l'échelle.
• HidP_GetUsageValue renvoie une valeur non mise à l'échelle dans un format non signé, ou une valeur mise à l'échelle qui est en dehors de sa plage normale.
• HidP_GetUsageValueArray renvoie un tableau de valeurs d'utilisation.

Pour utiliser HidP_GetUsageValueArray, les applications et les pilotes doivent allouer un tampon zéro-initialisé suffisamment grand 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 des valeurs d'usage, arrondi à l'octet supérieur.

Extraction des utilisations de boutons réglés sur ON

Pour extraire les utilisations HID des boutons qui sont réglés sur ACTIVÉ (1), les applications et les pilotes appellent l'une des routines de prise en charge HID suivantes :

• HidP_GetButtons (ou HidP_GetUsages) renvoie l'ID d'utilisation de tous les boutons activés sur une page d'utilisation spécifiée.
• HidP_GetButtonsEx (ou HidP_GetUsagesEx) Renvoie la page d'utilisation et l'ID d'utilisation de tous les boutons qui sont en position ON.

Ces routines renvoient un tableau contenant toutes les informations d'utilisation de tous les boutons actuellement activés. Implicitement, les boutons dont l'utilisation n'est pas renvoyée par ces routines sont mis à OFF (zéro).

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

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

• (pour HidP_GetButtons) la valeur renvoyée par HidP_MaxUsageListLength multipliée par sizeof(USAGE)
• (Pour HidP_GetButtonsEx) La valeur que retourne HidP_MaxUsageListLength multipliée par sizeof(USAGE_AND_PAGE)

Une fois qu'une application ou un pilote a utilisé ces routines pour obtenir des informations sur les boutons actuellement en marche, elle 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 support HIDClass suivantes. Ces routines renvoient la différence entre deux tableaux d'informations d'utilisation :

• HidP_UsageListDifference
• HidP_UsageAndPageListDifference

Définition de 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 une des routines HID de support 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 d'un 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 support HIDClass suivantes :

• HidP_SetButtons (ou HidP_SetUsages) Met un ensemble de boutons spécifié sur ON (1).
• HidP_UnsetButtons (ou HidP_UnsetUsages) désactive un ensemble spécifié de boutons (zéro).

Extraction et définition des données de contrôle à l'aide d'indices de données

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

• HidP_GetData
• HidP_SetData

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

Une application ou un pilote appelant ces routines peut obtenir et définir toutes les valeurs d'un rapport de la manière la plus efficace qui soit. Par exemple, pour obtenir toutes les valeurs des données selon leurs usages HID, il doit appeler HidP_GetUsageValue pour chaque usage. En revanche, pour obtenir toutes les données de valeur par index de données, il suffit d'appeler HidP_GetData une seule fois.

Une application ou un pilote utilise les indices de données spécifiés dans les tableaux de capacités de boutons et les tableaux de capacités de valeurs d'une collection pour identifier les utilisations HID.

Voir aussi

• Initialisation des rapports HID