HidP_GetUsageValueArray function (hidpi.h)

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

See also

HIDP_VALUE_CAPS

HidP_GetButtons

HidP_GetButtonsEx

HidP_GetCaps

HidP_GetScaledUsageValue

HidP_GetUsageValue

HidP_GetUsages

HidP_GetUsagesEx

_HIDP_PREPARSED_DATA