Runtime descriptor parsing from hidapi

[JunzheFan]

Hi, can I use this library to parse the report descriptor acquired from this hidapi librabry for Headset device https://github.com/libusb/hidapi/pull/451/files#diff-37a51f8fe6a77e89ab9694a39cf4e6c665cbdc96203d35ead0f55a9c37e0fc25 , is there any documentation for this library. thanks

[benedekkupper]

Yes you can!

The parser class is a generic template for achieving any kind of HID report descriptor parsing. It provides the necessary encapsulation while leaving the specifics to its subclasses. So far - to my knowledge - this library has only been used for descriptor parsing at compile-time, helping the HID device FW implementation, so there is no prior work done that illustrates a full example of descriptor parsing at runtime. The exception being the get_application_usage_id() method, this is something you can already use, for the purpose of finding the HID headset device from the list of HID devices available to the system.

Another reference for your implementation is report_protocol_properties::parser class, which while intended for compile-time use, is still a good example of how to extract important information from the HID report descriptor. The key difference is that compile-time descriptor parsing cannot rely on dynamic memory allocation, while for runtime parsing that's the highly advised way to go.

If you provide more specific details on what information you want to gain out of the descriptor, I can guide you further.

[JunzheFan]

Hi, I want to parse the descriptor at run-time on desktop end to a readable format in c++ instad of raw bytes, for example like the javascript webhid object strucuture implemented by google https://wicg.github.io/webhid/#hidreportitem-dictionary, so that I clearly read and do some computation based on some fields

[benedekkupper]

For that the best starting point is here:

hid-rp/hid-rp/hid/report_protocol.hpp

Lines 180 to 234 in dc2c953

	constexpr control parse_report_data_field(
	const item_type& main_item, const rdf::global_item_store& global_state,
	[[maybe_unused]] const items_view_type& main_section, unsigned tlc_count) override
	{
	using namespace hid::rdf;
	report::type rtype = main::tag_to_report_type(main_item.main_tag());
	// get report ID (or use 0 if not present)
	report::id::type report_id = 0;
	const auto* report_id_item = global_state.get_item(global::tag::REPORT_ID);
	if (report_id_item != nullptr)
	{
	report_id = report_id_item->value_unsigned();
	// report ID verification
	HID_RDF_ASSERT(report_id >= report::id::min(), ex_report_id_zero);
	HID_RDF_ASSERT(report_id <= report::id::max(), ex_report_id_excess);
	if (!uses_report_ids())
	{
	for (auto& sizes : report_bit_sizes_)
	{
	HID_RDF_ASSERT(sizes[0] == 0, ex_report_id_missing);
	}
	}
	auto& rid = max_report_ids_[static_cast<size_t>(rtype) - 1];
	rid = std::max(rid, report_id);
	}
	// get the items defining the size of this/these report data elements
	const auto* report_size_item = global_state.get_item(global::tag::REPORT_SIZE);
	HID_RDF_ASSERT(report_size_item != nullptr, ex_report_size_missing);
	auto report_size = report_size_item->value_unsigned();
	HID_RDF_ASSERT(report_size > 0, ex_report_size_zero);
	const auto* report_count_item = global_state.get_item(global::tag::REPORT_COUNT);
	HID_RDF_ASSERT(report_count_item != nullptr, ex_report_count_missing);
	auto report_count = report_count_item->value_unsigned();
	HID_RDF_ASSERT(report_count > 0, ex_report_count_zero);
	// increase size of this report
	bit_size(rtype, report_id) += report_size * report_count;
	// verify that the report doesn't cross TLC boundary
	auto& report_tlc_index = tlc_index(rtype, report_id);
	if (report_tlc_index == 0)
	{
	// first piece of the report, assign to TLC now
	report_tlc_index = tlc_count;
	}
	else
	{
	HID_RDF_ASSERT(report_tlc_index == tlc_count, ex_report_crossing_tlc_bounds);
	}
	return control::CONTINUE;
	}

You need to replace the internal logic to push a new item to a vector of HID report items, filled with the information you get out of the passed parameters. The vector is a member variable of your custom parser, that's how it can be accessed reasonably in this virtual function. You get the boolean values out of the main_item parameter, the usages are collected by iterating through the main_section (see also the aforementioned get_application_usage_id), the rest are acquired from global_state.