@@ -254,6 +254,112 @@ extern "C" {
254254 */
255255 void HID_API_EXPORT HID_API_CALL hid_free_enumeration (struct hid_device_info * devs );
256256
257+ /** @brief Callback handle.
258+
259+ Callbacks handles are generated by hid_hotplug_register_callback()
260+ and can be used to deregister callbacks. Callback handles are unique
261+ and it is safe to call hid_hotplug_deregister_callback() on
262+ an already deregistered callback.
263+
264+ @ingroup API
265+ */
266+ typedef int hid_hotplug_callback_handle ;
267+
268+ /**
269+ Hotplug events
270+
271+ @ingroup API
272+ */
273+ typedef enum {
274+ /** A device has been plugged in and is ready to use */
275+ HID_API_HOTPLUG_EVENT_DEVICE_ARRIVED = (1 << 0 ),
276+
277+ /** A device has left and is no longer available.
278+ It is the user's responsibility to call hid_close with a disconnected device.
279+ */
280+ HID_API_HOTPLUG_EVENT_DEVICE_LEFT = (1 << 1 )
281+ } hid_hotplug_event ;
282+
283+ /**
284+ Hotplug flags
285+
286+ @ingroup API
287+ */
288+ typedef enum {
289+ /** Arm the callback and fire it for all matching currently attached devices. */
290+ HID_API_HOTPLUG_ENUMERATE = (1 << 0 )
291+ } hid_hotplug_flag ;
292+
293+ /** @brief Hotplug callback function type. When requesting hotplug event notifications,
294+ you pass a pointer to a callback function of this type.
295+
296+ This callback may be called by an internal event thread and as such it is
297+ recommended the callback do minimal processing before returning.
298+
299+ hidapi will call this function later, when a matching event had happened on
300+ a matching device.
301+
302+ Note that when callbacks are called from hid_hotplug_register_callback()
303+ because of the \ref HID_API_HOTPLUG_ENUMERATE flag, the callback return
304+ value is ignored. In other words, you cannot cause a callback to be
305+ deregistered by returning 1 when it is called from hid_hotplug_register_callback().
306+
307+ @ingroup API
308+
309+ @param callback_handle The hid_hotplug_callback_handle callback handle.
310+ @param device The hid_device_info of device this event occurred on event that occurred.
311+ @param event Event that occurred.
312+ @param user_data User data provided when this callback was registered.
313+ (Optionally NULL).
314+
315+ @returns bool
316+ Whether this callback is finished processing events.
317+ Returning non-zero value will cause this callback to be deregistered.
318+ */
319+ typedef int (HID_API_CALL * hid_hotplug_callback_fn )(
320+ hid_hotplug_callback_handle callback_handle ,
321+ struct hid_device_info * device ,
322+ hid_hotplug_event event ,
323+ void * user_data );
324+
325+ /** @brief Register a HID hotplug callback function.
326+
327+ If @p vendor_id is set to 0 then any vendor matches.
328+ If @p product_id is set to 0 then any product matches.
329+ If @p vendor_id and @p product_id are both set to 0, then all HID devices will be notified.
330+
331+ @ingroup API
332+
333+ @param vendor_id The Vendor ID (VID) of the types of device to notify about.
334+ @param product_id The Product ID (PID) of the types of device to notify about.
335+ @param events Bitwise or of hotplug events that will trigger this callback.
336+ See \ref hid_hotplug_event.
337+ @param flags Bitwise or of hotplug flags that affect registration.
338+ See \ref hid_hotplug_flag.
339+ @param callback The callback function that will be called on device connection/disconnection.
340+ See \ref hid_hotplug_callback_fn.
341+ @param user_data The user data you wanted to provide to your callback function.
342+ @param callback_handle Pointer to store the handle of the allocated callback
343+ (Optionally NULL).
344+
345+ @returns
346+ This function returns 0 on success or -1 on error.
347+ */
348+ 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 );
349+
350+ /** @brief Deregister a callback from a HID hotplug.
351+
352+ This function is safe to call from within a hotplug callback.
353+
354+ @ingroup API
355+
356+ @param callback_handle The handle of the callback to deregister.
357+
358+ @returns
359+ This function returns 0 on success or -1 on error.
360+ */
361+ int HID_API_EXPORT HID_API_CALL hid_hotplug_deregister_callback (hid_hotplug_callback_handle callback_handle );
362+
257363 /** @brief Open a HID device using a Vendor ID (VID), Product ID
258364 (PID) and optionally a serial number.
259365
0 commit comments