HidP_GetUsageValueArray function (hidpi.h)

Article
10/21/2021

The HidP_GetUsageValueArray routine extracts the data associated with a HID control usage value array from a HID report.

Syntax

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
);

Parameters

[in] ReportType

Specifies a HIDP_REPORT_TYPE enumerator value that identifies the report type.

[in] UsagePage

Specifies the usage page of the usage value array.

[in] LinkCollection

Specifies the link collection that contains the usage value array. If LinkCollection is nonzero, the routine only searches for a usage value array in this link collection; otherwise, if LinkCollection is zero, the routine searches for a usage value array in the top-level collection associated with PreparsedData.

[in] Usage

Specifies the usage of the usage value array.

[in, out] UsageValue

Pointer to a caller-allocated buffer in which the routine returns the data associated with the usage value array.

[in] UsageValueByteLength

Specifies the length, in bytes, of the buffer at UsageValue.

[in] PreparsedData

Pointer to a top-level collection's preparsed data.

[in] Report

Pointer to a report that contains values.

[in] ReportLength

Specifies the length, in bytes, of the report located at Report.

Return value

HidP_GetUsageValueArray returns one of the following status values:

Return code	Description
HIDP_STATUS_SUCCESS	The routine successfully returned the value's data.
HIDP_INVALID_REPORT_LENGTH	The report length is not valid.
HIDP_INVALID_REPORT_TYPE	The specified report type is not valid.
HIDP_STATUS_NOT_VALUE_ARRAY	The requested usage is not a usage value array.
HIDP_STATUS_BUFFER_TOO_SMALL	The UsageValue buffer is too small to hold the requested usage.
HIDP_STATUS_INCOMPATIBLE_REPORT_ID	The collection contains a usage value array on the specified usage page in a report of the specified type, but there are no such usages in the specified report.
HIDP_STATUS_INVALID_PREPARSED_DATA	The preparsed data is not valid.
HIDP_STATUS_USAGE_NOT_FOUND	The collection does not contain a usage value array on the specified usage page in any report of the specified report type.

Remarks

The required size, in bytes, of UsageValueByteLength is determined by multiplying together the BitSize and ReportCount members of the usage value array's HIDP_VALUE_CAPS structure, and rounding the result up to the nearest byte.

HidP_GetUsageValueArray sets the UsageValue buffer in little-endian order, beginning with the least significant bit of the usage's data. The data is not byte-aligned, and is shifted such that the least significant bit of the data is located at the first bit of the UsageValue buffer.

HidP_GetUsageValueArray is designed to extract all the usage values for a usage whose report count is greater than 1. To extract a usage whose report count is equal to 1, use HidP_GetUsageValue.

For more information, see HID Collections.

Requirements

Requirement	Value
Minimum supported client	Available in Windows 2000 and later versions of Windows.
Target Platform	Universal
Header	hidpi.h (include Hidpi.h)
Library	Hidparse.lib
IRQL	<= DISPATCH_LEVEL