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 not available on older MSVC */
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 #if !defined(_WIN32_WCE)
53 #include <sys/types.h>
54 #endif
55 
56 #if defined(__linux) || defined(__APPLE__) || defined(__CYGWIN__)
57 #include <sys/time.h>
58 #endif
59 
60 #include <time.h>
61 #include <limits.h>
62 
63 /* 'interface' might be defined as a macro on Windows, so we need to
64  * undefine it so as not to break the current libusbx API, because
65  * libusb_config_descriptor has an 'interface' member
66  * As this can be problematic if you include windows.h after libusb.h
67  * in your sources, we force windows.h to be included first. */
68 #if defined(_WIN32) || defined(__CYGWIN__) || defined(_WIN32_WCE)
69 #include <windows.h>
70 #if defined(interface)
71 #undef interface
72 #endif
73 #if !defined(__CYGWIN__)
74 #include <winsock.h>
75 #endif
76 #endif
77 
103 /* LIBUSB_CALL must be defined on both definition and declaration of libusbx
104  * functions. You'd think that declaration would be enough, but cygwin will
105  * complain about conflicting types unless both are marked this way.
106  * The placement of this macro is important too; it must appear after the
107  * return type, before the function name. See internal documentation for
108  * API_EXPORTED.
109  */
110 #if defined(_WIN32) || defined(__CYGWIN__) || defined(_WIN32_WCE)
111 #define LIBUSB_CALL WINAPI
112 #else
113 #define LIBUSB_CALL
114 #endif
115 
139 #define LIBUSBX_API_VERSION 0x01000101
140 
141 #ifdef __cplusplus
142 extern "C" {
143 #endif
144 
153 static inline uint16_t libusb_cpu_to_le16(const uint16_t x)
154 {
155  union {
156  uint8_t b8[2];
157  uint16_t b16;
158  } _tmp;
159  _tmp.b8[1] = x >> 8;
160  _tmp.b8[0] = x & 0xff;
161  return _tmp.b16;
162 }
163 
172 #define libusb_le16_to_cpu libusb_cpu_to_le16
173 
174 /* standard USB stuff */
175 
184 
187 
190 
193 
196 
199 
201  LIBUSB_CLASS_PTP = 6, /* legacy name from libusb-0.1 usb.h */
202  LIBUSB_CLASS_IMAGE = 6,
203 
206 
209 
212 
215 
218 
221 
224 
227 
230 
233 
236 };
237 
243 
246 
249 
252 
255 
258 
261 
264 
267 
270 };
271 
272 /* Descriptor sizes per descriptor type */
273 #define LIBUSB_DT_DEVICE_SIZE 18
274 #define LIBUSB_DT_CONFIG_SIZE 9
275 #define LIBUSB_DT_INTERFACE_SIZE 9
276 #define LIBUSB_DT_ENDPOINT_SIZE 7
277 #define LIBUSB_DT_ENDPOINT_AUDIO_SIZE 9 /* Audio extension */
278 #define LIBUSB_DT_HUB_NONVAR_SIZE 7
279 
280 #define LIBUSB_ENDPOINT_ADDRESS_MASK 0x0f /* in bEndpointAddress */
281 #define LIBUSB_ENDPOINT_DIR_MASK 0x80
282 
290 
293 };
294 
295 #define LIBUSB_TRANSFER_TYPE_MASK 0x03 /* in bmAttributes */
296 
304 
307 
310 
313 };
314 
320 
323 
324  /* 0x02 is reserved */
325 
328 
329  /* 0x04 is reserved */
330 
333 
336 
339 
342 
345 
348 
351 
354 
357 
361 };
362 
370 
373 
376 
379 };
380 
388 
391 
394 
397 };
398 
399 #define LIBUSB_ISO_SYNC_TYPE_MASK 0x0C
400 
409 
412 
415 
418 };
419 
420 #define LIBUSB_ISO_USAGE_TYPE_MASK 0x30
421 
430 
433 
436 };
437 
445  uint8_t bLength;
446 
451 
454  uint16_t bcdUSB;
455 
457  uint8_t bDeviceClass;
458 
462 
466 
469 
471  uint16_t idVendor;
472 
474  uint16_t idProduct;
475 
477  uint16_t bcdDevice;
478 
480  uint8_t iManufacturer;
481 
483  uint8_t iProduct;
484 
486  uint8_t iSerialNumber;
487 
490 };
491 
499  uint8_t bLength;
500 
505 
511 
519  uint8_t bmAttributes;
520 
522  uint16_t wMaxPacketSize;
523 
525  uint8_t bInterval;
526 
529  uint8_t bRefresh;
530 
532  uint8_t bSynchAddress;
533 
536  const unsigned char *extra;
537 
540 };
541 
549  uint8_t bLength;
550 
555 
558 
561 
564  uint8_t bNumEndpoints;
565 
568 
572 
576 
578  uint8_t iInterface;
579 
583 
586  const unsigned char *extra;
587 
590 };
591 
599 
602 };
603 
611  uint8_t bLength;
612 
617 
619  uint16_t wTotalLength;
620 
622  uint8_t bNumInterfaces;
623 
626 
628  uint8_t iConfiguration;
629 
631  uint8_t bmAttributes;
632 
636  uint8_t MaxPower;
637 
641 
644  const unsigned char *extra;
645 
648 };
649 
658  uint8_t bmRequestType;
659 
665  uint8_t bRequest;
666 
668  uint16_t wValue;
669 
672  uint16_t wIndex;
673 
675  uint16_t wLength;
676 };
677 
678 #define LIBUSB_CONTROL_SETUP_SIZE (sizeof(struct libusb_control_setup))
679 
680 /* libusbx */
681 
682 struct libusb_context;
683 struct libusb_device;
684 struct libusb_device_handle;
685 
691  const uint16_t major;
692 
694  const uint16_t minor;
695 
697  const uint16_t micro;
698 
700  const uint16_t nano;
701 
703  const char *rc;
704 
706  const char* describe;
707 };
708 
727 
744 
745 
755 
762 
765 
768 
771 
774 };
775 
785 
788 
791 
794 
797 
800 
803 
806 
809 
812 
815 
818 
821 
822  /* NB! Remember to update libusb_error_name()
823  when adding new error codes here. */
824 
827 };
828 
835 
838 
841 
844 
848 
851 
854 
855  /* NB! Remember to update libusb_error_name()
856  when adding new status codes here. */
857 };
858 
864 
867 
873 
898 };
899 
904  unsigned int length;
905 
907  unsigned int actual_length;
908 
911 };
912 
913 struct libusb_transfer;
914 
924 typedef void (LIBUSB_CALL *libusb_transfer_cb_fn)(struct libusb_transfer *transfer);
925 
935 
937  uint8_t flags;
938 
940  unsigned char endpoint;
941 
943  unsigned char type;
944 
947  unsigned int timeout;
948 
957 
959  int length;
960 
965 
969 
971  void *user_data;
972 
974  unsigned char *buffer;
975 
979 
982 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
983  [] /* valid C99 code */
984 #else
985  [0] /* non-standard, but usually working code */
986 #endif
987  ;
988 };
989 
1008 };
1009 
1021  LIBUSB_LOG_LEVEL_NONE = 0,
1022  LIBUSB_LOG_LEVEL_ERROR,
1023  LIBUSB_LOG_LEVEL_WARNING,
1024  LIBUSB_LOG_LEVEL_INFO,
1025  LIBUSB_LOG_LEVEL_DEBUG,
1026 };
1027 
1030 void LIBUSB_CALL libusb_set_debug(libusb_context *ctx, int level);
1031 const struct libusb_version * LIBUSB_CALL libusb_get_version(void);
1032 int LIBUSB_CALL libusb_has_capability(uint32_t capability);
1033 const char * LIBUSB_CALL libusb_error_name(int errcode);
1034 
1036  libusb_device ***list);
1038  int unref_devices);
1041 
1043  int *config);
1045  struct libusb_device_descriptor *desc);
1047  struct libusb_config_descriptor **config);
1049  uint8_t config_index, struct libusb_config_descriptor **config);
1051  uint8_t bConfigurationValue, struct libusb_config_descriptor **config);
1053  struct libusb_config_descriptor *config);
1057 int LIBUSB_CALL libusb_get_port_path(libusb_context *ctx, libusb_device *dev, uint8_t* path, uint8_t path_length);
1061  unsigned char endpoint);
1063  unsigned char endpoint);
1064 
1068 
1070  int configuration);
1072  int interface_number);
1074  int interface_number);
1075 
1077  libusb_context *ctx, uint16_t vendor_id, uint16_t product_id);
1078 
1080  int interface_number, int alternate_setting);
1082  unsigned char endpoint);
1084 
1086  int interface_number);
1088  int interface_number);
1090  int interface_number);
1091 
1092 /* async I/O */
1093 
1106 static inline unsigned char *libusb_control_transfer_get_data(
1107  struct libusb_transfer *transfer)
1108 {
1109  return transfer->buffer + LIBUSB_CONTROL_SETUP_SIZE;
1110 }
1111 
1125  struct libusb_transfer *transfer)
1126 {
1127  return (struct libusb_control_setup *) transfer->buffer;
1128 }
1129 
1152 static inline void libusb_fill_control_setup(unsigned char *buffer,
1153  uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
1154  uint16_t wLength)
1155 {
1156  struct libusb_control_setup *setup = (struct libusb_control_setup *) buffer;
1157  setup->bmRequestType = bmRequestType;
1158  setup->bRequest = bRequest;
1159  setup->wValue = libusb_cpu_to_le16(wValue);
1160  setup->wIndex = libusb_cpu_to_le16(wIndex);
1161  setup->wLength = libusb_cpu_to_le16(wLength);
1162 }
1163 
1164 struct libusb_transfer * LIBUSB_CALL libusb_alloc_transfer(int iso_packets);
1165 int LIBUSB_CALL libusb_submit_transfer(struct libusb_transfer *transfer);
1166 int LIBUSB_CALL libusb_cancel_transfer(struct libusb_transfer *transfer);
1167 void LIBUSB_CALL libusb_free_transfer(struct libusb_transfer *transfer);
1168 
1196 static inline void libusb_fill_control_transfer(
1197  struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
1198  unsigned char *buffer, libusb_transfer_cb_fn callback, void *user_data,
1199  unsigned int timeout)
1200 {
1201  struct libusb_control_setup *setup = (struct libusb_control_setup *) buffer;
1202  transfer->dev_handle = dev_handle;
1203  transfer->endpoint = 0;
1204  transfer->type = LIBUSB_TRANSFER_TYPE_CONTROL;
1205  transfer->timeout = timeout;
1206  transfer->buffer = buffer;
1207  if (setup)
1208  transfer->length = LIBUSB_CONTROL_SETUP_SIZE
1209  + libusb_le16_to_cpu(setup->wLength);
1210  transfer->user_data = user_data;
1211  transfer->callback = callback;
1212 }
1213 
1227 static inline void libusb_fill_bulk_transfer(struct libusb_transfer *transfer,
1228  libusb_device_handle *dev_handle, unsigned char endpoint,
1229  unsigned char *buffer, int length, libusb_transfer_cb_fn callback,
1230  void *user_data, unsigned int timeout)
1231 {
1232  transfer->dev_handle = dev_handle;
1233  transfer->endpoint = endpoint;
1234  transfer->type = LIBUSB_TRANSFER_TYPE_BULK;
1235  transfer->timeout = timeout;
1236  transfer->buffer = buffer;
1237  transfer->length = length;
1238  transfer->user_data = user_data;
1239  transfer->callback = callback;
1240 }
1241 
1256  struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
1257  unsigned char endpoint, unsigned char *buffer, int length,
1258  libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
1259 {
1260  transfer->dev_handle = dev_handle;
1261  transfer->endpoint = endpoint;
1263  transfer->timeout = timeout;
1264  transfer->buffer = buffer;
1265  transfer->length = length;
1266  transfer->user_data = user_data;
1267  transfer->callback = callback;
1268 }
1269 
1284 static inline void libusb_fill_iso_transfer(struct libusb_transfer *transfer,
1285  libusb_device_handle *dev_handle, unsigned char endpoint,
1286  unsigned char *buffer, int length, int num_iso_packets,
1287  libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
1288 {
1289  transfer->dev_handle = dev_handle;
1290  transfer->endpoint = endpoint;
1292  transfer->timeout = timeout;
1293  transfer->buffer = buffer;
1294  transfer->length = length;
1295  transfer->num_iso_packets = num_iso_packets;
1296  transfer->user_data = user_data;
1297  transfer->callback = callback;
1298 }
1299 
1309  struct libusb_transfer *transfer, unsigned int length)
1310 {
1311  int i;
1312  for (i = 0; i < transfer->num_iso_packets; i++)
1313  transfer->iso_packet_desc[i].length = length;
1314 }
1315 
1332 static inline unsigned char *libusb_get_iso_packet_buffer(
1333  struct libusb_transfer *transfer, unsigned int packet)
1334 {
1335  int i;
1336  size_t offset = 0;
1337  int _packet;
1338 
1339  /* oops..slight bug in the API. packet is an unsigned int, but we use
1340  * signed integers almost everywhere else. range-check and convert to
1341  * signed to avoid compiler warnings. FIXME for libusb-2. */
1342  if (packet > INT_MAX)
1343  return NULL;
1344  _packet = packet;
1345 
1346  if (_packet >= transfer->num_iso_packets)
1347  return NULL;
1348 
1349  for (i = 0; i < _packet; i++)
1350  offset += transfer->iso_packet_desc[i].length;
1351 
1352  return transfer->buffer + offset;
1353 }
1354 
1374 static inline unsigned char *libusb_get_iso_packet_buffer_simple(
1375  struct libusb_transfer *transfer, unsigned int packet)
1376 {
1377  int _packet;
1378 
1379  /* oops..slight bug in the API. packet is an unsigned int, but we use
1380  * signed integers almost everywhere else. range-check and convert to
1381  * signed to avoid compiler warnings. FIXME for libusb-2. */
1382  if (packet > INT_MAX)
1383  return NULL;
1384  _packet = packet;
1385 
1386  if (_packet >= transfer->num_iso_packets)
1387  return NULL;
1388 
1389  return transfer->buffer + (transfer->iso_packet_desc[0].length * _packet);
1390 }
1391 
1392 /* sync I/O */
1393 
1395  uint8_t request_type, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
1396  unsigned char *data, uint16_t wLength, unsigned int timeout);
1397 
1399  unsigned char endpoint, unsigned char *data, int length,
1400  int *actual_length, unsigned int timeout);
1401 
1403  unsigned char endpoint, unsigned char *data, int length,
1404  int *actual_length, unsigned int timeout);
1405 
1419  uint8_t desc_type, uint8_t desc_index, unsigned char *data, int length)
1420 {
1422  LIBUSB_REQUEST_GET_DESCRIPTOR, (desc_type << 8) | desc_index, 0, data,
1423  (uint16_t) length, 1000);
1424 }
1425 
1441  uint8_t desc_index, uint16_t langid, unsigned char *data, int length)
1442 {
1444  LIBUSB_REQUEST_GET_DESCRIPTOR, (uint16_t)((LIBUSB_DT_STRING << 8) | desc_index),
1445  langid, data, (uint16_t) length, 1000);
1446 }
1447 
1449  uint8_t desc_index, unsigned char *data, int length);
1450 
1451 /* polling and timeouts */
1452 
1460 int LIBUSB_CALL libusb_wait_for_event(libusb_context *ctx, struct timeval *tv);
1461 
1463  struct timeval *tv);
1465  struct timeval *tv, int *completed);
1469  struct timeval *tv);
1472  struct timeval *tv);
1473 
1479  int fd;
1480 
1485  short events;
1486 };
1487 
1498 typedef void (LIBUSB_CALL *libusb_pollfd_added_cb)(int fd, short events,
1499  void *user_data);
1500 
1510 typedef void (LIBUSB_CALL *libusb_pollfd_removed_cb)(int fd, void *user_data);
1511 
1513  libusb_context *ctx);
1515  libusb_pollfd_added_cb added_cb, libusb_pollfd_removed_cb removed_cb,
1516  void *user_data);
1517 
1518 #ifdef __cplusplus
1519 }
1520 #endif
1521 
1522 #endif