1 /* -*- Mode: C; indent-tabs-mode:t ; c-basic-offset:8 -*- */
3 * Hotplug functions for libusbx
4 * Copyright © 2012-2013 Nathan Hjelm <hjelmn@mac.com>
5 * Copyright © 2012-2013 Peter Stuge <peter@stuge.se>
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
28 #ifdef HAVE_SYS_TYPES_H
29 #include <sys/types.h>
37 * @defgroup hotplug Device hotplug event notification
38 * This page details how to use the libusb hotplug interface.
40 * \page hotplug Device hotplug event notification
42 * \section intro Introduction
44 * Version 1.0.16, \ref LIBUSBX_API_VERSION >= 0x01000102, has added support
45 * for hotplug events. This interface allows you to request notification for
46 * the arrival and departure of matching USB devices.
48 * To receive hotplug notification you register a callback by calling
49 * libusb_hotplug_register_callback(). This function will optionally return
50 * a handle that can be passed to libusb_hotplug_deregister_callback().
52 * A callback function must return an int (0 or 1) indicating whether the callback is
53 * expecting additional events. Returning 0 will rearm the callback and 1 will cause
54 * the callback to be deregistered.
56 * Callbacks for a particulat context are automatically deregistered by libusb_exit().
58 * As of 1.0.16 there are two supported hotplug events:
59 * - LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED: A device has arrived and is ready to use
60 * - LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT: A device has left and is no longer available
62 * A hotplug event can listen for either or both of these events.
64 * Note: If you receive notification that a device has left and you have any
65 * a libusb_device_handles for the device it is up to you to call libusb_close()
66 * on each handle to free up any remaining resources associated with the device.
67 * Once a device has left any libusb_device_handle associated with the device
68 * are invalid and will remain so even if the device comes back.
70 * When handling a LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED event it is considered
71 * safe to call any libusbx function that takes a libusb_device. On the other hand,
72 * when handling a LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT event the only safe function
73 * is libusb_get_device_descriptor().
75 * The following code provides an example of the usage of the hotplug interface:
79 int hotplug_callback(struct libusb_context *ctx, struct libusb_device *dev,
80 libusb_hotplug_event event, void *user_data) {
81 static libusb_device_handle *handle = NULL;
82 struct libusb_device_descriptor desc;
85 (void)libusb_get_device_descriptor(dev, &desc);
87 if (LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED == event) {
88 rc = libusb_open(dev, &handle);
89 if (LIBUSB_SUCCESS != rc) {
90 printf("Could not open USB device\n");
92 } else if (LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT == event) {
98 printf("Unhandled event %d\n", event);
106 libusb_hotplug_callback_handle handle;
111 rc = libusb_hotplug_register_callback(NULL, LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED |
112 LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT, 0, 0x045a, 0x5005,
113 LIBUSB_HOTPLUG_MATCH_ANY, hotplug_callback, NULL,
115 if (LIBUSB_SUCCESS != rc) {
116 printf("Error creating a hotplug callback\n");
125 libusb_hotplug_deregister_callback(handle);
133 static int usbi_hotplug_match_cb (struct libusb_device *dev, libusb_hotplug_event event,
134 struct libusb_hotplug_callback *hotplug_cb)
136 struct libusb_context *ctx = dev->ctx;
138 /* Handle lazy deregistration of callback */
139 if (hotplug_cb->needs_free) {
144 if (!(hotplug_cb->events & event)) {
148 if (LIBUSB_HOTPLUG_MATCH_ANY != hotplug_cb->vendor_id &&
149 hotplug_cb->vendor_id != dev->device_descriptor.idVendor) {
153 if (LIBUSB_HOTPLUG_MATCH_ANY != hotplug_cb->product_id &&
154 hotplug_cb->product_id != dev->device_descriptor.idProduct) {
158 if (LIBUSB_HOTPLUG_MATCH_ANY != hotplug_cb->dev_class &&
159 hotplug_cb->dev_class != dev->device_descriptor.bDeviceClass) {
163 return hotplug_cb->cb (ctx == usbi_default_context ? NULL : ctx,
164 dev, event, hotplug_cb->user_data);
167 void usbi_hotplug_match(struct libusb_device *dev, libusb_hotplug_event event)
169 struct libusb_hotplug_callback *hotplug_cb, *next;
170 struct libusb_context *ctx = dev->ctx;
173 usbi_mutex_lock(&ctx->hotplug_cbs_lock);
175 list_for_each_entry_safe(hotplug_cb, next, &ctx->hotplug_cbs, list, struct libusb_hotplug_callback) {
176 usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
177 ret = usbi_hotplug_match_cb (dev, event, hotplug_cb);
178 usbi_mutex_lock(&ctx->hotplug_cbs_lock);
181 list_del(&hotplug_cb->list);
186 usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
188 /* loop through and disconnect all open handles for this device */
189 if (LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT == event) {
190 struct libusb_device_handle *handle;
192 usbi_mutex_lock(&ctx->open_devs_lock);
193 list_for_each_entry(handle, &ctx->open_devs, list, struct libusb_device_handle) {
194 if (dev == handle->dev) {
195 usbi_handle_disconnect (handle);
198 usbi_mutex_unlock(&ctx->open_devs_lock);
202 int API_EXPORTED libusb_hotplug_register_callback(libusb_context *ctx,
203 libusb_hotplug_event events, libusb_hotplug_flag flags,
204 int vendor_id, int product_id, int dev_class,
205 libusb_hotplug_callback_fn cb_fn, void *user_data,
206 libusb_hotplug_callback_handle *handle)
208 libusb_hotplug_callback *new_callback;
209 static int handle_id = 1;
211 /* check for hotplug support */
212 if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG)) {
213 return LIBUSB_ERROR_NOT_SUPPORTED;
216 /* check for sane values */
217 if ((LIBUSB_HOTPLUG_MATCH_ANY != vendor_id && (~0xffff & vendor_id)) ||
218 (LIBUSB_HOTPLUG_MATCH_ANY != product_id && (~0xffff & product_id)) ||
219 (LIBUSB_HOTPLUG_MATCH_ANY != dev_class && (~0xff & dev_class)) ||
221 return LIBUSB_ERROR_INVALID_PARAM;
224 USBI_GET_CONTEXT(ctx);
226 new_callback = (libusb_hotplug_callback *)calloc(1, sizeof (*new_callback));
228 return LIBUSB_ERROR_NO_MEM;
231 new_callback->ctx = ctx;
232 new_callback->vendor_id = vendor_id;
233 new_callback->product_id = product_id;
234 new_callback->dev_class = dev_class;
235 new_callback->flags = flags;
236 new_callback->events = events;
237 new_callback->cb = cb_fn;
238 new_callback->user_data = user_data;
239 new_callback->needs_free = 0;
241 usbi_mutex_lock(&ctx->hotplug_cbs_lock);
243 /* protect the handle by the context hotplug lock. it doesn't matter if the same handle
244 * is used for different contexts only that the handle is unique for this context */
245 new_callback->handle = handle_id++;
247 list_add(&new_callback->list, &ctx->hotplug_cbs);
249 if (flags & LIBUSB_HOTPLUG_ENUMERATE) {
250 struct libusb_device *dev;
252 usbi_mutex_lock(&ctx->usb_devs_lock);
254 list_for_each_entry(dev, &ctx->usb_devs, list, struct libusb_device) {
255 (void) usbi_hotplug_match_cb (dev, LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED, new_callback);
258 usbi_mutex_unlock(&ctx->usb_devs_lock);
261 usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
264 *handle = new_callback->handle;
267 return LIBUSB_SUCCESS;
270 void API_EXPORTED libusb_hotplug_deregister_callback (struct libusb_context *ctx,
271 libusb_hotplug_callback_handle handle)
273 struct libusb_hotplug_callback *hotplug_cb;
275 /* check for hotplug support */
276 if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG)) {
280 USBI_GET_CONTEXT(ctx);
282 usbi_mutex_lock(&ctx->hotplug_cbs_lock);
283 list_for_each_entry(hotplug_cb, &ctx->hotplug_cbs, list,
284 struct libusb_hotplug_callback) {
285 if (handle == hotplug_cb->handle) {
286 /* Mark this callback for deregistration */
287 hotplug_cb->needs_free = 1;
290 usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
293 void usbi_hotplug_deregister_all(struct libusb_context *ctx) {
294 struct libusb_hotplug_callback *hotplug_cb, *next;
296 usbi_mutex_lock(&ctx->hotplug_cbs_lock);
297 list_for_each_entry_safe(hotplug_cb, next, &ctx->hotplug_cbs, list,
298 struct libusb_hotplug_callback) {
299 list_del(&hotplug_cb->list);
303 usbi_mutex_unlock(&ctx->hotplug_cbs_lock);