HidP_GetUsageValueArray
This function extracts the data associated with a HID control usage value array from a HID report.
NTSTATUS HidP_GetUsageValueArray(
HIDP_REPORT_TYPE ReportType,
USAGE UsagePage,
USHORT LinkCollection,
USAGE Usage,
PCHAR UsageValue,
USHORT UsageValueByteLength,
PDIP_PREPARSED_DATA PreparsedData,
PCHAR Report,
ULONG ReportLength
);
Parameters
- ReportType
[in] HIDP_REPORT_TYPE enumerator value that identifies the report type. - UsagePage
[in] Usage page of the usage value array. - LinkCollection
[in] Optional. Link collection that contains the usage value array. If LinkCollection is nonzero, the function only searches for a usage value array in this link collection; otherwise, if LinkCollection is zero, the function searches for a usage value array in the top-level collection associated with PreparsedData. - Usage
[in] Usage of the usage value array. - UsageValue
[out] Pointer to a caller-allocated buffer in which the function returns the data associated with the usage value array. - UsageValueByteLength
[in] Length, in bytes, of the buffer at UsageValue. - PreparsedData
[in] Pointer to a top-level collection's preparsed data. - Report
[in] Pointer to a report that contains values. - ReportLength
[in] Length, in bytes, of the report located at Report.
Return Values
The following table shows the possible return values for this function.
| Value | Description |
|---|---|
| HIDP_STATUS_SUCCESS | The function successfully returned the value's data. |
| HIDP_INVALID_REPORT_LENGTH | Report length was not valid. |
| HIDP_INVALID_REPORT_TYPE | Specified report type was not valid. |
| HIDP_STATUS_NOT_VALUE_ARRAY | Requested usage was not a usage value array. |
| HIDP_STATUS_BUFFER_TOO_SMALL | UsageValue buffer was too small to hold the requested usage. |
| HIDP_STATUS_INCOMPATIBLE_REPORT_ID | Report contained a collection with buttons in the specified usage page, but there were no such usages in the report. |
| HIDP_STATUS_INVALID_PREPARSED_DATA | Preparsed data was not valid. |
| HIDP_STATUS_USAGE_NOT_FOUND | Report contained a requested usage that was not in any report supported by the top-level collection. |
Remarks
The terms button and usage are used synonymously.
Multiplying the BitSize and ReportCount members of the usage value array's HIDP_VALUE_CAPS structure, and rounding the result up to the nearest byte determines the required size of UsageValueByteLength.
Beginning with the least significant bit of the usage's data, HidP_GetUsageValueArray sets the UsageValue buffer in little-endian order. 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.
Requirements
OS Versions: Windows CE .NET 4.2 and later.
Header: Hidpi.h.
Link Library: Hidparse_lib.lib.
See Also
HID Drivers | HidP_GetButtons | HidP_GetButtonsEx | HidP_GetCaps | HidP_GetScaledUsageValue | HidP_GetUsages | HidP_GetUsagesEx | HidP_GetUsageValue | HIDP_REPORT_TYPE | HIDP_VALUE_CAPS
Last updated on Tuesday, May 18, 2004
© 1992-2003 Microsoft Corporation. All rights reserved.