Troubleshooting: HID Report Identifier Errors
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
Description
When a driver receives a HID report from a HID collection, it can be any report that the collection contains, because a collection can return reports in any order.
The following table shows the status values that the HidP_GetXXX functions return to indicate report identifier values.
| Status value | Description |
|---|---|
HIDP_STATUS_INCOMPATIBLE_REPORT_ID |
Requested usage is in a report supported by the HID collection, but not in the report that the driver specified. |
HIDP_STATUS_USAGE_NOT_FOUND |
Requested usage is not in any report supported by the top-level collection. |
For example, assume a driver receives a report from a collection, and then calls HidP_GetUsageValue to extract a usage value. If the report's identifier is seven, the function returns HIDP_STATUS_INCOMPATIBLE_REPORT_ID, which indicates that the device supports the returned value, but the returned value is not in the report. On the other hand, if the driver requests a value, the function returns HIDP_STATUS_USAGE_NOT_FOUND, which indicates that the value is not in any report supported by the collection.
When a driver uses the HidP_SetXXX functions to set usages in a report, the functions can also return the same two status values. The meaning of HIDP_STATUS_USAGE_NOT_FOUND is the same as with the HidP_GetXXX functions. However, the meaning of HIDP_STATUS_INCOMPATIBLE_REPORT_ID is different. This status value indicates that the report was previously configured with a report identifier, and the usage specified by the caller does not belong to that report identifier. After a driver uses HidP_SetUsages to set a button in a zero-initialized report, the report is configured with a report identifier of a specified value. If the driver subsequently attempts to use HidP_SetUsageValue to set a value in the same report, the function returns HIDP_STATUS_INCOMPATIBLE_REPORT_ID.
Resolution
The following list shows the actions the caller should take if a HidP_XXX function returns HIDP_STATUS_INCOMPATIBLE_REPORT_ID:
- If the caller sets usages, the caller should allocate a new report of the correct length, initialize it to zero, and then call the function again. The caller can send the report to the collection after successfully setting all usages in the report.
- If the caller extracts usages, the caller should call the function with a different report obtained from the collection.