RFC: add hid_get_report_descriptor API function

[Youw]

• Add ASAN checks for utest/MSVC build;

Resolves: #249

[DJm00n]

Hey @Youw! Nice PR!
Can you please give some information about limitations of this approach?

I wanted to test it with a bunch of game controllers that I have and prepare tests for them. How to generate those *_expected.rpt_desc files?

[Youw]

The main discussion is under #249.
And @JoergAtGithub did most of the job. I believe he has a tool to generate rpt files in one of his branches.

[JoergAtGithub]

@DJm00n I just opened PR #467 for the pp_data_dump.exe tool, that others can find it.

There are basically 3 restrictions with this approach:

1. It depends on the undocumented preparsed data struct (if Microsoft once decide to change the declaration of this struct, it would stop working - we tested it on Win7, Win10 and Win11 and between these versions, there are no changes)
2. The reconstructed descriptor is logical identical to the orginal, but not byte-wise
   for example

0x75, 0x08,        //   Report Size (8)
0x95, 0x06,        //   Report Count (6)
0x81, 0x00,        //   Input (Data,Array,Abs,No Wrap,Linear,Preferred State,No Null Position)
0x75, 0x08,        //   Report Size (8)
0x95, 0x06,        //   Report Count (6)
0x81, 0x00,        //   Input (Data,Array,Abs,No Wrap,Linear,Preferred State,No Null Position)

is logically the same as:

0x75, 0x08,        //   Report Size (8)
0x95, 0x06,        //   Report Count (6)
0x81, 0x00,        //   Input (Data,Array,Abs,No Wrap,Linear,Preferred State,No Null Position)
0x81, 0x00,        //   Input (Data,Array,Abs,No Wrap,Linear,Preferred State,No Null Position)

because the preparsed data contain only the logical relevant information, we can only assume, how it looked byte-wise

3. The preparsed data do not contain information about the padding bits, which:

• fill the gaps between the used bits (the number of these constant bits is determined, but not the type - but it doesn't matter logically)
• are appended at the end of the report. The HID test spec says only, that you shoul fill the remaining bits of the last byte with constant bit padding. But it doesn't prohibit to add more constant bytes at the end - the reconstrctor can only assume, that there are no unused constant bytes add the end of a report.

--
But there are also some specified syntax cases (#343 (comment)), which I implemented, but couldn't test, due to lack on real-world devices.
BTW: https://github.com/abend0c1/hidrdd/tree/master/examples contains all report descriptor examples published by the HID group in encoded form. If someone could program these into an HID device and than run pp_data_dump.exe, we would have several edge cases covered in the test case.

[mcuee]

Just FYI of others that #343 and #467 have been integrated in the following feature branch.
https://github.com/libusb/hidapi/tree/get-descriptor

More test results here:

• Need API to get the HID Report Descriptor or a similar data structure #249

[Youw]

It has been a long way to get at this point.
Thanks everyone.

I'll keep this PR for a couple of days. If no objections/issues found - I'll merge it to master after that.

[mcuee]

@Youw

This is a major improvement for HIDAPI. Just wondering if you want to start the process to release version 0.14. Thanks.

[Youw]

Release - not right now.
Bump a version - right away.