libusb/hotplug.c

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