HidP_GetUsageValue function

  • 2 minutes to read

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(
  HIDP_REPORT_TYPE     ReportType,
  USAGE                UsagePage,
  USHORT               LinkCollection,
  USAGE                Usage,
  PULONG               UsageValue,
  PHIDP_PREPARSED_DATA PreparsedData,
  PCHAR                Report,
  ULONG                ReportLength
);

Parameters

ReportType

Specifies a HIDP_REPORT_TYPE enumerator value that identifies the report type.

UsagePage

Specifies the value's usage page.

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.

Usage

Specifies the usage of the value.

UsageValue

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

PreparsedData

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

Report

Pointer to a report that contains values.

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

   
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

See also

HIDP_VALUE_CAPS

HidP_GetButtons

HidP_GetButtonsEx

HidP_GetCaps

HidP_GetScaledUsageValue

HidP_GetUsageValueArray

HidP_GetUsages

HidP_GetUsagesEx

_HIDP_PREPARSED_DATA