HID Report Interpretation
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
Extracting Value Data by Specifying Its Usage
The following table shows the functions that HID client drivers can use to extract value data from a HID report.
| Function | Description |
|---|---|
Returns a signed and scaled value. |
|
Returns a nonscaled value in an unsigned format or a scaled value that is out of its usual range. |
|
Returns a usage value array. To use HidP_GetUsageValueArray, applications and drivers must allocate a zero-initialized buffer that 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 button usages that are On, you must first allocate and zero-initialize the buffer used to return the array of button usages. Call HidP_MaxUsageListLength to determine the number of button usages in a specified usage page in the report. If the HID client driver specifies a usage page of zero, the function returns the number of all the button usages in the report.
The following table shows the functions that HID client drivers can use to extract the HID usages of buttons that are set to On (1), and the required buffer size. These functions return an array of all usage information for all buttons that are currently set to On. Implicitly, if these functions do not return the usage of the buttons, the usage is Off (zero).
| Function | Required buffer size | Description |
|---|---|---|
Value returned by HidP_MaxUsageListLength, multiplied by sizeof(USAGE). |
Returns the usage identifier of all buttons on a specified usage page that are On. |
|
Value returned by HidP_MaxUsageListLength, multiplied by sizeof(USAGE_AND_PAGE). |
Returns the usage page and usage identifier of all buttons that are On. |
After a HID client driver uses these functions to obtain information about which buttons are currently set to On, the HID client driver can determine the difference between the current state and the previous state of the buttons by calling HidP_UsageListDifference or HidP_UsageAndPageListDifference, which both return the difference between two arrays of usage information:
Setting Value Data by Specifying Its Usage
The following table shows the functions that a HID client driver can use to set a value in a properly initialized HID report.
| Function | Description |
|---|---|
Sets a signed and scaled value in a report. |
|
Sets a value in a report. |
|
Sets a usage value array in a report. |
Setting Button State by Specifying Its Usage
The following table shows the functions that a HID client driver can use to set the state of buttons in a properly initialized HID report.
| Function | Description |
|---|---|
Sets a specified set of buttons to On. |
|
Sets a specified set of buttons to Off. |
Extracting and Setting Control Data by Data Indexes
The following table shows the functions that a HID client driver can use with data indexes to extract and set control data in a HID report.
| Function | Description |
|---|---|
Returns an array of HIDP_DATA structures for a specified report that identifies the data indexes of all HID control buttons that are currently set to On, and for the data indexes and data associated with all HID control values. |
|
Sets a specified set of HID control button and value usages in a HID report. |
By calling these functions, a HID client driver can efficiently obtain and set all values in a report. For example, to obtain all value data by their HID usages, a HID client driver must call HidP_GetUsageValue for each usage. However, to obtain all value data by data index, it only has to call HidP_GetData once.
Use the data indexes specified in a collection's button capability arrays and value capability arrays to identify HID usages.