RFC: Hotplug implementation

hidapi/hidapi.h

@@ -261,6 +261,112 @@ extern "C" {
 		*/
 		void  HID_API_EXPORT HID_API_CALL hid_free_enumeration(struct hid_device_info *devs);
 
+		/** @brief Callback handle.
+
+			Callbacks handles are generated by hid_hotplug_register_callback()
+			and can be used to deregister callbacks. Callback handles are unique
+			and it is safe to call hid_hotplug_deregister_callback() on
+			an already deregistered callback.
+
+			@ingroup API
+		 */
+		typedef int hid_hotplug_callback_handle;
+
+		/**
+			Hotplug events
+
+			@ingroup API
+		*/
+		typedef enum {
+			/** A device has been plugged in and is ready to use */
+			HID_API_HOTPLUG_EVENT_DEVICE_ARRIVED = (1 << 0),
+
+			/** A device has left and is no longer available.
+				It is the user's responsibility to call hid_close with a disconnected device.
+			*/
+			HID_API_HOTPLUG_EVENT_DEVICE_LEFT = (1 << 1)
+		} hid_hotplug_event;
+
+		/**
+			Hotplug flags
+
+			@ingroup API
+		*/
+		typedef enum {
+			/** Arm the callback and fire it for all matching currently attached devices. */
+			HID_API_HOTPLUG_ENUMERATE = (1 << 0)
+		} hid_hotplug_flag;
+
+		/** @brief Hotplug callback function type. When requesting hotplug event notifications,
+			you pass a pointer to a callback function of this type.
+
+			This callback may be called by an internal event thread and as such it is
+			recommended the callback do minimal processing before returning.
+
+			hidapi will call this function later, when a matching event had happened on
+			a matching device.
+
+			Note that when callbacks are called from hid_hotplug_register_callback()
+			because of the \ref HID_API_HOTPLUG_ENUMERATE flag, the callback return
+			value is ignored. In other words, you cannot cause a callback to be
+			deregistered by returning 1 when it is called from hid_hotplug_register_callback().
+
+			@ingroup API
+
+			@param callback_handle The hid_hotplug_callback_handle callback handle.
+			@param device The hid_device_info of device this event occurred on event that occurred.
+			@param event Event that occurred.
+			@param user_data User data provided when this callback was registered.
+				(Optionally NULL).
+
+			@returns bool
+				Whether this callback is finished processing events.
+				Returning non-zero value will cause this callback to be deregistered.
+		 */
+		typedef int (HID_API_CALL *hid_hotplug_callback_fn)(
+			hid_hotplug_callback_handle callback_handle,
+			struct hid_device_info *device,
+			hid_hotplug_event event,
+			void *user_data);
+
+		/** @brief Register a HID hotplug callback function.
+
+			If @p vendor_id is set to 0 then any vendor matches.
+			If @p product_id is set to 0 then any product matches.
+			If @p vendor_id and @p product_id are both set to 0, then all HID devices will be notified.
+
+			@ingroup API
+
+			@param vendor_id The Vendor ID (VID) of the types of device to notify about.
+			@param product_id The Product ID (PID) of the types of device to notify about.
+			@param events Bitwise or of hotplug events that will trigger this callback.
+				See \ref hid_hotplug_event.
+			@param flags Bitwise or of hotplug flags that affect registration.
+				See \ref hid_hotplug_flag.
+			@param callback The callback function that will be called on device connection/disconnection.
+				See \ref hid_hotplug_callback_fn.
+			@param user_data The user data you wanted to provide to your callback function.
+			@param callback_handle Pointer to store the handle of the allocated callback
+				(Optionally NULL).
+
+			@returns
+				This function returns 0 on success or -1 on error.
+		*/
+		int HID_API_EXPORT HID_API_CALL hid_hotplug_register_callback(unsigned short vendor_id, unsigned short product_id, int events, int flags, hid_hotplug_callback_fn callback, void *user_data, hid_hotplug_callback_handle *callback_handle);
+
+		/** @brief Deregister a callback from a HID hotplug.
+
+			This function is safe to call from within a hotplug callback.
+
+			@ingroup API
+
+			@param callback_handle	The handle of the callback to deregister.
+
+			@returns
+				This function returns 0 on success or -1 on error.
+		*/
+		int HID_API_EXPORT HID_API_CALL hid_hotplug_deregister_callback(hid_hotplug_callback_handle callback_handle);
+
 		/** @brief Open a HID device using a Vendor ID (VID), Product ID
 			(PID) and optionally a serial number.