HidP_UnsetUsages function (hidpi.h)

Article
02/22/2024

The HidP_UnsetUsages routine sets specified HID control button usages OFF (zero) in a HID report.

Syntax

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

Parameters

[in] ReportType

Specifies a HIDP_REPORT_TYPE enumerator value that indicates the type of report located at Report.

[in] UsagePage

Specifies the usage page of the usages specified by UsageList.

[in, optional] LinkCollection

Specifies the link collection that contains the usages. If LinkCollection is nonzero, the routine only sets the usages, if they exist, in this link collection. If LinkCollection is zero, the routine sets the first usage for each usage it finds in the top-level collection associated with PreparsedData.

[in, out] UsageList

Pointer to the array of usages to set to OFF.

[in, out] UsageLength

Specifies, on input, the number of usages in UsageList. See the Remarks section for information about the output value.

[in] PreparsedData

Pointer to the preparsed data of the top-level collection associated with the report located at Report.

[in] Report

Pointer to a report.

[in] ReportLength

Specifies the size, in bytes, of the report located at Report, which must be equal to the report length for the specified report type that HidP_GetCaps returns in a collection's HIDP_CAPS structure.

Return value

HidP_UnsetUsages returns HIDP_STATUS_SUCCESS if it successfully sets to OFF all the usages in UsageList.

HidP_UnsetUsages returns one of the following status values if one of the input parameters is not valid:

Return code	Description
HIDP_STATUS_INVALID_PREPARSED_DATA	The preparsed data specified by PreparsedData is not valid.
HIDP_STATUS_INVALID_REPORT_LENGTH	The report length is not valid.
HIDP_STATUS_INVALID_REPORT_TYPE	The report type is not valid.
HIDP_STATUS_REPORT_DOES_NOT_EXIST	The collection does not contain a report of the specified type.

HidP_UnsetUsages returns one of the following status values if it was not able to set to OFF one of the usages in UsageList:

Return code	Description
HIDP_STATUS_BUTTON_NOT_PRESSED	A usage is already set to OFF.
HIDP_STATUS_INCOMPATIBLE_REPORT_ID	A usage is not contained in the specified report, but is contained in another report of the specified type.
HIDP_STATUS_USAGE_NOT_FOUND	The routine did not find a usage in any report of the specified type.

Remarks

HidP_UnsetUsages sets UsageLength as follows:

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