5252
5353 @ingroup API
5454*/
55- #define HID_API_VERSION_MINOR 14
55+ #define HID_API_VERSION_MINOR 15
5656/** @brief Static/compile-time patch version of the library.
5757
5858 @ingroup API
@@ -413,9 +413,9 @@ extern "C" {
413413 single report), followed by the report data (16 bytes). In
414414 this example, the length passed in would be 17.
415415
416- hid_write() will send the data on the first OUT endpoint, if
417- one exists. If it does not, it will send the data through
418- the Control Endpoint (Endpoint 0).
416+ hid_write() will send the data on the first interrupt OUT
417+ endpoint, if one exists. If it does not the behaviour is as
418+ @ref hid_send_output_report
419419
420420 @ingroup API
421421 @param dev A device handle returned from hid_open().
@@ -447,9 +447,11 @@ extern "C" {
447447 @returns
448448 This function returns the actual number of bytes read and
449449 -1 on error.
450- Call hid_error (dev) to get the failure reason.
450+ Call hid_read_error (dev) to get the failure reason.
451451 If no packet was available to be read within
452452 the timeout period, this function returns 0.
453+
454+ @note This function doesn't change the buffer returned by the hid_error(dev).
453455 */
454456 int HID_API_EXPORT HID_API_CALL hid_read_timeout (hid_device * dev , unsigned char * data , size_t length , int milliseconds );
455457
@@ -469,12 +471,36 @@ extern "C" {
469471 @returns
470472 This function returns the actual number of bytes read and
471473 -1 on error.
472- Call hid_error (dev) to get the failure reason.
474+ Call hid_read_error (dev) to get the failure reason.
473475 If no packet was available to be read and
474476 the handle is in non-blocking mode, this function returns 0.
477+
478+ @note This function doesn't change the buffer returned by the hid_error(dev).
475479 */
476480 int HID_API_EXPORT HID_API_CALL hid_read (hid_device * dev , unsigned char * data , size_t length );
477481
482+ /** @brief Get a string describing the last error which occurred during hid_read/hid_read_timeout.
483+
484+ Since version 0.15.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 15, 0)
485+
486+ This function is intended for logging/debugging purposes.
487+
488+ This function guarantees to never return NULL for a valid @ref dev.
489+ If there was no error in the last call to hid_read/hid_read_error -
490+ the returned string clearly indicates that.
491+
492+ Strings returned from hid_read_error() must not be freed by the user,
493+ i.e. owned by HIDAPI library.
494+ Device-specific error string may remain allocated at most until hid_close() is called.
495+
496+ @ingroup API
497+ @param dev A device handle. Shall never be NULL.
498+
499+ @returns
500+ A string describing the hid_read/hid_read_timeout error (if any).
501+ */
502+ HID_API_EXPORT const wchar_t * HID_API_CALL hid_read_error (hid_device * dev );
503+
478504 /** @brief Set the device handle to be non-blocking.
479505
480506 In non-blocking mode calls to hid_read() will return
@@ -551,6 +577,40 @@ extern "C" {
551577 */
552578 int HID_API_EXPORT HID_API_CALL hid_get_feature_report (hid_device * dev , unsigned char * data , size_t length );
553579
580+ /** @brief Send a Output report to the device.
581+
582+ Since version 0.15.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 15, 0)
583+
584+ Output reports are sent over the Control endpoint as a
585+ Set_Report transfer. The first byte of @p data[] must
586+ contain the Report ID. For devices which only support a
587+ single report, this must be set to 0x0. The remaining bytes
588+ contain the report data. Since the Report ID is mandatory,
589+ calls to hid_send_output_report() will always contain one
590+ more byte than the report contains. For example, if a hid
591+ report is 16 bytes long, 17 bytes must be passed to
592+ hid_send_output_report(): the Report ID (or 0x0, for
593+ devices which do not use numbered reports), followed by the
594+ report data (16 bytes). In this example, the length passed
595+ in would be 17.
596+
597+ This function sets the return value of hid_error().
598+
599+ @ingroup API
600+ @param dev A device handle returned from hid_open().
601+ @param data The data to send, including the report number as
602+ the first byte.
603+ @param length The length in bytes of the data to send, including
604+ the report number.
605+
606+ @returns
607+ This function returns the actual number of bytes written and
608+ -1 on error.
609+
610+ @see @ref hid_write
611+ */
612+ int HID_API_EXPORT HID_API_CALL hid_send_output_report (hid_device * dev , const unsigned char * data , size_t length );
613+
554614 /** @brief Get a input report from a HID device.
555615
556616 Since version 0.10.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 10, 0)
0 commit comments