HidP_GetUsageValue
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
This function extracts the data associated with a HID control value that matches selection criteria in a HID report.
Syntax
NTSTATUS HidP_GetUsageValue(
HIDP_REPORT_TYPE ReportType,
USAGE UsagePage,
USHORT LinkCollection,
USAGE Usage,
PULONG UsageValue,
PHIDP_PREPARSED_DATA PreparsedData,
PCHAR Report,
ULONG ReportLength
);
Parameters
- ReportType
[in] HIDP_REPORT_TYPE enumerator value that identifies the report type.
- UsagePage
[in] Usage page of the value.
- LinkCollection
[in] Link collection that contains the value. If LinkCollection is nonzero, the function only searches for the usage in this link collection; otherwise, if LinkCollection is zero, the function searches for the usage in the top-level collection associated with PreparsedData.
- Usage
[in] Usage of the value.
- UsageValue
[out] Pointer to a buffer in which the function returns the value data.
- PreparsedData
[in] Pointer to a top-level collection's preparsed data.
- Report
[in] Pointer to a report that contains values.
- ReportLength
[in] Length, in bytes, of the report located at Report.
Return Value
The following table shows the possible return values.
| Value | Description |
|---|---|
HIDP_STATUS_SUCCESS |
The function successfully returned the value data. |
HIDP_INVALID_REPORT_LENGTH |
Report length is not valid. |
HIDP_INVALID_REPORT_TYPE |
Specified report type is not valid. |
HIDP_STATUS_INCOMPATIBLE_REPORT_ID |
Report contains a collection with buttons in the specified usage page, but there are no such usages in the report. |
HIDP_STATUS_INVALID_PREPARSED_DATA |
Preparsed data is not valid. |
HIDP_STATUS_USAGE_NOT_FOUND |
Collection does not contain a value in the specified usage page in any report of the specified report type. |
Remarks
The terms button and usage are used synonymously.
HidP_GetUsageValue does not sign or scale the value. To extract a signed value, use HidP_GetScaledUsageValue. To manually assign the sign bit, you can determine the position of the sign bit from the information in a value's HIDP_VALUE_CAPS structure.
To extract a usage value array, use HidP_GetUsageValueArray.
Requirements
| Header | hidpi.h |
| Library | Hidparse_lib.lib |
| Windows Embedded CE | Windows CE .NET 4.2 and later |
See Also
Reference
HidP_GetButtons
HidP_GetButtonsEx
HidP_GetCaps
HidP_GetScaledUsageValue
HidP_GetUsages
HidP_GetUsagesEx
HidP_GetUsageValueArray
HIDP_REPORT_TYPE
HIDP_VALUE_CAPS