Edit

Share via

HidP_GetUsages function (hidpi.h)

  • Article

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

See also

HidP_GetButtons

HidP_GetButtonsEx

HidP_GetCaps

HidP_GetScaledUsageValue

HidP_GetUsageValue

HidP_GetUsageValueArray

HidP_GetUsagesEx

HidP_MaxUsageListLength

_HIDP_PREPARSED_DATA