HID Link Collections
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 link collection is a nested collection within a top-level collection. A top-level collection can have zero or more link collections.
The HidP_GetLinkCollectionNodes function returns a top-level collection's link collection array, which contains information about a top-level collection's link collections.
Link Collection Arrays
A link collection array describes all the link collections contained within a top-level collection. One HIDP_LINK_COLLECTION_NODE structure represents one link collection. The organization of the array's link nodes identifies the link collection's sequential and hierarchical order within a top-level collection. The first element of a link collection array represents a top-level collection, and the remaining members represent the top-level collection's link collections.
By traversing through the nodes in the link connection array, a HID client driver can determine the organization and usage of all the link collections in a top-level collection. In addition, the driver can organize controls by their associated link collections. This is possible because a top-level collection's button capability arrays and value capability arrays identify the link collection that contains each HID usage described by the capability arrays.
Link Collection Nodes
Link collections link together in a top-to-bottom and left-to-right order.
The following table shows the relationships of different nodes in a link collection array.
| Array element | Description |
|---|---|
Parent |
A collection's parent is the collection immediately above the collection in the top-to-bottom hierarchy. Link collections have one parent. The Parent member of a link node specifies the index of its parent in the link collection array. |
Children |
A link collection is a child of its parent. A parent can have zero or more children. The NumberOfChildren member of a link node structure specifies the number of children of that structure's parent. |
First child |
The first child is the left-most sibling in a set of siblings. The FirstChild member of a link collection node specifies the index to its first child in the link collection array. If a link collection node has no children, FirstChild is zero. |
Sibling |
All children of a parent are siblings. |
Next sibling |
Siblings are ordered from left to right. If there is more than one sibling, the sibling to the immediate right is the first sibling. The NextSibling member of a link collection node specifies the index to its next sibling in the link collection array. If a link collection node does not have a next sibling, NextSibling is zero. |
A HID client driver can determine a parent collection's children by starting with the parent's first child, and then traversing through the siblings of the first child until the NextSibling member of a sibling node is zero.
The following code example shows how to use a link collection node index to find the first child of link collection seven.
HIDP_LINK_COLLECTION_NODE Collection[10];
HIDP_LINK_COLLECTION_NODE Node1;
Node1 = Collection[Collection[7].FirstChild];
Aliased Collections
A device can use delimiter items in its report descriptor to delimit a set of aliased collections. An aliased link collection node represents each aliased collection.
The following list shows how a complete and unique set of more than two aliased nodes link together:
- Aliased nodes are in consecutive order in the link collection array.
- Except for the last aliased node, every node's IsAlias member is TRUE.
- The last node's IsAlias member is FALSE.
- The last node terminates the sequence of aliased nodes.
- The usage associated with the last node is the preferred usage.
A client driver can determine which collections are aliased by repeatedly incrementing the array index of a link collection array to find such sequences.
Each usage that button capability arrays and value capability arrays describe identifies the link collection that contains the usage. If a link collection is aliased, the capability arrays specify the preferred usage.