HidP_InitializeReportForID function (hidpi.h)

Article
10/21/2021

The HidP_InitializeReportForID routine initializes a HID report.

Syntax

NTSTATUS HidP_InitializeReportForID(
  [in]  HIDP_REPORT_TYPE     ReportType,
  [in]  UCHAR                ReportID,
  [in]  PHIDP_PREPARSED_DATA PreparsedData,
  [out] PCHAR                Report,
  [in]  ULONG                ReportLength
);

Parameters

[in] ReportType

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

[in] ReportID

Specifies a report ID.

[in] PreparsedData

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

[out] Report

Pointer to the caller-allocated buffer containing the HID report that HidP_InitializeReportForID initializes.

[in] ReportLength

Specifies the size, in bytes, of the HID report located at Report. ReportLength must be equal to the collection's report length for the specified report type, as specified by the XxxReportByteLength members of a collection's HIDP_CAPS structure.

Return value

HidP_InitializeReportForID returns one of the following status values:

Return code	Description
HIDP_STATUS_SUCCESS	The report was successfully initialized.
HIDP_STATUS_INVALID_PREPARSED_DATA	The preparsed data is not valid.
HIDP_STATUS_INVALID_REPORT_LENGTH	The specified length of the report is not equal to the collection's report length for the specified report type.
HIDP_STATUS_INVALID_REPORT_TYPE	The report type is not valid.
HIDP_STATUS_REPORT_DOES_NOT_EXIST	The specified report ID is not valid.

Remarks

Initializing a HID report sets all control data to zero or a control's null value, as defined by the USB HID standard. (Sending or receiving a null value indicates that the current value of a control should not be modified.)

HidP_InitializeReportForID does the following:

Sets to zero the bitfields of all buttons and values without null values.
Sets the bitfield of all controls with null values to their corresponding null value.

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