Lire en anglais

Partager via


HidP_GetButtonArray, fonction (hidpi.h)

HidP_GetButtonArray retourne un tableau de structures HIDP_BUTTON_ARRAY_DATA pour le rapport spécifié.

Syntaxe

NTSTATUS HidP_GetButtonArray(
  HIDP_REPORT_TYPE        ReportType,
  USAGE                   UsagePage,
  USHORT                  LinkCollection,
  USAGE                   Usage,
  PHIDP_BUTTON_ARRAY_DATA ButtonData,
  PUSHORT                 ButtonDataLength,
  PHIDP_PREPARSED_DATA    PreparsedData,
  PCHAR                   Report,
  ULONG                   ReportLength
);

Paramètres

ReportType

Valeur de l’énumération HIDP_REPORT_TYPE .

UsagePage

Page d’utilisation à laquelle l’utilisation donnée fait référence.

LinkCollection

(Facultatif) Cette valeur peut être utilisée pour différencier deux champs qui peuvent avoir les mêmes UsagePage et Usage , mais qui existent dans des collections différentes. Si la valeur LinkCollection est HIDP_LINK_COLLECTION_UNSPECIFIED, le premier tableau de boutons trouvé correspondant à UsagePage et Usage est retourné, quel que soit l’emplacement. Si la valeur LinkCollection est HIDP_LINK_COLLECTION_ROOT, le premier tableau de boutons trouvé dans la collection racine correspondant à UsagePage et Usage est retourné.

Usage

Utilisation dont les boutons HidP_GetButtonArray récupéreront.

ButtonData

Tableau de structures HIDP_BUTTON_ARRAY_DATA où les données des boutons définis sur ON seront placées. Le nombre d’éléments requis correspond au champ ReportCount du HIDP_BUTTON_CAPS pour ce contrôle. Cette mémoire tampon est fournie par l’appelant.

ButtonDataLength

En tant qu’entrée, ce paramètre spécifie la longueur du paramètre ButtonData en nombre d’éléments de tableau, et non en nombre d’octets. En tant que sortie, si HIDP_STATUS_SUCCESS est retourné, cette valeur est définie pour indiquer le nombre de ces éléments de tableau qui ont été remplis par la fonction . Le nombre maximal de structures HIDP_BUTTON_ARRAY_DATA pouvant être retournées est déterminé par HIDP_BUTTON_CAPS. ReportCount. Si HIDP_STATUS_BUFFER_TOO_SMALL est retourné, cette valeur contient le nombre d’éléments de tableau nécessaires pour terminer correctement la demande.

PreparsedData

Données pré-analysées retournées par hidCLASS.

Report

Paquet de rapport. Le premier octet doit être le ReportId. Ce paramètre est correctement défini si le rapport est lu à partir du système.

ReportLength

Longueur du paquet de rapport donné en octets.

Valeur retournée

HidP_GetButtonArray retourne l’une des valeurs status suivantes :

Code de retour Description
HIDP_STATUS_SUCCESS Récupération réussie des boutons à partir du paquet de rapport
HIDP_STATUS_INVALID_REPORT_TYPE Le paramètre ReportType n’est pas valide
HIDP_STATUS_INVALID_PREPARSED_DATA Le paramètre PreparsedData n’est pas valide
HIDP_STATUS_INVALID_REPORT_LENGTH La longueur du paquet de rapport n’est pas égale à la longueur spécifiée dans la structure HIDP_CAPS pour le Type de rapport donné
HIDP_STATUS_NOT_BUTTON_ARRAY Le contrôle spécifié n’est pas un tableau de boutons
HIDP_STATUS_BUFFER_TOO_SMALL La taille de la mémoire tampon passée dans laquelle retourner le tableau est trop petite
HIDP_STATUS_INCOMPATIBLE_REPORT_ID La page d’utilisation, l’utilisation et la collection de liens spécifiées existent dans un rapport avec un ID de rapport différent de celui du rapport transmis
HIDP_STATUS_USAGE_NOT_FOUND La combinaison de la page d’utilisation, de l’utilisation et de la collection de liens n’existe pas dans les rapports pour ce Type de rapport

Remarques

L’appelant doit utiliser HidP_GetVersion pour déterminer si cette fonction est disponible. HidP_GetButtonArray est disponible uniquement si HidP_GetVersion retourne une valeur de deux ou supérieure. La version 2 de l’API correspond à Windows 11.

Un tableau de boutons se produit lorsque la dernière utilisation de la séquence d’utilisations décrivant un élément main doit être répétée, car il y a moins d’utilisations définies que le ReportCount déclaré pour l’élément main donné. Dans ce cas, une seule HIDP_BUTTON_CAPS est allouée pour cette utilisation et le ReportCount de l’HIDP_BUTTON_CAPS est défini pour refléter le nombre de champs auxquels l’utilisation fait référence.

Un HIDP_BUTTON_CAPS qui décrit un tableau de boutons a toujours ReportCount supérieur à un. Si ReportCount est égal à un, il ne s’agit pas d’un tableau de boutons et ne peut pas être utilisé avec HidP_GetButtonArray. Consultez HidP_GetUsages à la place.

Configuration requise

Condition requise Valeur
En-tête hidpi.h

Voir aussi