Share via

HidP_GetUsageValueArray (Compact 2013)

  • Article

3/26/2014

This function extracts the data associated with a HID control usage value array from a HID report.

Syntax

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

Parameters

  • ReportType
    [in] HIDP_REPORT_TYPE enumerator value that identifies the report type.
  • UsagePage
    [in] Usage page of the usage value array.
  • LinkCollection
    [in] Optional. Link collection that contains the usage value array. If LinkCollection is nonzero, the function only searches for a usage value array in this link collection; otherwise, if LinkCollection is zero, the function searches for a usage value array in the top-level collection associated with PreparsedData.
  • Usage
    [in] Usage of the usage value array.
  • UsageValue
    [out] Pointer to a caller-allocated buffer in which the function returns the data associated with the usage value array.
  • UsageValueByteLength
    [in] Length, in bytes, of the buffer at UsageValue.
  • PreparsedData
    [in] Pointer to a top-level collection's preparsed data.
  • Report
    [in] Pointer to a report that contains values.
  • ReportLength
    [in] Length, in bytes, of the report located at Report.

Return Value

The following table shows the possible return values.

Value

Description

HIDP_STATUS_SUCCESS

The function successfully returned the value's data.

HIDP_INVALID_REPORT_LENGTH

Report length is not valid.

HIDP_INVALID_REPORT_TYPE

Specified report type is not valid.

HIDP_STATUS_NOT_VALUE_ARRAY

Requested usage is not a usage value array.

HIDP_STATUS_BUFFER_TOO_SMALL

UsageValue buffer is too small to hold the requested usage.

HIDP_STATUS_INCOMPATIBLE_REPORT_ID

Report contains a collection with buttons in the specified usage page, but there are no such usages in the report.

HIDP_STATUS_INVALID_PREPARSED_DATA

Preparsed data was not valid.

HIDP_STATUS_USAGE_NOT_FOUND

Report contains a requested usage that is 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 UsageValueByteLength.

Beginning with the least significant bit of the usage's data, HidP_GetUsageValueArray sets the UsageValue buffer in little-endian order. The data is not byte-aligned, and is shifted so that the least significant bit of data is the first bit of the UsageValue buffer.

Requirements

Header

hidpi.h

Library

Hidparse_lib.lib

See Also

Reference

HID Parser Functions
HidP_GetButtons
HidP_GetButtonsEx
HidP_GetCaps
HidP_GetScaledUsageValue
HidP_GetUsages
HidP_GetUsagesEx
HidP_GetUsageValue
HIDP_REPORT_TYPE
HIDP_VALUE_CAPS