1 /* -*- Mode: C; indent-tabs-mode:t ; c-basic-offset:8 -*- */ 2 /* 3 * Hotplug functions for libusb 4 * Copyright 2012-2013 Nathan Hjelm <hjelmn (at) mac.com> 5 * Copyright 2012-2013 Peter Stuge <peter (at) stuge.se> 6 * 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. 11 * 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. 16 * 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 20 */ 21 22 #include <config.h> 23 24 #include <errno.h> 25 #include <stdio.h> 26 #include <stdlib.h> 27 #include <string.h> 28 #ifdef HAVE_SYS_TYPES_H 29 #include <sys/types.h> 30 #endif 31 #include <assert.h> 32 33 #include "libusbi.h" 34 #include "hotplug.h" 35 36 /** 37 * @defgroup libusb_hotplug Device hotplug event notification 38 * This page details how to use the libusb hotplug interface, where available. 39 * 40 * Be mindful that not all platforms currently implement hotplug notification and 41 * that you should first call on \ref libusb_has_capability() with parameter 42 * \ref LIBUSB_CAP_HAS_HOTPLUG to confirm that hotplug support is available. 43 * 44 * \page libusb_hotplug Device hotplug event notification 45 * 46 * \section hotplug_intro Introduction 47 * 48 * Version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102, has added support 49 * for hotplug events on <b>some</b> platforms (you should test if your platform 50 * supports hotplug notification by calling \ref libusb_has_capability() with 51 * parameter \ref LIBUSB_CAP_HAS_HOTPLUG). 52 * 53 * This interface allows you to request notification for the arrival and departure 54 * of matching USB devices. 55 * 56 * To receive hotplug notification you register a callback by calling 57 * \ref libusb_hotplug_register_callback(). This function will optionally return 58 * a callback handle that can be passed to \ref libusb_hotplug_deregister_callback(). 59 * 60 * A callback function must return an int (0 or 1) indicating whether the callback is 61 * expecting additional events. Returning 0 will rearm the callback and 1 will cause 62 * the callback to be deregistered. Note that when callbacks are called from 63 * libusb_hotplug_register_callback() because of the \ref LIBUSB_HOTPLUG_ENUMERATE 64 * flag, the callback return value is ignored, iow you cannot cause a callback 65 * to be deregistered by returning 1 when it is called from 66 * libusb_hotplug_register_callback(). 67 * 68 * Callbacks for a particular context are automatically deregistered by libusb_exit(). 69 * 70 * As of 1.0.16 there are two supported hotplug events: 71 * - LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED: A device has arrived and is ready to use 72 * - LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT: A device has left and is no longer available 73 * 74 * A hotplug event can listen for either or both of these events. 75 * 76 * Note: If you receive notification that a device has left and you have any 77 * a libusb_device_handles for the device it is up to you to call libusb_close() 78 * on each device handle to free up any remaining resources associated with the device. 79 * Once a device has left any libusb_device_handle associated with the device 80 * are invalid and will remain so even if the device comes back. 81 * 82 * When handling a LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED event it is considered 83 * safe to call any libusb function that takes a libusb_device. It also safe to 84 * open a device and submit asynchronous transfers. However, most other functions 85 * that take a libusb_device_handle are <b>not</b> safe to call. Examples of such 86 * functions are any of the \ref libusb_syncio "synchronous API" functions or the blocking 87 * functions that retrieve various \ref libusb_desc "USB descriptors". These functions must 88 * be used outside of the context of the hotplug callback. 89 * 90 * When handling a LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT event the only safe function 91 * is libusb_get_device_descriptor(). 92 * 93 * The following code provides an example of the usage of the hotplug interface: 94 \code 95 #include <stdio.h> 96 #include <stdlib.h> 97 #include <time.h> 98 #include <libusb.h> 99 100 static int count = 0; 101 102 int hotplug_callback(struct libusb_context *ctx, struct libusb_device *dev, 103 libusb_hotplug_event event, void *user_data) { 104 static libusb_device_handle *dev_handle = NULL; 105 struct libusb_device_descriptor desc; 106 int rc; 107 108 (void)libusb_get_device_descriptor(dev, &desc); 109 110 if (LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED == event) { 111 rc = libusb_open(dev, &dev_handle); 112 if (LIBUSB_SUCCESS != rc) { 113 printf("Could not open USB device\n"); 114 } 115 } else if (LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT == event) { 116 if (dev_handle) { 117 libusb_close(dev_handle); 118 dev_handle = NULL; 119 } 120 } else { 121 printf("Unhandled event %d\n", event); 122 } 123 count++; 124 125 return 0; 126 } 127 128 int main (void) { 129 libusb_hotplug_callback_handle callback_handle; 130 int rc; 131 132 libusb_init(NULL); 133 134 rc = libusb_hotplug_register_callback(NULL, LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED | 135 LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT, 0, 0x045a, 0x5005, 136 LIBUSB_HOTPLUG_MATCH_ANY, hotplug_callback, NULL, 137 &callback_handle); 138 if (LIBUSB_SUCCESS != rc) { 139 printf("Error creating a hotplug callback\n"); 140 libusb_exit(NULL); 141 return EXIT_FAILURE; 142 } 143 144 while (count < 2) { 145 libusb_handle_events_completed(NULL, NULL); 146 nanosleep(&(struct timespec){0, 10000000UL}, NULL); 147 } 148 149 libusb_hotplug_deregister_callback(NULL, callback_handle); 150 libusb_exit(NULL); 151 152 return 0; 153 } 154 \endcode 155 */ 156 157 static int usbi_hotplug_match_cb (struct libusb_context *ctx, 158 struct libusb_device *dev, libusb_hotplug_event event, 159 struct libusb_hotplug_callback *hotplug_cb) 160 { 161 /* Handle lazy deregistration of callback */ 162 if (hotplug_cb->needs_free) { 163 /* Free callback */ 164 return 1; 165 } 166 167 if (!(hotplug_cb->events & event)) { 168 return 0; 169 } 170 171 if (LIBUSB_HOTPLUG_MATCH_ANY != hotplug_cb->vendor_id && 172 hotplug_cb->vendor_id != dev->device_descriptor.idVendor) { 173 return 0; 174 } 175 176 if (LIBUSB_HOTPLUG_MATCH_ANY != hotplug_cb->product_id && 177 hotplug_cb->product_id != dev->device_descriptor.idProduct) { 178 return 0; 179 } 180 181 if (LIBUSB_HOTPLUG_MATCH_ANY != hotplug_cb->dev_class && 182 hotplug_cb->dev_class != dev->device_descriptor.bDeviceClass) { 183 return 0; 184 } 185 186 return hotplug_cb->cb (ctx, dev, event, hotplug_cb->user_data); 187 } 188 189 void usbi_hotplug_match(struct libusb_context *ctx, struct libusb_device *dev, 190 libusb_hotplug_event event) 191 { 192 struct libusb_hotplug_callback *hotplug_cb, *next; 193 int ret; 194 195 usbi_mutex_lock(&ctx->hotplug_cbs_lock); 196 197 list_for_each_entry_safe(hotplug_cb, next, &ctx->hotplug_cbs, list, struct libusb_hotplug_callback) { 198 usbi_mutex_unlock(&ctx->hotplug_cbs_lock); 199 ret = usbi_hotplug_match_cb (ctx, dev, event, hotplug_cb); 200 usbi_mutex_lock(&ctx->hotplug_cbs_lock); 201 202 if (ret) { 203 list_del(&hotplug_cb->list); 204 free(hotplug_cb); 205 } 206 } 207 208 usbi_mutex_unlock(&ctx->hotplug_cbs_lock); 209 210 /* the backend is expected to call the callback for each active transfer */ 211 } 212 213 void usbi_hotplug_notification(struct libusb_context *ctx, struct libusb_device *dev, 214 libusb_hotplug_event event) 215 { 216 int pending_events; 217 libusb_hotplug_message *message = calloc(1, sizeof(*message)); 218 219 if (!message) { 220 usbi_err(ctx, "error allocating hotplug message"); 221 return; 222 } 223 224 message->event = event; 225 message->device = dev; 226 227 /* Take the event data lock and add this message to the list. 228 * Only signal an event if there are no prior pending events. */ 229 usbi_mutex_lock(&ctx->event_data_lock); 230 pending_events = usbi_pending_events(ctx); 231 list_add_tail(&message->list, &ctx->hotplug_msgs); 232 if (!pending_events) 233 usbi_signal_event(ctx); 234 usbi_mutex_unlock(&ctx->event_data_lock); 235 } 236 237 int API_EXPORTED libusb_hotplug_register_callback(libusb_context *ctx, 238 libusb_hotplug_event events, libusb_hotplug_flag flags, 239 int vendor_id, int product_id, int dev_class, 240 libusb_hotplug_callback_fn cb_fn, void *user_data, 241 libusb_hotplug_callback_handle *callback_handle) 242 { 243 libusb_hotplug_callback *new_callback; 244 static int handle_id = 1; 245 246 /* check for hotplug support */ 247 if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG)) { 248 return LIBUSB_ERROR_NOT_SUPPORTED; 249 } 250 251 /* check for sane values */ 252 if ((LIBUSB_HOTPLUG_MATCH_ANY != vendor_id && (~0xffff & vendor_id)) || 253 (LIBUSB_HOTPLUG_MATCH_ANY != product_id && (~0xffff & product_id)) || 254 (LIBUSB_HOTPLUG_MATCH_ANY != dev_class && (~0xff & dev_class)) || 255 !cb_fn) { 256 return LIBUSB_ERROR_INVALID_PARAM; 257 } 258 259 USBI_GET_CONTEXT(ctx); 260 261 new_callback = (libusb_hotplug_callback *)calloc(1, sizeof (*new_callback)); 262 if (!new_callback) { 263 return LIBUSB_ERROR_NO_MEM; 264 } 265 266 new_callback->ctx = ctx; 267 new_callback->vendor_id = vendor_id; 268 new_callback->product_id = product_id; 269 new_callback->dev_class = dev_class; 270 new_callback->flags = flags; 271 new_callback->events = events; 272 new_callback->cb = cb_fn; 273 new_callback->user_data = user_data; 274 new_callback->needs_free = 0; 275 276 usbi_mutex_lock(&ctx->hotplug_cbs_lock); 277 278 /* protect the handle by the context hotplug lock. it doesn't matter if the same handle 279 * is used for different contexts only that the handle is unique for this context */ 280 new_callback->handle = handle_id++; 281 282 list_add(&new_callback->list, &ctx->hotplug_cbs); 283 284 usbi_mutex_unlock(&ctx->hotplug_cbs_lock); 285 286 287 if (flags & LIBUSB_HOTPLUG_ENUMERATE) { 288 int i, len; 289 struct libusb_device **devs; 290 291 len = (int) libusb_get_device_list(ctx, &devs); 292 if (len < 0) { 293 libusb_hotplug_deregister_callback(ctx, 294 new_callback->handle); 295 return len; 296 } 297 298 for (i = 0; i < len; i++) { 299 usbi_hotplug_match_cb(ctx, devs[i], 300 LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED, 301 new_callback); 302 } 303 304 libusb_free_device_list(devs, 1); 305 } 306 307 308 if (callback_handle) 309 *callback_handle = new_callback->handle; 310 311 return LIBUSB_SUCCESS; 312 } 313 314 void API_EXPORTED libusb_hotplug_deregister_callback (struct libusb_context *ctx, 315 libusb_hotplug_callback_handle callback_handle) 316 { 317 struct libusb_hotplug_callback *hotplug_cb; 318 319 /* check for hotplug support */ 320 if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG)) { 321 return; 322 } 323 324 USBI_GET_CONTEXT(ctx); 325 326 usbi_mutex_lock(&ctx->hotplug_cbs_lock); 327 list_for_each_entry(hotplug_cb, &ctx->hotplug_cbs, list, 328 struct libusb_hotplug_callback) { 329 if (callback_handle == hotplug_cb->handle) { 330 /* Mark this callback for deregistration */ 331 hotplug_cb->needs_free = 1; 332 } 333 } 334 usbi_mutex_unlock(&ctx->hotplug_cbs_lock); 335 336 usbi_hotplug_notification(ctx, NULL, 0); 337 } 338 339 void usbi_hotplug_deregister_all(struct libusb_context *ctx) { 340 struct libusb_hotplug_callback *hotplug_cb, *next; 341 342 usbi_mutex_lock(&ctx->hotplug_cbs_lock); 343 list_for_each_entry_safe(hotplug_cb, next, &ctx->hotplug_cbs, list, 344 struct libusb_hotplug_callback) { 345 list_del(&hotplug_cb->list); 346 free(hotplug_cb); 347 } 348 349 usbi_mutex_unlock(&ctx->hotplug_cbs_lock); 350 } 351
