HidP_SetUsageValue function (hidpi.h)

Article
02/22/2024

The HidP_SetUsageValue routine sets a HID control value in a specified HID report.

Syntax

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

Parameters

[in] ReportType

Specifies a HIDP_REPORT_TYPE enumerator value that indicates the type of HID report located at Report.

[in] UsagePage

Specifies the usage page of a usage.

[in] LinkCollection

Specifies the link collection that contains the usage. If LinkCollection is nonzero, the routine only sets the usage, if one exists, in this link collection. If LinkCollection is zero, the routine sets the first usage it finds in the top-level collection associated with PreparsedData.

[in] Usage

Specifies the usage.

[in] UsageValue

Specifies the usage value.

[in] PreparsedData

Pointer to a top-level's preparsed data.

[in, out] Report

Pointer to a HID report.

[in] ReportLength

Specifies the size, in bytes, of the HID report located at Report, which must be equal to the report length for the specified report type that HidP_GetCaps returns in a collection's HIDP_CAPS structure.

Return value

HidP_SetUsageValue returns one of the following status values:

Return code	Description
HIDP_STATUS_SUCCESS	The routine successfully set the usage value.
HIDP_STATUS_INCOMPATIBLE_REPORT_ID	The usage does not exist in the specified report, but it does exist in a different report of the specified type.
HIDP_STATUS_INVALID_PREPARSED_DATA	The preparsed data is not valid.
HIDP_STATUS_REPORT_DOES_NOT_EXIST	There are no reports of the specified type.
HIDP_STATUS_USAGE_NOT_FOUND	The usage does not exist in any report of the specified report type.
HIDP_STATUS_INVALID_REPORT_LENGTH	The report length is not valid.
HIDP_STATUS_INVALID_REPORT_TYPE	The specified report type is not valid.

Remarks

HidP_SetUsageValue routine does not sign the value. A user-mode application or kernel-mode driver must either sign the value, at the position provided in the HIDP_VALUE_CAPS structure for this value, or call HidP_SetScaledUsageValue.

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