libusb/hotplug.c

   1 /* -*- Mode: C; indent-tabs-mode:t ; c-basic-offset:8 -*- */
   2 /*
   3  * Hotplug functions for libusbx
   4  * Copyright © 2012-2013 Nathan Hjelm <hjelmn@mac.com>
   5  * Copyright © 2012-2013 Peter Stuge <peter@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 #include <sys/types.h>
  29 #include <assert.h>
  30
  31 #include "libusbi.h"
  32 #include "hotplug.h"
  33
  34 /**
  35  * @defgroup hotplug  Device hotplug event notification
  36  * This page details how to use the libusb hotplug interface.
  37  *
  38  * \page hotplug Device hotplug event notification
  39  *
  40  * \section intro Introduction
  41  *
  42  * Version 1.0.16, \ref LIBUSBX_API_VERSION >= 0x01000102, has added support
  43  * for hotplug events. This interface allows you to request notification for
  44  * the arrival and departure of matching USB devices.
  45  *
  46  * To receive hotplug notification you register a callback by calling
  47  * libusb_hotplug_register_callback(). This function will optionally return
  48  * a handle that can be passed to libusb_hotplug_deregister_callback().
  49  *
  50  * A callback function must return an int (0 or 1) indicating whether the callback is
  51  * expecting additional events. Returning 0 will rearm the callback and 1 will cause
  52  * the callback to be deregistered.
  53  *
  54  * Callbacks for a particulat context are automatically deregistered by libusb_exit().
  55  *
  56  * As of 1.0.16 there are two supported hotplug events:
  57  *  - LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED: A device has arrived and is ready to use
  58  *  - LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT: A device has left and is no longer available
  59  *
  60  * A hotplug event can listen for either or both of these events.
  61  *
  62  * Note: If you receive notification that a device has left and you have any
  63  * a libusb_device_handles for the device it is up to you to call libusb_close()
  64  * on each handle to free up any remaining resources associated with the device.
  65  * Once a device has left any libusb_device_handle associated with the device
  66  * are invalid and will remain so even if the device comes back.
  67  *
  68  * When handling a LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED event it is considered
  69  * safe to call any libusbx function that takes a libusb_device. On the other hand,
  70  * when handling a LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT event the only safe function
  71  * is libusb_get_device_descriptor().
  72  *
  73  * The following code provides an example of the usage of the hotplug interface:
  74 \code
  75 static int count = 0;
  76
  77 int hotplug_callback(struct libusb_context *ctx, struct libusb_device *dev,
  78                      libusb_hotplug_event event, void *user_data) {
  79   static libusb_device_handle *handle = NULL;
  80   struct libusb_device_descriptor desc;
  81   int rc;
  82
  83   (void)libusb_get_device_descriptor(dev, &desc);
  84
  85   if (LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED == event) {
  86     rc = libusb_open(dev, &handle);
  87     if (LIBUSB_SUCCESS != rc) {
  88       printf("Could not open USB device\n");
  89     }
  90   } else if (LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT == event) {
  91     if (handle) {
  92       libusb_close(handle);
  93       handle = NULL;
  94     }
  95   } else {
  96     printf("Unhandled event %d\n", event);
  97   }
  98   count++;
  99
 100   return 0;
 101 }
 102
 103 int main (void) {
 104   libusb_hotplug_callback_handle handle;
 105   int rc;
 106
 107   libusb_init(NULL);
 108
 109   rc = libusb_hotplug_register_callback(NULL, LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED |
 110                                         LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT, 0, 0x045a, 0x5005,
 111                                         LIBUSB_HOTPLUG_MATCH_ANY, hotplug_callback, NULL,
 112                                         &handle);
 113   if (LIBUSB_SUCCESS != rc) {
 114     printf("Error creating a hotplug callback\n");
 115     libusb_exit(NULL);
 116     return EXIT_FAILURE;
 117   }
 118
 119   while (count < 2) {
 120     usleep(10000);
 121   }
 122
 123   libusb_hotplug_deregister_callback(handle);
 124   libusb_exit(NULL);
 125
 126   return 0;
 127 }
 128 \endcode
 129  */
 130
 131 static int usbi_hotplug_match_cb (struct libusb_device *dev, libusb_hotplug_event event,
 132                                    struct libusb_hotplug_callback *hotplug_cb)
 133 {
 134         struct libusb_context *ctx = dev->ctx;
 135
 136         /* Handle lazy deregistration of callback */
 137         if (hotplug_cb->needs_free) {
 138                 /* Free callback */
 139                 return 1;
 140         }
 141
 142         if (!(hotplug_cb->events & event)) {
 143                 return 0;
 144         }
 145
 146         if (LIBUSB_HOTPLUG_MATCH_ANY != hotplug_cb->vendor_id &&
 147             hotplug_cb->vendor_id != dev->device_descriptor.idVendor) {
 148                 return 0;
 149         }
 150
 151         if (LIBUSB_HOTPLUG_MATCH_ANY != hotplug_cb->product_id &&
 152             hotplug_cb->product_id != dev->device_descriptor.idProduct) {
 153                 return 0;
 154         }
 155
 156         if (LIBUSB_HOTPLUG_MATCH_ANY != hotplug_cb->dev_class &&
 157             hotplug_cb->dev_class != dev->device_descriptor.bDeviceClass) {
 158                 return 0;
 159         }
 160
 161         return hotplug_cb->cb (ctx == usbi_default_context ? NULL : ctx,
 162                                dev, event, hotplug_cb->user_data);
 163 }
 164
 165 void usbi_hotplug_match(struct libusb_device *dev, libusb_hotplug_event event)
 166 {
 167         struct libusb_hotplug_callback *hotplug_cb, *next;
 168         struct libusb_context *ctx = dev->ctx;
 169         int ret;
 170
 171         usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 172
 173         list_for_each_entry_safe(hotplug_cb, next, &ctx->hotplug_cbs, list, struct libusb_hotplug_callback) {
 174                 usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 175                 ret = usbi_hotplug_match_cb (dev, event, hotplug_cb);
 176                 usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 177
 178                 if (ret) {
 179                         list_del(&hotplug_cb->list);
 180                         free(hotplug_cb);
 181                 }
 182         }
 183
 184         usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 185
 186         /* loop through and disconnect all open handles for this device */
 187         if (LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT == event) {
 188                 struct libusb_device_handle *handle;
 189
 190                 usbi_mutex_lock(&ctx->open_devs_lock);
 191                 list_for_each_entry(handle, &ctx->open_devs, list, struct libusb_device_handle) {
 192                         if (dev == handle->dev) {
 193                                 usbi_handle_disconnect (handle);
 194                         }
 195                 }
 196                 usbi_mutex_unlock(&ctx->open_devs_lock);
 197         }
 198 }
 199
 200 int API_EXPORTED libusb_hotplug_register_callback(libusb_context *ctx,
 201         libusb_hotplug_event events, libusb_hotplug_flag flags,
 202         int vendor_id, int product_id, int dev_class,
 203         libusb_hotplug_callback_fn cb_fn, void *user_data,
 204         libusb_hotplug_callback_handle *handle)
 205 {
 206         libusb_hotplug_callback *new_callback;
 207         static int handle_id = 1;
 208
 209         /* check for hotplug support */
 210         if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG)) {
 211                 return LIBUSB_ERROR_NOT_SUPPORTED;
 212         }
 213
 214         /* check for sane values */
 215         if ((LIBUSB_HOTPLUG_MATCH_ANY != vendor_id && (~0xffff & vendor_id)) ||
 216             (LIBUSB_HOTPLUG_MATCH_ANY != product_id && (~0xffff & product_id)) ||
 217             (LIBUSB_HOTPLUG_MATCH_ANY != dev_class && (~0xff & dev_class)) ||
 218             !cb_fn) {
 219                 return LIBUSB_ERROR_INVALID_PARAM;
 220         }
 221
 222         USBI_GET_CONTEXT(ctx);
 223
 224         new_callback = (libusb_hotplug_callback *)calloc(1, sizeof (*new_callback));
 225         if (!new_callback) {
 226                 return LIBUSB_ERROR_NO_MEM;
 227         }
 228
 229         new_callback->ctx = ctx;
 230         new_callback->vendor_id = vendor_id;
 231         new_callback->product_id = product_id;
 232         new_callback->dev_class = dev_class;
 233         new_callback->flags = flags;
 234         new_callback->events = events;
 235         new_callback->cb = cb_fn;
 236         new_callback->user_data = user_data;
 237         new_callback->needs_free = 0;
 238
 239         usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 240
 241         /* protect the handle by the context hotplug lock. it doesn't matter if the same handle
 242          * is used for different contexts only that the handle is unique for this context */
 243         new_callback->handle = handle_id++;
 244
 245         list_add(&new_callback->list, &ctx->hotplug_cbs);
 246
 247         if (flags & LIBUSB_HOTPLUG_ENUMERATE) {
 248                 struct libusb_device *dev;
 249
 250                 usbi_mutex_lock(&ctx->usb_devs_lock);
 251
 252                 list_for_each_entry(dev, &ctx->usb_devs, list, struct libusb_device) {
 253                         (void) usbi_hotplug_match_cb (dev, LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED, new_callback);
 254                 }
 255
 256                 usbi_mutex_unlock(&ctx->usb_devs_lock);
 257         }
 258
 259         usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 260
 261         if (handle) {
 262                 *handle = new_callback->handle;
 263         }
 264
 265         return LIBUSB_SUCCESS;
 266 }
 267
 268 void API_EXPORTED libusb_hotplug_deregister_callback (struct libusb_context *ctx,
 269         libusb_hotplug_callback_handle handle)
 270 {
 271         struct libusb_hotplug_callback *hotplug_cb;
 272
 273         /* check for hotplug support */
 274         if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG)) {
 275                 return;
 276         }
 277
 278         USBI_GET_CONTEXT(ctx);
 279
 280         usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 281         list_for_each_entry(hotplug_cb, &ctx->hotplug_cbs, list,
 282                             struct libusb_hotplug_callback) {
 283                 if (handle == hotplug_cb->handle) {
 284                         /* Mark this callback for deregistration */
 285                         hotplug_cb->needs_free = 1;
 286                 }
 287         }
 288         usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 289 }
 290
 291 void usbi_hotplug_deregister_all(struct libusb_context *ctx) {
 292         struct libusb_hotplug_callback *hotplug_cb, *next;
 293
 294         usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 295         list_for_each_entry_safe(hotplug_cb, next, &ctx->hotplug_cbs, list,
 296                                  struct libusb_hotplug_callback) {
 297                 list_del(&hotplug_cb->list);
 298                 free(hotplug_cb);
 299         }
 300
 301         usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 302 }