Share via

HidP_SetUsageValueArray

  • Article

This function sets a HID control usage value array in a specified HID report.

NTSTATUS HidP_SetUsageValueArray(
  HIDP_REPORT_TYPE ReportType,
  USAGE UsagePage,
  USHORT LinkCollection,
  USAGE Usage,
  PCHAR UsageValue,
  USHORT UsageValueByteLength,
  PHIDP_PREPARSED_DATA PreparsedData,
  PCHAR Report,
  ULONG ReportLength
);

Parameters

  • ReportType
    [in] HIDP_REPORT_TYPE enumerator value that indicates the type of HID report located at Report.
  • UsagePage
    [in] Usage page of a usage.
  • LinkCollection
    [in] Optional. Link collection that contains the usage. If LinkCollection is nonzero, the function only sets the usage, if one exists, in this link collection. If LinkCollection is zero, the function sets the first usage it finds in the top-level collection associated with PreparsedData.
  • Usage
    [in] Usage.
  • UsageValue
    [in] Pointer to a caller-allocated buffer that contains the data associated with the usage value array.
  • UsageValueByteLength
    [in] Length, in bytes, of the UsageValue buffer.
  • PreparsedData
    [in] Pointer to a top-level's preparsed data.
  • Report
    [out] Pointer to a HID report.
  • ReportLength
    [in] 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 Values

The following table shows the possible return values for this function.

Value Description
HIDP_STATUS_SUCCESS The function successfully set the usage value.
HIDP_STATUS_INVALID_REPORT_LENGTH Report length was not valid.
HIDP_STATUS_INVALID_REPORT_TYPE Specified report type was not valid.
HIDP_STATUS_BUFFER_TOO_SMALL Size, in bytes, of the UsageValue buffer was too small.
HIDP_STATUS_INCOMPATIBLE_REPORT_ID Report contained a collection with buttons in the specified usage page, but there were no such usages in the report.
HIDP_STATUS_NOT_VALUE_ARRAY Specified usage was not a usage value array.
HIDP_STATUS_INVALID_PREPARSED_DATA Preparsed data was not valid.
HIDP_STATUS_REPORT_DOES_NOT_EXIST No reports of the specified type existed.
HIDP_STATUS_NOT_IMPLEMENTED Report size of data fields specified for the usage value array was not a multiple of eight bits.
HIDP_STATUS_USAGE_NOT_FOUND Report contained a requested usage that was not in any report supported by the top-level collection.

Remarks

The terms button and usage are used synonymously.

Multiplying the BitSize and ReportCount members of the usage value array's HIDP_VALUE_CAPS structure, and rounding the result up to the nearest byte determines the required size of the UsageValue buffer.

HidP_SetUsageValueArray only supports usage value arrays where each data field of the array is a multiple of eight bits.

The caller must set the UsageValue buffer exactly as it should occur in the report.

Requirements

OS Versions: Windows CE .NET 4.2 and later.
Header: Hidpi.h.
Link Library: Hidparse_lib.lib.

See Also

HID Drivers | HIDP_CAPS | HidP_GetCaps | HIDP_REPORT_TYPE | HidP_SetScaledUsageValue, HidP_SetUsageValue | HIDP_VALUE_CAPS

 Last updated on Tuesday, May 18, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.