HidP_GetUsageValueArray 函数 (hidpi.h)

项目
02/26/2024

HidP_GetUsageValueArray例程从 HID 报表中提取与 HID 控件使用值数组关联的数据。

语法

NTSTATUS HidP_GetUsageValueArray(
  [in]      HIDP_REPORT_TYPE     ReportType,
  [in]      USAGE                UsagePage,
  [in]      USHORT               LinkCollection,
  [in]      USAGE                Usage,
  [in, out] PCHAR                UsageValue,
  [in]      USHORT               UsageValueByteLength,
  [in]      PHIDP_PREPARSED_DATA PreparsedData,
  [in]      PCHAR                Report,
  [in]      ULONG                ReportLength
);

参数

[in] ReportType

指定标识报表类型的 HIDP_REPORT_TYPE 枚举器值。

[in] UsagePage

指定使用情况值数组的使用情况页。

[in] LinkCollection

指定包含使用情况值数组的链接集合。如果 LinkCollection 不为零，则例程仅搜索此链接集合中的使用情况值数组;否则，如果 LinkCollection 为零，则例程在与 PreparsedData 关联的顶级集合中搜索使用情况值数组。

[in] Usage

指定使用情况值数组的用法。

[in, out] UsageValue

指向调用方分配的缓冲区的指针，其中例程返回与使用情况值数组关联的数据。

[in] UsageValueByteLength

指定 UsageValue 处缓冲区的长度（以字节为单位）。

[in] PreparsedData

指向顶级集合的预先分析数据的指针。

[in] Report

指向包含值的报表的指针。

[in] ReportLength

指定位于 Report 的报表的长度 （以字节为单位）。

返回值

HidP_GetUsageValueArray 返回以下状态值之一：

返回代码	说明
HIDP_STATUS_SUCCESS	例程已成功返回值的数据。
HIDP_INVALID_REPORT_LENGTH	报表长度无效。
HIDP_INVALID_REPORT_TYPE	指定的报表类型无效。
HIDP_STATUS_NOT_VALUE_ARRAY	请求的使用情况不是使用情况值数组。
HIDP_STATUS_BUFFER_TOO_SMALL	UsageValue 缓冲区太小，无法容纳请求的使用情况。
HIDP_STATUS_INCOMPATIBLE_REPORT_ID	集合包含指定类型的报表中指定使用情况页上的用法值数组，但指定报表中没有此类用法。
HIDP_STATUS_INVALID_PREPARSED_DATA	预先分析的数据无效。
HIDP_STATUS_USAGE_NOT_FOUND	集合不包含指定报表类型的任何报表中指定使用情况页上的使用情况值数组。

注解

UsageValueByteLength 的所需大小（以字节为单位）是通过将使用情况值数组HIDP_VALUE_CAPS结构的 BitSize 和 ReportCount 成员相乘，并将结果向上舍入到最接近的字节来确定的。

HidP_GetUsageValueArray 按 little-endian 顺序设置 UsageValue 缓冲区，从使用情况数据的最小有效位开始。数据不是字节对齐的，并且已移动，以便数据中最小的有效位位于 UsageValue 缓冲区的第一位。

HidP_GetUsageValueArray 旨在提取报表计数大于 1 的使用情况的所有使用情况值。若要提取报表计数等于 1 的使用情况，请使用 HidP_GetUsageValue。

有关详细信息，请参阅 HID 集合。

要求

要求	值
最低受支持的客户端	在 Windows 2000 和更高版本的 Windows 中可用。
目标平台	通用
标头	hidpi.h (包括 Hidpi.h)
Library	Hidparse.lib
IRQL	<= DISPATCH_LEVEL