libusb/hotplug.c - third_party/libusb - Git at Google

 /* -*- Mode: C; indent-tabs-mode:t ; c-basic-offset:8 -*- */
 /*
  * Hotplug functions for libusb
  * Copyright © 2012-2021 Nathan Hjelm <hjelmn@mac.com>
  * Copyright © 2012-2013 Peter Stuge <peter@stuge.se>
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
  * License as published by the Free Software Foundation; either
  * version 2.1 of the License, or (at your option) any later version.
  *
  * This library is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General Public
  * License along with this library; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  */

 #include "libusbi.h"

 /**
  * @defgroup libusb_hotplug Device hotplug event notification
  * This page details how to use the libusb hotplug interface, where available.
  *
  * Be mindful that not all platforms currently implement hotplug notification and
  * that you should first call on \ref libusb_has_capability() with parameter
  * \ref LIBUSB_CAP_HAS_HOTPLUG to confirm that hotplug support is available.
  *
  * \page libusb_hotplug Device hotplug event notification
  *
  * \section hotplug_intro Introduction
  *
  * Version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102, has added support
  * for hotplug events on <b>some</b> platforms (you should test if your platform
  * supports hotplug notification by calling \ref libusb_has_capability() with
  * parameter \ref LIBUSB_CAP_HAS_HOTPLUG).
  *
  * This interface allows you to request notification for the arrival and departure
  * of matching USB devices.
  *
  * To receive hotplug notification you register a callback by calling
  * \ref libusb_hotplug_register_callback(). This function will optionally return
  * a callback handle that can be passed to \ref libusb_hotplug_deregister_callback().
  *
  * A callback function must return an int (0 or 1) indicating whether the callback is
  * expecting additional events. Returning 0 will rearm the callback and 1 will cause
  * the callback to be deregistered. Note that when callbacks are called from
  * libusb_hotplug_register_callback() because of the \ref LIBUSB_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
  * libusb_hotplug_register_callback().
  *
  * Callbacks for a particular context are automatically deregistered by libusb_exit().
  *
  * As of 1.0.16 there are two supported hotplug events:
  *  - LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED: A device has arrived and is ready to use
  *  - LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT: A device has left and is no longer available
  *
  * A hotplug event can listen for either or both of these events.
  *
  * Note: If you receive notification that a device has left and you have any
  * a libusb_device_handles for the device it is up to you to call libusb_close()
  * on each device handle to free up any remaining resources associated with the device.
  * Once a device has left any libusb_device_handle associated with the device
  * are invalid and will remain so even if the device comes back.
  *
  * When handling a LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED event it is considered
  * safe to call any libusb function that takes a libusb_device. It also safe to
  * open a device and submit asynchronous transfers. However, most other functions
  * that take a libusb_device_handle are <b>not</b> safe to call. Examples of such
  * functions are any of the \ref libusb_syncio "synchronous API" functions or the blocking
  * functions that retrieve various \ref libusb_desc "USB descriptors". These functions must
  * be used outside of the context of the hotplug callback.
  *
  * When handling a LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT event the only safe function
  * is libusb_get_device_descriptor().
  *
  * The following code provides an example of the usage of the hotplug interface:
 \code
 #include <stdio.h>
 #include <stdlib.h>
 #include <time.h>
 #include <libusb.h>

 static int count = 0;

 int hotplug_callback(struct libusb_context *ctx, struct libusb_device *dev,
                      libusb_hotplug_event event, void *user_data) {
   static libusb_device_handle *dev_handle = NULL;
   struct libusb_device_descriptor desc;
   int rc;

   (void)libusb_get_device_descriptor(dev, &desc);

   if (LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED == event) {
     rc = libusb_open(dev, &dev_handle);
     if (LIBUSB_SUCCESS != rc) {
       printf("Could not open USB device\n");
     }
   } else if (LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT == event) {
     if (dev_handle) {
       libusb_close(dev_handle);
       dev_handle = NULL;
     }
   } else {
     printf("Unhandled event %d\n", event);
   }
   count++;

   return 0;
 }

 int main (void) {
   libusb_hotplug_callback_handle callback_handle;
   int rc;

   libusb_init(NULL);

   rc = libusb_hotplug_register_callback(NULL, LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED |
                                         LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT, 0, 0x045a, 0x5005,
                                         LIBUSB_HOTPLUG_MATCH_ANY, hotplug_callback, NULL,
                                         &callback_handle);
   if (LIBUSB_SUCCESS != rc) {
     printf("Error creating a hotplug callback\n");
     libusb_exit(NULL);
     return EXIT_FAILURE;
   }

   while (count < 2) {
     libusb_handle_events_completed(NULL, NULL);
     nanosleep(&(struct timespec){0, 10000000UL}, NULL);
   }

   libusb_hotplug_deregister_callback(NULL, callback_handle);
   libusb_exit(NULL);

   return 0;
 }
 \endcode
  */

 #define VALID_HOTPLUG_EVENTS			\
 	(LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED |	\
 	 LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT)

 #define VALID_HOTPLUG_FLAGS			\
 	(LIBUSB_HOTPLUG_ENUMERATE)

 void usbi_hotplug_init(struct libusb_context *ctx)
 {
 	/* check for hotplug support */
 	if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
 		return;

 	usbi_mutex_init(&ctx->hotplug_cbs_lock);
 	list_init(&ctx->hotplug_cbs);
 	ctx->next_hotplug_cb_handle = 1;
 	usbi_atomic_store(&ctx->hotplug_ready, 1);
 }

 void usbi_hotplug_exit(struct libusb_context *ctx)
 {
 	struct usbi_hotplug_callback *hotplug_cb, *next_cb;
 	struct usbi_hotplug_message *msg;
 	struct libusb_device *dev, *next_dev;

 	/* check for hotplug support */
 	if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
 		return;

 	/* free all registered hotplug callbacks */
 	for_each_hotplug_cb_safe(ctx, hotplug_cb, next_cb) {
 		list_del(&hotplug_cb->list);
 		free(hotplug_cb);
 	}

 	/* free all pending hotplug messages */
 	while (!list_empty(&ctx->hotplug_msgs)) {
 		msg = list_first_entry(&ctx->hotplug_msgs, struct usbi_hotplug_message, list);

 		/* if the device left, the message holds a reference
 		 * and we must drop it */
 		if (msg->event == LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT)
 			libusb_unref_device(msg->device);

 		list_del(&msg->list);
 		free(msg);
 	}

 	/* free all discovered devices. due to parent references loop until no devices are freed. */
 	for_each_device_safe(ctx, dev, next_dev) {
 		/* remove the device from the usb_devs list only if there are no
 		 * references held, otherwise leave it on the list so that a
 		 * warning message will be shown */
 		if (usbi_atomic_load(&dev->refcnt) == 1) {
 			list_del(&dev->list);
 		}
 		if (dev->parent_dev && usbi_atomic_load(&dev->parent_dev->refcnt) == 1) {
 			/* the parent was before this device in the list and will be released.
 			   remove it from the list. this is safe as parent_dev can not be
 			   equal to next_dev. */
 			assert (dev->parent_dev != next_dev);
 			list_del(&dev->parent_dev->list);
 		}
 		libusb_unref_device(dev);
 	}

 	usbi_mutex_destroy(&ctx->hotplug_cbs_lock);
 }

 static int usbi_hotplug_match_cb(struct libusb_device *dev,
 	libusb_hotplug_event event, struct usbi_hotplug_callback *hotplug_cb)
 {
 	if (!(hotplug_cb->flags & event)) {
 		return 0;
 	}

 	if ((hotplug_cb->flags & USBI_HOTPLUG_VENDOR_ID_VALID) &&
 	    hotplug_cb->vendor_id != dev->device_descriptor.idVendor) {
 		return 0;
 	}

 	if ((hotplug_cb->flags & USBI_HOTPLUG_PRODUCT_ID_VALID) &&
 	    hotplug_cb->product_id != dev->device_descriptor.idProduct) {
 		return 0;
 	}

 	if ((hotplug_cb->flags & USBI_HOTPLUG_DEV_CLASS_VALID) &&
 	    hotplug_cb->dev_class != dev->device_descriptor.bDeviceClass) {
 		return 0;
 	}

 	return hotplug_cb->cb(DEVICE_CTX(dev), dev, event, hotplug_cb->user_data);
 }

 void usbi_hotplug_notification(struct libusb_context *ctx, struct libusb_device *dev,
 	libusb_hotplug_event event)
 {
 	struct usbi_hotplug_message *msg;
 	unsigned int event_flags;

 	/* Only generate a notification if hotplug is ready. This prevents hotplug
 	 * notifications from being generated during initial enumeration or if the
 	 * backend does not support hotplug. */
 	if (!usbi_atomic_load(&ctx->hotplug_ready))
 		return;

 	msg = calloc(1, sizeof(*msg));
 	if (!msg) {
 		usbi_err(ctx, "error allocating hotplug message");
 		return;
 	}

 	msg->event = event;
 	msg->device = dev;

 	/* Take the event data lock and add this message to the list.
 	 * Only signal an event if there are no prior pending events. */
 	usbi_mutex_lock(&ctx->event_data_lock);
 	event_flags = ctx->event_flags;
 	ctx->event_flags |= USBI_EVENT_HOTPLUG_MSG_PENDING;
 	list_add_tail(&msg->list, &ctx->hotplug_msgs);
 	if (!event_flags)
 		usbi_signal_event(&ctx->event);
 	usbi_mutex_unlock(&ctx->event_data_lock);
 }

 void usbi_hotplug_process(struct libusb_context *ctx, struct list_head *hotplug_msgs)
 {
 	struct usbi_hotplug_callback *hotplug_cb, *next_cb;
 	struct usbi_hotplug_message *msg;
 	int r;

 	usbi_mutex_lock(&ctx->hotplug_cbs_lock);

 	/* dispatch all pending hotplug messages */
 	while (!list_empty(hotplug_msgs)) {
 		msg = list_first_entry(hotplug_msgs, struct usbi_hotplug_message, list);

 		for_each_hotplug_cb_safe(ctx, hotplug_cb, next_cb) {
 			/* skip callbacks that have unregistered */
 			if (hotplug_cb->flags & USBI_HOTPLUG_NEEDS_FREE)
 				continue;

 			usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 			r = usbi_hotplug_match_cb(msg->device, msg->event, hotplug_cb);
 			usbi_mutex_lock(&ctx->hotplug_cbs_lock);

 			if (r) {
 				list_del(&hotplug_cb->list);
 				free(hotplug_cb);
 			}
 		}

 		/* if the device left, the message holds a reference
 		 * and we must drop it */
 		if (msg->event == LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT)
 			libusb_unref_device(msg->device);

 		list_del(&msg->list);
 		free(msg);
 	}

 	/* free any callbacks that have unregistered */
 	for_each_hotplug_cb_safe(ctx, hotplug_cb, next_cb) {
 		if (hotplug_cb->flags & USBI_HOTPLUG_NEEDS_FREE) {
 			usbi_dbg(ctx, "freeing hotplug cb %p with handle %d",
 				hotplug_cb, hotplug_cb->handle);
 			list_del(&hotplug_cb->list);
 			free(hotplug_cb);
 		}
 	}

 	usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 }

 int API_EXPORTED libusb_hotplug_register_callback(libusb_context *ctx,
 	int events, int flags,
 	int vendor_id, int product_id, int dev_class,
 	libusb_hotplug_callback_fn cb_fn, void *user_data,
 	libusb_hotplug_callback_handle *callback_handle)
 {
 	struct usbi_hotplug_callback *hotplug_cb;

 	/* check for sane values */
 	if (!events || (~VALID_HOTPLUG_EVENTS & events) ||
 	    (~VALID_HOTPLUG_FLAGS & flags) ||
 	    (LIBUSB_HOTPLUG_MATCH_ANY != vendor_id && (~0xffff & vendor_id)) ||
 	    (LIBUSB_HOTPLUG_MATCH_ANY != product_id && (~0xffff & product_id)) ||
 	    (LIBUSB_HOTPLUG_MATCH_ANY != dev_class && (~0xff & dev_class)) ||
 	    !cb_fn) {
 		return LIBUSB_ERROR_INVALID_PARAM;
 	}

 	/* check for hotplug support */
 	if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
 		return LIBUSB_ERROR_NOT_SUPPORTED;

 	ctx = usbi_get_context(ctx);

 	hotplug_cb = calloc(1, sizeof(*hotplug_cb));
 	if (!hotplug_cb)
 		return LIBUSB_ERROR_NO_MEM;

 	hotplug_cb->flags = (uint8_t)events;
 	if (LIBUSB_HOTPLUG_MATCH_ANY != vendor_id) {
 		hotplug_cb->flags |= USBI_HOTPLUG_VENDOR_ID_VALID;
 		hotplug_cb->vendor_id = (uint16_t)vendor_id;
 	}
 	if (LIBUSB_HOTPLUG_MATCH_ANY != product_id) {
 		hotplug_cb->flags |= USBI_HOTPLUG_PRODUCT_ID_VALID;
 		hotplug_cb->product_id = (uint16_t)product_id;
 	}
 	if (LIBUSB_HOTPLUG_MATCH_ANY != dev_class) {
 		hotplug_cb->flags |= USBI_HOTPLUG_DEV_CLASS_VALID;
 		hotplug_cb->dev_class = (uint8_t)dev_class;
 	}
 	hotplug_cb->cb = cb_fn;
 	hotplug_cb->user_data = user_data;

 	usbi_mutex_lock(&ctx->hotplug_cbs_lock);

 	/* protect the handle by the context hotplug lock */
 	hotplug_cb->handle = ctx->next_hotplug_cb_handle++;

 	/* handle the unlikely case of overflow */
 	if (ctx->next_hotplug_cb_handle < 0)
 		ctx->next_hotplug_cb_handle = 1;

 	list_add(&hotplug_cb->list, &ctx->hotplug_cbs);

 	usbi_mutex_unlock(&ctx->hotplug_cbs_lock);

 	usbi_dbg(ctx, "new hotplug cb %p with handle %d", hotplug_cb, hotplug_cb->handle);

 	if ((flags & LIBUSB_HOTPLUG_ENUMERATE) && (events & LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED)) {
 		ssize_t i, len;
 		struct libusb_device **devs;

 		len = libusb_get_device_list(ctx, &devs);
 		if (len < 0) {
 			libusb_hotplug_deregister_callback(ctx, hotplug_cb->handle);
 			return (int)len;
 		}

 		for (i = 0; i < len; i++) {
 			usbi_hotplug_match_cb(devs[i],
 					LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED,
 					hotplug_cb);
 		}

 		libusb_free_device_list(devs, 1);
 	}

 	if (callback_handle)
 		*callback_handle = hotplug_cb->handle;

 	return LIBUSB_SUCCESS;
 }

 void API_EXPORTED libusb_hotplug_deregister_callback(libusb_context *ctx,
 	libusb_hotplug_callback_handle callback_handle)
 {
 	struct usbi_hotplug_callback *hotplug_cb;
 	int deregistered = 0;

 	/* check for hotplug support */
 	if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
 		return;

 	usbi_dbg(ctx, "deregister hotplug cb %d", callback_handle);

 	ctx = usbi_get_context(ctx);

 	usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 	for_each_hotplug_cb(ctx, hotplug_cb) {
 		if (callback_handle == hotplug_cb->handle) {
 			/* mark this callback for deregistration */
 			hotplug_cb->flags |= USBI_HOTPLUG_NEEDS_FREE;
 			deregistered = 1;
 			break;
 		}
 	}
 	usbi_mutex_unlock(&ctx->hotplug_cbs_lock);

 	if (deregistered) {
 		unsigned int event_flags;

 		usbi_mutex_lock(&ctx->event_data_lock);
 		event_flags = ctx->event_flags;
 		ctx->event_flags |= USBI_EVENT_HOTPLUG_CB_DEREGISTERED;
 		if (!event_flags)
 			usbi_signal_event(&ctx->event);
 		usbi_mutex_unlock(&ctx->event_data_lock);
 	}
 }

 DEFAULT_VISIBILITY
 void * LIBUSB_CALL libusb_hotplug_get_user_data(libusb_context *ctx,
 	libusb_hotplug_callback_handle callback_handle)
 {
 	struct usbi_hotplug_callback *hotplug_cb;
 	void *user_data = NULL;

 	/* check for hotplug support */
 	if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
 		return NULL;

 	usbi_dbg(ctx, "get hotplug cb %d user data", callback_handle);

 	ctx = usbi_get_context(ctx);

 	usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 	for_each_hotplug_cb(ctx, hotplug_cb) {
 		if (callback_handle == hotplug_cb->handle) {
 			user_data = hotplug_cb->user_data;
 			break;
 		}
 	}
 	usbi_mutex_unlock(&ctx->hotplug_cbs_lock);

 	return user_data;
 }
	/* -- Mode: C; indent-tabs-mode:t ; c-basic-offset:8 -- */
	/*
	* Hotplug functions for libusb
	* Copyright © 2012-2021 Nathan Hjelm <hjelmn@mac.com>
	* Copyright © 2012-2013 Peter Stuge <peter@stuge.se>
	*
	* This library is free software; you can redistribute it and/or
	* modify it under the terms of the GNU Lesser General Public
	* License as published by the Free Software Foundation; either
	* version 2.1 of the License, or (at your option) any later version.
	*
	* This library is distributed in the hope that it will be useful,
	* but WITHOUT ANY WARRANTY; without even the implied warranty of
	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	* Lesser General Public License for more details.
	*
	* You should have received a copy of the GNU Lesser General Public
	* License along with this library; if not, write to the Free Software
	* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
	*/

	#include "libusbi.h"

	/**
	* @defgroup libusb_hotplug Device hotplug event notification
	* This page details how to use the libusb hotplug interface, where available.
	*
	* Be mindful that not all platforms currently implement hotplug notification and
	* that you should first call on \ref libusb_has_capability() with parameter
	* \ref LIBUSB_CAP_HAS_HOTPLUG to confirm that hotplug support is available.
	*
	* \page libusb_hotplug Device hotplug event notification
	*
	* \section hotplug_intro Introduction
	*
	* Version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102, has added support
	* for hotplug events on <b>some</b> platforms (you should test if your platform
	* supports hotplug notification by calling \ref libusb_has_capability() with
	* parameter \ref LIBUSB_CAP_HAS_HOTPLUG).
	*
	* This interface allows you to request notification for the arrival and departure
	* of matching USB devices.
	*
	* To receive hotplug notification you register a callback by calling
	* \ref libusb_hotplug_register_callback(). This function will optionally return
	* a callback handle that can be passed to \ref libusb_hotplug_deregister_callback().
	*
	* A callback function must return an int (0 or 1) indicating whether the callback is
	* expecting additional events. Returning 0 will rearm the callback and 1 will cause
	* the callback to be deregistered. Note that when callbacks are called from
	* libusb_hotplug_register_callback() because of the \ref LIBUSB_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
	* libusb_hotplug_register_callback().
	*
	* Callbacks for a particular context are automatically deregistered by libusb_exit().
	*
	* As of 1.0.16 there are two supported hotplug events:
	* - LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED: A device has arrived and is ready to use
	* - LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT: A device has left and is no longer available
	*
	* A hotplug event can listen for either or both of these events.
	*
	* Note: If you receive notification that a device has left and you have any
	* a libusb_device_handles for the device it is up to you to call libusb_close()
	* on each device handle to free up any remaining resources associated with the device.
	* Once a device has left any libusb_device_handle associated with the device
	* are invalid and will remain so even if the device comes back.
	*
	* When handling a LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED event it is considered
	* safe to call any libusb function that takes a libusb_device. It also safe to
	* open a device and submit asynchronous transfers. However, most other functions
	* that take a libusb_device_handle are <b>not</b> safe to call. Examples of such
	* functions are any of the \ref libusb_syncio "synchronous API" functions or the blocking
	* functions that retrieve various \ref libusb_desc "USB descriptors". These functions must
	* be used outside of the context of the hotplug callback.
	*
	* When handling a LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT event the only safe function
	* is libusb_get_device_descriptor().
	*
	* The following code provides an example of the usage of the hotplug interface:
	\code
	#include <stdio.h>
	#include <stdlib.h>
	#include <time.h>
	#include <libusb.h>

	static int count = 0;

	int hotplug_callback(struct libusb_context ctx, struct libusb_device dev,
	libusb_hotplug_event event, void *user_data) {
	static libusb_device_handle *dev_handle = NULL;
	struct libusb_device_descriptor desc;
	int rc;

	(void)libusb_get_device_descriptor(dev, &desc);

	if (LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED == event) {
	rc = libusb_open(dev, &dev_handle);
	if (LIBUSB_SUCCESS != rc) {
	printf("Could not open USB device\n");
	}
	} else if (LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT == event) {
	if (dev_handle) {
	libusb_close(dev_handle);
	dev_handle = NULL;
	}
	} else {
	printf("Unhandled event %d\n", event);
	}
	count++;

	return 0;
	}

	int main (void) {
	libusb_hotplug_callback_handle callback_handle;
	int rc;

	libusb_init(NULL);

	rc = libusb_hotplug_register_callback(NULL, LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED \|
	LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT, 0, 0x045a, 0x5005,
	LIBUSB_HOTPLUG_MATCH_ANY, hotplug_callback, NULL,
	&callback_handle);
	if (LIBUSB_SUCCESS != rc) {
	printf("Error creating a hotplug callback\n");
	libusb_exit(NULL);
	return EXIT_FAILURE;
	}

	while (count < 2) {
	libusb_handle_events_completed(NULL, NULL);
	nanosleep(&(struct timespec){0, 10000000UL}, NULL);
	}

	libusb_hotplug_deregister_callback(NULL, callback_handle);
	libusb_exit(NULL);

	return 0;
	}
	\endcode
	*/

	#define VALID_HOTPLUG_EVENTS \
	(LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED \| \
	LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT)

	#define VALID_HOTPLUG_FLAGS \
	(LIBUSB_HOTPLUG_ENUMERATE)

	void usbi_hotplug_init(struct libusb_context *ctx)
	{
	/* check for hotplug support */
	if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
	return;

	usbi_mutex_init(&ctx->hotplug_cbs_lock);
	list_init(&ctx->hotplug_cbs);
	ctx->next_hotplug_cb_handle = 1;
	usbi_atomic_store(&ctx->hotplug_ready, 1);
	}

	void usbi_hotplug_exit(struct libusb_context *ctx)
	{
	struct usbi_hotplug_callback hotplug_cb, next_cb;
	struct usbi_hotplug_message *msg;
	struct libusb_device dev, next_dev;

	/* check for hotplug support */
	if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
	return;

	/* free all registered hotplug callbacks */
	for_each_hotplug_cb_safe(ctx, hotplug_cb, next_cb) {
	list_del(&hotplug_cb->list);
	free(hotplug_cb);
	}

	/* free all pending hotplug messages */
	while (!list_empty(&ctx->hotplug_msgs)) {
	msg = list_first_entry(&ctx->hotplug_msgs, struct usbi_hotplug_message, list);

	/* if the device left, the message holds a reference
	* and we must drop it */
	if (msg->event == LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT)
	libusb_unref_device(msg->device);

	list_del(&msg->list);
	free(msg);
	}

	/* free all discovered devices. due to parent references loop until no devices are freed. */
	for_each_device_safe(ctx, dev, next_dev) {
	/* remove the device from the usb_devs list only if there are no
	* references held, otherwise leave it on the list so that a
	* warning message will be shown */
	if (usbi_atomic_load(&dev->refcnt) == 1) {
	list_del(&dev->list);
	}
	if (dev->parent_dev && usbi_atomic_load(&dev->parent_dev->refcnt) == 1) {
	/* the parent was before this device in the list and will be released.
	remove it from the list. this is safe as parent_dev can not be
	equal to next_dev. */
	assert (dev->parent_dev != next_dev);
	list_del(&dev->parent_dev->list);
	}
	libusb_unref_device(dev);
	}

	usbi_mutex_destroy(&ctx->hotplug_cbs_lock);
	}

	static int usbi_hotplug_match_cb(struct libusb_device *dev,
	libusb_hotplug_event event, struct usbi_hotplug_callback *hotplug_cb)
	{
	if (!(hotplug_cb->flags & event)) {
	return 0;
	}

	if ((hotplug_cb->flags & USBI_HOTPLUG_VENDOR_ID_VALID) &&
	hotplug_cb->vendor_id != dev->device_descriptor.idVendor) {
	return 0;
	}

	if ((hotplug_cb->flags & USBI_HOTPLUG_PRODUCT_ID_VALID) &&
	hotplug_cb->product_id != dev->device_descriptor.idProduct) {
	return 0;
	}

	if ((hotplug_cb->flags & USBI_HOTPLUG_DEV_CLASS_VALID) &&
	hotplug_cb->dev_class != dev->device_descriptor.bDeviceClass) {
	return 0;
	}

	return hotplug_cb->cb(DEVICE_CTX(dev), dev, event, hotplug_cb->user_data);
	}

	void usbi_hotplug_notification(struct libusb_context ctx, struct libusb_device dev,
	libusb_hotplug_event event)
	{
	struct usbi_hotplug_message *msg;
	unsigned int event_flags;

	/* Only generate a notification if hotplug is ready. This prevents hotplug
	* notifications from being generated during initial enumeration or if the
	* backend does not support hotplug. */
	if (!usbi_atomic_load(&ctx->hotplug_ready))
	return;

	msg = calloc(1, sizeof(*msg));
	if (!msg) {
	usbi_err(ctx, "error allocating hotplug message");
	return;
	}

	msg->event = event;
	msg->device = dev;

	/* Take the event data lock and add this message to the list.
	* Only signal an event if there are no prior pending events. */
	usbi_mutex_lock(&ctx->event_data_lock);
	event_flags = ctx->event_flags;
	ctx->event_flags \|= USBI_EVENT_HOTPLUG_MSG_PENDING;
	list_add_tail(&msg->list, &ctx->hotplug_msgs);
	if (!event_flags)
	usbi_signal_event(&ctx->event);
	usbi_mutex_unlock(&ctx->event_data_lock);
	}

	void usbi_hotplug_process(struct libusb_context ctx, struct list_head hotplug_msgs)
	{
	struct usbi_hotplug_callback hotplug_cb, next_cb;
	struct usbi_hotplug_message *msg;
	int r;

	usbi_mutex_lock(&ctx->hotplug_cbs_lock);

	/* dispatch all pending hotplug messages */
	while (!list_empty(hotplug_msgs)) {
	msg = list_first_entry(hotplug_msgs, struct usbi_hotplug_message, list);

	for_each_hotplug_cb_safe(ctx, hotplug_cb, next_cb) {
	/* skip callbacks that have unregistered */
	if (hotplug_cb->flags & USBI_HOTPLUG_NEEDS_FREE)
	continue;

	usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
	r = usbi_hotplug_match_cb(msg->device, msg->event, hotplug_cb);
	usbi_mutex_lock(&ctx->hotplug_cbs_lock);

	if (r) {
	list_del(&hotplug_cb->list);
	free(hotplug_cb);
	}
	}

	/* if the device left, the message holds a reference
	* and we must drop it */
	if (msg->event == LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT)
	libusb_unref_device(msg->device);

	list_del(&msg->list);
	free(msg);
	}

	/* free any callbacks that have unregistered */
	for_each_hotplug_cb_safe(ctx, hotplug_cb, next_cb) {
	if (hotplug_cb->flags & USBI_HOTPLUG_NEEDS_FREE) {
	usbi_dbg(ctx, "freeing hotplug cb %p with handle %d",
	hotplug_cb, hotplug_cb->handle);
	list_del(&hotplug_cb->list);
	free(hotplug_cb);
	}
	}

	usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
	}

	int API_EXPORTED libusb_hotplug_register_callback(libusb_context *ctx,
	int events, int flags,
	int vendor_id, int product_id, int dev_class,
	libusb_hotplug_callback_fn cb_fn, void *user_data,
	libusb_hotplug_callback_handle *callback_handle)
	{
	struct usbi_hotplug_callback *hotplug_cb;

	/* check for sane values */
	if (!events \|\| (~VALID_HOTPLUG_EVENTS & events) \|\|
	(~VALID_HOTPLUG_FLAGS & flags) \|\|
	(LIBUSB_HOTPLUG_MATCH_ANY != vendor_id && (~0xffff & vendor_id)) \|\|
	(LIBUSB_HOTPLUG_MATCH_ANY != product_id && (~0xffff & product_id)) \|\|
	(LIBUSB_HOTPLUG_MATCH_ANY != dev_class && (~0xff & dev_class)) \|\|
	!cb_fn) {
	return LIBUSB_ERROR_INVALID_PARAM;
	}

	/* check for hotplug support */
	if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
	return LIBUSB_ERROR_NOT_SUPPORTED;

	ctx = usbi_get_context(ctx);

	hotplug_cb = calloc(1, sizeof(*hotplug_cb));
	if (!hotplug_cb)
	return LIBUSB_ERROR_NO_MEM;

	hotplug_cb->flags = (uint8_t)events;
	if (LIBUSB_HOTPLUG_MATCH_ANY != vendor_id) {
	hotplug_cb->flags \|= USBI_HOTPLUG_VENDOR_ID_VALID;
	hotplug_cb->vendor_id = (uint16_t)vendor_id;
	}
	if (LIBUSB_HOTPLUG_MATCH_ANY != product_id) {
	hotplug_cb->flags \|= USBI_HOTPLUG_PRODUCT_ID_VALID;
	hotplug_cb->product_id = (uint16_t)product_id;
	}
	if (LIBUSB_HOTPLUG_MATCH_ANY != dev_class) {
	hotplug_cb->flags \|= USBI_HOTPLUG_DEV_CLASS_VALID;
	hotplug_cb->dev_class = (uint8_t)dev_class;
	}
	hotplug_cb->cb = cb_fn;
	hotplug_cb->user_data = user_data;

	usbi_mutex_lock(&ctx->hotplug_cbs_lock);

	/* protect the handle by the context hotplug lock */
	hotplug_cb->handle = ctx->next_hotplug_cb_handle++;

	/* handle the unlikely case of overflow */
	if (ctx->next_hotplug_cb_handle < 0)
	ctx->next_hotplug_cb_handle = 1;

	list_add(&hotplug_cb->list, &ctx->hotplug_cbs);

	usbi_mutex_unlock(&ctx->hotplug_cbs_lock);

	usbi_dbg(ctx, "new hotplug cb %p with handle %d", hotplug_cb, hotplug_cb->handle);

	if ((flags & LIBUSB_HOTPLUG_ENUMERATE) && (events & LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED)) {
	ssize_t i, len;
	struct libusb_device **devs;

	len = libusb_get_device_list(ctx, &devs);
	if (len < 0) {
	libusb_hotplug_deregister_callback(ctx, hotplug_cb->handle);
	return (int)len;
	}

	for (i = 0; i < len; i++) {
	usbi_hotplug_match_cb(devs[i],
	LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED,
	hotplug_cb);
	}

	libusb_free_device_list(devs, 1);
	}

	if (callback_handle)
	*callback_handle = hotplug_cb->handle;

	return LIBUSB_SUCCESS;
	}

	void API_EXPORTED libusb_hotplug_deregister_callback(libusb_context *ctx,
	libusb_hotplug_callback_handle callback_handle)
	{
	struct usbi_hotplug_callback *hotplug_cb;
	int deregistered = 0;

	/* check for hotplug support */
	if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
	return;

	usbi_dbg(ctx, "deregister hotplug cb %d", callback_handle);

	ctx = usbi_get_context(ctx);

	usbi_mutex_lock(&ctx->hotplug_cbs_lock);
	for_each_hotplug_cb(ctx, hotplug_cb) {
	if (callback_handle == hotplug_cb->handle) {
	/* mark this callback for deregistration */
	hotplug_cb->flags \|= USBI_HOTPLUG_NEEDS_FREE;
	deregistered = 1;
	break;
	}
	}
	usbi_mutex_unlock(&ctx->hotplug_cbs_lock);

	if (deregistered) {
	unsigned int event_flags;

	usbi_mutex_lock(&ctx->event_data_lock);
	event_flags = ctx->event_flags;
	ctx->event_flags \|= USBI_EVENT_HOTPLUG_CB_DEREGISTERED;
	if (!event_flags)
	usbi_signal_event(&ctx->event);
	usbi_mutex_unlock(&ctx->event_data_lock);
	}
	}

	DEFAULT_VISIBILITY
	void * LIBUSB_CALL libusb_hotplug_get_user_data(libusb_context *ctx,
	libusb_hotplug_callback_handle callback_handle)
	{
	struct usbi_hotplug_callback *hotplug_cb;
	void *user_data = NULL;

	/* check for hotplug support */
	if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG))
	return NULL;

	usbi_dbg(ctx, "get hotplug cb %d user data", callback_handle);

	ctx = usbi_get_context(ctx);

	usbi_mutex_lock(&ctx->hotplug_cbs_lock);
	for_each_hotplug_cb(ctx, hotplug_cb) {
	if (callback_handle == hotplug_cb->handle) {
	user_data = hotplug_cb->user_data;
	break;
	}
	}
	usbi_mutex_unlock(&ctx->hotplug_cbs_lock);

	return user_data;
	}