eXpand your USB potential
libusb.h
1 /*
2  * Public libusbx 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  * For more information, please visit: http://libusbx.org
7  *
8  * This library is free software; you can redistribute it and/or
9  * modify it under the terms of the GNU Lesser General Public
10  * License as published by the Free Software Foundation; either
11  * version 2.1 of the License, or (at your option) any later version.
12  *
13  * This library is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16  * Lesser General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public
19  * License along with this library; if not, write to the Free Software
20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
21  */
22 
23 #ifndef LIBUSB_H
24 #define LIBUSB_H
25 
26 #ifdef _MSC_VER
27 /* on MS environments, the inline keyword is available in C++ only */
28 #if !defined(__cplusplus)
29 #define inline __inline
30 #endif
31 /* ssize_t is also not available (copy/paste from MinGW) */
32 #ifndef _SSIZE_T_DEFINED
33 #define _SSIZE_T_DEFINED
34 #undef ssize_t
35 #ifdef _WIN64
36  typedef __int64 ssize_t;
37 #else
38  typedef int ssize_t;
39 #endif /* _WIN64 */
40 #endif /* _SSIZE_T_DEFINED */
41 #endif /* _MSC_VER */
42 
43 /* stdint.h is also not usually available on MS */
44 #if defined(_MSC_VER) && (_MSC_VER < 1600) && (!defined(_STDINT)) && (!defined(_STDINT_H))
45 typedef unsigned __int8 uint8_t;
46 typedef unsigned __int16 uint16_t;
47 typedef unsigned __int32 uint32_t;
48 #else
49 #include <stdint.h>
50 #endif
51 
52 #include <sys/types.h>
53 #include <time.h>
54 #include <limits.h>
55 
56 #if defined(__linux) || defined(__APPLE__) || defined(__CYGWIN__)
57 #include <sys/time.h>
58 #endif
59 
60 /* 'interface' might be defined as a macro on Windows, so we need to
61  * undefine it so as not to break the current libusbx API, because
62  * libusb_config_descriptor has an 'interface' member
63  * As this can be problematic if you include windows.h after libusb.h
64  * in your sources, we force windows.h to be included first. */
65 #if defined(_WIN32) || defined(__CYGWIN__)
66 #include <windows.h>
67 #if defined(interface)
68 #undef interface
69 #endif
70 #endif
71 
97 /* LIBUSB_CALL must be defined on both definition and declaration of libusbx
98  * functions. You'd think that declaration would be enough, but cygwin will
99  * complain about conflicting types unless both are marked this way.
100  * The placement of this macro is important too; it must appear after the
101  * return type, before the function name. See internal documentation for
102  * API_EXPORTED.
103  */
104 #if defined(_WIN32) || defined(__CYGWIN__)
105 #define LIBUSB_CALL WINAPI
106 #else
107 #define LIBUSB_CALL
108 #endif
109 
133 #define LIBUSBX_API_VERSION 0x010000FF
134 
135 #ifdef __cplusplus
136 extern "C" {
137 #endif
138 
147 static inline uint16_t libusb_cpu_to_le16(const uint16_t x)
148 {
149  union {
150  uint8_t b8[2];
151  uint16_t b16;
152  } _tmp;
153  _tmp.b8[1] = x >> 8;
154  _tmp.b8[0] = x & 0xff;
155  return _tmp.b16;
156 }
157 
166 #define libusb_le16_to_cpu libusb_cpu_to_le16
167 
168 /* standard USB stuff */
169 
178 
181 
184 
187 
190 
193 
195  LIBUSB_CLASS_PTP = 6, /* legacy name from libusb-0.1 usb.h */
196  LIBUSB_CLASS_IMAGE = 6,
197 
200 
203 
206 
209 
212 
215 
218 
221 
224 
227 
230 };
231 
237 
240 
243 
246 
249 
252 
255 
258 
261 
264 };
265 
266 /* Descriptor sizes per descriptor type */
267 #define LIBUSB_DT_DEVICE_SIZE 18
268 #define LIBUSB_DT_CONFIG_SIZE 9
269 #define LIBUSB_DT_INTERFACE_SIZE 9
270 #define LIBUSB_DT_ENDPOINT_SIZE 7
271 #define LIBUSB_DT_ENDPOINT_AUDIO_SIZE 9 /* Audio extension */
272 #define LIBUSB_DT_HUB_NONVAR_SIZE 7
273 
274 #define LIBUSB_ENDPOINT_ADDRESS_MASK 0x0f /* in bEndpointAddress */
275 #define LIBUSB_ENDPOINT_DIR_MASK 0x80
276 
284 
287 };
288 
289 #define LIBUSB_TRANSFER_TYPE_MASK 0x03 /* in bmAttributes */
290 
298 
301 
304 
307 };
308 
314 
317 
318  /* 0x02 is reserved */
319 
322 
323  /* 0x04 is reserved */
324 
327 
330 
333 
336 
339 
342 
345 
348 
351 
355 };
356 
364 
367 
370 
373 };
374 
382 
385 
388 
391 };
392 
393 #define LIBUSB_ISO_SYNC_TYPE_MASK 0x0C
394 
403 
406 
409 
412 };
413 
414 #define LIBUSB_ISO_USAGE_TYPE_MASK 0x30
415 
424 
427 
430 };
431 
439  uint8_t bLength;
440 
445 
448  uint16_t bcdUSB;
449 
451  uint8_t bDeviceClass;
452 
456 
460 
463 
465  uint16_t idVendor;
466 
468  uint16_t idProduct;
469 
471  uint16_t bcdDevice;
472 
474  uint8_t iManufacturer;
475 
477  uint8_t iProduct;
478 
480  uint8_t iSerialNumber;
481 
484 };
485 
493  uint8_t bLength;
494 
499 
505 
513  uint8_t bmAttributes;
514 
516  uint16_t wMaxPacketSize;
517 
519  uint8_t bInterval;
520 
523  uint8_t bRefresh;
524 
526  uint8_t bSynchAddress;
527 
530  const unsigned char *extra;
531 
534 };
535 
543  uint8_t bLength;
544 
549 
552 
555 
558  uint8_t bNumEndpoints;
559 
562 
566 
570 
572  uint8_t iInterface;
573 
577 
580  const unsigned char *extra;
581 
584 };
585 
593 
596 };
597 
605  uint8_t bLength;
606 
611 
613  uint16_t wTotalLength;
614 
616  uint8_t bNumInterfaces;
617 
620 
622  uint8_t iConfiguration;
623 
625  uint8_t bmAttributes;
626 
630  uint8_t MaxPower;
631 
635 
638  const unsigned char *extra;
639 
642 };
643 
652  uint8_t bmRequestType;
653 
659  uint8_t bRequest;
660 
662  uint16_t wValue;
663 
666  uint16_t wIndex;
667 
669  uint16_t wLength;
670 };
671 
672 #define LIBUSB_CONTROL_SETUP_SIZE (sizeof(struct libusb_control_setup))
673 
674 /* libusbx */
675 
676 struct libusb_context;
677 struct libusb_device;
678 struct libusb_device_handle;
679 
685  const uint16_t major;
686 
688  const uint16_t minor;
689 
691  const uint16_t micro;
692 
694  const uint16_t nano;
695 
697  const char *rc;
698 
700  const char* describe;
701 };
702 
721 
738 
739 
749 
756 
759 
762 
765 
768 };
769 
779 
782 
785 
788 
791 
794 
797 
800 
803 
806 
809 
812 
815 
816  /* NB! Remember to update libusb_error_name()
817  when adding new error codes here. */
818 
821 };
822 
829 
832 
835 
838 
842 
845 
848 
849  /* NB! Remember to update libusb_error_name()
850  when adding new status codes here. */
851 };
852 
858 
861 
867 
892 };
893 
898  unsigned int length;
899 
901  unsigned int actual_length;
902 
905 };
906 
907 struct libusb_transfer;
908 
918 typedef void (LIBUSB_CALL *libusb_transfer_cb_fn)(struct libusb_transfer *transfer);
919 
929 
931  uint8_t flags;
932 
934  unsigned char endpoint;
935 
937  unsigned char type;
938 
941  unsigned int timeout;
942 
951 
953  int length;
954 
959 
963 
965  void *user_data;
966 
968  unsigned char *buffer;
969 
973 
976 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
977  [] /* valid C99 code */
978 #else
979  [0] /* non-standard, but usually working code */
980 #endif
981  ;
982 };
983 
992 };
993 
1005  LIBUSB_LOG_LEVEL_NONE = 0,
1006  LIBUSB_LOG_LEVEL_ERROR,
1007  LIBUSB_LOG_LEVEL_WARNING,
1008  LIBUSB_LOG_LEVEL_INFO,
1009  LIBUSB_LOG_LEVEL_DEBUG,
1010 };
1011 
1014 void LIBUSB_CALL libusb_set_debug(libusb_context *ctx, int level);
1015 const struct libusb_version * LIBUSB_CALL libusb_get_version(void);
1016 int LIBUSB_CALL libusb_has_capability(uint32_t capability);
1017 const char * LIBUSB_CALL libusb_error_name(int errcode);
1018 
1020  libusb_device ***list);
1022  int unref_devices);
1025 
1027  int *config);
1029  struct libusb_device_descriptor *desc);
1031  struct libusb_config_descriptor **config);
1033  uint8_t config_index, struct libusb_config_descriptor **config);
1035  uint8_t bConfigurationValue, struct libusb_config_descriptor **config);
1037  struct libusb_config_descriptor *config);
1041 int LIBUSB_CALL libusb_get_port_path(libusb_context *ctx, libusb_device *dev, uint8_t* path, uint8_t path_length);
1045  unsigned char endpoint);
1047  unsigned char endpoint);
1048 
1052 
1054  int configuration);
1056  int interface_number);
1058  int interface_number);
1059 
1061  libusb_context *ctx, uint16_t vendor_id, uint16_t product_id);
1062 
1064  int interface_number, int alternate_setting);
1066  unsigned char endpoint);
1068 
1070  int interface_number);
1072  int interface_number);
1074  int interface_number);
1075 
1076 /* async I/O */
1077 
1090 static inline unsigned char *libusb_control_transfer_get_data(
1091  struct libusb_transfer *transfer)
1092 {
1093  return transfer->buffer + LIBUSB_CONTROL_SETUP_SIZE;
1094 }
1095 
1109  struct libusb_transfer *transfer)
1110 {
1111  return (struct libusb_control_setup *) transfer->buffer;
1112 }
1113 
1136 static inline void libusb_fill_control_setup(unsigned char *buffer,
1137  uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
1138  uint16_t wLength)
1139 {
1140  struct libusb_control_setup *setup = (struct libusb_control_setup *) buffer;
1141  setup->bmRequestType = bmRequestType;
1142  setup->bRequest = bRequest;
1143  setup->wValue = libusb_cpu_to_le16(wValue);
1144  setup->wIndex = libusb_cpu_to_le16(wIndex);
1145  setup->wLength = libusb_cpu_to_le16(wLength);
1146 }
1147 
1148 struct libusb_transfer * LIBUSB_CALL libusb_alloc_transfer(int iso_packets);
1149 int LIBUSB_CALL libusb_submit_transfer(struct libusb_transfer *transfer);
1150 int LIBUSB_CALL libusb_cancel_transfer(struct libusb_transfer *transfer);
1151 void LIBUSB_CALL libusb_free_transfer(struct libusb_transfer *transfer);
1152 
1180 static inline void libusb_fill_control_transfer(
1181  struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
1182  unsigned char *buffer, libusb_transfer_cb_fn callback, void *user_data,
1183  unsigned int timeout)
1184 {
1185  struct libusb_control_setup *setup = (struct libusb_control_setup *) buffer;
1186  transfer->dev_handle = dev_handle;
1187  transfer->endpoint = 0;
1188  transfer->type = LIBUSB_TRANSFER_TYPE_CONTROL;
1189  transfer->timeout = timeout;
1190  transfer->buffer = buffer;
1191  if (setup)
1192  transfer->length = LIBUSB_CONTROL_SETUP_SIZE
1193  + libusb_le16_to_cpu(setup->wLength);
1194  transfer->user_data = user_data;
1195  transfer->callback = callback;
1196 }
1197 
1211 static inline void libusb_fill_bulk_transfer(struct libusb_transfer *transfer,
1212  libusb_device_handle *dev_handle, unsigned char endpoint,
1213  unsigned char *buffer, int length, libusb_transfer_cb_fn callback,
1214  void *user_data, unsigned int timeout)
1215 {
1216  transfer->dev_handle = dev_handle;
1217  transfer->endpoint = endpoint;
1218  transfer->type = LIBUSB_TRANSFER_TYPE_BULK;
1219  transfer->timeout = timeout;
1220  transfer->buffer = buffer;
1221  transfer->length = length;
1222  transfer->user_data = user_data;
1223  transfer->callback = callback;
1224 }
1225 
1240  struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
1241  unsigned char endpoint, unsigned char *buffer, int length,
1242  libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
1243 {
1244  transfer->dev_handle = dev_handle;
1245  transfer->endpoint = endpoint;
1247  transfer->timeout = timeout;
1248  transfer->buffer = buffer;
1249  transfer->length = length;
1250  transfer->user_data = user_data;
1251  transfer->callback = callback;
1252 }
1253 
1268 static inline void libusb_fill_iso_transfer(struct libusb_transfer *transfer,
1269  libusb_device_handle *dev_handle, unsigned char endpoint,
1270  unsigned char *buffer, int length, int num_iso_packets,
1271  libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
1272 {
1273  transfer->dev_handle = dev_handle;
1274  transfer->endpoint = endpoint;
1276  transfer->timeout = timeout;
1277  transfer->buffer = buffer;
1278  transfer->length = length;
1279  transfer->num_iso_packets = num_iso_packets;
1280  transfer->user_data = user_data;
1281  transfer->callback = callback;
1282 }
1283 
1293  struct libusb_transfer *transfer, unsigned int length)
1294 {
1295  int i;
1296  for (i = 0; i < transfer->num_iso_packets; i++)
1297  transfer->iso_packet_desc[i].length = length;
1298 }
1299 
1316 static inline unsigned char *libusb_get_iso_packet_buffer(
1317  struct libusb_transfer *transfer, unsigned int packet)
1318 {
1319  int i;
1320  size_t offset = 0;
1321  int _packet;
1322 
1323  /* oops..slight bug in the API. packet is an unsigned int, but we use
1324  * signed integers almost everywhere else. range-check and convert to
1325  * signed to avoid compiler warnings. FIXME for libusb-2. */
1326  if (packet > INT_MAX)
1327  return NULL;
1328  _packet = packet;
1329 
1330  if (_packet >= transfer->num_iso_packets)
1331  return NULL;
1332 
1333  for (i = 0; i < _packet; i++)
1334  offset += transfer->iso_packet_desc[i].length;
1335 
1336  return transfer->buffer + offset;
1337 }
1338 
1358 static inline unsigned char *libusb_get_iso_packet_buffer_simple(
1359  struct libusb_transfer *transfer, unsigned int packet)
1360 {
1361  int _packet;
1362 
1363  /* oops..slight bug in the API. packet is an unsigned int, but we use
1364  * signed integers almost everywhere else. range-check and convert to
1365  * signed to avoid compiler warnings. FIXME for libusb-2. */
1366  if (packet > INT_MAX)
1367  return NULL;
1368  _packet = packet;
1369 
1370  if (_packet >= transfer->num_iso_packets)
1371  return NULL;
1372 
1373  return transfer->buffer + (transfer->iso_packet_desc[0].length * _packet);
1374 }
1375 
1376 /* sync I/O */
1377 
1379  uint8_t request_type, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
1380  unsigned char *data, uint16_t wLength, unsigned int timeout);
1381 
1383  unsigned char endpoint, unsigned char *data, int length,
1384  int *actual_length, unsigned int timeout);
1385 
1387  unsigned char endpoint, unsigned char *data, int length,
1388  int *actual_length, unsigned int timeout);
1389 
1403  uint8_t desc_type, uint8_t desc_index, unsigned char *data, int length)
1404 {
1406  LIBUSB_REQUEST_GET_DESCRIPTOR, (desc_type << 8) | desc_index, 0, data,
1407  (uint16_t) length, 1000);
1408 }
1409 
1425  uint8_t desc_index, uint16_t langid, unsigned char *data, int length)
1426 {
1428  LIBUSB_REQUEST_GET_DESCRIPTOR, (uint16_t)((LIBUSB_DT_STRING << 8) | desc_index),
1429  langid, data, (uint16_t) length, 1000);
1430 }
1431 
1433  uint8_t desc_index, unsigned char *data, int length);
1434 
1435 /* polling and timeouts */
1436 
1444 int LIBUSB_CALL libusb_wait_for_event(libusb_context *ctx, struct timeval *tv);
1445 
1447  struct timeval *tv);
1449  struct timeval *tv, int *completed);
1453  struct timeval *tv);
1456  struct timeval *tv);
1457 
1463  int fd;
1464 
1469  short events;
1470 };
1471 
1482 typedef void (LIBUSB_CALL *libusb_pollfd_added_cb)(int fd, short events,
1483  void *user_data);
1484 
1494 typedef void (LIBUSB_CALL *libusb_pollfd_removed_cb)(int fd, void *user_data);
1495 
1497  libusb_context *ctx);
1499  libusb_pollfd_added_cb added_cb, libusb_pollfd_removed_cb removed_cb,
1500  void *user_data);
1501 
1502 #ifdef __cplusplus
1503 }
1504 #endif
1505 
1506 #endif