HidP_GetUsageValue function (hidpi.h)

Article
10/21/2021

The HidP_GetUsageValue routine extracts the data associated with a HID control value that matches the selection criteria in a HID report.

Syntax

NTSTATUS HidP_GetUsageValue(
  [in]  HIDP_REPORT_TYPE     ReportType,
  [in]  USAGE                UsagePage,
  [in]  USHORT               LinkCollection,
  [in]  USAGE                Usage,
  [out] PULONG               UsageValue,
  [in]  PHIDP_PREPARSED_DATA PreparsedData,
  [in]  PCHAR                Report,
  [in]  ULONG                ReportLength
);

Parameters

[in] ReportType

Specifies a HIDP_REPORT_TYPE enumerator value that identifies the report type.

[in] UsagePage

Specifies the value's usage page.

[in] LinkCollection

Specifies the link collection that contains the value. If LinkCollection is nonzero, the routine only searches for the usage in this link collection; otherwise, if LinkCollection is zero, the routine searches for the usage in the top-level collection associated with PreparsedData.

[in] Usage

Specifies the usage of the value.

[out] UsageValue

Pointer to a buffer in which the routine returns the value data.

[in] PreparsedData

Pointer to a top-level collection's preparsed data.

[in] Report

Pointer to a report that contains values.

[in] ReportLength

Specifies the length, in bytes, of the report located at Report.

Return value

HidP_GetUsageValue returns one of the following status values:

Return code	Description
HIDP_STATUS_SUCCESS	The routine successfully returned the value data.
HIDP_INVALID_REPORT_LENGTH	The report length is not valid.
HIDP_INVALID_REPORT_TYPE	The specified report type is not valid.
HIDP_STATUS_INCOMPATIBLE_REPORT_ID	The collection contains a value on the specified usage page in a report of the specified type, but there are no such usages in the specified report.
HIDP_STATUS_INVALID_PREPARSED_DATA	The preparsed data is not valid.
HIDP_STATUS_USAGE_NOT_FOUND	The collection does not contain a value on the specified usage page in any report of the specified report type.

Remarks

HidP_GetUsageValue does not sign or scale the value. To extract a signed value, use HidP_GetScaledUsageValue. To manually assign the sign bit, the position of the sign bit can be determined from the information in a value's HIDP_VALUE_CAPS structure.

HidP_GetUsageValue is designed to extract a usage value for a usage whose report count is 1. If the specified usage has a report count greater than 1, the usage is part of a usage value array. HidP_GetUsageValue only returns the first data item in a usage value array. To extract all data items in a usage value array, use HidP_GetUsageValueArray.

For more information, see HID Collections.

Requirements

Requirement	Value
Minimum supported client	Available in Windows 2000 and later versions of Windows.
Target Platform	Universal
Header	hidpi.h (include Hidpi.h)
Library	Hidparse.lib
IRQL	<= DISPATCH_LEVEL