Share via

HID Value Capability Arrays (Windows Embedded CE 6.0)

  • Article

1/6/2010

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

Concepts

HID Driver Development Concepts
HID Button Capability Arrays
HID Data Indexes