通过

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 报表数据包的长度不等于 给定的 reportTypeHIDP_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 返回两个或更大的值时，HidP_SetButtonArray 才可用。 API 版本 2 对应于 Windows 11。

当描述主项的用法序列中的最后一个用法时，必须重复一个按钮数组，因为定义的用法少于为给定主项声明的 ReportCount。 在这种情况下，将为该使用情况分配单个 HIDP_BUTTON_CAPS，并将 HIDP_BUTTON_CAPS 的 ReportCount 设置为反映使用情况引用的字段数。

描述按钮数组的 HIDP_BUTTON_CAPS 将始终 ReportCount 大于 1。 如果 ReportCount 等于一个，则它不是按钮数组，不能与 HidP_SetButtonArray一起使用。 有关详细信息，请参阅 HidP_SetUsages。

要求

要求 价值
标头 hidpi.h

另请参阅