eXpand your USB potential
libusb.h
1 /*
2  * Public libusb header file
3  * Copyright © 2001 Johannes Erdfelt <johannes@erdfelt.com>
4  * Copyright © 2007-2008 Daniel Drake <dsd@gentoo.org>
5  * Copyright © 2012 Pete Batard <pete@akeo.ie>
6  * Copyright © 2012 Nathan Hjelm <hjelmn@cs.unm.edu>
7  * For more information, please visit: http://libusb.info
8  *
9  * This library is free software; you can redistribute it and/or
10  * modify it under the terms of the GNU Lesser General Public
11  * License as published by the Free Software Foundation; either
12  * version 2.1 of the License, or (at your option) any later version.
13  *
14  * This library is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17  * Lesser General Public License for more details.
18  *
19  * You should have received a copy of the GNU Lesser General Public
20  * License along with this library; if not, write to the Free Software
21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
22  */
23 
24 #ifndef LIBUSB_H
25 #define LIBUSB_H
26 
27 #ifdef _MSC_VER
28 /* on MS environments, the inline keyword is available in C++ only */
29 #if !defined(__cplusplus)
30 #define inline __inline
31 #endif
32 /* ssize_t is also not available (copy/paste from MinGW) */
33 #ifndef _SSIZE_T_DEFINED
34 #define _SSIZE_T_DEFINED
35 #undef ssize_t
36 #ifdef _WIN64
37  typedef __int64 ssize_t;
38 #else
39  typedef int ssize_t;
40 #endif /* _WIN64 */
41 #endif /* _SSIZE_T_DEFINED */
42 #endif /* _MSC_VER */
43 
44 /* stdint.h is not available on older MSVC */
45 #if defined(_MSC_VER) && (_MSC_VER < 1600) && (!defined(_STDINT)) && (!defined(_STDINT_H))
46 typedef unsigned __int8 uint8_t;
47 typedef unsigned __int16 uint16_t;
48 typedef unsigned __int32 uint32_t;
49 #else
50 #include <stdint.h>
51 #endif
52 
53 #if !defined(_WIN32_WCE)
54 #include <sys/types.h>
55 #endif
56 
57 #if defined(__linux) || defined(__APPLE__) || defined(__CYGWIN__)
58 #include <sys/time.h>
59 #endif
60 
61 #include <time.h>
62 #include <limits.h>
63 
64 /* 'interface' might be defined as a macro on Windows, so we need to
65  * undefine it so as not to break the current libusb API, because
66  * libusb_config_descriptor has an 'interface' member
67  * As this can be problematic if you include windows.h after libusb.h
68  * in your sources, we force windows.h to be included first. */
69 #if defined(_WIN32) || defined(__CYGWIN__) || defined(_WIN32_WCE)
70 #include <windows.h>
71 #if defined(interface)
72 #undef interface
73 #endif
74 #if !defined(__CYGWIN__)
75 #include <winsock.h>
76 #endif
77 #endif
78 
79 #if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5)
80 #define LIBUSB_DEPRECATED_FOR(f) \
81  __attribute__((deprecated("Use " #f " instead")))
82 #else
83 #define LIBUSB_DEPRECATED_FOR(f)
84 #endif /* __GNUC__ */
85 
111 /* LIBUSB_CALL must be defined on both definition and declaration of libusb
112  * functions. You'd think that declaration would be enough, but cygwin will
113  * complain about conflicting types unless both are marked this way.
114  * The placement of this macro is important too; it must appear after the
115  * return type, before the function name. See internal documentation for
116  * API_EXPORTED.
117  */
118 #if defined(_WIN32) || defined(__CYGWIN__) || defined(_WIN32_WCE)
119 #define LIBUSB_CALL WINAPI
120 #else
121 #define LIBUSB_CALL
122 #endif
123 
147 #define LIBUSB_API_VERSION 0x01000102
148 
149 /* The following is kept for compatibility, but will be deprecated in the future */
150 #define LIBUSBX_API_VERSION LIBUSB_API_VERSION
151 
152 #ifdef __cplusplus
153 extern "C" {
154 #endif
155 
164 static inline uint16_t libusb_cpu_to_le16(const uint16_t x)
165 {
166  union {
167  uint8_t b8[2];
168  uint16_t b16;
169  } _tmp;
170  _tmp.b8[1] = (uint8_t) (x >> 8);
171  _tmp.b8[0] = (uint8_t) (x & 0xff);
172  return _tmp.b16;
173 }
174 
183 #define libusb_le16_to_cpu libusb_cpu_to_le16
184 
185 /* standard USB stuff */
186 
195 
198 
201 
204 
207 
210 
212  LIBUSB_CLASS_PTP = 6, /* legacy name from libusb-0.1 usb.h */
213  LIBUSB_CLASS_IMAGE = 6,
214 
217 
220 
223 
226 
229 
232 
235 
238 
241 
244 
247 };
248 
254 
257 
260 
263 
266 
269 
272 
275 
278 
281 
284 
287 
290 };
291 
292 /* Descriptor sizes per descriptor type */
293 #define LIBUSB_DT_DEVICE_SIZE 18
294 #define LIBUSB_DT_CONFIG_SIZE 9
295 #define LIBUSB_DT_INTERFACE_SIZE 9
296 #define LIBUSB_DT_ENDPOINT_SIZE 7
297 #define LIBUSB_DT_ENDPOINT_AUDIO_SIZE 9 /* Audio extension */
298 #define LIBUSB_DT_HUB_NONVAR_SIZE 7
299 #define LIBUSB_DT_SS_ENDPOINT_COMPANION_SIZE 6
300 #define LIBUSB_DT_BOS_SIZE 5
301 #define LIBUSB_DT_DEVICE_CAPABILITY_SIZE 3
302 
303 /* BOS descriptor sizes */
304 #define LIBUSB_BT_USB_2_0_EXTENSION_SIZE 7
305 #define LIBUSB_BT_SS_USB_DEVICE_CAPABILITY_SIZE 10
306 #define LIBUSB_BT_CONTAINER_ID_SIZE 20
307 
308 /* We unwrap the BOS => define its max size */
309 #define LIBUSB_DT_BOS_MAX_SIZE ((LIBUSB_DT_BOS_SIZE) +\
310  (LIBUSB_BT_USB_2_0_EXTENSION_SIZE) +\
311  (LIBUSB_BT_SS_USB_DEVICE_CAPABILITY_SIZE) +\
312  (LIBUSB_BT_CONTAINER_ID_SIZE))
313 
314 #define LIBUSB_ENDPOINT_ADDRESS_MASK 0x0f /* in bEndpointAddress */
315 #define LIBUSB_ENDPOINT_DIR_MASK 0x80
316 
324 
327 };
328 
329 #define LIBUSB_TRANSFER_TYPE_MASK 0x03 /* in bmAttributes */
330 
338 
341 
344 
347 };
348 
354 
357 
358  /* 0x02 is reserved */
359 
362 
363  /* 0x04 is reserved */
364 
367 
370 
373 
376 
379 
382 
385 
388 
391 
395 };
396 
404 
407 
410 
413 };
414 
422 
425 
428 
431 };
432 
433 #define LIBUSB_ISO_SYNC_TYPE_MASK 0x0C
434 
443 
446 
449 
452 };
453 
454 #define LIBUSB_ISO_USAGE_TYPE_MASK 0x30
455 
464 
467 
470 };
471 
479  uint8_t bLength;
480 
485 
488  uint16_t bcdUSB;
489 
491  uint8_t bDeviceClass;
492 
496 
500 
503 
505  uint16_t idVendor;
506 
508  uint16_t idProduct;
509 
511  uint16_t bcdDevice;
512 
514  uint8_t iManufacturer;
515 
517  uint8_t iProduct;
518 
520  uint8_t iSerialNumber;
521 
524 };
525 
533  uint8_t bLength;
534 
539 
545 
553  uint8_t bmAttributes;
554 
556  uint16_t wMaxPacketSize;
557 
559  uint8_t bInterval;
560 
563  uint8_t bRefresh;
564 
566  uint8_t bSynchAddress;
567 
570  const unsigned char *extra;
571 
574 };
575 
583  uint8_t bLength;
584 
589 
592 
595 
598  uint8_t bNumEndpoints;
599 
602 
606 
610 
612  uint8_t iInterface;
613 
617 
620  const unsigned char *extra;
621 
624 };
625 
633 
636 };
637 
645  uint8_t bLength;
646 
651 
653  uint16_t wTotalLength;
654 
656  uint8_t bNumInterfaces;
657 
660 
662  uint8_t iConfiguration;
663 
665  uint8_t bmAttributes;
666 
670  uint8_t MaxPower;
671 
675 
678  const unsigned char *extra;
679 
682 };
683 
691 
693  uint8_t bLength;
694 
699 
700 
703  uint8_t bMaxBurst;
704 
709  uint8_t bmAttributes;
710 
714 };
715 
723  uint8_t bLength;
731  uint8_t dev_capability_data
732 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
733  [] /* valid C99 code */
734 #else
735  [0] /* non-standard, but usually working code */
736 #endif
737  ;
738 };
739 
747  uint8_t bLength;
748 
753 
755  uint16_t wTotalLength;
756 
759  uint8_t bNumDeviceCaps;
760 
763 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
764  [] /* valid C99 code */
765 #else
766  [0] /* non-standard, but usually working code */
767 #endif
768  ;
769 };
770 
778  uint8_t bLength;
779 
784 
789 
794  uint32_t bmAttributes;
795 };
796 
804  uint8_t bLength;
805 
810 
815 
820  uint8_t bmAttributes;
821 
824  uint16_t wSpeedSupported;
825 
831 
833  uint8_t bU1DevExitLat;
834 
836  uint16_t bU2DevExitLat;
837 };
838 
846  uint8_t bLength;
847 
852 
857 
859  uint8_t bReserved;
860 
862  uint8_t ContainerID[16];
863 };
864 
873  uint8_t bmRequestType;
874 
880  uint8_t bRequest;
881 
883  uint16_t wValue;
884 
887  uint16_t wIndex;
888 
890  uint16_t wLength;
891 };
892 
893 #define LIBUSB_CONTROL_SETUP_SIZE (sizeof(struct libusb_control_setup))
894 
895 /* libusb */
896 
897 struct libusb_context;
898 struct libusb_device;
899 struct libusb_device_handle;
900 struct libusb_hotplug_callback;
901 
907  const uint16_t major;
908 
910  const uint16_t minor;
911 
913  const uint16_t micro;
914 
916  const uint16_t nano;
917 
919  const char *rc;
920 
922  const char* describe;
923 };
924 
943 
960 
961 
971 
978 
981 
984 
987 
990 };
991 
999 
1002 
1005 
1008 };
1009 
1018 };
1019 
1028 };
1029 
1036 
1039 
1042 
1045 };
1046 
1057 
1060 
1063 
1066 
1069 
1072 
1075 
1078 
1081 
1084 
1087 
1090 
1093 
1094  /* NB: Remember to update LIBUSB_ERROR_COUNT below as well as the
1095  message strings in strerror.c when adding new error codes here. */
1096 
1099 };
1100 
1101 /* Total number of error codes in enum libusb_error */
1102 #define LIBUSB_ERROR_COUNT 14
1103 
1110 
1113 
1116 
1119 
1123 
1126 
1129 
1130  /* NB! Remember to update libusb_error_name()
1131  when adding new status codes here. */
1132 };
1133 
1139 
1142 
1148 
1173 };
1174 
1179  unsigned int length;
1180 
1182  unsigned int actual_length;
1183 
1186 };
1187 
1188 struct libusb_transfer;
1189 
1199 typedef void (LIBUSB_CALL *libusb_transfer_cb_fn)(struct libusb_transfer *transfer);
1200 
1210 
1212  uint8_t flags;
1213 
1215  unsigned char endpoint;
1216 
1218  unsigned char type;
1219 
1222  unsigned int timeout;
1223 
1232 
1234  int length;
1235 
1240 
1244 
1246  void *user_data;
1247 
1249  unsigned char *buffer;
1250 
1254 
1257 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
1258  [] /* valid C99 code */
1259 #else
1260  [0] /* non-standard, but usually working code */
1261 #endif
1262  ;
1263 };
1264 
1283 };
1284 
1296  LIBUSB_LOG_LEVEL_NONE = 0,
1297  LIBUSB_LOG_LEVEL_ERROR,
1298  LIBUSB_LOG_LEVEL_WARNING,
1299  LIBUSB_LOG_LEVEL_INFO,
1300  LIBUSB_LOG_LEVEL_DEBUG,
1301 };
1302 
1305 void LIBUSB_CALL libusb_set_debug(libusb_context *ctx, int level);
1306 const struct libusb_version * LIBUSB_CALL libusb_get_version(void);
1307 int LIBUSB_CALL libusb_has_capability(uint32_t capability);
1308 const char * LIBUSB_CALL libusb_error_name(int errcode);
1309 int LIBUSB_CALL libusb_setlocale(const char *locale);
1310 const char * LIBUSB_CALL libusb_strerror(enum libusb_error errcode);
1311 
1313  libusb_device ***list);
1315  int unref_devices);
1318 
1320  int *config);
1322  struct libusb_device_descriptor *desc);
1324  struct libusb_config_descriptor **config);
1326  uint8_t config_index, struct libusb_config_descriptor **config);
1328  uint8_t bConfigurationValue, struct libusb_config_descriptor **config);
1330  struct libusb_config_descriptor *config);
1332  struct libusb_context *ctx,
1333  const struct libusb_endpoint_descriptor *endpoint,
1334  struct libusb_ss_endpoint_companion_descriptor **ep_comp);
1336  struct libusb_ss_endpoint_companion_descriptor *ep_comp);
1338  struct libusb_bos_descriptor **bos);
1341  struct libusb_context *ctx,
1342  struct libusb_bos_dev_capability_descriptor *dev_cap,
1343  struct libusb_usb_2_0_extension_descriptor **usb_2_0_extension);
1345  struct libusb_usb_2_0_extension_descriptor *usb_2_0_extension);
1347  struct libusb_context *ctx,
1348  struct libusb_bos_dev_capability_descriptor *dev_cap,
1349  struct libusb_ss_usb_device_capability_descriptor **ss_usb_device_cap);
1351  struct libusb_ss_usb_device_capability_descriptor *ss_usb_device_cap);
1353  struct libusb_bos_dev_capability_descriptor *dev_cap,
1354  struct libusb_container_id_descriptor **container_id);
1356  struct libusb_container_id_descriptor *container_id);
1359 int LIBUSB_CALL libusb_get_port_numbers(libusb_device *dev, uint8_t* port_numbers, int port_numbers_len);
1360 LIBUSB_DEPRECATED_FOR(libusb_get_port_numbers)
1361 int LIBUSB_CALL libusb_get_port_path(libusb_context *ctx, libusb_device *dev, uint8_t* path, uint8_t path_length);
1366  unsigned char endpoint);
1368  unsigned char endpoint);
1369 
1373 
1375  int configuration);
1377  int interface_number);
1379  int interface_number);
1380 
1382  libusb_context *ctx, uint16_t vendor_id, uint16_t product_id);
1383 
1385  int interface_number, int alternate_setting);
1387  unsigned char endpoint);
1389 
1391  int interface_number);
1393  int interface_number);
1395  int interface_number);
1397  libusb_device_handle *dev, int enable);
1398 
1399 /* async I/O */
1400 
1413 static inline unsigned char *libusb_control_transfer_get_data(
1414  struct libusb_transfer *transfer)
1415 {
1416  return transfer->buffer + LIBUSB_CONTROL_SETUP_SIZE;
1417 }
1418 
1432  struct libusb_transfer *transfer)
1433 {
1434  return (struct libusb_control_setup *)(void *) transfer->buffer;
1435 }
1436 
1460 static inline void libusb_fill_control_setup(unsigned char *buffer,
1461  uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
1462  uint16_t wLength)
1463 {
1464  struct libusb_control_setup *setup = (struct libusb_control_setup *)(void *) buffer;
1465  setup->bmRequestType = bmRequestType;
1466  setup->bRequest = bRequest;
1467  setup->wValue = libusb_cpu_to_le16(wValue);
1468  setup->wIndex = libusb_cpu_to_le16(wIndex);
1469  setup->wLength = libusb_cpu_to_le16(wLength);
1470 }
1471 
1472 struct libusb_transfer * LIBUSB_CALL libusb_alloc_transfer(int iso_packets);
1473 int LIBUSB_CALL libusb_submit_transfer(struct libusb_transfer *transfer);
1474 int LIBUSB_CALL libusb_cancel_transfer(struct libusb_transfer *transfer);
1475 void LIBUSB_CALL libusb_free_transfer(struct libusb_transfer *transfer);
1476 
1505 static inline void libusb_fill_control_transfer(
1506  struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
1507  unsigned char *buffer, libusb_transfer_cb_fn callback, void *user_data,
1508  unsigned int timeout)
1509 {
1510  struct libusb_control_setup *setup = (struct libusb_control_setup *)(void *) buffer;
1511  transfer->dev_handle = dev_handle;
1512  transfer->endpoint = 0;
1513  transfer->type = LIBUSB_TRANSFER_TYPE_CONTROL;
1514  transfer->timeout = timeout;
1515  transfer->buffer = buffer;
1516  if (setup)
1517  transfer->length = (int) (LIBUSB_CONTROL_SETUP_SIZE
1518  + libusb_le16_to_cpu(setup->wLength));
1519  transfer->user_data = user_data;
1520  transfer->callback = callback;
1521 }
1522 
1536 static inline void libusb_fill_bulk_transfer(struct libusb_transfer *transfer,
1537  libusb_device_handle *dev_handle, unsigned char endpoint,
1538  unsigned char *buffer, int length, libusb_transfer_cb_fn callback,
1539  void *user_data, unsigned int timeout)
1540 {
1541  transfer->dev_handle = dev_handle;
1542  transfer->endpoint = endpoint;
1543  transfer->type = LIBUSB_TRANSFER_TYPE_BULK;
1544  transfer->timeout = timeout;
1545  transfer->buffer = buffer;
1546  transfer->length = length;
1547  transfer->user_data = user_data;
1548  transfer->callback = callback;
1549 }
1550 
1565  struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
1566  unsigned char endpoint, unsigned char *buffer, int length,
1567  libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
1568 {
1569  transfer->dev_handle = dev_handle;
1570  transfer->endpoint = endpoint;
1572  transfer->timeout = timeout;
1573  transfer->buffer = buffer;
1574  transfer->length = length;
1575  transfer->user_data = user_data;
1576  transfer->callback = callback;
1577 }
1578 
1593 static inline void libusb_fill_iso_transfer(struct libusb_transfer *transfer,
1594  libusb_device_handle *dev_handle, unsigned char endpoint,
1595  unsigned char *buffer, int length, int num_iso_packets,
1596  libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
1597 {
1598  transfer->dev_handle = dev_handle;
1599  transfer->endpoint = endpoint;
1601  transfer->timeout = timeout;
1602  transfer->buffer = buffer;
1603  transfer->length = length;
1604  transfer->num_iso_packets = num_iso_packets;
1605  transfer->user_data = user_data;
1606  transfer->callback = callback;
1607 }
1608 
1618  struct libusb_transfer *transfer, unsigned int length)
1619 {
1620  int i;
1621  for (i = 0; i < transfer->num_iso_packets; i++)
1622  transfer->iso_packet_desc[i].length = length;
1623 }
1624 
1641 static inline unsigned char *libusb_get_iso_packet_buffer(
1642  struct libusb_transfer *transfer, unsigned int packet)
1643 {
1644  int i;
1645  size_t offset = 0;
1646  int _packet;
1647 
1648  /* oops..slight bug in the API. packet is an unsigned int, but we use
1649  * signed integers almost everywhere else. range-check and convert to
1650  * signed to avoid compiler warnings. FIXME for libusb-2. */
1651  if (packet > INT_MAX)
1652  return NULL;
1653  _packet = (int) packet;
1654 
1655  if (_packet >= transfer->num_iso_packets)
1656  return NULL;
1657 
1658  for (i = 0; i < _packet; i++)
1659  offset += transfer->iso_packet_desc[i].length;
1660 
1661  return transfer->buffer + offset;
1662 }
1663 
1683 static inline unsigned char *libusb_get_iso_packet_buffer_simple(
1684  struct libusb_transfer *transfer, unsigned int packet)
1685 {
1686  int _packet;
1687 
1688  /* oops..slight bug in the API. packet is an unsigned int, but we use
1689  * signed integers almost everywhere else. range-check and convert to
1690  * signed to avoid compiler warnings. FIXME for libusb-2. */
1691  if (packet > INT_MAX)
1692  return NULL;
1693  _packet = (int) packet;
1694 
1695  if (_packet >= transfer->num_iso_packets)
1696  return NULL;
1697 
1698  return transfer->buffer + ((int) transfer->iso_packet_desc[0].length * _packet);
1699 }
1700 
1701 /* sync I/O */
1702 
1704  uint8_t request_type, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
1705  unsigned char *data, uint16_t wLength, unsigned int timeout);
1706 
1708  unsigned char endpoint, unsigned char *data, int length,
1709  int *actual_length, unsigned int timeout);
1710 
1712  unsigned char endpoint, unsigned char *data, int length,
1713  int *actual_length, unsigned int timeout);
1714 
1728  uint8_t desc_type, uint8_t desc_index, unsigned char *data, int length)
1729 {
1731  LIBUSB_REQUEST_GET_DESCRIPTOR, (uint16_t) ((desc_type << 8) | desc_index),
1732  0, data, (uint16_t) length, 1000);
1733 }
1734 
1750  uint8_t desc_index, uint16_t langid, unsigned char *data, int length)
1751 {
1753  LIBUSB_REQUEST_GET_DESCRIPTOR, (uint16_t)((LIBUSB_DT_STRING << 8) | desc_index),
1754  langid, data, (uint16_t) length, 1000);
1755 }
1756 
1758  uint8_t desc_index, unsigned char *data, int length);
1759 
1760 /* polling and timeouts */
1761 
1769 int LIBUSB_CALL libusb_wait_for_event(libusb_context *ctx, struct timeval *tv);
1770 
1772  struct timeval *tv);
1774  struct timeval *tv, int *completed);
1778  struct timeval *tv);
1781  struct timeval *tv);
1782 
1788  int fd;
1789 
1794  short events;
1795 };
1796 
1807 typedef void (LIBUSB_CALL *libusb_pollfd_added_cb)(int fd, short events,
1808  void *user_data);
1809 
1819 typedef void (LIBUSB_CALL *libusb_pollfd_removed_cb)(int fd, void *user_data);
1820 
1822  libusb_context *ctx);
1824  libusb_pollfd_added_cb added_cb, libusb_pollfd_removed_cb removed_cb,
1825  void *user_data);
1826 
1840 
1846 typedef enum {
1850 
1856 typedef enum {
1859 
1865 
1868 #define LIBUSB_HOTPLUG_MATCH_ANY -1
1869 
1893  libusb_device *device,
1894  libusb_hotplug_event event,
1895  void *user_data);
1896 
1932  libusb_hotplug_event events,
1933  libusb_hotplug_flag flags,
1934  int vendor_id, int product_id,
1935  int dev_class,
1937  void *user_data,
1938  libusb_hotplug_callback_handle *handle);
1939 
1952  libusb_hotplug_callback_handle handle);
1953 
1954 #ifdef __cplusplus
1955 }
1956 #endif
1957 
1958 #endif