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
usbi_hotplug_match_cb(struct libusb_context * ctx,struct libusb_device * dev,libusb_hotplug_event event,struct libusb_hotplug_callback * hotplug_cb)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
usbi_hotplug_match(struct libusb_context * ctx,struct libusb_device * dev,libusb_hotplug_event event)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
usbi_hotplug_notification(struct libusb_context * ctx,struct libusb_device * dev,libusb_hotplug_event event)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
libusb_hotplug_register_callback(libusb_context * ctx,libusb_hotplug_event events,libusb_hotplug_flag flags,int vendor_id,int product_id,int dev_class,libusb_hotplug_callback_fn cb_fn,void * user_data,libusb_hotplug_callback_handle * callback_handle)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
libusb_hotplug_deregister_callback(struct libusb_context * ctx,libusb_hotplug_callback_handle callback_handle)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
usbi_hotplug_deregister_all(struct libusb_context * ctx)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