1 /* -*- Mode: C; indent-tabs-mode:t ; c-basic-offset:8 -*- */ 2 /* 3 * Hotplug functions for libusbx 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 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 hotplug Device hotplug event notification 45 * 46 * \section intro Introduction 47 * 48 * Version 1.0.16, \ref LIBUSBX_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 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 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 libusbx function that takes a libusb_device. On the other hand, 84 * when handling a LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT event the only safe function 85 * is libusb_get_device_descriptor(). 86 * 87 * The following code provides an example of the usage of the hotplug interface: 88 \code 89 static int count = 0; 90 91 int hotplug_callback(struct libusb_context *ctx, struct libusb_device *dev, 92 libusb_hotplug_event event, void *user_data) { 93 static libusb_device_handle *handle = NULL; 94 struct libusb_device_descriptor desc; 95 int rc; 96 97 (void)libusb_get_device_descriptor(dev, &desc); 98 99 if (LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED == event) { 100 rc = libusb_open(dev, &handle); 101 if (LIBUSB_SUCCESS != rc) { 102 printf("Could not open USB device\n"); 103 } 104 } else if (LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT == event) { 105 if (handle) { 106 libusb_close(handle); 107 handle = NULL; 108 } 109 } else { 110 printf("Unhandled event %d\n", event); 111 } 112 count++; 113 114 return 0; 115 } 116 117 int main (void) { 118 libusb_hotplug_callback_handle handle; 119 int rc; 120 121 libusb_init(NULL); 122 123 rc = libusb_hotplug_register_callback(NULL, LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED | 124 LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT, 0, 0x045a, 0x5005, 125 LIBUSB_HOTPLUG_MATCH_ANY, hotplug_callback, NULL, 126 &handle); 127 if (LIBUSB_SUCCESS != rc) { 128 printf("Error creating a hotplug callback\n"); 129 libusb_exit(NULL); 130 return EXIT_FAILURE; 131 } 132 133 while (count < 2) { 134 usleep(10000); 135 } 136 137 libusb_hotplug_deregister_callback(handle); 138 libusb_exit(NULL); 139 140 return 0; 141 } 142 \endcode 143 */ 144 145 static int usbi_hotplug_match_cb (struct libusb_context *ctx, 146 struct libusb_device *dev, libusb_hotplug_event event, 147 struct libusb_hotplug_callback *hotplug_cb) 148 { 149 /* Handle lazy deregistration of callback */ 150 if (hotplug_cb->needs_free) { 151 /* Free callback */ 152 return 1; 153 } 154 155 if (!(hotplug_cb->events & event)) { 156 return 0; 157 } 158 159 if (LIBUSB_HOTPLUG_MATCH_ANY != hotplug_cb->vendor_id && 160 hotplug_cb->vendor_id != dev->device_descriptor.idVendor) { 161 return 0; 162 } 163 164 if (LIBUSB_HOTPLUG_MATCH_ANY != hotplug_cb->product_id && 165 hotplug_cb->product_id != dev->device_descriptor.idProduct) { 166 return 0; 167 } 168 169 if (LIBUSB_HOTPLUG_MATCH_ANY != hotplug_cb->dev_class && 170 hotplug_cb->dev_class != dev->device_descriptor.bDeviceClass) { 171 return 0; 172 } 173 174 return hotplug_cb->cb (ctx, dev, event, hotplug_cb->user_data); 175 } 176 177 void usbi_hotplug_match(struct libusb_context *ctx, struct libusb_device *dev, 178 libusb_hotplug_event event) 179 { 180 struct libusb_hotplug_callback *hotplug_cb, *next; 181 int ret; 182 183 usbi_mutex_lock(&ctx->hotplug_cbs_lock); 184 185 list_for_each_entry_safe(hotplug_cb, next, &ctx->hotplug_cbs, list, struct libusb_hotplug_callback) { 186 usbi_mutex_unlock(&ctx->hotplug_cbs_lock); 187 ret = usbi_hotplug_match_cb (ctx, dev, event, hotplug_cb); 188 usbi_mutex_lock(&ctx->hotplug_cbs_lock); 189 190 if (ret) { 191 list_del(&hotplug_cb->list); 192 free(hotplug_cb); 193 } 194 } 195 196 usbi_mutex_unlock(&ctx->hotplug_cbs_lock); 197 198 /* the backend is expected to call the callback for each active transfer */ 199 } 200 201 int API_EXPORTED libusb_hotplug_register_callback(libusb_context *ctx, 202 libusb_hotplug_event events, libusb_hotplug_flag flags, 203 int vendor_id, int product_id, int dev_class, 204 libusb_hotplug_callback_fn cb_fn, void *user_data, 205 libusb_hotplug_callback_handle *handle) 206 { 207 libusb_hotplug_callback *new_callback; 208 static int handle_id = 1; 209 210 /* check for hotplug support */ 211 if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG)) { 212 return LIBUSB_ERROR_NOT_SUPPORTED; 213 } 214 215 /* check for sane values */ 216 if ((LIBUSB_HOTPLUG_MATCH_ANY != vendor_id && (~0xffff & vendor_id)) || 217 (LIBUSB_HOTPLUG_MATCH_ANY != product_id && (~0xffff & product_id)) || 218 (LIBUSB_HOTPLUG_MATCH_ANY != dev_class && (~0xff & dev_class)) || 219 !cb_fn) { 220 return LIBUSB_ERROR_INVALID_PARAM; 221 } 222 223 USBI_GET_CONTEXT(ctx); 224 225 new_callback = (libusb_hotplug_callback *)calloc(1, sizeof (*new_callback)); 226 if (!new_callback) { 227 return LIBUSB_ERROR_NO_MEM; 228 } 229 230 new_callback->ctx = ctx; 231 new_callback->vendor_id = vendor_id; 232 new_callback->product_id = product_id; 233 new_callback->dev_class = dev_class; 234 new_callback->flags = flags; 235 new_callback->events = events; 236 new_callback->cb = cb_fn; 237 new_callback->user_data = user_data; 238 new_callback->needs_free = 0; 239 240 usbi_mutex_lock(&ctx->hotplug_cbs_lock); 241 242 /* protect the handle by the context hotplug lock. it doesn't matter if the same handle 243 * is used for different contexts only that the handle is unique for this context */ 244 new_callback->handle = handle_id++; 245 246 list_add(&new_callback->list, &ctx->hotplug_cbs); 247 248 usbi_mutex_unlock(&ctx->hotplug_cbs_lock); 249 250 251 if (flags & LIBUSB_HOTPLUG_ENUMERATE) { 252 int i, len; 253 struct libusb_device **devs; 254 255 len = (int) libusb_get_device_list(ctx, &devs); 256 if (len < 0) { 257 libusb_hotplug_deregister_callback(ctx, 258 new_callback->handle); 259 return len; 260 } 261 262 for (i = 0; i < len; i++) { 263 usbi_hotplug_match_cb(ctx, devs[i], 264 LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED, 265 new_callback); 266 } 267 268 libusb_free_device_list(devs, 1); 269 } 270 271 272 if (handle) { 273 *handle = new_callback->handle; 274 } 275 276 return LIBUSB_SUCCESS; 277 } 278 279 void API_EXPORTED libusb_hotplug_deregister_callback (struct libusb_context *ctx, 280 libusb_hotplug_callback_handle handle) 281 { 282 struct libusb_hotplug_callback *hotplug_cb; 283 libusb_hotplug_message message; 284 ssize_t ret; 285 286 /* check for hotplug support */ 287 if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG)) { 288 return; 289 } 290 291 USBI_GET_CONTEXT(ctx); 292 293 usbi_mutex_lock(&ctx->hotplug_cbs_lock); 294 list_for_each_entry(hotplug_cb, &ctx->hotplug_cbs, list, 295 struct libusb_hotplug_callback) { 296 if (handle == hotplug_cb->handle) { 297 /* Mark this callback for deregistration */ 298 hotplug_cb->needs_free = 1; 299 } 300 } 301 usbi_mutex_unlock(&ctx->hotplug_cbs_lock); 302 303 /* wakeup handle_events to do the actual free */ 304 memset(&message, 0, sizeof(message)); 305 ret = usbi_write(ctx->hotplug_pipe[1], &message, sizeof(message)); 306 if (sizeof(message) != ret) { 307 usbi_err(ctx, "error writing hotplug message"); 308 } 309 } 310 311 void usbi_hotplug_deregister_all(struct libusb_context *ctx) { 312 struct libusb_hotplug_callback *hotplug_cb, *next; 313 314 usbi_mutex_lock(&ctx->hotplug_cbs_lock); 315 list_for_each_entry_safe(hotplug_cb, next, &ctx->hotplug_cbs, list, 316 struct libusb_hotplug_callback) { 317 list_del(&hotplug_cb->list); 318 free(hotplug_cb); 319 } 320 321 usbi_mutex_unlock(&ctx->hotplug_cbs_lock); 322 } 323
