HID Value Capability Arrays
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
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 |
|---|---|
Returns a value capability array describing all the values contained in a caller-specified report type. |
|
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.