HidP_GetUsagesEx function (hidpi.h)

The HidP_GetUsagesEx routine returns a list of the all the HID control button usages that are set to ON in a HID report.

Syntax

NTSTATUS HidP_GetUsagesEx(
  [in]      HIDP_REPORT_TYPE     ReportType,
  [in]      USHORT               LinkCollection,
  [in, out] PUSAGE_AND_PAGE      ButtonList,
  [in, out] ULONG                *UsageLength,
  [in]      PHIDP_PREPARSED_DATA PreparsedData,
  [in]      PCHAR                Report,
  [in]      ULONG                ReportLength
);

Parameters

[in] ReportType

Specifies a HIDP_REPORT_TYPE enumerator value that identifies the report type.

[in] LinkCollection

Specifies the link collection of the button usages. If LinkCollection is nonzero, the routine only returns information about the buttons that this link collection contains; otherwise, if LinkCollection is zero, the routine returns information about all the buttons in the top-level collection associated with PreparsedData.

[in, out] ButtonList

Pointer to a caller-allocated buffer that routine uses to return the usage and usage page identifiers for each button that is set to ON (1).

[in, out] UsageLength

Specifies, on input, the length, in array elements, of the ButtonList buffer. Specifies, on output, the number usages that are currently set to ON in the specified report.

[in] PreparsedData

Pointer to a top-level collection's preparsed data.

[in] Report

Pointer to a report that contains button data.

[in] ReportLength

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

Return value

HidP_GetUsagesEx returns one of the following status values:

Return code Description
HIDP_STATUS_SUCCESS
The routine successfully returned all button usages set to ON.
HIDP_INVALID_REPORT_LENGTH
The report length is not valid.
HIDP_INVALID_REPORT_TYPE
The specified report type is not valid.
HIDP_STATUS_BUFFER_TOO_SMALL
The UsageList buffer is too small to hold all the usages currently set to ON in the specified report.
HIDP_STATUS_INCOMPATIBLE_REPORT_ID
The collection contains buttons 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.

Remarks

User-mode applications and kernel-mode drivers call HidP_MaxUsageListLength to determine the maximum number of buttons that be returned for specified report type. Alternatively, applications or drivers can call HidP_GetUsagesEx and set (*UsageLength) to zero to return the required length in UsageLength. In other words, UsageLength should be a valid pointer that points to a ULONG value 0 to get the required length.

Applications or drivers determine the required report length from the XxxReportByteLength members in a top-level collection's HIDP_CAPS structure.

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_GetButtons

HidP_GetButtonsEx

HidP_GetCaps

HidP_GetScaledUsageValue

HidP_GetUsageValue

HidP_GetUsageValueArray

HidP_GetUsagesEx

HidP_MaxUsageListLength

USAGE_AND_PAGE

_HIDP_PREPARSED_DATA