HidP_SetButtonArray 函数 (hidpi.h)
HidP_SetButtonArray 函数通过HIDP_BUTTON_ARRAY_DATA结构数组设置按钮的状态。
语法
NTSTATUS HidP_SetButtonArray(
HIDP_REPORT_TYPE ReportType,
USAGE UsagePage,
USHORT LinkCollection,
USAGE Usage,
PHIDP_BUTTON_ARRAY_DATA ButtonData,
USHORT ButtonDataLength,
PHIDP_PREPARSED_DATA PreparsedData,
PCHAR Report,
ULONG ReportLength
);
参数
ReportType
从HIDP_REPORT_TYPE枚举HidP_Output或HidP_Feature的值。
UsagePage
给定用法所引用的使用情况页。
LinkCollection
(可选) 此值可用于区分可能具有相同 UsagePage 和 Usage 但存在于不同集合中的两个字段。 如果值为 HIDP_LINK_COLLECTION_UNSPECIFIED，则无论位置如何，都将返回与 UsagePage 和 Usage 匹配的第一个找到的按钮数组。 如果值为 HIDP_LINK_COLLECTION_ROOT，则会返回根集合中与 UsagePage 和 Usage 匹配的第一个按钮数组。
Usage
将设置其按钮数组 HidP_SetButtonArray 的用法。
ButtonData
具有要设置为按钮数组中的值的缓冲区。
ButtonDataLength
ButtonData 缓冲区中的元素数。
PreparsedData
从 HIDCLASS 返回的已分析数据。
Report
报告数据包。 第一个字节 必须是ReportId。
ReportLength
给定报告数据包的长度（以字节为单位）。
返回值
HidP_SetButtonArray 返回以下状态值之一：
| 返回代码 | 说明 |
|---|---|
| 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_REPORT_DOES_NOT_EXIST | 此设备上没有给定 ReportType 的报告 |
| HIDP_STATUS_NOT_BUTTON_ARRAY | 指定的控件不是按钮数组 |
| HIDP_STATUS_INCOMPATIBLE_REPORT_ID | 指定的使用情况页、使用情况和链接集合存在于报表中，其报表 ID 与传入的报表不同 |
| HIDP_STATUS_USAGE_NOT_FOUND | 此 ReportType 的任何报表中都不存在使用情况页、使用情况和链接集合组合 |
| HIDP_STATUS_DATA_INDEX_OUT_OF_RANGE | 提供的某个HIDP_BUTTON_ARRAY_DATA结构的 ArrayIndex 超出了此按钮数组的有效范围 |
注解
HidP_SetButtonArray为指定的 LinkCollection 内找到的第一个按钮数组设置按钮的状态，并为指定的报表提供使用情况。
调用方应使用 HidP_GetVersion 来确定此函数是否可用。 仅当HidP_GetVersion 返回值 2 或更大时， HidP_SetButtonArray 才可用。 API 版本 2 对应于Windows 11。
当描述main项的用法序列中的最后一个用法时，必须重复出现按钮数组，因为定义的用法少于为给定main项声明的 ReportCount。 在这种情况下，为该用法分配单个HIDP_BUTTON_CAPS，并将HIDP_BUTTON_CAPS的 ReportCount 设置为反映使用情况引用的字段数。
描述按钮数组 的HIDP_BUTTON_CAPS 始终具有大于 1 的 ReportCount 。 如果 ReportCount 等于 1，则它不是按钮数组，不能与 HidP_SetButtonArray一起使用。 有关详细信息，请参阅 HidP_SetUsages。
要求
| 要求 | 值 |
|---|---|
| Header | hidpi.h |