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 |
|---|---|
|
The routine successfully returned the value's data. |
|
The report length is not valid. |
|
The specified report type is not valid. |
|
The requested usage is not a usage value array. |
|
The UsageValue buffer is too small to hold the requested usage. |
|
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. |
|
The preparsed data is not valid. |
|
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 |