Partager via

Obtention des rapports IHM

  • Article

Cet article décrit comment les applications en mode utilisateur et les pilotes en mode noyau obtiennent des rapports HID à partir d'une collection HID.

Obtention de rapports HID par des applications en mode utilisateur

Cette section traite de l'obtention de rapports d'entrée HID ou de rapports de fonctionnalité HID par des applications en mode utilisateur à l'aide de ReadFile ou des routines HidD_GetXxx.

Toutefois, une application ne doit utiliser les routines HidD_GetXxx que pour obtenir l'état actuel d'un appareil. Si une application tente d'utiliser HidD_GetInputReport pour obtenir en permanence des rapports d'entrée, ces rapports peuvent être perdus. En outre, certains appareils ne prennent pas en charge HidD_GetInputReport et ne répondent plus si cette routine est utilisée.

Utilisation de ReadFile

Une application utilise la poignée d'ouverture de fichier qu'elle a obtenue en utilisant CreateFile pour ouvrir un fichier sur la collection. Lorsque l'application appelle ReadFile, elle n'a pas besoin de spécifier des E/S superposées car les pilotes HID Client Drivers mettent en mémoire tampon les rapports dans un tampon en anneau. Toutefois, une application peut utiliser des E/S superposées pour avoir plus d'une requête de lecture en cours.

Utilisation des routines HidD_GetXxx

Une application peut utiliser les routines de support HIDClass suivantes pour obtenir les rapports d'entrée et les rapports de fonctionnalité les plus récents d'une collection HID :

  • HidD_GetInputReport : Renvoie un rapport d'entrée à partir d'une collection HID (Windows XP et versions ultérieures).
  • HidD_GetFeature : Renvoie un rapport de fonctionnalité à partir d'une collection HID.

Une application peut demander le renvoi d'un rapport spécifique. Pour récupérer un rapport spécifique à l'aide des routines HidD_GetXxx, l'application alloue le tampon de sortie du rapport, initialise le tampon à zéro et définit le premier octet du tampon à l'ID du rapport spécifique. Pour plus d'informations, voir Initialisation des rapports HID.

Obtention des rapports HID par les pilotes en mode noyau

Cette section explique comment un pilote en mode noyau doit utiliser les requêtes IRP_MJ_READ comme approche principale pour obtenir en continu les rapports d'entrée HID.

Les requêtes de lecture consécutives renvoient les rapports d'entrée dans l'ordre dans lequel ils ont été reçus de la collection. Le pilote peut également utiliser les requêtes IOCTL_HID_GET_Xxx pour obtenir les rapports d'entrée et de fonctionnalité. Toutefois, le pilote ne doit utiliser les requêtes IOCTL_HID_GET_Xxx que pour obtenir l'état actuel d'un appareil. Si le pilote tente d'utiliser IOCTL_HID_GET_INPUT_REPORT pour obtenir en permanence des rapports d'entrée, les rapports peuvent être perdus. En outre, certains appareils ne prennent pas en charge IOCTL_HID_GET_INPUT_REPORT et ne répondent plus si cette requête est utilisée.

Utilisation des requêtes IRP_MJ_READ

Pour des informations générales sur l'utilisation et la réutilisation des paquets de requêtes d'E/S (IRP), voir Manipulation des IRP et Réutilisation des IRP.

Si un pilote réutilise une IRP, la routine IoCompletion de l'IRP doit terminer la requête avec un statut STATUS_MORE_PROCESSING_REQUIRED (et ne pas libérer l'IRP). Lorsque le pilote n'a plus besoin de l'IRP, il doit la compléter et la libérer en appelant IoCompleteRequest et IoFreeIrp. Par exemple, un pilote peut généralement compléter et libérer l'IRP dans sa routine Unload, ou après le retrait d'un appareil.

Si un pilote utilise une IRP pour une seule requête de lecture, la routine IoCompletion de l'IRP doit terminer et libérer l'IRP et renvoyer STATUS_SUCCESS.

Avant qu'un pilote puisse requérir un rapport d'entrée, il doit d'abord allouer un tampon de rapport d'entrée non initialisé à partir du pool de mémoire non paginé. La taille, en octets, de la mémoire tampon est spécifiée par le membre InputReportByteLength de la structure HIDP_CAPS d'une collection HID. Un pilote doit ensuite utiliser une MDL pour mapper le tampon de rapport d'entrée pour une requête de lecture. Le pilote appelle IoAllocateMdl pour allouer la MDL pour un tampon de rapport d'entrée, et définit le membre Irp->MdlAddress de l'IRP de lecture à l'adresse MDL du tampon de rapport d'entrée. Le pilote doit libérer le tampon d'état et la MDL lorsqu'ils ne sont plus nécessaires.

Outre la définition de l'adresse MDL de l'IRP de lecture, le pilote doit également définir l'emplacement de la pile d'E/S du pilote de niveau inférieur suivant. Un pilote accède à l'emplacement de la pile d'E/S du pilote de niveau inférieur suivant en appelant IoGetNextIrpStackLocation. Le pilote définit les membres suivants de l'emplacement de la pile d'E/S :

  • Parameters.Read.Length : Définit la taille, en octets, du tampon de lecture. La taille doit être supérieure ou égale à la valeur spécifiée par le membre InputReportByteLength de la structure HIDP_CAPS d'une collection HID.
  • Parameters.Read.Key : La valeur de ce paramètre est égale à zéro.
  • Parameters.Read.ByteOffset.QuadPart : Mis à zéro.
  • MajorFunction : Défini à IRP_MJ_READ.
  • FileObject : Défini sur le pointeur de l'objet fichier qui représente le fichier ouvert sur la collection HID.

Une fois que le pilote a obtenu un rapport d'entrée, il peut accéder aux données de contrôle, comme décrit dans la section Interprétation des rapports HID.

Utilisation des requêtes IOCTL_HID_GET_Xxx

Un pilote peut utiliser les requêtes d'E/S suivantes pour obtenir les rapports d'entrée et de fonctionnalité les plus récents d'une collection HID :

Un pilote peut requérir le retour d'un rapport spécifique. Pour récupérer un rapport spécifique à l'aide de ces requêtes d'E/S, le pilote alloue d'abord la mémoire tampon du rapport de sortie, puis réinitialise la mémoire tampon et définit le premier octet de la mémoire tampon à l'ID du rapport spécifique.

Pour plus d'informations, voir Interprétation des rapports HID.