HidP_GetUsageValue routine

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

Syntax


NTSTATUS __stdcall 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

ReportType [in]

Specifies a HIDP_REPORT_TYPE enumerator value that identifies the report type.

UsagePage [in]

Specifies the value's usage page.

LinkCollection [in]

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 [in]

Specifies the usage of the value.

UsageValue [out]

Pointer to a buffer in which the routine 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]

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

Return value

HidP_GetUsageValue returns one of the following status values:

Return codeDescription
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

Version

Available in Windows 2000 and later versions of Windows.

Header

Hidpi.h (include Hidpi.h)

Library

Hidparse.lib

IRQL

<= DISPATCH_LEVEL

See also

_HIDP_PREPARSED_DATA
HidP_GetButtons
HidP_GetButtonsEx
HidP_GetCaps
HidP_GetScaledUsageValue
HidP_GetUsages
HidP_GetUsagesEx
HidP_GetUsageValueArray
HIDP_VALUE_CAPS

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft