Export (0) Print
Expand All

HidP_GetUsages routine

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 __stdcall HidP_GetUsages(
  _In_     HIDP_REPORT_TYPE ReportType,
  _In_     USAGE UsagePage,
  _In_     USHORT LinkCollection,
  _Out_    PUSAGE UsageList,
  _Inout_  PULONG UsageLength,
  _In_     PHIDP_PREPARSED_DATA PreparsedData,
  _Out_    PCHAR Report,
  _In_     ULONG ReportLength
);

Parameters

ReportType [in]

Specifies a HIDP_REPORT_TYPE enumerator value that identifies the report type.

UsagePage [in]

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

LinkCollection [in]

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.

UsageList [out]

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.

UsageLength [in, out]

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.

PreparsedData [in]

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

Report [out]

Pointer to a report.

ReportLength [in]

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

Return value

HidP_GetUsages returns one of the following status values:

Return codeDescription
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 UsageList to zero to return the required length in UsageLength.

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

Version

Available in Windows 2000 and later versions of Windows.

Header

Hidpi.h (include Hidpi.h)

Library

Hidparse.lib

IRQL

<= DISPATCH_LEVEL

See also

_HIDP_PREPARSED_DATA
HidP_GetButtons
HidP_GetButtonsEx
HidP_GetCaps
HidP_GetScaledUsageValue
HidP_GetUsagesEx
HidP_GetUsageValue
HidP_GetUsageValueArray
HidP_MaxUsageListLength

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft