Edit

Share via

HidP_SetScaledUsageValue function (hidpi.h)

  • Article

The HidP_SetScaledUsageValue routine converts a signed and scaled physical number to a HID usage's logical value, and sets the usage value in a specified HID report.

Syntax

NTSTATUS HidP_SetScaledUsageValue(
  [in]      HIDP_REPORT_TYPE     ReportType,
  [in]      USAGE                UsagePage,
  [in]      USHORT               LinkCollection,
  [in]      USAGE                Usage,
  [in]      LONG                 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 signed and scaled physical number, which the routine converts to the usage's logical 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_SetScaledUsageValue returns one of the following status values:

Return code Description
HIDP_STATUS_SUCCESS
 The routine successfully set the usage value.
HIDP_STATUS_BAD_LOG_PHY_VALUES
 The usage has an illegal logical or physical range that prevents scaling.
HIDP_STATUS_VALUE_OUT_OF_RANGE
 The specified physical value is out-of-range and the usage does not have null value.
HIDP_STATUS_INVALID_REPORT_LENGTH
 The report length is not valid.
HIDP_STATUS_INVALID_REPORT_TYPE
 The specified report type is not valid.
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_USAGE_NOT_FOUND
 The usage does not exist in any report of the specified report type.
HIDP_STATUS_NULL
 The specified physical value is out-of-range, the usage has a null value, and the routine set the null value.

Remarks

HidP_SetScaledUsageValue sets the sign bit.

If the routine returns HIDP_STATUS_INCOMPATIBLE_REPORT_ID, the specified report does contain the usage. However, a user-mode application or kernel-mode driver can set the usage in a zero-initialized report. See Initializing HID Reports.

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

See also

HIDP_CAPS

HIDP_REPORT_TYPE

HidP_GetCaps

HidP_SetUsageValue

HidP_SetUsageValueArray

_HIDP_PREPARSED_DATA