Fire v0.12.0 (signal11#398)

- add convenient macros to check HIDAPI version in runtime;
- mark in which version all recent HIAPI API functions where added;

Author: Youw

VERSION

@@ -1 +1 @@
-0.11.2
+0.12.0

hidapi/hidapi.h

@@ -48,18 +48,40 @@
 
 	@ingroup API
 */
-#define HID_API_VERSION_MINOR 11
+#define HID_API_VERSION_MINOR 12
 /** @brief Static/compile-time patch version of the library.
 
 	@ingroup API
 */
-#define HID_API_VERSION_PATCH 2
+#define HID_API_VERSION_PATCH 0
 
 /* Helper macros */
 #define HID_API_AS_STR_IMPL(x) #x
 #define HID_API_AS_STR(x) HID_API_AS_STR_IMPL(x)
 #define HID_API_TO_VERSION_STR(v1, v2, v3) HID_API_AS_STR(v1.v2.v3)
 
+/** @brief Coverts a version as Major/Minor/Patch into a number:
+	<8 bit major><16 bit minor><8 bit patch>.
+
+	This macro was added in version 0.12.0.
+
+	Convenient function to be used for compile-time checks, like:
+	#if HID_API_VERSION >= HID_API_MAKE_VERSION(0, 12, 0)
+
+	@ingroup API
+*/
+#define HID_API_MAKE_VERSION(mj, mn, p) (((mj) << 24) | ((mn) << 8) | (p))
+
+/** @brief Static/compile-time version of the library.
+
+	This macro was added in version 0.12.0.
+
+	@see @ref HID_API_MAKE_VERSION.
+
+	@ingroup API
+*/
+#define HID_API_VERSION HID_API_MAKE_VERSION(HID_API_VERSION_MAJOR, HID_API_VERSION_MINOR, HID_API_VERSION_PATCH)
+
 /** @brief Static/compile-time string version of the library.
 
 	@ingroup API
@@ -369,6 +391,8 @@ extern "C" {
 
 		/** @brief Get a input report from a HID device.
 
+			Since version 0.10.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 10, 0)
+
 			Set the first byte of @p data[] to the Report ID of the
 			report to be read. Make sure to allow space for this
 			extra byte in @p data[]. Upon return, the first byte will

hidtest/Makefile.am

@@ -18,3 +18,7 @@ hidtest_SOURCES = test.c
 hidtest_LDADD = $(top_builddir)/$(backend)/libhidapi.la
 
 endif
+
+if OS_DARWIN
+AM_CPPFLAGS += -I$(top_srcdir)/mac/
+endif

hidtest/test.c

@@ -28,6 +28,18 @@
 	#include <unistd.h>
 #endif
 
+// Fallback/example
+#ifndef HID_API_MAKE_VERSION
+#define HID_API_MAKE_VERSION(mj, mn, p) (((mj) << 24) | ((mn) << 8) | (p))
+#endif
+#ifndef HID_API_VERSION
+#define HID_API_VERSION HID_API_MAKE_VERSION(HID_API_VERSION_MAJOR, HID_API_VERSION_MINOR, HID_API_VERSION_PATCH)
+#endif
+
+#if defined(__APPLE__) && HID_API_VERSION >= HID_API_MAKE_VERSION(0, 12, 0)
+#include <hidapi_darwin.h>
+#endif
+
 int main(int argc, char* argv[])
 {
 	(void)argc;
@@ -43,7 +55,7 @@ int main(int argc, char* argv[])
 	struct hid_device_info *devs, *cur_dev;
 
 	printf("hidapi test/example tool. Compiled with hidapi version %s, runtime version %s.\n", HID_API_VERSION_STR, hid_version_str());
-	if (hid_version()->major == HID_API_VERSION_MAJOR && hid_version()->minor == HID_API_VERSION_MINOR && hid_version()->patch == HID_API_VERSION_PATCH) {
+	if (HID_API_VERSION == HID_API_MAKE_VERSION(hid_version()->major, hid_version()->minor, hid_version()->patch)) {
 		printf("Compile-time version matches runtime version of hidapi.\n\n");
 	}
 	else {
@@ -53,6 +65,12 @@ int main(int argc, char* argv[])
 	if (hid_init())
 		return -1;
 
+#if defined(__APPLE__) && HID_API_VERSION >= HID_API_MAKE_VERSION(0, 12, 0)
+	// To work properly needs to be called before hid_open/hid_open_path after hid_init.
+	// Best/recommended option - call it right after hid_init.
+	hid_darwin_set_open_exclusive(0);
+#endif
+
 	devs = hid_enumerate(0x0, 0x0);
 	cur_dev = devs;
 	while (cur_dev) {

libusb/hidapi_libusb.h

@@ -19,6 +19,8 @@
 
 /** @file
  * @defgroup API hidapi API
+
+ * Since version 0.11.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 11, 0).
  */
 
 #ifndef HIDAPI_LIBUSB_H__

mac/Makefile-manual

@@ -11,7 +11,7 @@ all: hidtest
 CC=gcc
 COBJS=hid.o ../hidtest/test.o
 OBJS=$(COBJS)
-CFLAGS+=-I../hidapi -Wall -g -c 
+CFLAGS+=-I../hidapi -I. -Wall -g -c
 LIBS=-framework IOKit -framework CoreFoundation -framework AppKit
 
 

mac/hidapi_darwin.h

@@ -19,6 +19,8 @@
 
 /** @file
  * @defgroup API hidapi API
+
+ * Since version 0.12.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 12, 0)
  */
 
 #ifndef HIDAPI_DARWIN_H__
@@ -34,6 +36,8 @@ extern "C" {
 
 		/** @brief Get the location ID for a HID device.
 
+			Since version 0.12.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 12, 0)
+
 			@ingroup API
 			@param dev A device handle returned from hid_open().
 			@param location_id The device's location ID on return.
@@ -49,6 +53,8 @@ extern "C" {
 			By default on Darwin platform all devices opened by HIDAPI with @ref hid_open or @ref hid_open_path
 			are opened in exclusive mode (see kIOHIDOptionsTypeSeizeDevice).
 
+			Since version 0.12.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 12, 0)
+
 			@ingroup API
 			@param open_exclusive When set to 0 - all further devices will be opened
 				in non-exclusive mode. Otherwise - all further devices will be opened
@@ -63,6 +69,8 @@ extern "C" {
 
 		/** @brief Getter for option set by @ref hid_darwin_set_open_exclusive.
 
+			Since version 0.12.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 12, 0)
+
 			@ingroup API
 			@return 1 if all further devices will be opened in exclusive mode.
 
@@ -73,6 +81,8 @@ extern "C" {
 
 		/** @brief Check how the device was opened.
 
+			Since version 0.12.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 12, 0)
+
 			@ingroup API
 			@param dev A device to get property from.
 

windows/hidapi_winapi.h

@@ -19,6 +19,8 @@
 
 /** @file
  * @defgroup API hidapi API
+ *
+ * Since version 0.12.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 12, 0)
  */
 
 #ifndef HIDAPI_WINAPI_H__
@@ -34,6 +36,8 @@ extern "C" {
 
 		/** @brief Get the container ID for a HID device.
 
+			Since version 0.12.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 12, 0)
+
 			This function returns the `DEVPKEY_Device_ContainerId` property of
 			the given device. This can be used to correlate different
 			interfaces/ports on the same hardware device.