fonction HidP_GetButtonArray (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 le même UsagePage et Utilisation, mais qui existent dans différentes collections. Si la valeur LinkCollection est HIDP_LINK_COLLECTION_UNSPECIFIED, le premier tableau de boutons trouvé correspondant à l' UsagePage et d’utilisation 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 au UsagePage et 'utilisation 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 est le champ ReportCount du HIDP_BUTTON_CAPS pour ce contrôle. Cette mémoire tampon est fournie par l’appelant.
ButtonDataLength
Comme entrée, ce paramètre spécifie la longueur du paramètre ButtonData en nombre d’éléments de tableau, et non le nombre d’octets. En sortie, si HIDP_STATUS_SUCCESS est retournée, cette valeur est définie pour indiquer le nombre d’éléments de tableau renseignés 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ée, cette valeur contient le nombre d’éléments de tableau nécessaires pour terminer correctement la requête.
PreparsedData
Données pré-analysées retournées par le HIDCLASS.
Report
Paquet de rapport. Le premier octet doit être le ReportId. Cela sera correctement défini si le rapport est lu à partir du système.
ReportLength
Longueur du paquet de rapport donné en octets.
Valeur de retour
HidP_GetButtonArray retourne l’une des valeurs d’état suivantes :
| Retourner le code | Description |
|---|---|
| HIDP_STATUS_SUCCESS | Récupération réussie des boutons 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 ReportType 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 passé dans le rapport |
| 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 de cette ReportType |
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érieures. 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 principal doit être répétée, car il existe moins d’utilisations définies que le ReportCount déclaré pour l’élément principal 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 aura 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.
Exigences
| Exigence | Valeur |
|---|---|
| d’en-tête | hidpi.h |