HID Value Capability Arrays (Windows CE 5.0)
A value capability array contains information about the value usages supported by a top-level collection for a specific type of HID report. Information about a collection's value capability arrays is contained in its HIDP_CAPS structure.
The following table shows the functions that a HID client driver can use to obtain button capability information.
| Function | Description |
|---|---|
| HidP_GetValueCaps | Returns a value capability array describing all the values contained in a caller-specified report type. |
| HidP_GetSpecificValueCaps | Filters the value capability information it returns by a caller-specified usage page, usage, link collection, and report type. |
A value capability array contains HIDP_VALUE_CAPS structures. The following list shows the information contained in a HIDP_VALUE_CAPS structure:
- Usage page for a usage or usage range
- Report identifier of the report that contains the value
- Usage identifier or a usage range
- Whether a usage is aliased
- Link collection that contains the usage or usage range
- Size, in bits, of a value, and the report count, which is the number of individual values described by the structure
- Attributes of each value, including whether it has a NULL value, its units and exponent, and its logical and physical ranges
- String descriptors and designators associated with the usage or usage range
- Data indexes that the HID parser assigns a usage or usage range
The following list shows the general conditions for all the usages described by a value capability array:
- Each capability structure represents a usage, a usage range, or a usage value array that is associated with a variable main item. Array main items are not supported for values.
- Aliased usages can be used. A usage range cannot be aliased. Aliased values are linked together in a value capability array in the same way as aliased buttons as linked together in a button capability array.
- The HID parser uses only the minimum required usages to assign a usage to each value. The parser assigns usages in the order that report descriptors specify them. Usages in a report descriptor that are not required are discarded. The value capability array does not contain any information about discarded usages.
- The HID parser assigns a unique data index to each usage described in the capability array.
Usage Value Arrays
A usage value array is a consecutive set of values specified in a main item, all of which have the same usage. This occurs if only one usage is specified for a main item whose report count is greater than one.
If the report count for a usage is one, use HidP_GetUsageValue to extract the usage value. If the usage's report count is greater than one, HidP_GetUsageValue only returns the first data item in a usage value array. To extract all the data items in a usage value array, use HidP_GetUsageValueArray.
See Also
HID Button Capability Arrays | HID Data Indexes
Send Feedback on this topic to the authors