A cross-platform user library to access USB devices
libusb.h
00001 /*
00002  * Public libusb 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://libusb.info
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__) || defined(__HAIKU__)
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 libusb 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 libusb
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 
00144 #define LIBUSB_API_VERSION 0x01000105
00145 
00146 /* The following is kept for compatibility, but will be deprecated in the future */
00147 #define LIBUSBX_API_VERSION LIBUSB_API_VERSION
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 
00346     LIBUSB_TRANSFER_TYPE_BULK_STREAM = 4,
00347 };
00348 
00351 enum libusb_standard_request {
00353     LIBUSB_REQUEST_GET_STATUS = 0x00,
00354 
00356     LIBUSB_REQUEST_CLEAR_FEATURE = 0x01,
00357 
00358     /* 0x02 is reserved */
00359 
00361     LIBUSB_REQUEST_SET_FEATURE = 0x03,
00362 
00363     /* 0x04 is reserved */
00364 
00366     LIBUSB_REQUEST_SET_ADDRESS = 0x05,
00367 
00369     LIBUSB_REQUEST_GET_DESCRIPTOR = 0x06,
00370 
00372     LIBUSB_REQUEST_SET_DESCRIPTOR = 0x07,
00373 
00375     LIBUSB_REQUEST_GET_CONFIGURATION = 0x08,
00376 
00378     LIBUSB_REQUEST_SET_CONFIGURATION = 0x09,
00379 
00381     LIBUSB_REQUEST_GET_INTERFACE = 0x0A,
00382 
00384     LIBUSB_REQUEST_SET_INTERFACE = 0x0B,
00385 
00387     LIBUSB_REQUEST_SYNCH_FRAME = 0x0C,
00388 
00390     LIBUSB_REQUEST_SET_SEL = 0x30,
00391 
00394     LIBUSB_SET_ISOCH_DELAY = 0x31,
00395 };
00396 
00401 enum libusb_request_type {
00403     LIBUSB_REQUEST_TYPE_STANDARD = (0x00 << 5),
00404 
00406     LIBUSB_REQUEST_TYPE_CLASS = (0x01 << 5),
00407 
00409     LIBUSB_REQUEST_TYPE_VENDOR = (0x02 << 5),
00410 
00412     LIBUSB_REQUEST_TYPE_RESERVED = (0x03 << 5)
00413 };
00414 
00419 enum libusb_request_recipient {
00421     LIBUSB_RECIPIENT_DEVICE = 0x00,
00422 
00424     LIBUSB_RECIPIENT_INTERFACE = 0x01,
00425 
00427     LIBUSB_RECIPIENT_ENDPOINT = 0x02,
00428 
00430     LIBUSB_RECIPIENT_OTHER = 0x03,
00431 };
00432 
00433 #define LIBUSB_ISO_SYNC_TYPE_MASK       0x0C
00434 
00440 enum libusb_iso_sync_type {
00442     LIBUSB_ISO_SYNC_TYPE_NONE = 0,
00443 
00445     LIBUSB_ISO_SYNC_TYPE_ASYNC = 1,
00446 
00448     LIBUSB_ISO_SYNC_TYPE_ADAPTIVE = 2,
00449 
00451     LIBUSB_ISO_SYNC_TYPE_SYNC = 3
00452 };
00453 
00454 #define LIBUSB_ISO_USAGE_TYPE_MASK 0x30
00455 
00461 enum libusb_iso_usage_type {
00463     LIBUSB_ISO_USAGE_TYPE_DATA = 0,
00464 
00466     LIBUSB_ISO_USAGE_TYPE_FEEDBACK = 1,
00467 
00469     LIBUSB_ISO_USAGE_TYPE_IMPLICIT = 2,
00470 };
00471 
00477 struct libusb_device_descriptor {
00479     uint8_t  bLength;
00480 
00484     uint8_t  bDescriptorType;
00485 
00488     uint16_t bcdUSB;
00489 
00491     uint8_t  bDeviceClass;
00492 
00495     uint8_t  bDeviceSubClass;
00496 
00499     uint8_t  bDeviceProtocol;
00500 
00502     uint8_t  bMaxPacketSize0;
00503 
00505     uint16_t idVendor;
00506 
00508     uint16_t idProduct;
00509 
00511     uint16_t bcdDevice;
00512 
00514     uint8_t  iManufacturer;
00515 
00517     uint8_t  iProduct;
00518 
00520     uint8_t  iSerialNumber;
00521 
00523     uint8_t  bNumConfigurations;
00524 };
00525 
00531 struct libusb_endpoint_descriptor {
00533     uint8_t  bLength;
00534 
00538     uint8_t  bDescriptorType;
00539 
00544     uint8_t  bEndpointAddress;
00545 
00553     uint8_t  bmAttributes;
00554 
00556     uint16_t wMaxPacketSize;
00557 
00559     uint8_t  bInterval;
00560 
00563     uint8_t  bRefresh;
00564 
00566     uint8_t  bSynchAddress;
00567 
00570     const unsigned char *extra;
00571 
00573     int extra_length;
00574 };
00575 
00581 struct libusb_interface_descriptor {
00583     uint8_t  bLength;
00584 
00588     uint8_t  bDescriptorType;
00589 
00591     uint8_t  bInterfaceNumber;
00592 
00594     uint8_t  bAlternateSetting;
00595 
00598     uint8_t  bNumEndpoints;
00599 
00601     uint8_t  bInterfaceClass;
00602 
00605     uint8_t  bInterfaceSubClass;
00606 
00609     uint8_t  bInterfaceProtocol;
00610 
00612     uint8_t  iInterface;
00613 
00616     const struct libusb_endpoint_descriptor *endpoint;
00617 
00620     const unsigned char *extra;
00621 
00623     int extra_length;
00624 };
00625 
00629 struct libusb_interface {
00632     const struct libusb_interface_descriptor *altsetting;
00633 
00635     int num_altsetting;
00636 };
00637 
00643 struct libusb_config_descriptor {
00645     uint8_t  bLength;
00646 
00650     uint8_t  bDescriptorType;
00651 
00653     uint16_t wTotalLength;
00654 
00656     uint8_t  bNumInterfaces;
00657 
00659     uint8_t  bConfigurationValue;
00660 
00662     uint8_t  iConfiguration;
00663 
00665     uint8_t  bmAttributes;
00666 
00671     uint8_t  MaxPower;
00672 
00675     const struct libusb_interface *interface;
00676 
00679     const unsigned char *extra;
00680 
00682     int extra_length;
00683 };
00684 
00691 struct libusb_ss_endpoint_companion_descriptor {
00692 
00694     uint8_t  bLength;
00695 
00699     uint8_t  bDescriptorType;
00700 
00701 
00704     uint8_t  bMaxBurst;
00705 
00710     uint8_t  bmAttributes;
00711 
00714     uint16_t wBytesPerInterval;
00715 };
00716 
00722 struct libusb_bos_dev_capability_descriptor {
00724     uint8_t bLength;
00728     uint8_t bDescriptorType;
00730     uint8_t bDevCapabilityType;
00732     uint8_t dev_capability_data
00733 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
00734     [] /* valid C99 code */
00735 #else
00736     [0] /* non-standard, but usually working code */
00737 #endif
00738     ;
00739 };
00740 
00746 struct libusb_bos_descriptor {
00748     uint8_t  bLength;
00749 
00753     uint8_t  bDescriptorType;
00754 
00756     uint16_t wTotalLength;
00757 
00760     uint8_t  bNumDeviceCaps;
00761 
00763     struct libusb_bos_dev_capability_descriptor *dev_capability
00764 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
00765     [] /* valid C99 code */
00766 #else
00767     [0] /* non-standard, but usually working code */
00768 #endif
00769     ;
00770 };
00771 
00777 struct libusb_usb_2_0_extension_descriptor {
00779     uint8_t  bLength;
00780 
00784     uint8_t  bDescriptorType;
00785 
00789     uint8_t  bDevCapabilityType;
00790 
00795     uint32_t  bmAttributes;
00796 };
00797 
00803 struct libusb_ss_usb_device_capability_descriptor {
00805     uint8_t  bLength;
00806 
00810     uint8_t  bDescriptorType;
00811 
00815     uint8_t  bDevCapabilityType;
00816 
00821     uint8_t  bmAttributes;
00822 
00825     uint16_t wSpeedSupported;
00826 
00831     uint8_t  bFunctionalitySupport;
00832 
00834     uint8_t  bU1DevExitLat;
00835 
00837     uint16_t bU2DevExitLat;
00838 };
00839 
00845 struct libusb_container_id_descriptor {
00847     uint8_t  bLength;
00848 
00852     uint8_t  bDescriptorType;
00853 
00857     uint8_t  bDevCapabilityType;
00858 
00860     uint8_t bReserved;
00861 
00863     uint8_t  ContainerID[16];
00864 };
00865 
00868 struct libusb_control_setup {
00874     uint8_t  bmRequestType;
00875 
00881     uint8_t  bRequest;
00882 
00884     uint16_t wValue;
00885 
00888     uint16_t wIndex;
00889 
00891     uint16_t wLength;
00892 };
00893 
00894 #define LIBUSB_CONTROL_SETUP_SIZE (sizeof(struct libusb_control_setup))
00895 
00896 /* libusb */
00897 
00898 struct libusb_context;
00899 struct libusb_device;
00900 struct libusb_device_handle;
00901 
00905 struct libusb_version {
00907     const uint16_t major;
00908 
00910     const uint16_t minor;
00911 
00913     const uint16_t micro;
00914 
00916     const uint16_t nano;
00917 
00919     const char *rc;
00920 
00922     const char* describe;
00923 };
00924 
00942 typedef struct libusb_context libusb_context;
00943 
00959 typedef struct libusb_device libusb_device;
00960 
00961 
00970 typedef struct libusb_device_handle libusb_device_handle;
00971 
00975 enum libusb_speed {
00977     LIBUSB_SPEED_UNKNOWN = 0,
00978 
00980     LIBUSB_SPEED_LOW = 1,
00981 
00983     LIBUSB_SPEED_FULL = 2,
00984 
00986     LIBUSB_SPEED_HIGH = 3,
00987 
00989     LIBUSB_SPEED_SUPER = 4,
00990 };
00991 
00996 enum libusb_supported_speed {
00998     LIBUSB_LOW_SPEED_OPERATION   = 1,
00999 
01001     LIBUSB_FULL_SPEED_OPERATION  = 2,
01002 
01004     LIBUSB_HIGH_SPEED_OPERATION  = 4,
01005 
01007     LIBUSB_SUPER_SPEED_OPERATION = 8,
01008 };
01009 
01015 enum libusb_usb_2_0_extension_attributes {
01017     LIBUSB_BM_LPM_SUPPORT = 2,
01018 };
01019 
01025 enum libusb_ss_usb_device_capability_attributes {
01027     LIBUSB_BM_LTM_SUPPORT = 2,
01028 };
01029 
01033 enum libusb_bos_type {
01035     LIBUSB_BT_WIRELESS_USB_DEVICE_CAPABILITY    = 1,
01036 
01038     LIBUSB_BT_USB_2_0_EXTENSION         = 2,
01039 
01041     LIBUSB_BT_SS_USB_DEVICE_CAPABILITY      = 3,
01042 
01044     LIBUSB_BT_CONTAINER_ID              = 4,
01045 };
01046 
01054 enum libusb_error {
01056     LIBUSB_SUCCESS = 0,
01057 
01059     LIBUSB_ERROR_IO = -1,
01060 
01062     LIBUSB_ERROR_INVALID_PARAM = -2,
01063 
01065     LIBUSB_ERROR_ACCESS = -3,
01066 
01068     LIBUSB_ERROR_NO_DEVICE = -4,
01069 
01071     LIBUSB_ERROR_NOT_FOUND = -5,
01072 
01074     LIBUSB_ERROR_BUSY = -6,
01075 
01077     LIBUSB_ERROR_TIMEOUT = -7,
01078 
01080     LIBUSB_ERROR_OVERFLOW = -8,
01081 
01083     LIBUSB_ERROR_PIPE = -9,
01084 
01086     LIBUSB_ERROR_INTERRUPTED = -10,
01087 
01089     LIBUSB_ERROR_NO_MEM = -11,
01090 
01092     LIBUSB_ERROR_NOT_SUPPORTED = -12,
01093 
01094     /* NB: Remember to update LIBUSB_ERROR_COUNT below as well as the
01095        message strings in strerror.c when adding new error codes here. */
01096 
01098     LIBUSB_ERROR_OTHER = -99,
01099 };
01100 
01101 /* Total number of error codes in enum libusb_error */
01102 #define LIBUSB_ERROR_COUNT 14
01103 
01106 enum libusb_transfer_status {
01109     LIBUSB_TRANSFER_COMPLETED,
01110 
01112     LIBUSB_TRANSFER_ERROR,
01113 
01115     LIBUSB_TRANSFER_TIMED_OUT,
01116 
01118     LIBUSB_TRANSFER_CANCELLED,
01119 
01122     LIBUSB_TRANSFER_STALL,
01123 
01125     LIBUSB_TRANSFER_NO_DEVICE,
01126 
01128     LIBUSB_TRANSFER_OVERFLOW,
01129 
01130     /* NB! Remember to update libusb_error_name()
01131        when adding new status codes here. */
01132 };
01133 
01136 enum libusb_transfer_flags {
01138     LIBUSB_TRANSFER_SHORT_NOT_OK = 1<<0,
01139 
01144     LIBUSB_TRANSFER_FREE_BUFFER = 1<<1,
01145 
01150     LIBUSB_TRANSFER_FREE_TRANSFER = 1<<2,
01151 
01175     LIBUSB_TRANSFER_ADD_ZERO_PACKET = 1 << 3,
01176 };
01177 
01180 struct libusb_iso_packet_descriptor {
01182     unsigned int length;
01183 
01185     unsigned int actual_length;
01186 
01188     enum libusb_transfer_status status;
01189 };
01190 
01191 struct libusb_transfer;
01192 
01202 typedef void (LIBUSB_CALL *libusb_transfer_cb_fn)(struct libusb_transfer *transfer);
01203 
01210 struct libusb_transfer {
01212     libusb_device_handle *dev_handle;
01213 
01215     uint8_t flags;
01216 
01218     unsigned char endpoint;
01219 
01221     unsigned char type;
01222 
01225     unsigned int timeout;
01226 
01234     enum libusb_transfer_status status;
01235 
01237     int length;
01238 
01242     int actual_length;
01243 
01246     libusb_transfer_cb_fn callback;
01247 
01249     void *user_data;
01250 
01252     unsigned char *buffer;
01253 
01256     int num_iso_packets;
01257 
01259     struct libusb_iso_packet_descriptor iso_packet_desc
01260 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
01261     [] /* valid C99 code */
01262 #else
01263     [0] /* non-standard, but usually working code */
01264 #endif
01265     ;
01266 };
01267 
01273 enum libusb_capability {
01275     LIBUSB_CAP_HAS_CAPABILITY = 0x0000,
01277     LIBUSB_CAP_HAS_HOTPLUG = 0x0001,
01282     LIBUSB_CAP_HAS_HID_ACCESS = 0x0100,
01285     LIBUSB_CAP_SUPPORTS_DETACH_KERNEL_DRIVER = 0x0101
01286 };
01287 
01298 enum libusb_log_level {
01299     LIBUSB_LOG_LEVEL_NONE = 0,
01300     LIBUSB_LOG_LEVEL_ERROR,
01301     LIBUSB_LOG_LEVEL_WARNING,
01302     LIBUSB_LOG_LEVEL_INFO,
01303     LIBUSB_LOG_LEVEL_DEBUG,
01304 };
01305 
01306 int LIBUSB_CALL libusb_init(libusb_context **ctx);
01307 void LIBUSB_CALL libusb_exit(libusb_context *ctx);
01308 void LIBUSB_CALL libusb_set_debug(libusb_context *ctx, int level);
01309 const struct libusb_version * LIBUSB_CALL libusb_get_version(void);
01310 int LIBUSB_CALL libusb_has_capability(uint32_t capability);
01311 const char * LIBUSB_CALL libusb_error_name(int errcode);
01312 int LIBUSB_CALL libusb_setlocale(const char *locale);
01313 const char * LIBUSB_CALL libusb_strerror(enum libusb_error errcode);
01314 
01315 ssize_t LIBUSB_CALL libusb_get_device_list(libusb_context *ctx,
01316     libusb_device ***list);
01317 void LIBUSB_CALL libusb_free_device_list(libusb_device **list,
01318     int unref_devices);
01319 libusb_device * LIBUSB_CALL libusb_ref_device(libusb_device *dev);
01320 void LIBUSB_CALL libusb_unref_device(libusb_device *dev);
01321 
01322 int LIBUSB_CALL libusb_get_configuration(libusb_device_handle *dev,
01323     int *config);
01324 int LIBUSB_CALL libusb_get_device_descriptor(libusb_device *dev,
01325     struct libusb_device_descriptor *desc);
01326 int LIBUSB_CALL libusb_get_active_config_descriptor(libusb_device *dev,
01327     struct libusb_config_descriptor **config);
01328 int LIBUSB_CALL libusb_get_config_descriptor(libusb_device *dev,
01329     uint8_t config_index, struct libusb_config_descriptor **config);
01330 int LIBUSB_CALL libusb_get_config_descriptor_by_value(libusb_device *dev,
01331     uint8_t bConfigurationValue, struct libusb_config_descriptor **config);
01332 void LIBUSB_CALL libusb_free_config_descriptor(
01333     struct libusb_config_descriptor *config);
01334 int LIBUSB_CALL libusb_get_ss_endpoint_companion_descriptor(
01335     struct libusb_context *ctx,
01336     const struct libusb_endpoint_descriptor *endpoint,
01337     struct libusb_ss_endpoint_companion_descriptor **ep_comp);
01338 void LIBUSB_CALL libusb_free_ss_endpoint_companion_descriptor(
01339     struct libusb_ss_endpoint_companion_descriptor *ep_comp);
01340 int LIBUSB_CALL libusb_get_bos_descriptor(libusb_device_handle *dev_handle,
01341     struct libusb_bos_descriptor **bos);
01342 void LIBUSB_CALL libusb_free_bos_descriptor(struct libusb_bos_descriptor *bos);
01343 int LIBUSB_CALL libusb_get_usb_2_0_extension_descriptor(
01344     struct libusb_context *ctx,
01345     struct libusb_bos_dev_capability_descriptor *dev_cap,
01346     struct libusb_usb_2_0_extension_descriptor **usb_2_0_extension);
01347 void LIBUSB_CALL libusb_free_usb_2_0_extension_descriptor(
01348     struct libusb_usb_2_0_extension_descriptor *usb_2_0_extension);
01349 int LIBUSB_CALL libusb_get_ss_usb_device_capability_descriptor(
01350     struct libusb_context *ctx,
01351     struct libusb_bos_dev_capability_descriptor *dev_cap,
01352     struct libusb_ss_usb_device_capability_descriptor **ss_usb_device_cap);
01353 void LIBUSB_CALL libusb_free_ss_usb_device_capability_descriptor(
01354     struct libusb_ss_usb_device_capability_descriptor *ss_usb_device_cap);
01355 int LIBUSB_CALL libusb_get_container_id_descriptor(struct libusb_context *ctx,
01356     struct libusb_bos_dev_capability_descriptor *dev_cap,
01357     struct libusb_container_id_descriptor **container_id);
01358 void LIBUSB_CALL libusb_free_container_id_descriptor(
01359     struct libusb_container_id_descriptor *container_id);
01360 uint8_t LIBUSB_CALL libusb_get_bus_number(libusb_device *dev);
01361 uint8_t LIBUSB_CALL libusb_get_port_number(libusb_device *dev);
01362 int LIBUSB_CALL libusb_get_port_numbers(libusb_device *dev, uint8_t* port_numbers, int port_numbers_len);
01363 LIBUSB_DEPRECATED_FOR(libusb_get_port_numbers)
01364 int LIBUSB_CALL libusb_get_port_path(libusb_context *ctx, libusb_device *dev, uint8_t* path, uint8_t path_length);
01365 libusb_device * LIBUSB_CALL libusb_get_parent(libusb_device *dev);
01366 uint8_t LIBUSB_CALL libusb_get_device_address(libusb_device *dev);
01367 int LIBUSB_CALL libusb_get_device_speed(libusb_device *dev);
01368 int LIBUSB_CALL libusb_get_max_packet_size(libusb_device *dev,
01369     unsigned char endpoint);
01370 int LIBUSB_CALL libusb_get_max_iso_packet_size(libusb_device *dev,
01371     unsigned char endpoint);
01372 
01373 int LIBUSB_CALL libusb_open(libusb_device *dev, libusb_device_handle **dev_handle);
01374 void LIBUSB_CALL libusb_close(libusb_device_handle *dev_handle);
01375 libusb_device * LIBUSB_CALL libusb_get_device(libusb_device_handle *dev_handle);
01376 
01377 int LIBUSB_CALL libusb_set_configuration(libusb_device_handle *dev_handle,
01378     int configuration);
01379 int LIBUSB_CALL libusb_claim_interface(libusb_device_handle *dev_handle,
01380     int interface_number);
01381 int LIBUSB_CALL libusb_release_interface(libusb_device_handle *dev_handle,
01382     int interface_number);
01383 
01384 libusb_device_handle * LIBUSB_CALL libusb_open_device_with_vid_pid(
01385     libusb_context *ctx, uint16_t vendor_id, uint16_t product_id);
01386 
01387 int LIBUSB_CALL libusb_set_interface_alt_setting(libusb_device_handle *dev_handle,
01388     int interface_number, int alternate_setting);
01389 int LIBUSB_CALL libusb_clear_halt(libusb_device_handle *dev_handle,
01390     unsigned char endpoint);
01391 int LIBUSB_CALL libusb_reset_device(libusb_device_handle *dev_handle);
01392 
01393 int LIBUSB_CALL libusb_alloc_streams(libusb_device_handle *dev_handle,
01394     uint32_t num_streams, unsigned char *endpoints, int num_endpoints);
01395 int LIBUSB_CALL libusb_free_streams(libusb_device_handle *dev_handle,
01396     unsigned char *endpoints, int num_endpoints);
01397 
01398 unsigned char * LIBUSB_CALL libusb_dev_mem_alloc(libusb_device_handle *dev_handle,
01399     size_t length);
01400 int LIBUSB_CALL libusb_dev_mem_free(libusb_device_handle *dev_handle,
01401     unsigned char *buffer, size_t length);
01402 
01403 int LIBUSB_CALL libusb_kernel_driver_active(libusb_device_handle *dev_handle,
01404     int interface_number);
01405 int LIBUSB_CALL libusb_detach_kernel_driver(libusb_device_handle *dev_handle,
01406     int interface_number);
01407 int LIBUSB_CALL libusb_attach_kernel_driver(libusb_device_handle *dev_handle,
01408     int interface_number);
01409 int LIBUSB_CALL libusb_set_auto_detach_kernel_driver(
01410     libusb_device_handle *dev_handle, int enable);
01411 
01412 /* async I/O */
01413 
01426 static inline unsigned char *libusb_control_transfer_get_data(
01427     struct libusb_transfer *transfer)
01428 {
01429     return transfer->buffer + LIBUSB_CONTROL_SETUP_SIZE;
01430 }
01431 
01444 static inline struct libusb_control_setup *libusb_control_transfer_get_setup(
01445     struct libusb_transfer *transfer)
01446 {
01447     return (struct libusb_control_setup *)(void *) transfer->buffer;
01448 }
01449 
01473 static inline void libusb_fill_control_setup(unsigned char *buffer,
01474     uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
01475     uint16_t wLength)
01476 {
01477     struct libusb_control_setup *setup = (struct libusb_control_setup *)(void *) buffer;
01478     setup->bmRequestType = bmRequestType;
01479     setup->bRequest = bRequest;
01480     setup->wValue = libusb_cpu_to_le16(wValue);
01481     setup->wIndex = libusb_cpu_to_le16(wIndex);
01482     setup->wLength = libusb_cpu_to_le16(wLength);
01483 }
01484 
01485 struct libusb_transfer * LIBUSB_CALL libusb_alloc_transfer(int iso_packets);
01486 int LIBUSB_CALL libusb_submit_transfer(struct libusb_transfer *transfer);
01487 int LIBUSB_CALL libusb_cancel_transfer(struct libusb_transfer *transfer);
01488 void LIBUSB_CALL libusb_free_transfer(struct libusb_transfer *transfer);
01489 void LIBUSB_CALL libusb_transfer_set_stream_id(
01490     struct libusb_transfer *transfer, uint32_t stream_id);
01491 uint32_t LIBUSB_CALL libusb_transfer_get_stream_id(
01492     struct libusb_transfer *transfer);
01493 
01522 static inline void libusb_fill_control_transfer(
01523     struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
01524     unsigned char *buffer, libusb_transfer_cb_fn callback, void *user_data,
01525     unsigned int timeout)
01526 {
01527     struct libusb_control_setup *setup = (struct libusb_control_setup *)(void *) buffer;
01528     transfer->dev_handle = dev_handle;
01529     transfer->endpoint = 0;
01530     transfer->type = LIBUSB_TRANSFER_TYPE_CONTROL;
01531     transfer->timeout = timeout;
01532     transfer->buffer = buffer;
01533     if (setup)
01534         transfer->length = (int) (LIBUSB_CONTROL_SETUP_SIZE
01535             + libusb_le16_to_cpu(setup->wLength));
01536     transfer->user_data = user_data;
01537     transfer->callback = callback;
01538 }
01539 
01553 static inline void libusb_fill_bulk_transfer(struct libusb_transfer *transfer,
01554     libusb_device_handle *dev_handle, unsigned char endpoint,
01555     unsigned char *buffer, int length, libusb_transfer_cb_fn callback,
01556     void *user_data, unsigned int timeout)
01557 {
01558     transfer->dev_handle = dev_handle;
01559     transfer->endpoint = endpoint;
01560     transfer->type = LIBUSB_TRANSFER_TYPE_BULK;
01561     transfer->timeout = timeout;
01562     transfer->buffer = buffer;
01563     transfer->length = length;
01564     transfer->user_data = user_data;
01565     transfer->callback = callback;
01566 }
01567 
01584 static inline void libusb_fill_bulk_stream_transfer(
01585     struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
01586     unsigned char endpoint, uint32_t stream_id,
01587     unsigned char *buffer, int length, libusb_transfer_cb_fn callback,
01588     void *user_data, unsigned int timeout)
01589 {
01590     libusb_fill_bulk_transfer(transfer, dev_handle, endpoint, buffer,
01591                   length, callback, user_data, timeout);
01592     transfer->type = LIBUSB_TRANSFER_TYPE_BULK_STREAM;
01593     libusb_transfer_set_stream_id(transfer, stream_id);
01594 }
01595 
01609 static inline void libusb_fill_interrupt_transfer(
01610     struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
01611     unsigned char endpoint, unsigned char *buffer, int length,
01612     libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
01613 {
01614     transfer->dev_handle = dev_handle;
01615     transfer->endpoint = endpoint;
01616     transfer->type = LIBUSB_TRANSFER_TYPE_INTERRUPT;
01617     transfer->timeout = timeout;
01618     transfer->buffer = buffer;
01619     transfer->length = length;
01620     transfer->user_data = user_data;
01621     transfer->callback = callback;
01622 }
01623 
01638 static inline void libusb_fill_iso_transfer(struct libusb_transfer *transfer,
01639     libusb_device_handle *dev_handle, unsigned char endpoint,
01640     unsigned char *buffer, int length, int num_iso_packets,
01641     libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
01642 {
01643     transfer->dev_handle = dev_handle;
01644     transfer->endpoint = endpoint;
01645     transfer->type = LIBUSB_TRANSFER_TYPE_ISOCHRONOUS;
01646     transfer->timeout = timeout;
01647     transfer->buffer = buffer;
01648     transfer->length = length;
01649     transfer->num_iso_packets = num_iso_packets;
01650     transfer->user_data = user_data;
01651     transfer->callback = callback;
01652 }
01653 
01662 static inline void libusb_set_iso_packet_lengths(
01663     struct libusb_transfer *transfer, unsigned int length)
01664 {
01665     int i;
01666     for (i = 0; i < transfer->num_iso_packets; i++)
01667         transfer->iso_packet_desc[i].length = length;
01668 }
01669 
01686 static inline unsigned char *libusb_get_iso_packet_buffer(
01687     struct libusb_transfer *transfer, unsigned int packet)
01688 {
01689     int i;
01690     size_t offset = 0;
01691     int _packet;
01692 
01693     /* oops..slight bug in the API. packet is an unsigned int, but we use
01694      * signed integers almost everywhere else. range-check and convert to
01695      * signed to avoid compiler warnings. FIXME for libusb-2. */
01696     if (packet > INT_MAX)
01697         return NULL;
01698     _packet = (int) packet;
01699 
01700     if (_packet >= transfer->num_iso_packets)
01701         return NULL;
01702 
01703     for (i = 0; i < _packet; i++)
01704         offset += transfer->iso_packet_desc[i].length;
01705 
01706     return transfer->buffer + offset;
01707 }
01708 
01728 static inline unsigned char *libusb_get_iso_packet_buffer_simple(
01729     struct libusb_transfer *transfer, unsigned int packet)
01730 {
01731     int _packet;
01732 
01733     /* oops..slight bug in the API. packet is an unsigned int, but we use
01734      * signed integers almost everywhere else. range-check and convert to
01735      * signed to avoid compiler warnings. FIXME for libusb-2. */
01736     if (packet > INT_MAX)
01737         return NULL;
01738     _packet = (int) packet;
01739 
01740     if (_packet >= transfer->num_iso_packets)
01741         return NULL;
01742 
01743     return transfer->buffer + ((int) transfer->iso_packet_desc[0].length * _packet);
01744 }
01745 
01746 /* sync I/O */
01747 
01748 int LIBUSB_CALL libusb_control_transfer(libusb_device_handle *dev_handle,
01749     uint8_t request_type, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
01750     unsigned char *data, uint16_t wLength, unsigned int timeout);
01751 
01752 int LIBUSB_CALL libusb_bulk_transfer(libusb_device_handle *dev_handle,
01753     unsigned char endpoint, unsigned char *data, int length,
01754     int *actual_length, unsigned int timeout);
01755 
01756 int LIBUSB_CALL libusb_interrupt_transfer(libusb_device_handle *dev_handle,
01757     unsigned char endpoint, unsigned char *data, int length,
01758     int *actual_length, unsigned int timeout);
01759 
01772 static inline int libusb_get_descriptor(libusb_device_handle *dev_handle,
01773     uint8_t desc_type, uint8_t desc_index, unsigned char *data, int length)
01774 {
01775     return libusb_control_transfer(dev_handle, LIBUSB_ENDPOINT_IN,
01776         LIBUSB_REQUEST_GET_DESCRIPTOR, (uint16_t) ((desc_type << 8) | desc_index),
01777         0, data, (uint16_t) length, 1000);
01778 }
01779 
01794 static inline int libusb_get_string_descriptor(libusb_device_handle *dev_handle,
01795     uint8_t desc_index, uint16_t langid, unsigned char *data, int length)
01796 {
01797     return libusb_control_transfer(dev_handle, LIBUSB_ENDPOINT_IN,
01798         LIBUSB_REQUEST_GET_DESCRIPTOR, (uint16_t)((LIBUSB_DT_STRING << 8) | desc_index),
01799         langid, data, (uint16_t) length, 1000);
01800 }
01801 
01802 int LIBUSB_CALL libusb_get_string_descriptor_ascii(libusb_device_handle *dev_handle,
01803     uint8_t desc_index, unsigned char *data, int length);
01804 
01805 /* polling and timeouts */
01806 
01807 int LIBUSB_CALL libusb_try_lock_events(libusb_context *ctx);
01808 void LIBUSB_CALL libusb_lock_events(libusb_context *ctx);
01809 void LIBUSB_CALL libusb_unlock_events(libusb_context *ctx);
01810 int LIBUSB_CALL libusb_event_handling_ok(libusb_context *ctx);
01811 int LIBUSB_CALL libusb_event_handler_active(libusb_context *ctx);
01812 void LIBUSB_CALL libusb_interrupt_event_handler(libusb_context *ctx);
01813 void LIBUSB_CALL libusb_lock_event_waiters(libusb_context *ctx);
01814 void LIBUSB_CALL libusb_unlock_event_waiters(libusb_context *ctx);
01815 int LIBUSB_CALL libusb_wait_for_event(libusb_context *ctx, struct timeval *tv);
01816 
01817 int LIBUSB_CALL libusb_handle_events_timeout(libusb_context *ctx,
01818     struct timeval *tv);
01819 int LIBUSB_CALL libusb_handle_events_timeout_completed(libusb_context *ctx,
01820     struct timeval *tv, int *completed);
01821 int LIBUSB_CALL libusb_handle_events(libusb_context *ctx);
01822 int LIBUSB_CALL libusb_handle_events_completed(libusb_context *ctx, int *completed);
01823 int LIBUSB_CALL libusb_handle_events_locked(libusb_context *ctx,
01824     struct timeval *tv);
01825 int LIBUSB_CALL libusb_pollfds_handle_timeouts(libusb_context *ctx);
01826 int LIBUSB_CALL libusb_get_next_timeout(libusb_context *ctx,
01827     struct timeval *tv);
01828 
01832 struct libusb_pollfd {
01834     int fd;
01835 
01840     short events;
01841 };
01842 
01853 typedef void (LIBUSB_CALL *libusb_pollfd_added_cb)(int fd, short events,
01854     void *user_data);
01855 
01865 typedef void (LIBUSB_CALL *libusb_pollfd_removed_cb)(int fd, void *user_data);
01866 
01867 const struct libusb_pollfd ** LIBUSB_CALL libusb_get_pollfds(
01868     libusb_context *ctx);
01869 void LIBUSB_CALL libusb_free_pollfds(const struct libusb_pollfd **pollfds);
01870 void LIBUSB_CALL libusb_set_pollfd_notifiers(libusb_context *ctx,
01871     libusb_pollfd_added_cb added_cb, libusb_pollfd_removed_cb removed_cb,
01872     void *user_data);
01873 
01886 typedef int libusb_hotplug_callback_handle;
01887 
01893 typedef enum {
01895     LIBUSB_HOTPLUG_NO_FLAGS = 0,
01896 
01898     LIBUSB_HOTPLUG_ENUMERATE = 1<<0,
01899 } libusb_hotplug_flag;
01900 
01906 typedef enum {
01908     LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED = 0x01,
01909 
01913     LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT    = 0x02,
01914 } libusb_hotplug_event;
01915 
01918 #define LIBUSB_HOTPLUG_MATCH_ANY -1
01919 
01942 typedef int (LIBUSB_CALL *libusb_hotplug_callback_fn)(libusb_context *ctx,
01943                         libusb_device *device,
01944                         libusb_hotplug_event event,
01945                         void *user_data);
01946 
01981 int LIBUSB_CALL libusb_hotplug_register_callback(libusb_context *ctx,
01982                         libusb_hotplug_event events,
01983                         libusb_hotplug_flag flags,
01984                         int vendor_id, int product_id,
01985                         int dev_class,
01986                         libusb_hotplug_callback_fn cb_fn,
01987                         void *user_data,
01988                         libusb_hotplug_callback_handle *callback_handle);
01989 
02001 void LIBUSB_CALL libusb_hotplug_deregister_callback(libusb_context *ctx,
02002                         libusb_hotplug_callback_handle callback_handle);
02003 
02004 #ifdef __cplusplus
02005 }
02006 #endif
02007 
02008 #endif