解释 HID 报告

项目
06/15/2023

本部分介绍用户模式应用程序和内核模式驱动程序如何使用 HidP_XxxHIDClass 支持例程来解释 HID 报表中的控制数据。

通过指定值数据的使用情况提取值数据

若要从 HID 报表中提取值数据，应用程序或驱动程序可以使用以下 HID 支持例程之一：

HidP_GetScaledUsageValue 返回带符号和缩放的值。
HidP_GetUsageValue 返回一个无符号格式的非缩放值，或者一个已缩放的值，该值在正常范围内。
HidP_GetUsageValueArray 返回一个使用情况值数组。

若要使用 HidP_GetUsageValueArray 应用程序和驱动程序必须分配一个零初始化缓冲区，该缓冲区足够大，可以保存使用值数组。所需大小（以字节为单位）是使用情况值数组HIDP_VALUE_CAPS结构的 BitSize 和 ReportCount 成员的乘积，向上舍入到最接近的字节。

提取设置为 ON 的按钮用法

若要提取设置为 ON (1) 的按钮的 HID 用法，应用程序和驱动程序调用以下 HID 支持例程之一：

HidP_GetButtons (或 HidP_GetUsages) 返回指定使用页上设置为 ON 的所有按钮的使用 ID。
HidP_GetButtonsEx (或 HidP_GetUsagesEx) 返回设置为 ON 的所有按钮的使用情况页和使用情况 ID。

这些例程返回当前设置为 ON 的所有按钮的所有使用情况信息数组。隐式地，这些例程未返回其用法的按钮设置为 OFF (零) 。

若要调用这些例程，应用程序和驱动程序必须首先分配并零初始化用于返回按钮用法数组的缓冲区。应用程序或驱动程序调用 HidP_MaxUsageListLength 来确定报表中指定使用情况页中的按钮用法数。如果应用程序或驱动程序将使用情况页指定为零，则例程将返回报表中所有按钮用法的数目。

所需的缓冲区大小（以字节为单位）如下所示：

(for HidP_GetButtons) 返回的值 HidP_MaxUsageListLength次 size 为 (USAGE)
(for HidP_GetButtonsEx) 返回的值 HidP_MaxUsageListLength倍大小为 (USAGE_AND_PAGE)

在应用程序或驱动程序使用这些例程获取有关哪些按钮当前设置为 ON 的信息后，它可以通过调用以下 HIDClass 支持例程之一来确定按钮的当前状态与以前状态之间的差异。这些例程返回两个使用信息数组之间的差异：

按数据索引提取和设置控制数据

若要使用数据索引提取和设置 HID 报表中的控制数据，应用程序或驱动程序可以使用以下 HIDClass 支持例程：

这些例程对于提供“增值”服务的应用程序或驱动程序特别有用。例如，为 HIDClass 设备支持的所有控件提供自定义接口的。 Microsoft DirectInput 就是一个示例。

通过调用这些例程，应用程序或驱动程序可以最有效地获取和设置报表中的所有值。例如，若要按其 HID 用法获取所有值数据，必须为每个用法调用 HidP_GetUsageValue 。但是，若要按数据索引获取所有值数据，只需调用 HidP_GetData 一次。

应用程序或驱动程序使用集合的按钮功能数组和值功能数组中指定的数据索引来标识 HID 用法。

通过指定值数据的用法来设置值数据

应用程序或驱动程序可以通过调用以下 HID 支持例程之一在正确初始化的 HID 报表中设置值：

HidP_SetScaledUsageValue 在报表中设置有符号和缩放的值。
HidP_SetUsageValue 设置报表中的值。
HidP_SetUsageValueArray 在报表中设置使用情况值数组。

通过指定按钮的用法来设置按钮状态

应用程序或驱动程序可以通过调用以下 HIDClass 支持例程之一，在正确初始化的 HID 报表中设置按钮的状态：

HidP_SetButtons (或 HidP_SetUsages) 将一组指定的按钮设置为 ON (1) 。
HidP_UnsetButtons (或 HidP_UnsetUsages) 将一组指定的按钮设置为 OFF (零) 。

按数据索引提取和设置 HID 控制数据