5252
5353 @ingroup API
5454*/
55- #define HID_API_VERSION_MINOR 15
55+ #define HID_API_VERSION_MINOR 16
5656/** @brief Static/compile-time patch version of the library.
5757
5858 @ingroup API
@@ -144,6 +144,13 @@ extern "C" {
144144 Specifications:
145145 https://www.microsoft.com/download/details.aspx?id=103325 */
146146 HID_API_BUS_SPI = 0x04 ,
147+
148+ /** Virtual device
149+ E.g.: https://elixir.bootlin.com/linux/v4.0/source/include/uapi/linux/input.h#L955
150+
151+ Since version 0.16.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 16, 0)
152+ */
153+ HID_API_BUS_VIRTUAL = 0x05 ,
147154 } hid_bus_type ;
148155
149156 /** hidapi info structure */
@@ -341,9 +348,11 @@ extern "C" {
341348 @returns
342349 This function returns the actual number of bytes read and
343350 -1 on error.
344- Call hid_error (dev) to get the failure reason.
351+ Call hid_read_error (dev) to get the failure reason.
345352 If no packet was available to be read within
346353 the timeout period, this function returns 0.
354+
355+ @note This function doesn't change the buffer returned by the hid_error(dev).
347356 */
348357 int HID_API_EXPORT HID_API_CALL hid_read_timeout (hid_device * dev , unsigned char * data , size_t length , int milliseconds );
349358
@@ -363,12 +372,36 @@ extern "C" {
363372 @returns
364373 This function returns the actual number of bytes read and
365374 -1 on error.
366- Call hid_error (dev) to get the failure reason.
375+ Call hid_read_error (dev) to get the failure reason.
367376 If no packet was available to be read and
368377 the handle is in non-blocking mode, this function returns 0.
378+
379+ @note This function doesn't change the buffer returned by the hid_error(dev).
369380 */
370381 int HID_API_EXPORT HID_API_CALL hid_read (hid_device * dev , unsigned char * data , size_t length );
371382
383+ /** @brief Get a string describing the last error which occurred during hid_read/hid_read_timeout.
384+
385+ Since version 0.15.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 15, 0)
386+
387+ This function is intended for logging/debugging purposes.
388+
389+ This function guarantees to never return NULL for a valid @ref dev.
390+ If there was no error in the last call to hid_read/hid_read_error -
391+ the returned string clearly indicates that.
392+
393+ Strings returned from hid_read_error() must not be freed by the user,
394+ i.e. owned by HIDAPI library.
395+ Device-specific error string may remain allocated at most until hid_close() is called.
396+
397+ @ingroup API
398+ @param dev A device handle. Shall never be NULL.
399+
400+ @returns
401+ A string describing the hid_read/hid_read_timeout error (if any).
402+ */
403+ HID_API_EXPORT const wchar_t * HID_API_CALL hid_read_error (hid_device * dev );
404+
372405 /** @brief Set the device handle to be non-blocking.
373406
374407 In non-blocking mode calls to hid_read() will return
0 commit comments