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__)
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 
00147 #define LIBUSB_API_VERSION 0x01000103
00148 
00149 /* The following is kept for compatibility, but will be deprecated in the future */
00150 #define LIBUSBX_API_VERSION LIBUSB_API_VERSION
00151 
00152 #ifdef __cplusplus
00153 extern "C" {
00154 #endif
00155 
00164 static inline uint16_t libusb_cpu_to_le16(const uint16_t x)
00165 {
00166     union {
00167         uint8_t  b8[2];
00168         uint16_t b16;
00169     } _tmp;
00170     _tmp.b8[1] = (uint8_t) (x >> 8);
00171     _tmp.b8[0] = (uint8_t) (x & 0xff);
00172     return _tmp.b16;
00173 }
00174 
00183 #define libusb_le16_to_cpu libusb_cpu_to_le16
00184 
00185 /* standard USB stuff */
00186 
00189 enum libusb_class_code {
00194     LIBUSB_CLASS_PER_INTERFACE = 0,
00195 
00197     LIBUSB_CLASS_AUDIO = 1,
00198 
00200     LIBUSB_CLASS_COMM = 2,
00201 
00203     LIBUSB_CLASS_HID = 3,
00204 
00206     LIBUSB_CLASS_PHYSICAL = 5,
00207 
00209     LIBUSB_CLASS_PRINTER = 7,
00210 
00212     LIBUSB_CLASS_PTP = 6, /* legacy name from libusb-0.1 usb.h */
00213     LIBUSB_CLASS_IMAGE = 6,
00214 
00216     LIBUSB_CLASS_MASS_STORAGE = 8,
00217 
00219     LIBUSB_CLASS_HUB = 9,
00220 
00222     LIBUSB_CLASS_DATA = 10,
00223 
00225     LIBUSB_CLASS_SMART_CARD = 0x0b,
00226 
00228     LIBUSB_CLASS_CONTENT_SECURITY = 0x0d,
00229 
00231     LIBUSB_CLASS_VIDEO = 0x0e,
00232 
00234     LIBUSB_CLASS_PERSONAL_HEALTHCARE = 0x0f,
00235 
00237     LIBUSB_CLASS_DIAGNOSTIC_DEVICE = 0xdc,
00238 
00240     LIBUSB_CLASS_WIRELESS = 0xe0,
00241 
00243     LIBUSB_CLASS_APPLICATION = 0xfe,
00244 
00246     LIBUSB_CLASS_VENDOR_SPEC = 0xff
00247 };
00248 
00251 enum libusb_descriptor_type {
00253     LIBUSB_DT_DEVICE = 0x01,
00254 
00256     LIBUSB_DT_CONFIG = 0x02,
00257 
00259     LIBUSB_DT_STRING = 0x03,
00260 
00262     LIBUSB_DT_INTERFACE = 0x04,
00263 
00265     LIBUSB_DT_ENDPOINT = 0x05,
00266 
00268     LIBUSB_DT_BOS = 0x0f,
00269 
00271     LIBUSB_DT_DEVICE_CAPABILITY = 0x10,
00272 
00274     LIBUSB_DT_HID = 0x21,
00275 
00277     LIBUSB_DT_REPORT = 0x22,
00278 
00280     LIBUSB_DT_PHYSICAL = 0x23,
00281 
00283     LIBUSB_DT_HUB = 0x29,
00284 
00286     LIBUSB_DT_SUPERSPEED_HUB = 0x2a,
00287 
00289     LIBUSB_DT_SS_ENDPOINT_COMPANION = 0x30
00290 };
00291 
00292 /* Descriptor sizes per descriptor type */
00293 #define LIBUSB_DT_DEVICE_SIZE           18
00294 #define LIBUSB_DT_CONFIG_SIZE           9
00295 #define LIBUSB_DT_INTERFACE_SIZE        9
00296 #define LIBUSB_DT_ENDPOINT_SIZE         7
00297 #define LIBUSB_DT_ENDPOINT_AUDIO_SIZE       9   /* Audio extension */
00298 #define LIBUSB_DT_HUB_NONVAR_SIZE       7
00299 #define LIBUSB_DT_SS_ENDPOINT_COMPANION_SIZE    6
00300 #define LIBUSB_DT_BOS_SIZE          5
00301 #define LIBUSB_DT_DEVICE_CAPABILITY_SIZE    3
00302 
00303 /* BOS descriptor sizes */
00304 #define LIBUSB_BT_USB_2_0_EXTENSION_SIZE    7
00305 #define LIBUSB_BT_SS_USB_DEVICE_CAPABILITY_SIZE 10
00306 #define LIBUSB_BT_CONTAINER_ID_SIZE     20
00307 
00308 /* We unwrap the BOS => define its max size */
00309 #define LIBUSB_DT_BOS_MAX_SIZE      ((LIBUSB_DT_BOS_SIZE)     +\
00310                     (LIBUSB_BT_USB_2_0_EXTENSION_SIZE)       +\
00311                     (LIBUSB_BT_SS_USB_DEVICE_CAPABILITY_SIZE) +\
00312                     (LIBUSB_BT_CONTAINER_ID_SIZE))
00313 
00314 #define LIBUSB_ENDPOINT_ADDRESS_MASK    0x0f    /* in bEndpointAddress */
00315 #define LIBUSB_ENDPOINT_DIR_MASK        0x80
00316 
00321 enum libusb_endpoint_direction {
00323     LIBUSB_ENDPOINT_IN = 0x80,
00324 
00326     LIBUSB_ENDPOINT_OUT = 0x00
00327 };
00328 
00329 #define LIBUSB_TRANSFER_TYPE_MASK           0x03    /* in bmAttributes */
00330 
00335 enum libusb_transfer_type {
00337     LIBUSB_TRANSFER_TYPE_CONTROL = 0,
00338 
00340     LIBUSB_TRANSFER_TYPE_ISOCHRONOUS = 1,
00341 
00343     LIBUSB_TRANSFER_TYPE_BULK = 2,
00344 
00346     LIBUSB_TRANSFER_TYPE_INTERRUPT = 3,
00347 
00349     LIBUSB_TRANSFER_TYPE_BULK_STREAM = 4,
00350 };
00351 
00354 enum libusb_standard_request {
00356     LIBUSB_REQUEST_GET_STATUS = 0x00,
00357 
00359     LIBUSB_REQUEST_CLEAR_FEATURE = 0x01,
00360 
00361     /* 0x02 is reserved */
00362 
00364     LIBUSB_REQUEST_SET_FEATURE = 0x03,
00365 
00366     /* 0x04 is reserved */
00367 
00369     LIBUSB_REQUEST_SET_ADDRESS = 0x05,
00370 
00372     LIBUSB_REQUEST_GET_DESCRIPTOR = 0x06,
00373 
00375     LIBUSB_REQUEST_SET_DESCRIPTOR = 0x07,
00376 
00378     LIBUSB_REQUEST_GET_CONFIGURATION = 0x08,
00379 
00381     LIBUSB_REQUEST_SET_CONFIGURATION = 0x09,
00382 
00384     LIBUSB_REQUEST_GET_INTERFACE = 0x0A,
00385 
00387     LIBUSB_REQUEST_SET_INTERFACE = 0x0B,
00388 
00390     LIBUSB_REQUEST_SYNCH_FRAME = 0x0C,
00391 
00393     LIBUSB_REQUEST_SET_SEL = 0x30,
00394 
00397     LIBUSB_SET_ISOCH_DELAY = 0x31,
00398 };
00399 
00404 enum libusb_request_type {
00406     LIBUSB_REQUEST_TYPE_STANDARD = (0x00 << 5),
00407 
00409     LIBUSB_REQUEST_TYPE_CLASS = (0x01 << 5),
00410 
00412     LIBUSB_REQUEST_TYPE_VENDOR = (0x02 << 5),
00413 
00415     LIBUSB_REQUEST_TYPE_RESERVED = (0x03 << 5)
00416 };
00417 
00422 enum libusb_request_recipient {
00424     LIBUSB_RECIPIENT_DEVICE = 0x00,
00425 
00427     LIBUSB_RECIPIENT_INTERFACE = 0x01,
00428 
00430     LIBUSB_RECIPIENT_ENDPOINT = 0x02,
00431 
00433     LIBUSB_RECIPIENT_OTHER = 0x03,
00434 };
00435 
00436 #define LIBUSB_ISO_SYNC_TYPE_MASK       0x0C
00437 
00443 enum libusb_iso_sync_type {
00445     LIBUSB_ISO_SYNC_TYPE_NONE = 0,
00446 
00448     LIBUSB_ISO_SYNC_TYPE_ASYNC = 1,
00449 
00451     LIBUSB_ISO_SYNC_TYPE_ADAPTIVE = 2,
00452 
00454     LIBUSB_ISO_SYNC_TYPE_SYNC = 3
00455 };
00456 
00457 #define LIBUSB_ISO_USAGE_TYPE_MASK 0x30
00458 
00464 enum libusb_iso_usage_type {
00466     LIBUSB_ISO_USAGE_TYPE_DATA = 0,
00467 
00469     LIBUSB_ISO_USAGE_TYPE_FEEDBACK = 1,
00470 
00472     LIBUSB_ISO_USAGE_TYPE_IMPLICIT = 2,
00473 };
00474 
00480 struct libusb_device_descriptor {
00482     uint8_t  bLength;
00483 
00487     uint8_t  bDescriptorType;
00488 
00491     uint16_t bcdUSB;
00492 
00494     uint8_t  bDeviceClass;
00495 
00498     uint8_t  bDeviceSubClass;
00499 
00502     uint8_t  bDeviceProtocol;
00503 
00505     uint8_t  bMaxPacketSize0;
00506 
00508     uint16_t idVendor;
00509 
00511     uint16_t idProduct;
00512 
00514     uint16_t bcdDevice;
00515 
00517     uint8_t  iManufacturer;
00518 
00520     uint8_t  iProduct;
00521 
00523     uint8_t  iSerialNumber;
00524 
00526     uint8_t  bNumConfigurations;
00527 };
00528 
00534 struct libusb_endpoint_descriptor {
00536     uint8_t  bLength;
00537 
00541     uint8_t  bDescriptorType;
00542 
00547     uint8_t  bEndpointAddress;
00548 
00556     uint8_t  bmAttributes;
00557 
00559     uint16_t wMaxPacketSize;
00560 
00562     uint8_t  bInterval;
00563 
00566     uint8_t  bRefresh;
00567 
00569     uint8_t  bSynchAddress;
00570 
00573     const unsigned char *extra;
00574 
00576     int extra_length;
00577 };
00578 
00584 struct libusb_interface_descriptor {
00586     uint8_t  bLength;
00587 
00591     uint8_t  bDescriptorType;
00592 
00594     uint8_t  bInterfaceNumber;
00595 
00597     uint8_t  bAlternateSetting;
00598 
00601     uint8_t  bNumEndpoints;
00602 
00604     uint8_t  bInterfaceClass;
00605 
00608     uint8_t  bInterfaceSubClass;
00609 
00612     uint8_t  bInterfaceProtocol;
00613 
00615     uint8_t  iInterface;
00616 
00619     const struct libusb_endpoint_descriptor *endpoint;
00620 
00623     const unsigned char *extra;
00624 
00626     int extra_length;
00627 };
00628 
00632 struct libusb_interface {
00635     const struct libusb_interface_descriptor *altsetting;
00636 
00638     int num_altsetting;
00639 };
00640 
00646 struct libusb_config_descriptor {
00648     uint8_t  bLength;
00649 
00653     uint8_t  bDescriptorType;
00654 
00656     uint16_t wTotalLength;
00657 
00659     uint8_t  bNumInterfaces;
00660 
00662     uint8_t  bConfigurationValue;
00663 
00665     uint8_t  iConfiguration;
00666 
00668     uint8_t  bmAttributes;
00669 
00673     uint8_t  MaxPower;
00674 
00677     const struct libusb_interface *interface;
00678 
00681     const unsigned char *extra;
00682 
00684     int extra_length;
00685 };
00686 
00693 struct libusb_ss_endpoint_companion_descriptor {
00694 
00696     uint8_t  bLength;
00697 
00701     uint8_t  bDescriptorType;
00702 
00703 
00706     uint8_t  bMaxBurst;
00707 
00712     uint8_t  bmAttributes;
00713 
00716     uint16_t wBytesPerInterval;
00717 };
00718 
00724 struct libusb_bos_dev_capability_descriptor {
00726     uint8_t bLength;
00730     uint8_t bDescriptorType;
00732     uint8_t bDevCapabilityType;
00734     uint8_t dev_capability_data
00735 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
00736     [] /* valid C99 code */
00737 #else
00738     [0] /* non-standard, but usually working code */
00739 #endif
00740     ;
00741 };
00742 
00748 struct libusb_bos_descriptor {
00750     uint8_t  bLength;
00751 
00755     uint8_t  bDescriptorType;
00756 
00758     uint16_t wTotalLength;
00759 
00762     uint8_t  bNumDeviceCaps;
00763 
00765     struct libusb_bos_dev_capability_descriptor *dev_capability
00766 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
00767     [] /* valid C99 code */
00768 #else
00769     [0] /* non-standard, but usually working code */
00770 #endif
00771     ;
00772 };
00773 
00779 struct libusb_usb_2_0_extension_descriptor {
00781     uint8_t  bLength;
00782 
00786     uint8_t  bDescriptorType;
00787 
00791     uint8_t  bDevCapabilityType;
00792 
00797     uint32_t  bmAttributes;
00798 };
00799 
00805 struct libusb_ss_usb_device_capability_descriptor {
00807     uint8_t  bLength;
00808 
00812     uint8_t  bDescriptorType;
00813 
00817     uint8_t  bDevCapabilityType;
00818 
00823     uint8_t  bmAttributes;
00824 
00827     uint16_t wSpeedSupported;
00828 
00833     uint8_t  bFunctionalitySupport;
00834 
00836     uint8_t  bU1DevExitLat;
00837 
00839     uint16_t bU2DevExitLat;
00840 };
00841 
00847 struct libusb_container_id_descriptor {
00849     uint8_t  bLength;
00850 
00854     uint8_t  bDescriptorType;
00855 
00859     uint8_t  bDevCapabilityType;
00860 
00862     uint8_t bReserved;
00863 
00865     uint8_t  ContainerID[16];
00866 };
00867 
00870 struct libusb_control_setup {
00876     uint8_t  bmRequestType;
00877 
00883     uint8_t  bRequest;
00884 
00886     uint16_t wValue;
00887 
00890     uint16_t wIndex;
00891 
00893     uint16_t wLength;
00894 };
00895 
00896 #define LIBUSB_CONTROL_SETUP_SIZE (sizeof(struct libusb_control_setup))
00897 
00898 /* libusb */
00899 
00900 struct libusb_context;
00901 struct libusb_device;
00902 struct libusb_device_handle;
00903 struct libusb_hotplug_callback;
00904 
00908 struct libusb_version {
00910     const uint16_t major;
00911 
00913     const uint16_t minor;
00914 
00916     const uint16_t micro;
00917 
00919     const uint16_t nano;
00920 
00922     const char *rc;
00923 
00925     const char* describe;
00926 };
00927 
00945 typedef struct libusb_context libusb_context;
00946 
00962 typedef struct libusb_device libusb_device;
00963 
00964 
00973 typedef struct libusb_device_handle libusb_device_handle;
00974 
00978 enum libusb_speed {
00980     LIBUSB_SPEED_UNKNOWN = 0,
00981 
00983     LIBUSB_SPEED_LOW = 1,
00984 
00986     LIBUSB_SPEED_FULL = 2,
00987 
00989     LIBUSB_SPEED_HIGH = 3,
00990 
00992     LIBUSB_SPEED_SUPER = 4,
00993 };
00994 
00999 enum libusb_supported_speed {
01001     LIBUSB_LOW_SPEED_OPERATION   = 1,
01002 
01004     LIBUSB_FULL_SPEED_OPERATION  = 2,
01005 
01007     LIBUSB_HIGH_SPEED_OPERATION  = 4,
01008 
01010     LIBUSB_SUPER_SPEED_OPERATION = 8,
01011 };
01012 
01018 enum libusb_usb_2_0_extension_attributes {
01020     LIBUSB_BM_LPM_SUPPORT = 2,
01021 };
01022 
01028 enum libusb_ss_usb_device_capability_attributes {
01030     LIBUSB_BM_LTM_SUPPORT = 2,
01031 };
01032 
01036 enum libusb_bos_type {
01038     LIBUSB_BT_WIRELESS_USB_DEVICE_CAPABILITY    = 1,
01039 
01041     LIBUSB_BT_USB_2_0_EXTENSION         = 2,
01042 
01044     LIBUSB_BT_SS_USB_DEVICE_CAPABILITY      = 3,
01045 
01047     LIBUSB_BT_CONTAINER_ID              = 4,
01048 };
01049 
01057 enum libusb_error {
01059     LIBUSB_SUCCESS = 0,
01060 
01062     LIBUSB_ERROR_IO = -1,
01063 
01065     LIBUSB_ERROR_INVALID_PARAM = -2,
01066 
01068     LIBUSB_ERROR_ACCESS = -3,
01069 
01071     LIBUSB_ERROR_NO_DEVICE = -4,
01072 
01074     LIBUSB_ERROR_NOT_FOUND = -5,
01075 
01077     LIBUSB_ERROR_BUSY = -6,
01078 
01080     LIBUSB_ERROR_TIMEOUT = -7,
01081 
01083     LIBUSB_ERROR_OVERFLOW = -8,
01084 
01086     LIBUSB_ERROR_PIPE = -9,
01087 
01089     LIBUSB_ERROR_INTERRUPTED = -10,
01090 
01092     LIBUSB_ERROR_NO_MEM = -11,
01093 
01095     LIBUSB_ERROR_NOT_SUPPORTED = -12,
01096 
01097     /* NB: Remember to update LIBUSB_ERROR_COUNT below as well as the
01098        message strings in strerror.c when adding new error codes here. */
01099 
01101     LIBUSB_ERROR_OTHER = -99,
01102 };
01103 
01104 /* Total number of error codes in enum libusb_error */
01105 #define LIBUSB_ERROR_COUNT 14
01106 
01109 enum libusb_transfer_status {
01112     LIBUSB_TRANSFER_COMPLETED,
01113 
01115     LIBUSB_TRANSFER_ERROR,
01116 
01118     LIBUSB_TRANSFER_TIMED_OUT,
01119 
01121     LIBUSB_TRANSFER_CANCELLED,
01122 
01125     LIBUSB_TRANSFER_STALL,
01126 
01128     LIBUSB_TRANSFER_NO_DEVICE,
01129 
01131     LIBUSB_TRANSFER_OVERFLOW,
01132 
01133     /* NB! Remember to update libusb_error_name()
01134        when adding new status codes here. */
01135 };
01136 
01139 enum libusb_transfer_flags {
01141     LIBUSB_TRANSFER_SHORT_NOT_OK = 1<<0,
01142 
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 *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 **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,
01378     int configuration);
01379 int LIBUSB_CALL libusb_claim_interface(libusb_device_handle *dev,
01380     int interface_number);
01381 int LIBUSB_CALL libusb_release_interface(libusb_device_handle *dev,
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,
01388     int interface_number, int alternate_setting);
01389 int LIBUSB_CALL libusb_clear_halt(libusb_device_handle *dev,
01390     unsigned char endpoint);
01391 int LIBUSB_CALL libusb_reset_device(libusb_device_handle *dev);
01392 
01393 int LIBUSB_CALL libusb_alloc_streams(libusb_device_handle *dev,
01394     uint32_t num_streams, unsigned char *endpoints, int num_endpoints);
01395 int LIBUSB_CALL libusb_free_streams(libusb_device_handle *dev,
01396     unsigned char *endpoints, int num_endpoints);
01397 
01398 int LIBUSB_CALL libusb_kernel_driver_active(libusb_device_handle *dev,
01399     int interface_number);
01400 int LIBUSB_CALL libusb_detach_kernel_driver(libusb_device_handle *dev,
01401     int interface_number);
01402 int LIBUSB_CALL libusb_attach_kernel_driver(libusb_device_handle *dev,
01403     int interface_number);
01404 int LIBUSB_CALL libusb_set_auto_detach_kernel_driver(
01405     libusb_device_handle *dev, int enable);
01406 
01407 /* async I/O */
01408 
01421 static inline unsigned char *libusb_control_transfer_get_data(
01422     struct libusb_transfer *transfer)
01423 {
01424     return transfer->buffer + LIBUSB_CONTROL_SETUP_SIZE;
01425 }
01426 
01439 static inline struct libusb_control_setup *libusb_control_transfer_get_setup(
01440     struct libusb_transfer *transfer)
01441 {
01442     return (struct libusb_control_setup *)(void *) transfer->buffer;
01443 }
01444 
01468 static inline void libusb_fill_control_setup(unsigned char *buffer,
01469     uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
01470     uint16_t wLength)
01471 {
01472     struct libusb_control_setup *setup = (struct libusb_control_setup *)(void *) buffer;
01473     setup->bmRequestType = bmRequestType;
01474     setup->bRequest = bRequest;
01475     setup->wValue = libusb_cpu_to_le16(wValue);
01476     setup->wIndex = libusb_cpu_to_le16(wIndex);
01477     setup->wLength = libusb_cpu_to_le16(wLength);
01478 }
01479 
01480 struct libusb_transfer * LIBUSB_CALL libusb_alloc_transfer(int iso_packets);
01481 int LIBUSB_CALL libusb_submit_transfer(struct libusb_transfer *transfer);
01482 int LIBUSB_CALL libusb_cancel_transfer(struct libusb_transfer *transfer);
01483 void LIBUSB_CALL libusb_free_transfer(struct libusb_transfer *transfer);
01484 void LIBUSB_CALL libusb_transfer_set_stream_id(
01485     struct libusb_transfer *transfer, uint32_t stream_id);
01486 uint32_t LIBUSB_CALL libusb_transfer_get_stream_id(
01487     struct libusb_transfer *transfer);
01488 
01517 static inline void libusb_fill_control_transfer(
01518     struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
01519     unsigned char *buffer, libusb_transfer_cb_fn callback, void *user_data,
01520     unsigned int timeout)
01521 {
01522     struct libusb_control_setup *setup = (struct libusb_control_setup *)(void *) buffer;
01523     transfer->dev_handle = dev_handle;
01524     transfer->endpoint = 0;
01525     transfer->type = LIBUSB_TRANSFER_TYPE_CONTROL;
01526     transfer->timeout = timeout;
01527     transfer->buffer = buffer;
01528     if (setup)
01529         transfer->length = (int) (LIBUSB_CONTROL_SETUP_SIZE
01530             + libusb_le16_to_cpu(setup->wLength));
01531     transfer->user_data = user_data;
01532     transfer->callback = callback;
01533 }
01534 
01548 static inline void libusb_fill_bulk_transfer(struct libusb_transfer *transfer,
01549     libusb_device_handle *dev_handle, unsigned char endpoint,
01550     unsigned char *buffer, int length, libusb_transfer_cb_fn callback,
01551     void *user_data, unsigned int timeout)
01552 {
01553     transfer->dev_handle = dev_handle;
01554     transfer->endpoint = endpoint;
01555     transfer->type = LIBUSB_TRANSFER_TYPE_BULK;
01556     transfer->timeout = timeout;
01557     transfer->buffer = buffer;
01558     transfer->length = length;
01559     transfer->user_data = user_data;
01560     transfer->callback = callback;
01561 }
01562 
01579 static inline void libusb_fill_bulk_stream_transfer(
01580     struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
01581     unsigned char endpoint, uint32_t stream_id,
01582     unsigned char *buffer, int length, libusb_transfer_cb_fn callback,
01583     void *user_data, unsigned int timeout)
01584 {
01585     libusb_fill_bulk_transfer(transfer, dev_handle, endpoint, buffer,
01586                   length, callback, user_data, timeout);
01587     transfer->type = LIBUSB_TRANSFER_TYPE_BULK_STREAM;
01588     libusb_transfer_set_stream_id(transfer, stream_id);
01589 }
01590 
01604 static inline void libusb_fill_interrupt_transfer(
01605     struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
01606     unsigned char endpoint, unsigned char *buffer, int length,
01607     libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
01608 {
01609     transfer->dev_handle = dev_handle;
01610     transfer->endpoint = endpoint;
01611     transfer->type = LIBUSB_TRANSFER_TYPE_INTERRUPT;
01612     transfer->timeout = timeout;
01613     transfer->buffer = buffer;
01614     transfer->length = length;
01615     transfer->user_data = user_data;
01616     transfer->callback = callback;
01617 }
01618 
01633 static inline void libusb_fill_iso_transfer(struct libusb_transfer *transfer,
01634     libusb_device_handle *dev_handle, unsigned char endpoint,
01635     unsigned char *buffer, int length, int num_iso_packets,
01636     libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
01637 {
01638     transfer->dev_handle = dev_handle;
01639     transfer->endpoint = endpoint;
01640     transfer->type = LIBUSB_TRANSFER_TYPE_ISOCHRONOUS;
01641     transfer->timeout = timeout;
01642     transfer->buffer = buffer;
01643     transfer->length = length;
01644     transfer->num_iso_packets = num_iso_packets;
01645     transfer->user_data = user_data;
01646     transfer->callback = callback;
01647 }
01648 
01657 static inline void libusb_set_iso_packet_lengths(
01658     struct libusb_transfer *transfer, unsigned int length)
01659 {
01660     int i;
01661     for (i = 0; i < transfer->num_iso_packets; i++)
01662         transfer->iso_packet_desc[i].length = length;
01663 }
01664 
01681 static inline unsigned char *libusb_get_iso_packet_buffer(
01682     struct libusb_transfer *transfer, unsigned int packet)
01683 {
01684     int i;
01685     size_t offset = 0;
01686     int _packet;
01687 
01688     /* oops..slight bug in the API. packet is an unsigned int, but we use
01689      * signed integers almost everywhere else. range-check and convert to
01690      * signed to avoid compiler warnings. FIXME for libusb-2. */
01691     if (packet > INT_MAX)
01692         return NULL;
01693     _packet = (int) packet;
01694 
01695     if (_packet >= transfer->num_iso_packets)
01696         return NULL;
01697 
01698     for (i = 0; i < _packet; i++)
01699         offset += transfer->iso_packet_desc[i].length;
01700 
01701     return transfer->buffer + offset;
01702 }
01703 
01723 static inline unsigned char *libusb_get_iso_packet_buffer_simple(
01724     struct libusb_transfer *transfer, unsigned int packet)
01725 {
01726     int _packet;
01727 
01728     /* oops..slight bug in the API. packet is an unsigned int, but we use
01729      * signed integers almost everywhere else. range-check and convert to
01730      * signed to avoid compiler warnings. FIXME for libusb-2. */
01731     if (packet > INT_MAX)
01732         return NULL;
01733     _packet = (int) packet;
01734 
01735     if (_packet >= transfer->num_iso_packets)
01736         return NULL;
01737 
01738     return transfer->buffer + ((int) transfer->iso_packet_desc[0].length * _packet);
01739 }
01740 
01741 /* sync I/O */
01742 
01743 int LIBUSB_CALL libusb_control_transfer(libusb_device_handle *dev_handle,
01744     uint8_t request_type, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
01745     unsigned char *data, uint16_t wLength, unsigned int timeout);
01746 
01747 int LIBUSB_CALL libusb_bulk_transfer(libusb_device_handle *dev_handle,
01748     unsigned char endpoint, unsigned char *data, int length,
01749     int *actual_length, unsigned int timeout);
01750 
01751 int LIBUSB_CALL libusb_interrupt_transfer(libusb_device_handle *dev_handle,
01752     unsigned char endpoint, unsigned char *data, int length,
01753     int *actual_length, unsigned int timeout);
01754 
01767 static inline int libusb_get_descriptor(libusb_device_handle *dev,
01768     uint8_t desc_type, uint8_t desc_index, unsigned char *data, int length)
01769 {
01770     return libusb_control_transfer(dev, LIBUSB_ENDPOINT_IN,
01771         LIBUSB_REQUEST_GET_DESCRIPTOR, (uint16_t) ((desc_type << 8) | desc_index),
01772         0, data, (uint16_t) length, 1000);
01773 }
01774 
01789 static inline int libusb_get_string_descriptor(libusb_device_handle *dev,
01790     uint8_t desc_index, uint16_t langid, unsigned char *data, int length)
01791 {
01792     return libusb_control_transfer(dev, LIBUSB_ENDPOINT_IN,
01793         LIBUSB_REQUEST_GET_DESCRIPTOR, (uint16_t)((LIBUSB_DT_STRING << 8) | desc_index),
01794         langid, data, (uint16_t) length, 1000);
01795 }
01796 
01797 int LIBUSB_CALL libusb_get_string_descriptor_ascii(libusb_device_handle *dev,
01798     uint8_t desc_index, unsigned char *data, int length);
01799 
01800 /* polling and timeouts */
01801 
01802 int LIBUSB_CALL libusb_try_lock_events(libusb_context *ctx);
01803 void LIBUSB_CALL libusb_lock_events(libusb_context *ctx);
01804 void LIBUSB_CALL libusb_unlock_events(libusb_context *ctx);
01805 int LIBUSB_CALL libusb_event_handling_ok(libusb_context *ctx);
01806 int LIBUSB_CALL libusb_event_handler_active(libusb_context *ctx);
01807 void LIBUSB_CALL libusb_lock_event_waiters(libusb_context *ctx);
01808 void LIBUSB_CALL libusb_unlock_event_waiters(libusb_context *ctx);
01809 int LIBUSB_CALL libusb_wait_for_event(libusb_context *ctx, struct timeval *tv);
01810 
01811 int LIBUSB_CALL libusb_handle_events_timeout(libusb_context *ctx,
01812     struct timeval *tv);
01813 int LIBUSB_CALL libusb_handle_events_timeout_completed(libusb_context *ctx,
01814     struct timeval *tv, int *completed);
01815 int LIBUSB_CALL libusb_handle_events(libusb_context *ctx);
01816 int LIBUSB_CALL libusb_handle_events_completed(libusb_context *ctx, int *completed);
01817 int LIBUSB_CALL libusb_handle_events_locked(libusb_context *ctx,
01818     struct timeval *tv);
01819 int LIBUSB_CALL libusb_pollfds_handle_timeouts(libusb_context *ctx);
01820 int LIBUSB_CALL libusb_get_next_timeout(libusb_context *ctx,
01821     struct timeval *tv);
01822 
01826 struct libusb_pollfd {
01828     int fd;
01829 
01834     short events;
01835 };
01836 
01847 typedef void (LIBUSB_CALL *libusb_pollfd_added_cb)(int fd, short events,
01848     void *user_data);
01849 
01859 typedef void (LIBUSB_CALL *libusb_pollfd_removed_cb)(int fd, void *user_data);
01860 
01861 const struct libusb_pollfd ** LIBUSB_CALL libusb_get_pollfds(
01862     libusb_context *ctx);
01863 void LIBUSB_CALL libusb_set_pollfd_notifiers(libusb_context *ctx,
01864     libusb_pollfd_added_cb added_cb, libusb_pollfd_removed_cb removed_cb,
01865     void *user_data);
01866 
01879 typedef int libusb_hotplug_callback_handle;
01880 
01886 typedef enum {
01888     LIBUSB_HOTPLUG_ENUMERATE = 1,
01889 } libusb_hotplug_flag;
01890 
01896 typedef enum {
01898     LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED = 0x01,
01899 
01903     LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT    = 0x02,
01904 } libusb_hotplug_event;
01905 
01908 #define LIBUSB_HOTPLUG_MATCH_ANY -1
01909 
01932 typedef int (LIBUSB_CALL *libusb_hotplug_callback_fn)(libusb_context *ctx,
01933                         libusb_device *device,
01934                         libusb_hotplug_event event,
01935                         void *user_data);
01936 
01971 int LIBUSB_CALL libusb_hotplug_register_callback(libusb_context *ctx,
01972                         libusb_hotplug_event events,
01973                         libusb_hotplug_flag flags,
01974                         int vendor_id, int product_id,
01975                         int dev_class,
01976                         libusb_hotplug_callback_fn cb_fn,
01977                         void *user_data,
01978                         libusb_hotplug_callback_handle *handle);
01979 
01991 void LIBUSB_CALL libusb_hotplug_deregister_callback(libusb_context *ctx,
01992                         libusb_hotplug_callback_handle handle);
01993 
01994 #ifdef __cplusplus
01995 }
01996 #endif
01997 
01998 #endif