Interpreting HID reports
This article 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:
- HidP_GetScaledUsageValue Returns a signed and scaled value.
- HidP_GetUsageValue Returns a nonscaled value in an unsigned format or a scaled value that is out of its Normal range.
- HidP_GetUsageValueArray Returns a usage value array.
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:
- HidP_GetButtons (or HidP_GetUsages) Returns the usage ID of all buttons on a specified usage page that are set to ON.
- HidP_GetButtonsEx (or HidP_GetUsagesEx) Returns the usage page and usage ID of all buttons that are set to ON.
These routines return an array of all usage information for all buttons that are currently set to ON. Implicitly, buttons whose usage isn't 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:
- (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 uses 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 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 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:
- HidP_SetScaledUsageValue Sets a signed and scaled value in a report.
- HidP_SetUsageValue Sets a value in a report.
- HidP_SetUsageValueArray Sets a usage value array in a report.
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:
- HidP_SetButtons (or HidP_SetUsages) Sets a specified set of buttons to ON (1).
- HidP_UnsetButtons (or HidP_UnsetUsages) Sets a specified set of buttons to OFF (zero).
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 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, 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.