Skip to content

Clarify usage vs data index semantics in HID report parsing #4037

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DJm00n wants to merge 2 commits into
base: staging
Choose a base branch
from
Open

Clarify usage vs data index semantics in HID report parsing #4037

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0581557
Clarify usage vs data index semantics in HID report parsing
DJm00n Apr 17, 2026
478fb10
Update metadata and formatting in HID reports article
DJm00n Apr 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions windows-driver-docs-pr/hid/interpreting-hid-reports.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,16 +63,18 @@ An application or driver can set the state of buttons in a properly initialized

## 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).
Copy link

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Contributor

@EliotSeattle EliotSeattle Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot apply changes based on this feedback

Copy link

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.

To use data indices to extract and set control data in a HID report, an application or driver can use the following [HIDClass support routines](/windows-hardware/drivers/ddi/_hid/#hidclass-support-routines):

- [HidP_GetData](/windows-hardware/drivers/ddi/hidpi/nf-hidpi-hidp_getdata)
- [HidP_SetData](/windows-hardware/drivers/ddi/hidpi/nf-hidpi-hidp_setdata)

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.
Copy link

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.

An application or driver uses the data indices specified in a collection's [Button Capability Arrays](./button-capability-arrays.md) and [Value Capability Arrays](./value-capability-arrays.md) to identify HID usages.
An application or driver uses the data indices specified in a collection's [Button Capability Arrays](./button-capability-arrays.md) and [Value Capability Arrays](./value-capability-arrays.md) to associate data indices with HID usages.

## See also

Expand Down