Edit

Interpreting HID Reports

  • Article

This section describes how user-mode applications and kernel-mode drivers use the HidP_Xxx HIDClass support routines to interpret control data in a HID report.

Extracting Value Data by Specifying Its Usage

To extract value data from a HID report, an application or driver can use one of the following HID support routines:

To use HidP_GetUsageValueArray applications and drivers must allocate a zero-initialized buffer, which is large enough to hold the usage value array. The required size in bytes is the product of the BitSize and ReportCount members of the usage value array's HIDP_VALUE_CAPS structure, rounded up to the nearest byte.

Extracting Button Usages That Are Set to ON

To extract the HID usages of buttons that are set to ON (1), applications and drivers call one of the following HID support routines:

These routines return an array of all usage information for all buttons that are currently set to ON. Implicitly, buttons whose usage is not returned by these routines are set to OFF (zero).

To call these routines, applications and drivers must first allocate and zero-initialize the buffer used to return the array of button usages. An application or driver calls HidP_MaxUsageListLength to determine the number of button usages in a specified usage page in the report. If the application or driver specifies a usage page of zero, the routine returns the number of all the button usages in the report.

The required buffer size, in bytes, is the following:

  • (For HidP_GetButtons) The value returned by HidP_MaxUsageListLength times sizeof(USAGE)

  • (For HidP_GetButtonsEx) The value returned by HidP_MaxUsageListLength times sizeof(USAGE_AND_PAGE)

After an application or driver has used these routines to obtain information about which buttons are currently set to ON, it can determine the difference between the current state and the previous state of the buttons by calling one of the following HIDClass support routines. These routines return the difference between two arrays of usage information:

Extracting and Setting Control Data by Data Indices

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:

These routines are particularly 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.

By calling these routines, an application or driver can most efficiently obtain and set all values in a report. For example, to obtain all value data by their HID usages it has to call 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 uses the data indices specified in a collection's Button Capability Arrays and Value Capability Arrays to identify HID usages.

Setting Value Data by Specifying Its Usage

An application or driver can set a value in a properly-initialized HID report by calling one of the following HID support routines:

Setting Button State by Specifying Its Usage

An application or driver can set the state of buttons in a properly-initialized HID report by calling one of the following HIDClass support routines:

Extracting and Setting HID Control Data by Data Indices

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:

These routines are particularly 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.

By calling these routines, an application or driver can most efficiently obtain and set all values in a report. For example, to obtain all value data by their HID usages, it has to call 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 uses the data indices specified in a collection's Button Capability Arrays and Value Capability Arrays to identify HID usages.

See also

Initializing HID Reports