HidP_GetUsages function (hidpi.h)

Article
10/21/2021

The HidP_GetUsages routine returns a list of all the HID control button usages that are on a specified usage page and are set to ON in a HID report.

Syntax

NTSTATUS HidP_GetUsages(
  [in]      HIDP_REPORT_TYPE     ReportType,
  [in]      USAGE                UsagePage,
  [in]      USHORT               LinkCollection,
  [out]     PUSAGE               UsageList,
  [in, out] PULONG               UsageLength,
  [in]      PHIDP_PREPARSED_DATA PreparsedData,
  [out]     PCHAR                Report,
  [in]      ULONG                ReportLength
);

Parameters

[in] ReportType

Specifies a HIDP_REPORT_TYPE enumerator value that identifies the report type.

[in] UsagePage

Specifies the usage page of the button usages. The routine only returns information about buttons on this usage page.

[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.

[out] UsageList

Pointer to a caller-allocated buffer that the routine uses to return the usages of all buttons that are set to ON and belong to the usage page specified by UsagePage.

[in, out] UsageLength

Specifies, on input, the length, in array elements, of the UsageList buffer. Specifies, on output, the number of buttons that are set to ON on the specified usage page.

[in] PreparsedData

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

[out] Report

Pointer to a report.

[in] ReportLength

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

Return value

HidP_GetUsages 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 that are currently set to ON on the specified usage page.
HIDP_STATUS_INCOMPATIBLE_REPORT_ID	The collection contains buttons on the specified usage page 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.
HIDP_STATUS_USAGE_NOT_FOUND	The collection does not contain any buttons on the specified usage page in any report of the specified report type.

Remarks

User-mode applications and kernel-mode drivers call HidP_MaxUsageListLength to determine the maximum number of buttons that can be returned for specified report type. Alternatively, applications or drivers can call HidP_GetUsages 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