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#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.
63 *
64 * Callbacks for a particular context are automatically deregistered by libusb_exit().
65 *
66 * As of 1.0.16 there are two supported hotplug events:
67 *  - LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED: A device has arrived and is ready to use
68 *  - LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT: A device has left and is no longer available
69 *
70 * A hotplug event can listen for either or both of these events.
71 *
72 * Note: If you receive notification that a device has left and you have any
73 * a libusb_device_handles for the device it is up to you to call libusb_close()
74 * on each handle to free up any remaining resources associated with the device.
75 * Once a device has left any libusb_device_handle associated with the device
76 * are invalid and will remain so even if the device comes back.
77 *
78 * When handling a LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED event it is considered
79 * safe to call any libusbx function that takes a libusb_device. On the other hand,
80 * when handling a LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT event the only safe function
81 * is libusb_get_device_descriptor().
82 *
83 * The following code provides an example of the usage of the hotplug interface:
84\code
85static int count = 0;
86
87int hotplug_callback(struct libusb_context *ctx, struct libusb_device *dev,
88                     libusb_hotplug_event event, void *user_data) {
89  static libusb_device_handle *handle = NULL;
90  struct libusb_device_descriptor desc;
91  int rc;
92
93  (void)libusb_get_device_descriptor(dev, &desc);
94
95  if (LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED == event) {
96    rc = libusb_open(dev, &handle);
97    if (LIBUSB_SUCCESS != rc) {
98      printf("Could not open USB device\n");
99    }
100  } else if (LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT == event) {
101    if (handle) {
102      libusb_close(handle);
103      handle = NULL;
104    }
105  } else {
106    printf("Unhandled event %d\n", event);
107  }
108  count++;
109
110  return 0;
111}
112
113int main (void) {
114  libusb_hotplug_callback_handle handle;
115  int rc;
116
117  libusb_init(NULL);
118
119  rc = libusb_hotplug_register_callback(NULL, LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED |
120                                        LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT, 0, 0x045a, 0x5005,
121                                        LIBUSB_HOTPLUG_MATCH_ANY, hotplug_callback, NULL,
122                                        &handle);
123  if (LIBUSB_SUCCESS != rc) {
124    printf("Error creating a hotplug callback\n");
125    libusb_exit(NULL);
126    return EXIT_FAILURE;
127  }
128
129  while (count < 2) {
130    usleep(10000);
131  }
132
133  libusb_hotplug_deregister_callback(handle);
134  libusb_exit(NULL);
135
136  return 0;
137}
138\endcode
139 */
140
141static int usbi_hotplug_match_cb (struct libusb_context *ctx,
142	struct libusb_device *dev, libusb_hotplug_event event,
143	struct libusb_hotplug_callback *hotplug_cb)
144{
145	/* Handle lazy deregistration of callback */
146	if (hotplug_cb->needs_free) {
147		/* Free callback */
148		return 1;
149	}
150
151	if (!(hotplug_cb->events & event)) {
152		return 0;
153	}
154
155	if (LIBUSB_HOTPLUG_MATCH_ANY != hotplug_cb->vendor_id &&
156	    hotplug_cb->vendor_id != dev->device_descriptor.idVendor) {
157		return 0;
158	}
159
160	if (LIBUSB_HOTPLUG_MATCH_ANY != hotplug_cb->product_id &&
161	    hotplug_cb->product_id != dev->device_descriptor.idProduct) {
162		return 0;
163	}
164
165	if (LIBUSB_HOTPLUG_MATCH_ANY != hotplug_cb->dev_class &&
166	    hotplug_cb->dev_class != dev->device_descriptor.bDeviceClass) {
167		return 0;
168	}
169
170	return hotplug_cb->cb (ctx == usbi_default_context ? NULL : ctx,
171			       dev, event, hotplug_cb->user_data);
172}
173
174void usbi_hotplug_match(struct libusb_context *ctx, struct libusb_device *dev,
175	libusb_hotplug_event event)
176{
177	struct libusb_hotplug_callback *hotplug_cb, *next;
178	int ret;
179
180	usbi_mutex_lock(&ctx->hotplug_cbs_lock);
181
182	list_for_each_entry_safe(hotplug_cb, next, &ctx->hotplug_cbs, list, struct libusb_hotplug_callback) {
183		usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
184		ret = usbi_hotplug_match_cb (ctx, dev, event, hotplug_cb);
185		usbi_mutex_lock(&ctx->hotplug_cbs_lock);
186
187		if (ret) {
188			list_del(&hotplug_cb->list);
189			free(hotplug_cb);
190		}
191	}
192
193	usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
194
195	/* loop through and disconnect all open handles for this device */
196	if (LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT == event) {
197		struct libusb_device_handle *handle;
198
199		usbi_mutex_lock(&ctx->open_devs_lock);
200		list_for_each_entry(handle, &ctx->open_devs, list, struct libusb_device_handle) {
201			if (dev == handle->dev) {
202				usbi_handle_disconnect (handle);
203			}
204		}
205		usbi_mutex_unlock(&ctx->open_devs_lock);
206	}
207}
208
209int API_EXPORTED libusb_hotplug_register_callback(libusb_context *ctx,
210	libusb_hotplug_event events, libusb_hotplug_flag flags,
211	int vendor_id, int product_id, int dev_class,
212	libusb_hotplug_callback_fn cb_fn, void *user_data,
213	libusb_hotplug_callback_handle *handle)
214{
215	libusb_hotplug_callback *new_callback;
216	static int handle_id = 1;
217
218	/* check for hotplug support */
219	if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG)) {
220		return LIBUSB_ERROR_NOT_SUPPORTED;
221	}
222
223	/* check for sane values */
224	if ((LIBUSB_HOTPLUG_MATCH_ANY != vendor_id && (~0xffff & vendor_id)) ||
225	    (LIBUSB_HOTPLUG_MATCH_ANY != product_id && (~0xffff & product_id)) ||
226	    (LIBUSB_HOTPLUG_MATCH_ANY != dev_class && (~0xff & dev_class)) ||
227	    !cb_fn) {
228		return LIBUSB_ERROR_INVALID_PARAM;
229	}
230
231	USBI_GET_CONTEXT(ctx);
232
233	new_callback = (libusb_hotplug_callback *)calloc(1, sizeof (*new_callback));
234	if (!new_callback) {
235		return LIBUSB_ERROR_NO_MEM;
236	}
237
238	new_callback->ctx = ctx;
239	new_callback->vendor_id = vendor_id;
240	new_callback->product_id = product_id;
241	new_callback->dev_class = dev_class;
242	new_callback->flags = flags;
243	new_callback->events = events;
244	new_callback->cb = cb_fn;
245	new_callback->user_data = user_data;
246	new_callback->needs_free = 0;
247
248	usbi_mutex_lock(&ctx->hotplug_cbs_lock);
249
250	/* protect the handle by the context hotplug lock. it doesn't matter if the same handle
251	 * is used for different contexts only that the handle is unique for this context */
252	new_callback->handle = handle_id++;
253
254	list_add(&new_callback->list, &ctx->hotplug_cbs);
255
256	if (flags & LIBUSB_HOTPLUG_ENUMERATE) {
257		struct libusb_device *dev;
258
259		usbi_mutex_lock(&ctx->usb_devs_lock);
260
261		list_for_each_entry(dev, &ctx->usb_devs, list, struct libusb_device) {
262			(void) usbi_hotplug_match_cb (ctx, dev, LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED, new_callback);
263		}
264
265		usbi_mutex_unlock(&ctx->usb_devs_lock);
266	}
267
268	usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
269
270	if (handle) {
271		*handle = new_callback->handle;
272	}
273
274	return LIBUSB_SUCCESS;
275}
276
277void API_EXPORTED libusb_hotplug_deregister_callback (struct libusb_context *ctx,
278	libusb_hotplug_callback_handle handle)
279{
280	struct libusb_hotplug_callback *hotplug_cb;
281	libusb_hotplug_message message;
282	ssize_t ret;
283
284	/* check for hotplug support */
285	if (!libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG)) {
286		return;
287	}
288
289	USBI_GET_CONTEXT(ctx);
290
291	usbi_mutex_lock(&ctx->hotplug_cbs_lock);
292	list_for_each_entry(hotplug_cb, &ctx->hotplug_cbs, list,
293			    struct libusb_hotplug_callback) {
294		if (handle == hotplug_cb->handle) {
295			/* Mark this callback for deregistration */
296			hotplug_cb->needs_free = 1;
297		}
298	}
299	usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
300
301	/* wakeup handle_events to do the actual free */
302	memset(&message, 0, sizeof(message));
303	ret = usbi_write(ctx->hotplug_pipe[1], &message, sizeof(message));
304	if (sizeof(message) != ret) {
305		usbi_err(ctx, "error writing hotplug message");
306	}
307}
308
309void usbi_hotplug_deregister_all(struct libusb_context *ctx) {
310	struct libusb_hotplug_callback *hotplug_cb, *next;
311
312	usbi_mutex_lock(&ctx->hotplug_cbs_lock);
313	list_for_each_entry_safe(hotplug_cb, next, &ctx->hotplug_cbs, list,
314				 struct libusb_hotplug_callback) {
315		list_del(&hotplug_cb->list);
316		free(hotplug_cb);
317	}
318
319	usbi_mutex_unlock(&ctx->hotplug_cbs_lock);
320}
321