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 support 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 non 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 de valeurs d'utilisation, arrondi à l'octet supérieur.
Extraction des utilisations de boutons réglés sur ON
Pour extraire les utilisations HID des boutons qui sont activés (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 d'une page d'utilisation spécifiée qui sont activés.
- HidP_GetButtonsEx (ou HidP_GetUsagesEx) Renvoie la page d'utilisation et l'ID d'utilisation de tous les boutons qui sont activés.
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 de boutons dans une page d'utilisation spécifiée du 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 retournée par 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 activés, 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 support HIDClass suivantes. Ces routines renvoient la différence entre deux tableaux d'informations d'utilisation :
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 support HIDClass suivantes :
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 en 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 données de valeur par leur utilisation HID, il faut appeler HidP_GetUsageValue pour chaque utilisation. 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.
Définition de données de valeur en spécifiant leur utilisation
Une application ou un pilote peut définir une valeur dans un état HID correctement initialisé en appelant l'une des routines de support HID suivantes :
- HidP_SetScaledUsageValue Définit une valeur signée et mise à l'échelle dans un état.
- HidP_SetUsageValue Définit une valeur dans un rapport.
- HidP_SetUsageValueArray Définit un tableau de valeurs d'utilisation dans un état.
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 état 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) Met un ensemble spécifique de boutons sur OFF (zéro).
Extraction et réglage des données de contrôle HID à 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 support HIDClass suivantes :
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 en 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 données de valeur en fonction de leur utilisation HID, il faut appeler HidP_GetUsageValue pour chaque utilisation. 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.