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

另请参阅