eXpand your USB potential
libusb.h
00001 /*
00002  * Public libusbx header file
00003  * Copyright © 2001 Johannes Erdfelt <johannes@erdfelt.com>
00004  * Copyright © 2007-2008 Daniel Drake <dsd@gentoo.org>
00005  * Copyright © 2012 Pete Batard <pete@akeo.ie>
00006  * Copyright © 2012 Nathan Hjelm <hjelmn@cs.unm.edu>
00007  * For more information, please visit: http://libusbx.org
00008  *
00009  * This library is free software; you can redistribute it and/or
00010  * modify it under the terms of the GNU Lesser General Public
00011  * License as published by the Free Software Foundation; either
00012  * version 2.1 of the License, or (at your option) any later version.
00013  *
00014  * This library is distributed in the hope that it will be useful,
00015  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00016  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00017  * Lesser General Public License for more details.
00018  *
00019  * You should have received a copy of the GNU Lesser General Public
00020  * License along with this library; if not, write to the Free Software
00021  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
00022  */
00023 
00024 #ifndef LIBUSB_H
00025 #define LIBUSB_H
00026 
00027 #ifdef _MSC_VER
00028 /* on MS environments, the inline keyword is available in C++ only */
00029 #if !defined(__cplusplus)
00030 #define inline __inline
00031 #endif
00032 /* ssize_t is also not available (copy/paste from MinGW) */
00033 #ifndef _SSIZE_T_DEFINED
00034 #define _SSIZE_T_DEFINED
00035 #undef ssize_t
00036 #ifdef _WIN64
00037   typedef __int64 ssize_t;
00038 #else
00039   typedef int ssize_t;
00040 #endif /* _WIN64 */
00041 #endif /* _SSIZE_T_DEFINED */
00042 #endif /* _MSC_VER */
00043 
00044 /* stdint.h is not available on older MSVC */
00045 #if defined(_MSC_VER) && (_MSC_VER < 1600) && (!defined(_STDINT)) && (!defined(_STDINT_H))
00046 typedef unsigned __int8   uint8_t;
00047 typedef unsigned __int16  uint16_t;
00048 typedef unsigned __int32  uint32_t;
00049 #else
00050 #include <stdint.h>
00051 #endif
00052 
00053 #if !defined(_WIN32_WCE)
00054 #include <sys/types.h>
00055 #endif
00056 
00057 #if defined(__linux) || defined(__APPLE__) || defined(__CYGWIN__)
00058 #include <sys/time.h>
00059 #endif
00060 
00061 #include <time.h>
00062 #include <limits.h>
00063 
00064 /* 'interface' might be defined as a macro on Windows, so we need to
00065  * undefine it so as not to break the current libusbx API, because
00066  * libusb_config_descriptor has an 'interface' member
00067  * As this can be problematic if you include windows.h after libusb.h
00068  * in your sources, we force windows.h to be included first. */
00069 #if defined(_WIN32) || defined(__CYGWIN__) || defined(_WIN32_WCE)
00070 #include <windows.h>
00071 #if defined(interface)
00072 #undef interface
00073 #endif
00074 #if !defined(__CYGWIN__)
00075 #include <winsock.h>
00076 #endif
00077 #endif
00078 
00079 #if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5)
00080 #define LIBUSB_DEPRECATED_FOR(f) \
00081   __attribute__((deprecated("Use " #f " instead")))
00082 #else
00083 #define LIBUSB_DEPRECATED_FOR(f)
00084 #endif /* __GNUC__ */
00085 
00111 /* LIBUSB_CALL must be defined on both definition and declaration of libusbx
00112  * functions. You'd think that declaration would be enough, but cygwin will
00113  * complain about conflicting types unless both are marked this way.
00114  * The placement of this macro is important too; it must appear after the
00115  * return type, before the function name. See internal documentation for
00116  * API_EXPORTED.
00117  */
00118 #if defined(_WIN32) || defined(__CYGWIN__) || defined(_WIN32_WCE)
00119 #define LIBUSB_CALL WINAPI
00120 #else
00121 #define LIBUSB_CALL
00122 #endif
00123 
00147 #define LIBUSBX_API_VERSION 0x01000102
00148 
00149 #ifdef __cplusplus
00150 extern "C" {
00151 #endif
00152 
00161 static inline uint16_t libusb_cpu_to_le16(const uint16_t x)
00162 {
00163     union {
00164         uint8_t  b8[2];
00165         uint16_t b16;
00166     } _tmp;
00167     _tmp.b8[1] = (uint8_t) (x >> 8);
00168     _tmp.b8[0] = (uint8_t) (x & 0xff);
00169     return _tmp.b16;
00170 }
00171 
00180 #define libusb_le16_to_cpu libusb_cpu_to_le16
00181 
00182 /* standard USB stuff */
00183 
00186 enum libusb_class_code {
00191     LIBUSB_CLASS_PER_INTERFACE = 0,
00192 
00194     LIBUSB_CLASS_AUDIO = 1,
00195 
00197     LIBUSB_CLASS_COMM = 2,
00198 
00200     LIBUSB_CLASS_HID = 3,
00201 
00203     LIBUSB_CLASS_PHYSICAL = 5,
00204 
00206     LIBUSB_CLASS_PRINTER = 7,
00207 
00209     LIBUSB_CLASS_PTP = 6, /* legacy name from libusb-0.1 usb.h */
00210     LIBUSB_CLASS_IMAGE = 6,
00211 
00213     LIBUSB_CLASS_MASS_STORAGE = 8,
00214 
00216     LIBUSB_CLASS_HUB = 9,
00217 
00219     LIBUSB_CLASS_DATA = 10,
00220 
00222     LIBUSB_CLASS_SMART_CARD = 0x0b,
00223 
00225     LIBUSB_CLASS_CONTENT_SECURITY = 0x0d,
00226 
00228     LIBUSB_CLASS_VIDEO = 0x0e,
00229 
00231     LIBUSB_CLASS_PERSONAL_HEALTHCARE = 0x0f,
00232 
00234     LIBUSB_CLASS_DIAGNOSTIC_DEVICE = 0xdc,
00235 
00237     LIBUSB_CLASS_WIRELESS = 0xe0,
00238 
00240     LIBUSB_CLASS_APPLICATION = 0xfe,
00241 
00243     LIBUSB_CLASS_VENDOR_SPEC = 0xff
00244 };
00245 
00248 enum libusb_descriptor_type {
00250     LIBUSB_DT_DEVICE = 0x01,
00251 
00253     LIBUSB_DT_CONFIG = 0x02,
00254 
00256     LIBUSB_DT_STRING = 0x03,
00257 
00259     LIBUSB_DT_INTERFACE = 0x04,
00260 
00262     LIBUSB_DT_ENDPOINT = 0x05,
00263 
00265     LIBUSB_DT_BOS = 0x0f,
00266 
00268     LIBUSB_DT_DEVICE_CAPABILITY = 0x10,
00269 
00271     LIBUSB_DT_HID = 0x21,
00272 
00274     LIBUSB_DT_REPORT = 0x22,
00275 
00277     LIBUSB_DT_PHYSICAL = 0x23,
00278 
00280     LIBUSB_DT_HUB = 0x29,
00281 
00283     LIBUSB_DT_SUPERSPEED_HUB = 0x2a,
00284 
00286     LIBUSB_DT_SS_ENDPOINT_COMPANION = 0x30
00287 };
00288 
00289 /* Descriptor sizes per descriptor type */
00290 #define LIBUSB_DT_DEVICE_SIZE           18
00291 #define LIBUSB_DT_CONFIG_SIZE           9
00292 #define LIBUSB_DT_INTERFACE_SIZE        9
00293 #define LIBUSB_DT_ENDPOINT_SIZE         7
00294 #define LIBUSB_DT_ENDPOINT_AUDIO_SIZE       9   /* Audio extension */
00295 #define LIBUSB_DT_HUB_NONVAR_SIZE       7
00296 #define LIBUSB_DT_SS_ENDPOINT_COMPANION_SIZE    6
00297 #define LIBUSB_DT_BOS_SIZE          5
00298 #define LIBUSB_DT_DEVICE_CAPABILITY_SIZE    3
00299 
00300 /* BOS descriptor sizes */
00301 #define LIBUSB_BT_USB_2_0_EXTENSION_SIZE    7
00302 #define LIBUSB_BT_SS_USB_DEVICE_CAPABILITY_SIZE 10
00303 #define LIBUSB_BT_CONTAINER_ID_SIZE     20
00304 
00305 /* We unwrap the BOS => define its max size */
00306 #define LIBUSB_DT_BOS_MAX_SIZE      ((LIBUSB_DT_BOS_SIZE)     +\
00307                     (LIBUSB_BT_USB_2_0_EXTENSION_SIZE)       +\
00308                     (LIBUSB_BT_SS_USB_DEVICE_CAPABILITY_SIZE) +\
00309                     (LIBUSB_BT_CONTAINER_ID_SIZE))
00310 
00311 #define LIBUSB_ENDPOINT_ADDRESS_MASK    0x0f    /* in bEndpointAddress */
00312 #define LIBUSB_ENDPOINT_DIR_MASK        0x80
00313 
00318 enum libusb_endpoint_direction {
00320     LIBUSB_ENDPOINT_IN = 0x80,
00321 
00323     LIBUSB_ENDPOINT_OUT = 0x00
00324 };
00325 
00326 #define LIBUSB_TRANSFER_TYPE_MASK           0x03    /* in bmAttributes */
00327 
00332 enum libusb_transfer_type {
00334     LIBUSB_TRANSFER_TYPE_CONTROL = 0,
00335 
00337     LIBUSB_TRANSFER_TYPE_ISOCHRONOUS = 1,
00338 
00340     LIBUSB_TRANSFER_TYPE_BULK = 2,
00341 
00343     LIBUSB_TRANSFER_TYPE_INTERRUPT = 3
00344 };
00345 
00348 enum libusb_standard_request {
00350     LIBUSB_REQUEST_GET_STATUS = 0x00,
00351 
00353     LIBUSB_REQUEST_CLEAR_FEATURE = 0x01,
00354 
00355     /* 0x02 is reserved */
00356 
00358     LIBUSB_REQUEST_SET_FEATURE = 0x03,
00359 
00360     /* 0x04 is reserved */
00361 
00363     LIBUSB_REQUEST_SET_ADDRESS = 0x05,
00364 
00366     LIBUSB_REQUEST_GET_DESCRIPTOR = 0x06,
00367 
00369     LIBUSB_REQUEST_SET_DESCRIPTOR = 0x07,
00370 
00372     LIBUSB_REQUEST_GET_CONFIGURATION = 0x08,
00373 
00375     LIBUSB_REQUEST_SET_CONFIGURATION = 0x09,
00376 
00378     LIBUSB_REQUEST_GET_INTERFACE = 0x0A,
00379 
00381     LIBUSB_REQUEST_SET_INTERFACE = 0x0B,
00382 
00384     LIBUSB_REQUEST_SYNCH_FRAME = 0x0C,
00385 
00387     LIBUSB_REQUEST_SET_SEL = 0x30,
00388 
00391     LIBUSB_SET_ISOCH_DELAY = 0x31,
00392 };
00393 
00398 enum libusb_request_type {
00400     LIBUSB_REQUEST_TYPE_STANDARD = (0x00 << 5),
00401 
00403     LIBUSB_REQUEST_TYPE_CLASS = (0x01 << 5),
00404 
00406     LIBUSB_REQUEST_TYPE_VENDOR = (0x02 << 5),
00407 
00409     LIBUSB_REQUEST_TYPE_RESERVED = (0x03 << 5)
00410 };
00411 
00416 enum libusb_request_recipient {
00418     LIBUSB_RECIPIENT_DEVICE = 0x00,
00419 
00421     LIBUSB_RECIPIENT_INTERFACE = 0x01,
00422 
00424     LIBUSB_RECIPIENT_ENDPOINT = 0x02,
00425 
00427     LIBUSB_RECIPIENT_OTHER = 0x03,
00428 };
00429 
00430 #define LIBUSB_ISO_SYNC_TYPE_MASK       0x0C
00431 
00437 enum libusb_iso_sync_type {
00439     LIBUSB_ISO_SYNC_TYPE_NONE = 0,
00440 
00442     LIBUSB_ISO_SYNC_TYPE_ASYNC = 1,
00443 
00445     LIBUSB_ISO_SYNC_TYPE_ADAPTIVE = 2,
00446 
00448     LIBUSB_ISO_SYNC_TYPE_SYNC = 3
00449 };
00450 
00451 #define LIBUSB_ISO_USAGE_TYPE_MASK 0x30
00452 
00458 enum libusb_iso_usage_type {
00460     LIBUSB_ISO_USAGE_TYPE_DATA = 0,
00461 
00463     LIBUSB_ISO_USAGE_TYPE_FEEDBACK = 1,
00464 
00466     LIBUSB_ISO_USAGE_TYPE_IMPLICIT = 2,
00467 };
00468 
00474 struct libusb_device_descriptor {
00476     uint8_t  bLength;
00477 
00481     uint8_t  bDescriptorType;
00482 
00485     uint16_t bcdUSB;
00486 
00488     uint8_t  bDeviceClass;
00489 
00492     uint8_t  bDeviceSubClass;
00493 
00496     uint8_t  bDeviceProtocol;
00497 
00499     uint8_t  bMaxPacketSize0;
00500 
00502     uint16_t idVendor;
00503 
00505     uint16_t idProduct;
00506 
00508     uint16_t bcdDevice;
00509 
00511     uint8_t  iManufacturer;
00512 
00514     uint8_t  iProduct;
00515 
00517     uint8_t  iSerialNumber;
00518 
00520     uint8_t  bNumConfigurations;
00521 };
00522 
00528 struct libusb_endpoint_descriptor {
00530     uint8_t  bLength;
00531 
00535     uint8_t  bDescriptorType;
00536 
00541     uint8_t  bEndpointAddress;
00542 
00550     uint8_t  bmAttributes;
00551 
00553     uint16_t wMaxPacketSize;
00554 
00556     uint8_t  bInterval;
00557 
00560     uint8_t  bRefresh;
00561 
00563     uint8_t  bSynchAddress;
00564 
00567     const unsigned char *extra;
00568 
00570     int extra_length;
00571 };
00572 
00578 struct libusb_interface_descriptor {
00580     uint8_t  bLength;
00581 
00585     uint8_t  bDescriptorType;
00586 
00588     uint8_t  bInterfaceNumber;
00589 
00591     uint8_t  bAlternateSetting;
00592 
00595     uint8_t  bNumEndpoints;
00596 
00598     uint8_t  bInterfaceClass;
00599 
00602     uint8_t  bInterfaceSubClass;
00603 
00606     uint8_t  bInterfaceProtocol;
00607 
00609     uint8_t  iInterface;
00610 
00613     const struct libusb_endpoint_descriptor *endpoint;
00614 
00617     const unsigned char *extra;
00618 
00620     int extra_length;
00621 };
00622 
00626 struct libusb_interface {
00629     const struct libusb_interface_descriptor *altsetting;
00630 
00632     int num_altsetting;
00633 };
00634 
00640 struct libusb_config_descriptor {
00642     uint8_t  bLength;
00643 
00647     uint8_t  bDescriptorType;
00648 
00650     uint16_t wTotalLength;
00651 
00653     uint8_t  bNumInterfaces;
00654 
00656     uint8_t  bConfigurationValue;
00657 
00659     uint8_t  iConfiguration;
00660 
00662     uint8_t  bmAttributes;
00663 
00667     uint8_t  MaxPower;
00668 
00671     const struct libusb_interface *interface;
00672 
00675     const unsigned char *extra;
00676 
00678     int extra_length;
00679 };
00680 
00687 struct libusb_ss_endpoint_companion_descriptor {
00688 
00690     uint8_t  bLength;
00691 
00695     uint8_t  bDescriptorType;
00696 
00697 
00700     uint8_t  bMaxBurst;
00701 
00706     uint8_t  bmAttributes;
00707 
00710     uint16_t wBytesPerInterval;
00711 };
00712 
00718 struct libusb_bos_dev_capability_descriptor {
00720     uint8_t bLength;
00724     uint8_t bDescriptorType;
00726     uint8_t bDevCapabilityType;
00728     uint8_t dev_capability_data
00729 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
00730     [] /* valid C99 code */
00731 #else
00732     [0] /* non-standard, but usually working code */
00733 #endif
00734     ;
00735 };
00736 
00742 struct libusb_bos_descriptor {
00744     uint8_t  bLength;
00745 
00749     uint8_t  bDescriptorType;
00750 
00752     uint16_t wTotalLength;
00753 
00756     uint8_t  bNumDeviceCaps;
00757 
00759     struct libusb_bos_dev_capability_descriptor *dev_capability
00760 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
00761     [] /* valid C99 code */
00762 #else
00763     [0] /* non-standard, but usually working code */
00764 #endif
00765     ;
00766 };
00767 
00773 struct libusb_usb_2_0_extension_descriptor {
00775     uint8_t  bLength;
00776 
00780     uint8_t  bDescriptorType;
00781 
00785     uint8_t  bDevCapabilityType;
00786 
00791     uint32_t  bmAttributes;
00792 };
00793 
00799 struct libusb_ss_usb_device_capability_descriptor {
00801     uint8_t  bLength;
00802 
00806     uint8_t  bDescriptorType;
00807 
00811     uint8_t  bDevCapabilityType;
00812 
00817     uint8_t  bmAttributes;
00818 
00821     uint16_t wSpeedSupported;
00822 
00827     uint8_t  bFunctionalitySupport;
00828 
00830     uint8_t  bU1DevExitLat;
00831 
00833     uint16_t bU2DevExitLat;
00834 };
00835 
00841 struct libusb_container_id_descriptor {
00843     uint8_t  bLength;
00844 
00848     uint8_t  bDescriptorType;
00849 
00853     uint8_t  bDevCapabilityType;
00854 
00856     uint8_t bReserved;
00857 
00859     uint8_t  ContainerID[16];
00860 };
00861 
00864 struct libusb_control_setup {
00870     uint8_t  bmRequestType;
00871 
00877     uint8_t  bRequest;
00878 
00880     uint16_t wValue;
00881 
00884     uint16_t wIndex;
00885 
00887     uint16_t wLength;
00888 };
00889 
00890 #define LIBUSB_CONTROL_SETUP_SIZE (sizeof(struct libusb_control_setup))
00891 
00892 /* libusbx */
00893 
00894 struct libusb_context;
00895 struct libusb_device;
00896 struct libusb_device_handle;
00897 struct libusb_hotplug_callback;
00898 
00902 struct libusb_version {
00904     const uint16_t major;
00905 
00907     const uint16_t minor;
00908 
00910     const uint16_t micro;
00911 
00913     const uint16_t nano;
00914 
00916     const char *rc;
00917 
00919     const char* describe;
00920 };
00921 
00939 typedef struct libusb_context libusb_context;
00940 
00956 typedef struct libusb_device libusb_device;
00957 
00958 
00967 typedef struct libusb_device_handle libusb_device_handle;
00968 
00972 enum libusb_speed {
00974     LIBUSB_SPEED_UNKNOWN = 0,
00975 
00977     LIBUSB_SPEED_LOW = 1,
00978 
00980     LIBUSB_SPEED_FULL = 2,
00981 
00983     LIBUSB_SPEED_HIGH = 3,
00984 
00986     LIBUSB_SPEED_SUPER = 4,
00987 };
00988 
00993 enum libusb_supported_speed {
00995     LIBUSB_LOW_SPEED_OPERATION   = 1,
00996 
00998     LIBUSB_FULL_SPEED_OPERATION  = 2,
00999 
01001     LIBUSB_HIGH_SPEED_OPERATION  = 4,
01002 
01004     LIBUSB_SUPER_SPEED_OPERATION = 8,
01005 };
01006 
01012 enum libusb_usb_2_0_extension_attributes {
01014     LIBUSB_BM_LPM_SUPPORT = 2,
01015 };
01016 
01022 enum libusb_ss_usb_device_capability_attributes {
01024     LIBUSB_BM_LTM_SUPPORT = 2,
01025 };
01026 
01030 enum libusb_bos_type {
01032     LIBUSB_BT_WIRELESS_USB_DEVICE_CAPABILITY    = 1,
01033 
01035     LIBUSB_BT_USB_2_0_EXTENSION         = 2,
01036 
01038     LIBUSB_BT_SS_USB_DEVICE_CAPABILITY      = 3,
01039 
01041     LIBUSB_BT_CONTAINER_ID              = 4,
01042 };
01043 
01051 enum libusb_error {
01053     LIBUSB_SUCCESS = 0,
01054 
01056     LIBUSB_ERROR_IO = -1,
01057 
01059     LIBUSB_ERROR_INVALID_PARAM = -2,
01060 
01062     LIBUSB_ERROR_ACCESS = -3,
01063 
01065     LIBUSB_ERROR_NO_DEVICE = -4,
01066 
01068     LIBUSB_ERROR_NOT_FOUND = -5,
01069 
01071     LIBUSB_ERROR_BUSY = -6,
01072 
01074     LIBUSB_ERROR_TIMEOUT = -7,
01075 
01077     LIBUSB_ERROR_OVERFLOW = -8,
01078 
01080     LIBUSB_ERROR_PIPE = -9,
01081 
01083     LIBUSB_ERROR_INTERRUPTED = -10,
01084 
01086     LIBUSB_ERROR_NO_MEM = -11,
01087 
01089     LIBUSB_ERROR_NOT_SUPPORTED = -12,
01090 
01091     /* NB: Remember to update LIBUSB_ERROR_COUNT below as well as the
01092        message strings in strerror.c when adding new error codes here. */
01093 
01095     LIBUSB_ERROR_OTHER = -99,
01096 };
01097 
01098 /* Total number of error codes in enum libusb_error */
01099 #define LIBUSB_ERROR_COUNT 14
01100 
01103 enum libusb_transfer_status {
01106     LIBUSB_TRANSFER_COMPLETED,
01107 
01109     LIBUSB_TRANSFER_ERROR,
01110 
01112     LIBUSB_TRANSFER_TIMED_OUT,
01113 
01115     LIBUSB_TRANSFER_CANCELLED,
01116 
01119     LIBUSB_TRANSFER_STALL,
01120 
01122     LIBUSB_TRANSFER_NO_DEVICE,
01123 
01125     LIBUSB_TRANSFER_OVERFLOW,
01126 
01127     /* NB! Remember to update libusb_error_name()
01128        when adding new status codes here. */
01129 };
01130 
01133 enum libusb_transfer_flags {
01135     LIBUSB_TRANSFER_SHORT_NOT_OK = 1<<0,
01136 
01138     LIBUSB_TRANSFER_FREE_BUFFER = 1<<1,
01139 
01144     LIBUSB_TRANSFER_FREE_TRANSFER = 1<<2,
01145 
01169     LIBUSB_TRANSFER_ADD_ZERO_PACKET = 1 << 3,
01170 };
01171 
01174 struct libusb_iso_packet_descriptor {
01176     unsigned int length;
01177 
01179     unsigned int actual_length;
01180 
01182     enum libusb_transfer_status status;
01183 };
01184 
01185 struct libusb_transfer;
01186 
01196 typedef void (LIBUSB_CALL *libusb_transfer_cb_fn)(struct libusb_transfer *transfer);
01197 
01204 struct libusb_transfer {
01206     libusb_device_handle *dev_handle;
01207 
01209     uint8_t flags;
01210 
01212     unsigned char endpoint;
01213 
01215     unsigned char type;
01216 
01219     unsigned int timeout;
01220 
01228     enum libusb_transfer_status status;
01229 
01231     int length;
01232 
01236     int actual_length;
01237 
01240     libusb_transfer_cb_fn callback;
01241 
01243     void *user_data;
01244 
01246     unsigned char *buffer;
01247 
01250     int num_iso_packets;
01251 
01253     struct libusb_iso_packet_descriptor iso_packet_desc
01254 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
01255     [] /* valid C99 code */
01256 #else
01257     [0] /* non-standard, but usually working code */
01258 #endif
01259     ;
01260 };
01261 
01267 enum libusb_capability {
01269     LIBUSB_CAP_HAS_CAPABILITY = 0x0000,
01271     LIBUSB_CAP_HAS_HOTPLUG = 0x0001,
01276     LIBUSB_CAP_HAS_HID_ACCESS = 0x0100,
01279     LIBUSB_CAP_SUPPORTS_DETACH_KERNEL_DRIVER = 0x0101
01280 };
01281 
01292 enum libusb_log_level {
01293     LIBUSB_LOG_LEVEL_NONE = 0,
01294     LIBUSB_LOG_LEVEL_ERROR,
01295     LIBUSB_LOG_LEVEL_WARNING,
01296     LIBUSB_LOG_LEVEL_INFO,
01297     LIBUSB_LOG_LEVEL_DEBUG,
01298 };
01299 
01300 int LIBUSB_CALL libusb_init(libusb_context **ctx);
01301 void LIBUSB_CALL libusb_exit(libusb_context *ctx);
01302 void LIBUSB_CALL libusb_set_debug(libusb_context *ctx, int level);
01303 const struct libusb_version * LIBUSB_CALL libusb_get_version(void);
01304 int LIBUSB_CALL libusb_has_capability(uint32_t capability);
01305 const char * LIBUSB_CALL libusb_error_name(int errcode);
01306 int LIBUSB_CALL libusb_setlocale(const char *locale);
01307 const char * LIBUSB_CALL libusb_strerror(enum libusb_error errcode);
01308 
01309 ssize_t LIBUSB_CALL libusb_get_device_list(libusb_context *ctx,
01310     libusb_device ***list);
01311 void LIBUSB_CALL libusb_free_device_list(libusb_device **list,
01312     int unref_devices);
01313 libusb_device * LIBUSB_CALL libusb_ref_device(libusb_device *dev);
01314 void LIBUSB_CALL libusb_unref_device(libusb_device *dev);
01315 
01316 int LIBUSB_CALL libusb_get_configuration(libusb_device_handle *dev,
01317     int *config);
01318 int LIBUSB_CALL libusb_get_device_descriptor(libusb_device *dev,
01319     struct libusb_device_descriptor *desc);
01320 int LIBUSB_CALL libusb_get_active_config_descriptor(libusb_device *dev,
01321     struct libusb_config_descriptor **config);
01322 int LIBUSB_CALL libusb_get_config_descriptor(libusb_device *dev,
01323     uint8_t config_index, struct libusb_config_descriptor **config);
01324 int LIBUSB_CALL libusb_get_config_descriptor_by_value(libusb_device *dev,
01325     uint8_t bConfigurationValue, struct libusb_config_descriptor **config);
01326 void LIBUSB_CALL libusb_free_config_descriptor(
01327     struct libusb_config_descriptor *config);
01328 int LIBUSB_CALL libusb_get_ss_endpoint_companion_descriptor(
01329     struct libusb_context *ctx,
01330     const struct libusb_endpoint_descriptor *endpoint,
01331     struct libusb_ss_endpoint_companion_descriptor **ep_comp);
01332 void LIBUSB_CALL libusb_free_ss_endpoint_companion_descriptor(
01333     struct libusb_ss_endpoint_companion_descriptor *ep_comp);
01334 int LIBUSB_CALL libusb_get_bos_descriptor(libusb_device_handle *handle,
01335     struct libusb_bos_descriptor **bos);
01336 void LIBUSB_CALL libusb_free_bos_descriptor(struct libusb_bos_descriptor *bos);
01337 int LIBUSB_CALL libusb_get_usb_2_0_extension_descriptor(
01338     struct libusb_context *ctx,
01339     struct libusb_bos_dev_capability_descriptor *dev_cap,
01340     struct libusb_usb_2_0_extension_descriptor **usb_2_0_extension);
01341 void LIBUSB_CALL libusb_free_usb_2_0_extension_descriptor(
01342     struct libusb_usb_2_0_extension_descriptor *usb_2_0_extension);
01343 int LIBUSB_CALL libusb_get_ss_usb_device_capability_descriptor(
01344     struct libusb_context *ctx,
01345     struct libusb_bos_dev_capability_descriptor *dev_cap,
01346     struct libusb_ss_usb_device_capability_descriptor **ss_usb_device_cap);
01347 void LIBUSB_CALL libusb_free_ss_usb_device_capability_descriptor(
01348     struct libusb_ss_usb_device_capability_descriptor *ss_usb_device_cap);
01349 int LIBUSB_CALL libusb_get_container_id_descriptor(struct libusb_context *ctx,
01350     struct libusb_bos_dev_capability_descriptor *dev_cap,
01351     struct libusb_container_id_descriptor **container_id);
01352 void LIBUSB_CALL libusb_free_container_id_descriptor(
01353     struct libusb_container_id_descriptor *container_id);
01354 uint8_t LIBUSB_CALL libusb_get_bus_number(libusb_device *dev);
01355 uint8_t LIBUSB_CALL libusb_get_port_number(libusb_device *dev);
01356 int LIBUSB_CALL libusb_get_port_numbers(libusb_device *dev, uint8_t* port_numbers, int port_numbers_len);
01357 LIBUSB_DEPRECATED_FOR(libusb_get_port_numbers)
01358 int LIBUSB_CALL libusb_get_port_path(libusb_context *ctx, libusb_device *dev, uint8_t* path, uint8_t path_length);
01359 libusb_device * LIBUSB_CALL libusb_get_parent(libusb_device *dev);
01360 uint8_t LIBUSB_CALL libusb_get_device_address(libusb_device *dev);
01361 int LIBUSB_CALL libusb_get_device_speed(libusb_device *dev);
01362 int LIBUSB_CALL libusb_get_max_packet_size(libusb_device *dev,
01363     unsigned char endpoint);
01364 int LIBUSB_CALL libusb_get_max_iso_packet_size(libusb_device *dev,
01365     unsigned char endpoint);
01366 
01367 int LIBUSB_CALL libusb_open(libusb_device *dev, libusb_device_handle **handle);
01368 void LIBUSB_CALL libusb_close(libusb_device_handle *dev_handle);
01369 libusb_device * LIBUSB_CALL libusb_get_device(libusb_device_handle *dev_handle);
01370 
01371 int LIBUSB_CALL libusb_set_configuration(libusb_device_handle *dev,
01372     int configuration);
01373 int LIBUSB_CALL libusb_claim_interface(libusb_device_handle *dev,
01374     int interface_number);
01375 int LIBUSB_CALL libusb_release_interface(libusb_device_handle *dev,
01376     int interface_number);
01377 
01378 libusb_device_handle * LIBUSB_CALL libusb_open_device_with_vid_pid(
01379     libusb_context *ctx, uint16_t vendor_id, uint16_t product_id);
01380 
01381 int LIBUSB_CALL libusb_set_interface_alt_setting(libusb_device_handle *dev,
01382     int interface_number, int alternate_setting);
01383 int LIBUSB_CALL libusb_clear_halt(libusb_device_handle *dev,
01384     unsigned char endpoint);
01385 int LIBUSB_CALL libusb_reset_device(libusb_device_handle *dev);
01386 
01387 int LIBUSB_CALL libusb_kernel_driver_active(libusb_device_handle *dev,
01388     int interface_number);
01389 int LIBUSB_CALL libusb_detach_kernel_driver(libusb_device_handle *dev,
01390     int interface_number);
01391 int LIBUSB_CALL libusb_attach_kernel_driver(libusb_device_handle *dev,
01392     int interface_number);
01393 int LIBUSB_CALL libusb_set_auto_detach_kernel_driver(
01394     libusb_device_handle *dev, int enable);
01395 
01396 /* async I/O */
01397 
01410 static inline unsigned char *libusb_control_transfer_get_data(
01411     struct libusb_transfer *transfer)
01412 {
01413     return transfer->buffer + LIBUSB_CONTROL_SETUP_SIZE;
01414 }
01415 
01428 static inline struct libusb_control_setup *libusb_control_transfer_get_setup(
01429     struct libusb_transfer *transfer)
01430 {
01431     return (struct libusb_control_setup *) transfer->buffer;
01432 }
01433 
01456 static inline void libusb_fill_control_setup(unsigned char *buffer,
01457     uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
01458     uint16_t wLength)
01459 {
01460     struct libusb_control_setup *setup = (struct libusb_control_setup *) buffer;
01461     setup->bmRequestType = bmRequestType;
01462     setup->bRequest = bRequest;
01463     setup->wValue = libusb_cpu_to_le16(wValue);
01464     setup->wIndex = libusb_cpu_to_le16(wIndex);
01465     setup->wLength = libusb_cpu_to_le16(wLength);
01466 }
01467 
01468 struct libusb_transfer * LIBUSB_CALL libusb_alloc_transfer(int iso_packets);
01469 int LIBUSB_CALL libusb_submit_transfer(struct libusb_transfer *transfer);
01470 int LIBUSB_CALL libusb_cancel_transfer(struct libusb_transfer *transfer);
01471 void LIBUSB_CALL libusb_free_transfer(struct libusb_transfer *transfer);
01472 
01500 static inline void libusb_fill_control_transfer(
01501     struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
01502     unsigned char *buffer, libusb_transfer_cb_fn callback, void *user_data,
01503     unsigned int timeout)
01504 {
01505     struct libusb_control_setup *setup = (struct libusb_control_setup *) buffer;
01506     transfer->dev_handle = dev_handle;
01507     transfer->endpoint = 0;
01508     transfer->type = LIBUSB_TRANSFER_TYPE_CONTROL;
01509     transfer->timeout = timeout;
01510     transfer->buffer = buffer;
01511     if (setup)
01512         transfer->length = (int) (LIBUSB_CONTROL_SETUP_SIZE
01513             + libusb_le16_to_cpu(setup->wLength));
01514     transfer->user_data = user_data;
01515     transfer->callback = callback;
01516 }
01517 
01531 static inline void libusb_fill_bulk_transfer(struct libusb_transfer *transfer,
01532     libusb_device_handle *dev_handle, unsigned char endpoint,
01533     unsigned char *buffer, int length, libusb_transfer_cb_fn callback,
01534     void *user_data, unsigned int timeout)
01535 {
01536     transfer->dev_handle = dev_handle;
01537     transfer->endpoint = endpoint;
01538     transfer->type = LIBUSB_TRANSFER_TYPE_BULK;
01539     transfer->timeout = timeout;
01540     transfer->buffer = buffer;
01541     transfer->length = length;
01542     transfer->user_data = user_data;
01543     transfer->callback = callback;
01544 }
01545 
01559 static inline void libusb_fill_interrupt_transfer(
01560     struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
01561     unsigned char endpoint, unsigned char *buffer, int length,
01562     libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
01563 {
01564     transfer->dev_handle = dev_handle;
01565     transfer->endpoint = endpoint;
01566     transfer->type = LIBUSB_TRANSFER_TYPE_INTERRUPT;
01567     transfer->timeout = timeout;
01568     transfer->buffer = buffer;
01569     transfer->length = length;
01570     transfer->user_data = user_data;
01571     transfer->callback = callback;
01572 }
01573 
01588 static inline void libusb_fill_iso_transfer(struct libusb_transfer *transfer,
01589     libusb_device_handle *dev_handle, unsigned char endpoint,
01590     unsigned char *buffer, int length, int num_iso_packets,
01591     libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
01592 {
01593     transfer->dev_handle = dev_handle;
01594     transfer->endpoint = endpoint;
01595     transfer->type = LIBUSB_TRANSFER_TYPE_ISOCHRONOUS;
01596     transfer->timeout = timeout;
01597     transfer->buffer = buffer;
01598     transfer->length = length;
01599     transfer->num_iso_packets = num_iso_packets;
01600     transfer->user_data = user_data;
01601     transfer->callback = callback;
01602 }
01603 
01612 static inline void libusb_set_iso_packet_lengths(
01613     struct libusb_transfer *transfer, unsigned int length)
01614 {
01615     int i;
01616     for (i = 0; i < transfer->num_iso_packets; i++)
01617         transfer->iso_packet_desc[i].length = length;
01618 }
01619 
01636 static inline unsigned char *libusb_get_iso_packet_buffer(
01637     struct libusb_transfer *transfer, unsigned int packet)
01638 {
01639     int i;
01640     size_t offset = 0;
01641     int _packet;
01642 
01643     /* oops..slight bug in the API. packet is an unsigned int, but we use
01644      * signed integers almost everywhere else. range-check and convert to
01645      * signed to avoid compiler warnings. FIXME for libusb-2. */
01646     if (packet > INT_MAX)
01647         return NULL;
01648     _packet = (int) packet;
01649 
01650     if (_packet >= transfer->num_iso_packets)
01651         return NULL;
01652 
01653     for (i = 0; i < _packet; i++)
01654         offset += transfer->iso_packet_desc[i].length;
01655 
01656     return transfer->buffer + offset;
01657 }
01658 
01678 static inline unsigned char *libusb_get_iso_packet_buffer_simple(
01679     struct libusb_transfer *transfer, unsigned int packet)
01680 {
01681     int _packet;
01682 
01683     /* oops..slight bug in the API. packet is an unsigned int, but we use
01684      * signed integers almost everywhere else. range-check and convert to
01685      * signed to avoid compiler warnings. FIXME for libusb-2. */
01686     if (packet > INT_MAX)
01687         return NULL;
01688     _packet = (int) packet;
01689 
01690     if (_packet >= transfer->num_iso_packets)
01691         return NULL;
01692 
01693     return transfer->buffer + ((int) transfer->iso_packet_desc[0].length * _packet);
01694 }
01695 
01696 /* sync I/O */
01697 
01698 int LIBUSB_CALL libusb_control_transfer(libusb_device_handle *dev_handle,
01699     uint8_t request_type, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
01700     unsigned char *data, uint16_t wLength, unsigned int timeout);
01701 
01702 int LIBUSB_CALL libusb_bulk_transfer(libusb_device_handle *dev_handle,
01703     unsigned char endpoint, unsigned char *data, int length,
01704     int *actual_length, unsigned int timeout);
01705 
01706 int LIBUSB_CALL libusb_interrupt_transfer(libusb_device_handle *dev_handle,
01707     unsigned char endpoint, unsigned char *data, int length,
01708     int *actual_length, unsigned int timeout);
01709 
01722 static inline int libusb_get_descriptor(libusb_device_handle *dev,
01723     uint8_t desc_type, uint8_t desc_index, unsigned char *data, int length)
01724 {
01725     return libusb_control_transfer(dev, LIBUSB_ENDPOINT_IN,
01726         LIBUSB_REQUEST_GET_DESCRIPTOR, (uint16_t) ((desc_type << 8) | desc_index),
01727         0, data, (uint16_t) length, 1000);
01728 }
01729 
01744 static inline int libusb_get_string_descriptor(libusb_device_handle *dev,
01745     uint8_t desc_index, uint16_t langid, unsigned char *data, int length)
01746 {
01747     return libusb_control_transfer(dev, LIBUSB_ENDPOINT_IN,
01748         LIBUSB_REQUEST_GET_DESCRIPTOR, (uint16_t)((LIBUSB_DT_STRING << 8) | desc_index),
01749         langid, data, (uint16_t) length, 1000);
01750 }
01751 
01752 int LIBUSB_CALL libusb_get_string_descriptor_ascii(libusb_device_handle *dev,
01753     uint8_t desc_index, unsigned char *data, int length);
01754 
01755 /* polling and timeouts */
01756 
01757 int LIBUSB_CALL libusb_try_lock_events(libusb_context *ctx);
01758 void LIBUSB_CALL libusb_lock_events(libusb_context *ctx);
01759 void LIBUSB_CALL libusb_unlock_events(libusb_context *ctx);
01760 int LIBUSB_CALL libusb_event_handling_ok(libusb_context *ctx);
01761 int LIBUSB_CALL libusb_event_handler_active(libusb_context *ctx);
01762 void LIBUSB_CALL libusb_lock_event_waiters(libusb_context *ctx);
01763 void LIBUSB_CALL libusb_unlock_event_waiters(libusb_context *ctx);
01764 int LIBUSB_CALL libusb_wait_for_event(libusb_context *ctx, struct timeval *tv);
01765 
01766 int LIBUSB_CALL libusb_handle_events_timeout(libusb_context *ctx,
01767     struct timeval *tv);
01768 int LIBUSB_CALL libusb_handle_events_timeout_completed(libusb_context *ctx,
01769     struct timeval *tv, int *completed);
01770 int LIBUSB_CALL libusb_handle_events(libusb_context *ctx);
01771 int LIBUSB_CALL libusb_handle_events_completed(libusb_context *ctx, int *completed);
01772 int LIBUSB_CALL libusb_handle_events_locked(libusb_context *ctx,
01773     struct timeval *tv);
01774 int LIBUSB_CALL libusb_pollfds_handle_timeouts(libusb_context *ctx);
01775 int LIBUSB_CALL libusb_get_next_timeout(libusb_context *ctx,
01776     struct timeval *tv);
01777 
01781 struct libusb_pollfd {
01783     int fd;
01784 
01789     short events;
01790 };
01791 
01802 typedef void (LIBUSB_CALL *libusb_pollfd_added_cb)(int fd, short events,
01803     void *user_data);
01804 
01814 typedef void (LIBUSB_CALL *libusb_pollfd_removed_cb)(int fd, void *user_data);
01815 
01816 const struct libusb_pollfd ** LIBUSB_CALL libusb_get_pollfds(
01817     libusb_context *ctx);
01818 void LIBUSB_CALL libusb_set_pollfd_notifiers(libusb_context *ctx,
01819     libusb_pollfd_added_cb added_cb, libusb_pollfd_removed_cb removed_cb,
01820     void *user_data);
01821 
01834 typedef int libusb_hotplug_callback_handle;
01835 
01841 typedef enum {
01843     LIBUSB_HOTPLUG_ENUMERATE = 1,
01844 } libusb_hotplug_flag;
01845 
01851 typedef enum {
01853     LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED = 0x01,
01854 
01858     LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT    = 0x02,
01859 } libusb_hotplug_event;
01860 
01863 #define LIBUSB_HOTPLUG_MATCH_ANY -1
01864 
01887 typedef int (LIBUSB_CALL *libusb_hotplug_callback_fn)(libusb_context *ctx,
01888                         libusb_device *device,
01889                         libusb_hotplug_event event,
01890                         void *user_data);
01891 
01914 int LIBUSB_CALL libusb_hotplug_register_callback(libusb_context *ctx,
01915                         libusb_hotplug_event events,
01916                         libusb_hotplug_flag flags,
01917                         int vendor_id, int product_id,
01918                         int dev_class,
01919                         libusb_hotplug_callback_fn cb_fn,
01920                         void *user_data,
01921                         libusb_hotplug_callback_handle *handle);
01922 
01934 void LIBUSB_CALL libusb_hotplug_deregister_callback(libusb_context *ctx,
01935                         libusb_hotplug_callback_handle handle);
01936 
01937 #ifdef __cplusplus
01938 }
01939 #endif
01940 
01941 #endif