HidP_GetButtonArray 函数 (hidpi.h)
HidP_GetButtonArray 返回指定报表 的HIDP_BUTTON_ARRAY_DATA 结构的数组。
语法
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
);
参数
ReportType
来自HIDP_REPORT_TYPE枚举的值。
UsagePage
给定使用情况引用的使用情况页。
LinkCollection
(可选) 此值可用于区分可能具有相同 UsagePage 和 Usage 但存在于不同集合中的两个字段。 如果 LinkCollection 值 HIDP_LINK_COLLECTION_UNSPECIFIED，则将返回与 UsagePage 和 Usage 匹配的第一个按钮数组，而不考虑位置。 如果 LinkCollection 值 HIDP_LINK_COLLECTION_ROOT，则将返回在根集合中找到的第一个与 UsagePage 和 Usage 匹配的按钮数组。
Usage
将检索其按钮 HidP_GetButtonArray 的用法。
ButtonData
一个HIDP_BUTTON_ARRAY_DATA结构的数组，其中将放置设置为 ON 的按钮的数据。 所需的元素数是此控件HIDP_BUTTON_CAPS的 ReportCount 字段。 此缓冲区由调用方提供。
ButtonDataLength
作为输入，此参数以数组元素数而不是字节数指定 ButtonData 参数的长度。 作为输出，如果返回HIDP_STATUS_SUCCESS，则此值设置为指示函数填充了多少个数组元素。 可返回 的最大HIDP_BUTTON_ARRAY_DATA 结构数由HIDP_BUTTON_CAPS确定。ReportCount。 如果返回HIDP_STATUS_BUFFER_TOO_SMALL，则此值包含成功完成请求所需的数组元素数。
PreparsedData
HIDCLASS 返回的预分析数据。
Report
报告数据包。 第一个字节必须是 ReportId。 如果从系统读取报表，则会正确设置此值。
ReportLength
给定报告数据包的长度（以字节为单位）。
返回值
HidP_GetButtonArray 返回以下状态值之一：
| 返回代码 | 说明 |
|---|---|
| HIDP_STATUS_SUCCESS | 已成功从报告数据包中检索按钮 |
| HIDP_STATUS_INVALID_REPORT_TYPE | ReportType 参数无效 |
| HIDP_STATUS_INVALID_PREPARSED_DATA | PreparsedData 参数无效 |
| HIDP_STATUS_INVALID_REPORT_LENGTH | 报告数据包的长度不等于给定 ReportType 的 HIDP_CAPS 结构中指定的长度 |
| HIDP_STATUS_NOT_BUTTON_ARRAY | 指定的控件不是按钮数组 |
| HIDP_STATUS_BUFFER_TOO_SMALL | 要在其中返回数组的传入缓冲区的大小太小 |
| HIDP_STATUS_INCOMPATIBLE_REPORT_ID | 指定的使用情况页、使用情况和链接集合存在于报表中，其报表 ID 与传入的报表不同 |
| HIDP_STATUS_USAGE_NOT_FOUND | 此 ReportType 的任何报表中都不存在使用情况页、使用情况和链接集合组合 |
注解
调用方应使用 HidP_GetVersion 来确定此函数是否可用。 仅当HidP_GetVersion 返回两个或更大的值时， HidP_GetButtonArray 才可用。 API 版本 2 对应于 Windows 11。
当描述main项的用法序列中的最后一个用法必须重复时，会出现按钮数组，因为定义的用法少于为给定main项声明的 ReportCount。 在这种情况下，为该用法分配一个HIDP_BUTTON_CAPS，并将HIDP_BUTTON_CAPS的 ReportCount 设置为反映使用情况引用的字段数。
描述按钮数组的 HIDP_BUTTON_CAPS 将始终具有大于 1 的 ReportCount 。 如果 ReportCount 等于 1，则它不是按钮数组，不能与 HidP_GetButtonArray一起使用。 请参阅 HidP_GetUsages 。
要求
| 要求 | 值 |
|---|---|
| Header | hidpi.h |