HID Button 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 button capability array contains information about the button usages supported by a top-level collection for a specific type of HID report. A HIDP_CAPS structure contains information about a collection's capability.
The following table shows the functions that HID client drivers can use to obtain button capability information.
| Function | Description |
|---|---|
Returns a button capability array describing all the button usages contained in a specified report type. |
|
Filters the button capability information it returns by a caller-specified usage page, usage identifier, and link collection. |
A button capability array contains HIDP_BUTTON_CAPS structures. The following list shows the information contained in the HIDP_BUTTON_CAPS structure about a HID usage or usage range:
- Usage page for the usage or usage range
- Report identifier of the report that contains the button data
- Usage identifier or usage range
- Flag that indicates whether a usage is an aliased usage
- Link collection that contains the usage or usage range
- String descriptors and designators associated with the usage or usage range
- Data indexes that the HID parser assigned to the usage or usage range
The following list shows the general conditions for all usages described by a button capability array:
- Each capability structure represents a single usage or usage range that is associated with a variable main item or an array main item.
- Variable main items can use aliased usages. A usage that is associated with an array item cannot be aliased. A usage range cannot be aliased.
- The HID parser uses only the minimum required number of usages to assign a usage to each button. The parser assigns usages in the order in which the report descriptor specifies. The parser discards usages in a report descriptor that are not required. The button capability array does not contain any information about discarded usages.
- If the number of usages specified for a variable item is less than the number of buttons in the item, the capability array contains only one capability structure that describes one button usage, which is the last usage specified in the report descriptor for the variable main item.
- The HID parser assigns a unique data index to each usage described in the capability array.
Variable Main Item Button Usages
Capability structures in a button capability array describe each usage or usage range specified in a report descriptor.
The IsAlias member of capability structures is TRUE in every structure except the last structure added to the capability array. IsAlias is FALSE in the last capability structure. The preferred usage is the last aliased usage in the sequence.
A HID driver can determine which button usages are aliased by scanning for these sequences.
The following table shows an example of aliased usages.
| Report descriptor aliased usage order | Capability array usage order | IsAlias value |
|---|---|---|
Usage 1 |
Usage 3 |
TRUE |
Usage 2 |
Usage 2 |
TRUE |
Usage 3 |
Usage 1 |
FALSE |
Array Main Item Button Usages
A capability structure in a button capability array describes each usage or usage range for a button array main item specified in a report descriptor. The order in which the capability structures are added to a capability array is the reverse of the order in which the usages are specified for a main item.
The HID parser assigns a data index to each usage associated with the array item in the order in which a report descriptor specifies the usages.
The following table shows the correspondence between a set of usages, as specified in a report descriptor, and the usages and data indexes, as specified in the capability array. In this table, n is the first data index that the parser assigns to the first usage associated with the array item.
| Report descriptor usage order | Capability array usage order | DataIndex, or DataIndexMax - DataIndexMin |
|---|---|---|
Usage 1 |
Usage range 2 |
From n+7 to n+8 |
Usage range 1, with 4 usages |
Usage 2 |
n+5 |
Usage 2 |
Usage range 1 |
From n+1 to n+4 |
Usage range 2, with 2 usages |
Usage 1 |
n |