Clarify usage vs data index semantics in HID report parsing#4037
Clarify usage vs data index semantics in HID report parsing#4037DJm00n wants to merge 2 commits intoMicrosoftDocs:stagingfrom
Conversation
Adds clarification that HID usages do not uniquely identify value instances and do not define report order. Recommends using data indices (HidP_GetData) for complete and unambiguous value retrieval.
|
Learn Build status updates of commit 0581557: ✅ Validation status: passed
For more details, please refer to the build report. |
|
Learn Build status updates of commit 478fb10: ✅ Validation status: passed
For more details, please refer to the build report. |
|
Can you review the proposed changes? IMPORTANT: When the changes are ready for publication, adding a #label:"aq-pr-triaged" |
prmerger-automator
Bot
added
the
aq-pr-triaged
|
@DJm00n : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change. |
There was a problem hiding this comment.
Pull request overview
This PR clarifies that HID usages describe control meaning but don’t reliably provide a unique, ordered identifier for value instances in a report, and recommends using data indices (via HidP_GetData) for unambiguous retrieval.
Changes:
- Adds guidance explaining why usage-based value lookup can be ambiguous and recommends data-index-based retrieval.
- Rewords the “retrieve all values” discussion to contrast per-usage calls vs a single HidP_GetData call.
- Clarifies that capability arrays are used to associate data indices with usages (not to “identify” usages).
|
|
||
| ## Extracting and setting control data by data indices | ||
|
|
||
| [HidP_GetUsageValue](/windows-hardware/drivers/ddi/hidpi/nf-hidpi-hidp_getusagevalue) assumes that a [usage](./hid-usages.md) uniquely identifies a value instance. This is not guaranteed by the HID specification. A usage defines the meaning of a control, but not a unique value instance within a report. Multiple values in a report may share the same usage, and their order is defined by the report layout, not by usage values. Data indices uniquely identify each value and preserve report order. HidP_GetData should be used when complete and unambiguous input data is required. Value capabilities with **ReportCount** greater than 1 may represent usage value arrays and should be accessed using [HidP_GetUsageValueArray](/windows-hardware/drivers/ddi/hidpi/nf-hidpi-hidp_getusagevaluearray). |
There was a problem hiding this comment.
The new guidance about HidP_GetUsageValue/uniqueness is a bit imprecise compared to the repo’s established definition of a usage value array. In hid/value-capability-arrays.md it’s clarified that the ambiguity primarily occurs when only one usage is specified for a main item with ReportCount > 1, and that HidP_GetUsageValue returns only the first element of that array. Consider rephrasing this paragraph to explicitly tie the non-uniqueness to usage value arrays (and the “single usage + ReportCount > 1” condition) and/or call out that callers may need to disambiguate using data indices (or link collection + data indices) rather than stating that the API broadly “assumes” uniqueness.
|
|
||
| ## Extracting and setting control data by data indices | ||
|
|
||
| [HidP_GetUsageValue](/windows-hardware/drivers/ddi/hidpi/nf-hidpi-hidp_getusagevalue) assumes that a [usage](./hid-usages.md) uniquely identifies a value instance. This is not guaranteed by the HID specification. A usage defines the meaning of a control, but not a unique value instance within a report. Multiple values in a report may share the same usage, and their order is defined by the report layout, not by usage values. Data indices uniquely identify each value and preserve report order. HidP_GetData should be used when complete and unambiguous input data is required. Value capabilities with **ReportCount** greater than 1 may represent usage value arrays and should be accessed using [HidP_GetUsageValueArray](/windows-hardware/drivers/ddi/hidpi/nf-hidpi-hidp_getusagevaluearray). |
There was a problem hiding this comment.
HidP_GetData is referenced here without bolding or a link, while surrounding API mentions are consistently linked. Consider linking (or at least bolding) HidP_GetData in this paragraph for consistency and easier navigation.
| These routines are useful to an application or driver that provides a "value-added" service. For example, one that provides a custom interface to all the controls supported by a HIDClass device. Microsoft DirectInput is one example. | ||
|
|
||
| An application or driver calling these routines can most efficiently obtain and set all values in a report. For example, to obtain all value data by their [HID usages](./hid-usages.md), it has to call [HidP_GetUsageValue](/windows-hardware/drivers/ddi/hidpi/nf-hidpi-hidp_getusagevalue) for each usage. However, to obtain all value data by data index, it only has to call **HidP_GetData** once. | ||
| An application or driver calling these routines can most efficiently obtain and set all values in a report. For example, retrieving values by [usage](./hid-usages.md) requires calling [HidP_GetUsageValue](/windows-hardware/drivers/ddi/hidpi/nf-hidpi-hidp_getusagevalue) for each usage, while [HidP_GetData](/windows-hardware/drivers/ddi/hidpi/nf-hidpi-hidp_getdata) retrieves all values in a single call using data indices. |
There was a problem hiding this comment.
This example suggests you can “obtain all value data” by iterating usages with HidP_GetUsageValue. However, the doc already notes that multiple values can share the same usage (for example, usage value arrays), in which case HidP_GetUsageValue won’t retrieve every instance. Please reword the example to avoid implying that per-usage iteration is sufficient to retrieve all values in a report.
Adds clarification that HID usages do not uniquely identify value instances and do not define report order. Recommends using data indices (HidP_GetData) for complete and unambiguous value retrieval.