app/src/main/jni/libusb-1.0.22/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 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         if (!(hotplug_cb->flags & event)) {
 162                 return 0;
 163         }
 164
 165         if ((hotplug_cb->flags & USBI_HOTPLUG_VENDOR_ID_VALID) &&
 166             hotplug_cb->vendor_id != dev->device_descriptor.idVendor) {
 167                 return 0;
 168         }
 169
 170         if ((hotplug_cb->flags & USBI_HOTPLUG_PRODUCT_ID_VALID) &&
 171             hotplug_cb->product_id != dev->device_descriptor.idProduct) {
 172                 return 0;
 173         }
 174
 175         if ((hotplug_cb->flags & USBI_HOTPLUG_DEV_CLASS_VALID) &&
 176             hotplug_cb->dev_class != dev->device_descriptor.bDeviceClass) {
 177                 return 0;
 178         }
 179
 180         return hotplug_cb->cb(ctx, dev, event, hotplug_cb->user_data);
 181 }
 182
 183 void usbi_hotplug_match(struct libusb_context *ctx, struct libusb_device *dev,
 184         libusb_hotplug_event event)
 185 {
 186         struct libusb_hotplug_callback *hotplug_cb, *next;
 187         int ret;
 188
 189         usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 190
 191         list_for_each_entry_safe(hotplug_cb, next, &ctx->hotplug_cbs, list, struct libusb_hotplug_callback) {
 192                 if (hotplug_cb->flags & USBI_HOTPLUG_NEEDS_FREE) {
 193                         /* process deregistration in usbi_hotplug_deregister() */
 194                         continue;
 195                 }
 196
 197                 usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 198                 ret = usbi_hotplug_match_cb(ctx, dev, event, hotplug_cb);
 199                 usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 200
 201                 if (ret) {
 202                         list_del(&hotplug_cb->list);
 203                         free(hotplug_cb);
 204                 }
 205         }
 206
 207         usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 208 }
 209
 210 void usbi_hotplug_notification(struct libusb_context *ctx, struct libusb_device *dev,
 211         libusb_hotplug_event event)
 212 {
 213         int pending_events;
 214         struct libusb_hotplug_message *message = calloc(1, sizeof(*message));
 215
 216         if (!message) {
 217                 usbi_err(ctx, "error allocating hotplug message");
 218                 return;
 219         }
 220
 221         message->event = event;
 222         message->device = dev;
 223
 224         /* Take the event data lock and add this message to the list.
 225          * Only signal an event if there are no prior pending events. */
 226         usbi_mutex_lock(&ctx->event_data_lock);
 227         pending_events = usbi_pending_events(ctx);
 228         list_add_tail(&message->list, &ctx->hotplug_msgs);
 229         if (!pending_events)
 230                 usbi_signal_event(ctx);
 231         usbi_mutex_unlock(&ctx->event_data_lock);
 232 }
 233
 234 int API_EXPORTED libusb_hotplug_register_callback(libusb_context *ctx,
 235         libusb_hotplug_event events, libusb_hotplug_flag flags,
 236         int vendor_id, int product_id, int dev_class,
 237         libusb_hotplug_callback_fn cb_fn, void *user_data,
 238         libusb_hotplug_callback_handle *callback_handle)
 239 {
 240         struct libusb_hotplug_callback *new_callback;
 241
 242         /* check for sane values */
 243         if ((!events || (~(LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED | LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT) & events)) ||
 244             (flags && (~LIBUSB_HOTPLUG_ENUMERATE & flags)) ||
 245             (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         /* check for hotplug support */
 253         if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG)) {
 254                 return LIBUSB_ERROR_NOT_SUPPORTED;
 255         }
 256
 257         USBI_GET_CONTEXT(ctx);
 258
 259         new_callback = calloc(1, sizeof(*new_callback));
 260         if (!new_callback) {
 261                 return LIBUSB_ERROR_NO_MEM;
 262         }
 263
 264         new_callback->flags = (uint8_t)events;
 265         if (LIBUSB_HOTPLUG_MATCH_ANY != vendor_id) {
 266                 new_callback->flags |= USBI_HOTPLUG_VENDOR_ID_VALID;
 267                 new_callback->vendor_id = (uint16_t)vendor_id;
 268         }
 269         if (LIBUSB_HOTPLUG_MATCH_ANY != product_id) {
 270                 new_callback->flags |= USBI_HOTPLUG_PRODUCT_ID_VALID;
 271                 new_callback->product_id = (uint16_t)product_id;
 272         }
 273         if (LIBUSB_HOTPLUG_MATCH_ANY != dev_class) {
 274                 new_callback->flags |= USBI_HOTPLUG_DEV_CLASS_VALID;
 275                 new_callback->dev_class = (uint8_t)dev_class;
 276         }
 277         new_callback->cb = cb_fn;
 278         new_callback->user_data = user_data;
 279
 280         usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 281
 282         /* protect the handle by the context hotplug lock */
 283         new_callback->handle = ctx->next_hotplug_cb_handle++;
 284
 285         /* handle the unlikely case of overflow */
 286         if (ctx->next_hotplug_cb_handle < 0)
 287                 ctx->next_hotplug_cb_handle = 1;
 288
 289         list_add(&new_callback->list, &ctx->hotplug_cbs);
 290
 291         usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 292
 293         usbi_dbg("new hotplug cb %p with handle %d", new_callback, new_callback->handle);
 294
 295         if ((flags & LIBUSB_HOTPLUG_ENUMERATE) && (events & LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED)) {
 296                 ssize_t i, len;
 297                 struct libusb_device **devs;
 298
 299                 len = libusb_get_device_list(ctx, &devs);
 300                 if (len < 0) {
 301                         libusb_hotplug_deregister_callback(ctx,
 302                                                         new_callback->handle);
 303                         return (int)len;
 304                 }
 305
 306                 for (i = 0; i < len; i++) {
 307                         usbi_hotplug_match_cb(ctx, devs[i],
 308                                         LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED,
 309                                         new_callback);
 310                 }
 311
 312                 libusb_free_device_list(devs, 1);
 313         }
 314
 315
 316         if (callback_handle)
 317                 *callback_handle = new_callback->handle;
 318
 319         return LIBUSB_SUCCESS;
 320 }
 321
 322 void API_EXPORTED libusb_hotplug_deregister_callback(struct libusb_context *ctx,
 323         libusb_hotplug_callback_handle callback_handle)
 324 {
 325         struct libusb_hotplug_callback *hotplug_cb;
 326         int deregistered = 0;
 327
 328         /* check for hotplug support */
 329         if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG)) {
 330                 return;
 331         }
 332
 333         USBI_GET_CONTEXT(ctx);
 334
 335         usbi_dbg("deregister hotplug cb %d", callback_handle);
 336
 337         usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 338         list_for_each_entry(hotplug_cb, &ctx->hotplug_cbs, list, struct libusb_hotplug_callback) {
 339                 if (callback_handle == hotplug_cb->handle) {
 340                         /* Mark this callback for deregistration */
 341                         hotplug_cb->flags |= USBI_HOTPLUG_NEEDS_FREE;
 342                         deregistered = 1;
 343                 }
 344         }
 345         usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 346
 347         if (deregistered) {
 348                 int pending_events;
 349
 350                 usbi_mutex_lock(&ctx->event_data_lock);
 351                 pending_events = usbi_pending_events(ctx);
 352                 ctx->event_flags |= USBI_EVENT_HOTPLUG_CB_DEREGISTERED;
 353                 if (!pending_events)
 354                         usbi_signal_event(ctx);
 355                 usbi_mutex_unlock(&ctx->event_data_lock);
 356         }
 357 }
 358
 359 void usbi_hotplug_deregister(struct libusb_context *ctx, int forced)
 360 {
 361         struct libusb_hotplug_callback *hotplug_cb, *next;
 362
 363         usbi_mutex_lock(&ctx->hotplug_cbs_lock);
 364         list_for_each_entry_safe(hotplug_cb, next, &ctx->hotplug_cbs, list, struct libusb_hotplug_callback) {
 365                 if (forced || (hotplug_cb->flags & USBI_HOTPLUG_NEEDS_FREE)) {
 366                         usbi_dbg("freeing hotplug cb %p with handle %d", hotplug_cb,
 367                                  hotplug_cb->handle);
 368                         list_del(&hotplug_cb->list);
 369                         free(hotplug_cb);
 370                 }
 371         }
 372         usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
 373 }