Home | History | Annotate | Download | only in libusb
      1 /*
      2  * Public libusb header file
      3  * Copyright  2001 Johannes Erdfelt <johannes (at) erdfelt.com>
      4  * Copyright  2007-2008 Daniel Drake <dsd (at) gentoo.org>
      5  * Copyright  2012 Pete Batard <pete (at) akeo.ie>
      6  * Copyright  2012 Nathan Hjelm <hjelmn (at) cs.unm.edu>
      7  * For more information, please visit: http://libusb.info
      8  *
      9  * This library is free software; you can redistribute it and/or
     10  * modify it under the terms of the GNU Lesser General Public
     11  * License as published by the Free Software Foundation; either
     12  * version 2.1 of the License, or (at your option) any later version.
     13  *
     14  * This library is distributed in the hope that it will be useful,
     15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
     16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     17  * Lesser General Public License for more details.
     18  *
     19  * You should have received a copy of the GNU Lesser General Public
     20  * License along with this library; if not, write to the Free Software
     21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
     22  */
     23 
     24 #ifndef LIBUSB_H
     25 #define LIBUSB_H
     26 
     27 #ifdef _MSC_VER
     28 /* on MS environments, the inline keyword is available in C++ only */
     29 #if !defined(__cplusplus)
     30 #define inline __inline
     31 #endif
     32 /* ssize_t is also not available (copy/paste from MinGW) */
     33 #ifndef _SSIZE_T_DEFINED
     34 #define _SSIZE_T_DEFINED
     35 #undef ssize_t
     36 #ifdef _WIN64
     37   typedef __int64 ssize_t;
     38 #else
     39   typedef int ssize_t;
     40 #endif /* _WIN64 */
     41 #endif /* _SSIZE_T_DEFINED */
     42 #endif /* _MSC_VER */
     43 
     44 /* stdint.h is not available on older MSVC */
     45 #if defined(_MSC_VER) && (_MSC_VER < 1600) && (!defined(_STDINT)) && (!defined(_STDINT_H))
     46 typedef unsigned __int8   uint8_t;
     47 typedef unsigned __int16  uint16_t;
     48 typedef unsigned __int32  uint32_t;
     49 #else
     50 #include <stdint.h>
     51 #endif
     52 
     53 #if !defined(_WIN32_WCE)
     54 #include <sys/types.h>
     55 #endif
     56 
     57 #if defined(__linux) || defined(__APPLE__) || defined(__CYGWIN__) || defined(__HAIKU__)
     58 #include <sys/time.h>
     59 #endif
     60 
     61 #include <time.h>
     62 #include <limits.h>
     63 
     64 /* 'interface' might be defined as a macro on Windows, so we need to
     65  * undefine it so as not to break the current libusb API, because
     66  * libusb_config_descriptor has an 'interface' member
     67  * As this can be problematic if you include windows.h after libusb.h
     68  * in your sources, we force windows.h to be included first. */
     69 #if defined(_WIN32) || defined(__CYGWIN__) || defined(_WIN32_WCE)
     70 #include <windows.h>
     71 #if defined(interface)
     72 #undef interface
     73 #endif
     74 #if !defined(__CYGWIN__)
     75 #include <winsock.h>
     76 #endif
     77 #endif
     78 
     79 #if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5)
     80 #define LIBUSB_DEPRECATED_FOR(f) \
     81   __attribute__((deprecated("Use " #f " instead")))
     82 #else
     83 #define LIBUSB_DEPRECATED_FOR(f)
     84 #endif /* __GNUC__ */
     85 
     86 /** \def LIBUSB_CALL
     87  * \ingroup libusb_misc
     88  * libusb's Windows calling convention.
     89  *
     90  * Under Windows, the selection of available compilers and configurations
     91  * means that, unlike other platforms, there is not <em>one true calling
     92  * convention</em> (calling convention: the manner in which parameters are
     93  * passed to functions in the generated assembly code).
     94  *
     95  * Matching the Windows API itself, libusb uses the WINAPI convention (which
     96  * translates to the <tt>stdcall</tt> convention) and guarantees that the
     97  * library is compiled in this way. The public header file also includes
     98  * appropriate annotations so that your own software will use the right
     99  * convention, even if another convention is being used by default within
    100  * your codebase.
    101  *
    102  * The one consideration that you must apply in your software is to mark
    103  * all functions which you use as libusb callbacks with this LIBUSB_CALL
    104  * annotation, so that they too get compiled for the correct calling
    105  * convention.
    106  *
    107  * On non-Windows operating systems, this macro is defined as nothing. This
    108  * means that you can apply it to your code without worrying about
    109  * cross-platform compatibility.
    110  */
    111 /* LIBUSB_CALL must be defined on both definition and declaration of libusb
    112  * functions. You'd think that declaration would be enough, but cygwin will
    113  * complain about conflicting types unless both are marked this way.
    114  * The placement of this macro is important too; it must appear after the
    115  * return type, before the function name. See internal documentation for
    116  * API_EXPORTED.
    117  */
    118 #if defined(_WIN32) || defined(__CYGWIN__) || defined(_WIN32_WCE)
    119 #define LIBUSB_CALL WINAPI
    120 #else
    121 #define LIBUSB_CALL
    122 #endif
    123 
    124 /** \def LIBUSB_API_VERSION
    125  * \ingroup libusb_misc
    126  * libusb's API version.
    127  *
    128  * Since version 1.0.13, to help with feature detection, libusb defines
    129  * a LIBUSB_API_VERSION macro that gets increased every time there is a
    130  * significant change to the API, such as the introduction of a new call,
    131  * the definition of a new macro/enum member, or any other element that
    132  * libusb applications may want to detect at compilation time.
    133  *
    134  * The macro is typically used in an application as follows:
    135  * \code
    136  * #if defined(LIBUSB_API_VERSION) && (LIBUSB_API_VERSION >= 0x01001234)
    137  * // Use one of the newer features from the libusb API
    138  * #endif
    139  * \endcode
    140  *
    141  * Internally, LIBUSB_API_VERSION is defined as follows:
    142  * (libusb major << 24) | (libusb minor << 16) | (16 bit incremental)
    143  */
    144 #define LIBUSB_API_VERSION 0x01000105
    145 
    146 /* The following is kept for compatibility, but will be deprecated in the future */
    147 #define LIBUSBX_API_VERSION LIBUSB_API_VERSION
    148 
    149 #ifdef __cplusplus
    150 extern "C" {
    151 #endif
    152 
    153 /**
    154  * \ingroup libusb_misc
    155  * Convert a 16-bit value from host-endian to little-endian format. On
    156  * little endian systems, this function does nothing. On big endian systems,
    157  * the bytes are swapped.
    158  * \param x the host-endian value to convert
    159  * \returns the value in little-endian byte order
    160  */
    161 static inline uint16_t libusb_cpu_to_le16(const uint16_t x)
    162 {
    163 	union {
    164 		uint8_t  b8[2];
    165 		uint16_t b16;
    166 	} _tmp;
    167 	_tmp.b8[1] = (uint8_t) (x >> 8);
    168 	_tmp.b8[0] = (uint8_t) (x & 0xff);
    169 	return _tmp.b16;
    170 }
    171 
    172 /** \def libusb_le16_to_cpu
    173  * \ingroup libusb_misc
    174  * Convert a 16-bit value from little-endian to host-endian format. On
    175  * little endian systems, this function does nothing. On big endian systems,
    176  * the bytes are swapped.
    177  * \param x the little-endian value to convert
    178  * \returns the value in host-endian byte order
    179  */
    180 #define libusb_le16_to_cpu libusb_cpu_to_le16
    181 
    182 /* standard USB stuff */
    183 
    184 /** \ingroup libusb_desc
    185  * Device and/or Interface Class codes */
    186 enum libusb_class_code {
    187 	/** In the context of a \ref libusb_device_descriptor "device descriptor",
    188 	 * this bDeviceClass value indicates that each interface specifies its
    189 	 * own class information and all interfaces operate independently.
    190 	 */
    191 	LIBUSB_CLASS_PER_INTERFACE = 0,
    192 
    193 	/** Audio class */
    194 	LIBUSB_CLASS_AUDIO = 1,
    195 
    196 	/** Communications class */
    197 	LIBUSB_CLASS_COMM = 2,
    198 
    199 	/** Human Interface Device class */
    200 	LIBUSB_CLASS_HID = 3,
    201 
    202 	/** Physical */
    203 	LIBUSB_CLASS_PHYSICAL = 5,
    204 
    205 	/** Printer class */
    206 	LIBUSB_CLASS_PRINTER = 7,
    207 
    208 	/** Image class */
    209 	LIBUSB_CLASS_PTP = 6, /* legacy name from libusb-0.1 usb.h */
    210 	LIBUSB_CLASS_IMAGE = 6,
    211 
    212 	/** Mass storage class */
    213 	LIBUSB_CLASS_MASS_STORAGE = 8,
    214 
    215 	/** Hub class */
    216 	LIBUSB_CLASS_HUB = 9,
    217 
    218 	/** Data class */
    219 	LIBUSB_CLASS_DATA = 10,
    220 
    221 	/** Smart Card */
    222 	LIBUSB_CLASS_SMART_CARD = 0x0b,
    223 
    224 	/** Content Security */
    225 	LIBUSB_CLASS_CONTENT_SECURITY = 0x0d,
    226 
    227 	/** Video */
    228 	LIBUSB_CLASS_VIDEO = 0x0e,
    229 
    230 	/** Personal Healthcare */
    231 	LIBUSB_CLASS_PERSONAL_HEALTHCARE = 0x0f,
    232 
    233 	/** Diagnostic Device */
    234 	LIBUSB_CLASS_DIAGNOSTIC_DEVICE = 0xdc,
    235 
    236 	/** Wireless class */
    237 	LIBUSB_CLASS_WIRELESS = 0xe0,
    238 
    239 	/** Application class */
    240 	LIBUSB_CLASS_APPLICATION = 0xfe,
    241 
    242 	/** Class is vendor-specific */
    243 	LIBUSB_CLASS_VENDOR_SPEC = 0xff
    244 };
    245 
    246 /** \ingroup libusb_desc
    247  * Descriptor types as defined by the USB specification. */
    248 enum libusb_descriptor_type {
    249 	/** Device descriptor. See libusb_device_descriptor. */
    250 	LIBUSB_DT_DEVICE = 0x01,
    251 
    252 	/** Configuration descriptor. See libusb_config_descriptor. */
    253 	LIBUSB_DT_CONFIG = 0x02,
    254 
    255 	/** String descriptor */
    256 	LIBUSB_DT_STRING = 0x03,
    257 
    258 	/** Interface descriptor. See libusb_interface_descriptor. */
    259 	LIBUSB_DT_INTERFACE = 0x04,
    260 
    261 	/** Endpoint descriptor. See libusb_endpoint_descriptor. */
    262 	LIBUSB_DT_ENDPOINT = 0x05,
    263 
    264 	/** BOS descriptor */
    265 	LIBUSB_DT_BOS = 0x0f,
    266 
    267 	/** Device Capability descriptor */
    268 	LIBUSB_DT_DEVICE_CAPABILITY = 0x10,
    269 
    270 	/** HID descriptor */
    271 	LIBUSB_DT_HID = 0x21,
    272 
    273 	/** HID report descriptor */
    274 	LIBUSB_DT_REPORT = 0x22,
    275 
    276 	/** Physical descriptor */
    277 	LIBUSB_DT_PHYSICAL = 0x23,
    278 
    279 	/** Hub descriptor */
    280 	LIBUSB_DT_HUB = 0x29,
    281 
    282 	/** SuperSpeed Hub descriptor */
    283 	LIBUSB_DT_SUPERSPEED_HUB = 0x2a,
    284 
    285 	/** SuperSpeed Endpoint Companion descriptor */
    286 	LIBUSB_DT_SS_ENDPOINT_COMPANION = 0x30
    287 };
    288 
    289 /* Descriptor sizes per descriptor type */
    290 #define LIBUSB_DT_DEVICE_SIZE			18
    291 #define LIBUSB_DT_CONFIG_SIZE			9
    292 #define LIBUSB_DT_INTERFACE_SIZE		9
    293 #define LIBUSB_DT_ENDPOINT_SIZE			7
    294 #define LIBUSB_DT_ENDPOINT_AUDIO_SIZE		9	/* Audio extension */
    295 #define LIBUSB_DT_HUB_NONVAR_SIZE		7
    296 #define LIBUSB_DT_SS_ENDPOINT_COMPANION_SIZE	6
    297 #define LIBUSB_DT_BOS_SIZE			5
    298 #define LIBUSB_DT_DEVICE_CAPABILITY_SIZE	3
    299 
    300 /* BOS descriptor sizes */
    301 #define LIBUSB_BT_USB_2_0_EXTENSION_SIZE	7
    302 #define LIBUSB_BT_SS_USB_DEVICE_CAPABILITY_SIZE	10
    303 #define LIBUSB_BT_CONTAINER_ID_SIZE		20
    304 
    305 /* We unwrap the BOS => define its max size */
    306 #define LIBUSB_DT_BOS_MAX_SIZE		((LIBUSB_DT_BOS_SIZE)     +\
    307 					(LIBUSB_BT_USB_2_0_EXTENSION_SIZE)       +\
    308 					(LIBUSB_BT_SS_USB_DEVICE_CAPABILITY_SIZE) +\
    309 					(LIBUSB_BT_CONTAINER_ID_SIZE))
    310 
    311 #define LIBUSB_ENDPOINT_ADDRESS_MASK	0x0f    /* in bEndpointAddress */
    312 #define LIBUSB_ENDPOINT_DIR_MASK		0x80
    313 
    314 /** \ingroup libusb_desc
    315  * Endpoint direction. Values for bit 7 of the
    316  * \ref libusb_endpoint_descriptor::bEndpointAddress "endpoint address" scheme.
    317  */
    318 enum libusb_endpoint_direction {
    319 	/** In: device-to-host */
    320 	LIBUSB_ENDPOINT_IN = 0x80,
    321 
    322 	/** Out: host-to-device */
    323 	LIBUSB_ENDPOINT_OUT = 0x00
    324 };
    325 
    326 #define LIBUSB_TRANSFER_TYPE_MASK			0x03    /* in bmAttributes */
    327 
    328 /** \ingroup libusb_desc
    329  * Endpoint transfer type. Values for bits 0:1 of the
    330  * \ref libusb_endpoint_descriptor::bmAttributes "endpoint attributes" field.
    331  */
    332 enum libusb_transfer_type {
    333 	/** Control endpoint */
    334 	LIBUSB_TRANSFER_TYPE_CONTROL = 0,
    335 
    336 	/** Isochronous endpoint */
    337 	LIBUSB_TRANSFER_TYPE_ISOCHRONOUS = 1,
    338 
    339 	/** Bulk endpoint */
    340 	LIBUSB_TRANSFER_TYPE_BULK = 2,
    341 
    342 	/** Interrupt endpoint */
    343 	LIBUSB_TRANSFER_TYPE_INTERRUPT = 3,
    344 
    345 	/** Stream endpoint */
    346 	LIBUSB_TRANSFER_TYPE_BULK_STREAM = 4,
    347 };
    348 
    349 /** \ingroup libusb_misc
    350  * Standard requests, as defined in table 9-5 of the USB 3.0 specifications */
    351 enum libusb_standard_request {
    352 	/** Request status of the specific recipient */
    353 	LIBUSB_REQUEST_GET_STATUS = 0x00,
    354 
    355 	/** Clear or disable a specific feature */
    356 	LIBUSB_REQUEST_CLEAR_FEATURE = 0x01,
    357 
    358 	/* 0x02 is reserved */
    359 
    360 	/** Set or enable a specific feature */
    361 	LIBUSB_REQUEST_SET_FEATURE = 0x03,
    362 
    363 	/* 0x04 is reserved */
    364 
    365 	/** Set device address for all future accesses */
    366 	LIBUSB_REQUEST_SET_ADDRESS = 0x05,
    367 
    368 	/** Get the specified descriptor */
    369 	LIBUSB_REQUEST_GET_DESCRIPTOR = 0x06,
    370 
    371 	/** Used to update existing descriptors or add new descriptors */
    372 	LIBUSB_REQUEST_SET_DESCRIPTOR = 0x07,
    373 
    374 	/** Get the current device configuration value */
    375 	LIBUSB_REQUEST_GET_CONFIGURATION = 0x08,
    376 
    377 	/** Set device configuration */
    378 	LIBUSB_REQUEST_SET_CONFIGURATION = 0x09,
    379 
    380 	/** Return the selected alternate setting for the specified interface */
    381 	LIBUSB_REQUEST_GET_INTERFACE = 0x0A,
    382 
    383 	/** Select an alternate interface for the specified interface */
    384 	LIBUSB_REQUEST_SET_INTERFACE = 0x0B,
    385 
    386 	/** Set then report an endpoint's synchronization frame */
    387 	LIBUSB_REQUEST_SYNCH_FRAME = 0x0C,
    388 
    389 	/** Sets both the U1 and U2 Exit Latency */
    390 	LIBUSB_REQUEST_SET_SEL = 0x30,
    391 
    392 	/** Delay from the time a host transmits a packet to the time it is
    393 	  * received by the device. */
    394 	LIBUSB_SET_ISOCH_DELAY = 0x31,
    395 };
    396 
    397 /** \ingroup libusb_misc
    398  * Request type bits of the
    399  * \ref libusb_control_setup::bmRequestType "bmRequestType" field in control
    400  * transfers. */
    401 enum libusb_request_type {
    402 	/** Standard */
    403 	LIBUSB_REQUEST_TYPE_STANDARD = (0x00 << 5),
    404 
    405 	/** Class */
    406 	LIBUSB_REQUEST_TYPE_CLASS = (0x01 << 5),
    407 
    408 	/** Vendor */
    409 	LIBUSB_REQUEST_TYPE_VENDOR = (0x02 << 5),
    410 
    411 	/** Reserved */
    412 	LIBUSB_REQUEST_TYPE_RESERVED = (0x03 << 5)
    413 };
    414 
    415 /** \ingroup libusb_misc
    416  * Recipient bits of the
    417  * \ref libusb_control_setup::bmRequestType "bmRequestType" field in control
    418  * transfers. Values 4 through 31 are reserved. */
    419 enum libusb_request_recipient {
    420 	/** Device */
    421 	LIBUSB_RECIPIENT_DEVICE = 0x00,
    422 
    423 	/** Interface */
    424 	LIBUSB_RECIPIENT_INTERFACE = 0x01,
    425 
    426 	/** Endpoint */
    427 	LIBUSB_RECIPIENT_ENDPOINT = 0x02,
    428 
    429 	/** Other */
    430 	LIBUSB_RECIPIENT_OTHER = 0x03,
    431 };
    432 
    433 #define LIBUSB_ISO_SYNC_TYPE_MASK		0x0C
    434 
    435 /** \ingroup libusb_desc
    436  * Synchronization type for isochronous endpoints. Values for bits 2:3 of the
    437  * \ref libusb_endpoint_descriptor::bmAttributes "bmAttributes" field in
    438  * libusb_endpoint_descriptor.
    439  */
    440 enum libusb_iso_sync_type {
    441 	/** No synchronization */
    442 	LIBUSB_ISO_SYNC_TYPE_NONE = 0,
    443 
    444 	/** Asynchronous */
    445 	LIBUSB_ISO_SYNC_TYPE_ASYNC = 1,
    446 
    447 	/** Adaptive */
    448 	LIBUSB_ISO_SYNC_TYPE_ADAPTIVE = 2,
    449 
    450 	/** Synchronous */
    451 	LIBUSB_ISO_SYNC_TYPE_SYNC = 3
    452 };
    453 
    454 #define LIBUSB_ISO_USAGE_TYPE_MASK 0x30
    455 
    456 /** \ingroup libusb_desc
    457  * Usage type for isochronous endpoints. Values for bits 4:5 of the
    458  * \ref libusb_endpoint_descriptor::bmAttributes "bmAttributes" field in
    459  * libusb_endpoint_descriptor.
    460  */
    461 enum libusb_iso_usage_type {
    462 	/** Data endpoint */
    463 	LIBUSB_ISO_USAGE_TYPE_DATA = 0,
    464 
    465 	/** Feedback endpoint */
    466 	LIBUSB_ISO_USAGE_TYPE_FEEDBACK = 1,
    467 
    468 	/** Implicit feedback Data endpoint */
    469 	LIBUSB_ISO_USAGE_TYPE_IMPLICIT = 2,
    470 };
    471 
    472 /** \ingroup libusb_desc
    473  * A structure representing the standard USB device descriptor. This
    474  * descriptor is documented in section 9.6.1 of the USB 3.0 specification.
    475  * All multiple-byte fields are represented in host-endian format.
    476  */
    477 struct libusb_device_descriptor {
    478 	/** Size of this descriptor (in bytes) */
    479 	uint8_t  bLength;
    480 
    481 	/** Descriptor type. Will have value
    482 	 * \ref libusb_descriptor_type::LIBUSB_DT_DEVICE LIBUSB_DT_DEVICE in this
    483 	 * context. */
    484 	uint8_t  bDescriptorType;
    485 
    486 	/** USB specification release number in binary-coded decimal. A value of
    487 	 * 0x0200 indicates USB 2.0, 0x0110 indicates USB 1.1, etc. */
    488 	uint16_t bcdUSB;
    489 
    490 	/** USB-IF class code for the device. See \ref libusb_class_code. */
    491 	uint8_t  bDeviceClass;
    492 
    493 	/** USB-IF subclass code for the device, qualified by the bDeviceClass
    494 	 * value */
    495 	uint8_t  bDeviceSubClass;
    496 
    497 	/** USB-IF protocol code for the device, qualified by the bDeviceClass and
    498 	 * bDeviceSubClass values */
    499 	uint8_t  bDeviceProtocol;
    500 
    501 	/** Maximum packet size for endpoint 0 */
    502 	uint8_t  bMaxPacketSize0;
    503 
    504 	/** USB-IF vendor ID */
    505 	uint16_t idVendor;
    506 
    507 	/** USB-IF product ID */
    508 	uint16_t idProduct;
    509 
    510 	/** Device release number in binary-coded decimal */
    511 	uint16_t bcdDevice;
    512 
    513 	/** Index of string descriptor describing manufacturer */
    514 	uint8_t  iManufacturer;
    515 
    516 	/** Index of string descriptor describing product */
    517 	uint8_t  iProduct;
    518 
    519 	/** Index of string descriptor containing device serial number */
    520 	uint8_t  iSerialNumber;
    521 
    522 	/** Number of possible configurations */
    523 	uint8_t  bNumConfigurations;
    524 };
    525 
    526 /** \ingroup libusb_desc
    527  * A structure representing the standard USB endpoint descriptor. This
    528  * descriptor is documented in section 9.6.6 of the USB 3.0 specification.
    529  * All multiple-byte fields are represented in host-endian format.
    530  */
    531 struct libusb_endpoint_descriptor {
    532 	/** Size of this descriptor (in bytes) */
    533 	uint8_t  bLength;
    534 
    535 	/** Descriptor type. Will have value
    536 	 * \ref libusb_descriptor_type::LIBUSB_DT_ENDPOINT LIBUSB_DT_ENDPOINT in
    537 	 * this context. */
    538 	uint8_t  bDescriptorType;
    539 
    540 	/** The address of the endpoint described by this descriptor. Bits 0:3 are
    541 	 * the endpoint number. Bits 4:6 are reserved. Bit 7 indicates direction,
    542 	 * see \ref libusb_endpoint_direction.
    543 	 */
    544 	uint8_t  bEndpointAddress;
    545 
    546 	/** Attributes which apply to the endpoint when it is configured using
    547 	 * the bConfigurationValue. Bits 0:1 determine the transfer type and
    548 	 * correspond to \ref libusb_transfer_type. Bits 2:3 are only used for
    549 	 * isochronous endpoints and correspond to \ref libusb_iso_sync_type.
    550 	 * Bits 4:5 are also only used for isochronous endpoints and correspond to
    551 	 * \ref libusb_iso_usage_type. Bits 6:7 are reserved.
    552 	 */
    553 	uint8_t  bmAttributes;
    554 
    555 	/** Maximum packet size this endpoint is capable of sending/receiving. */
    556 	uint16_t wMaxPacketSize;
    557 
    558 	/** Interval for polling endpoint for data transfers. */
    559 	uint8_t  bInterval;
    560 
    561 	/** For audio devices only: the rate at which synchronization feedback
    562 	 * is provided. */
    563 	uint8_t  bRefresh;
    564 
    565 	/** For audio devices only: the address if the synch endpoint */
    566 	uint8_t  bSynchAddress;
    567 
    568 	/** Extra descriptors. If libusb encounters unknown endpoint descriptors,
    569 	 * it will store them here, should you wish to parse them. */
    570 	const unsigned char *extra;
    571 
    572 	/** Length of the extra descriptors, in bytes. */
    573 	int extra_length;
    574 };
    575 
    576 /** \ingroup libusb_desc
    577  * A structure representing the standard USB interface descriptor. This
    578  * descriptor is documented in section 9.6.5 of the USB 3.0 specification.
    579  * All multiple-byte fields are represented in host-endian format.
    580  */
    581 struct libusb_interface_descriptor {
    582 	/** Size of this descriptor (in bytes) */
    583 	uint8_t  bLength;
    584 
    585 	/** Descriptor type. Will have value
    586 	 * \ref libusb_descriptor_type::LIBUSB_DT_INTERFACE LIBUSB_DT_INTERFACE
    587 	 * in this context. */
    588 	uint8_t  bDescriptorType;
    589 
    590 	/** Number of this interface */
    591 	uint8_t  bInterfaceNumber;
    592 
    593 	/** Value used to select this alternate setting for this interface */
    594 	uint8_t  bAlternateSetting;
    595 
    596 	/** Number of endpoints used by this interface (excluding the control
    597 	 * endpoint). */
    598 	uint8_t  bNumEndpoints;
    599 
    600 	/** USB-IF class code for this interface. See \ref libusb_class_code. */
    601 	uint8_t  bInterfaceClass;
    602 
    603 	/** USB-IF subclass code for this interface, qualified by the
    604 	 * bInterfaceClass value */
    605 	uint8_t  bInterfaceSubClass;
    606 
    607 	/** USB-IF protocol code for this interface, qualified by the
    608 	 * bInterfaceClass and bInterfaceSubClass values */
    609 	uint8_t  bInterfaceProtocol;
    610 
    611 	/** Index of string descriptor describing this interface */
    612 	uint8_t  iInterface;
    613 
    614 	/** Array of endpoint descriptors. This length of this array is determined
    615 	 * by the bNumEndpoints field. */
    616 	const struct libusb_endpoint_descriptor *endpoint;
    617 
    618 	/** Extra descriptors. If libusb encounters unknown interface descriptors,
    619 	 * it will store them here, should you wish to parse them. */
    620 	const unsigned char *extra;
    621 
    622 	/** Length of the extra descriptors, in bytes. */
    623 	int extra_length;
    624 };
    625 
    626 /** \ingroup libusb_desc
    627  * A collection of alternate settings for a particular USB interface.
    628  */
    629 struct libusb_interface {
    630 	/** Array of interface descriptors. The length of this array is determined
    631 	 * by the num_altsetting field. */
    632 	const struct libusb_interface_descriptor *altsetting;
    633 
    634 	/** The number of alternate settings that belong to this interface */
    635 	int num_altsetting;
    636 };
    637 
    638 /** \ingroup libusb_desc
    639  * A structure representing the standard USB configuration descriptor. This
    640  * descriptor is documented in section 9.6.3 of the USB 3.0 specification.
    641  * All multiple-byte fields are represented in host-endian format.
    642  */
    643 struct libusb_config_descriptor {
    644 	/** Size of this descriptor (in bytes) */
    645 	uint8_t  bLength;
    646 
    647 	/** Descriptor type. Will have value
    648 	 * \ref libusb_descriptor_type::LIBUSB_DT_CONFIG LIBUSB_DT_CONFIG
    649 	 * in this context. */
    650 	uint8_t  bDescriptorType;
    651 
    652 	/** Total length of data returned for this configuration */
    653 	uint16_t wTotalLength;
    654 
    655 	/** Number of interfaces supported by this configuration */
    656 	uint8_t  bNumInterfaces;
    657 
    658 	/** Identifier value for this configuration */
    659 	uint8_t  bConfigurationValue;
    660 
    661 	/** Index of string descriptor describing this configuration */
    662 	uint8_t  iConfiguration;
    663 
    664 	/** Configuration characteristics */
    665 	uint8_t  bmAttributes;
    666 
    667 	/** Maximum power consumption of the USB device from this bus in this
    668 	 * configuration when the device is fully operation. Expressed in units
    669 	 * of 2 mA when the device is operating in high-speed mode and in units
    670 	 * of 8 mA when the device is operating in super-speed mode. */
    671 	uint8_t  MaxPower;
    672 
    673 	/** Array of interfaces supported by this configuration. The length of
    674 	 * this array is determined by the bNumInterfaces field. */
    675 	const struct libusb_interface *interface;
    676 
    677 	/** Extra descriptors. If libusb encounters unknown configuration
    678 	 * descriptors, it will store them here, should you wish to parse them. */
    679 	const unsigned char *extra;
    680 
    681 	/** Length of the extra descriptors, in bytes. */
    682 	int extra_length;
    683 };
    684 
    685 /** \ingroup libusb_desc
    686  * A structure representing the superspeed endpoint companion
    687  * descriptor. This descriptor is documented in section 9.6.7 of
    688  * the USB 3.0 specification. All multiple-byte fields are represented in
    689  * host-endian format.
    690  */
    691 struct libusb_ss_endpoint_companion_descriptor {
    692 
    693 	/** Size of this descriptor (in bytes) */
    694 	uint8_t  bLength;
    695 
    696 	/** Descriptor type. Will have value
    697 	 * \ref libusb_descriptor_type::LIBUSB_DT_SS_ENDPOINT_COMPANION in
    698 	 * this context. */
    699 	uint8_t  bDescriptorType;
    700 
    701 
    702 	/** The maximum number of packets the endpoint can send or
    703 	 *  receive as part of a burst. */
    704 	uint8_t  bMaxBurst;
    705 
    706 	/** In bulk EP:	bits 4:0 represents the	maximum	number of
    707 	 *  streams the	EP supports. In	isochronous EP:	bits 1:0
    708 	 *  represents the Mult	- a zero based value that determines
    709 	 *  the	maximum	number of packets within a service interval  */
    710 	uint8_t  bmAttributes;
    711 
    712 	/** The	total number of bytes this EP will transfer every
    713 	 *  service interval. valid only for periodic EPs. */
    714 	uint16_t wBytesPerInterval;
    715 };
    716 
    717 /** \ingroup libusb_desc
    718  * A generic representation of a BOS Device Capability descriptor. It is
    719  * advised to check bDevCapabilityType and call the matching
    720  * libusb_get_*_descriptor function to get a structure fully matching the type.
    721  */
    722 struct libusb_bos_dev_capability_descriptor {
    723 	/** Size of this descriptor (in bytes) */
    724 	uint8_t bLength;
    725 	/** Descriptor type. Will have value
    726 	 * \ref libusb_descriptor_type::LIBUSB_DT_DEVICE_CAPABILITY
    727 	 * LIBUSB_DT_DEVICE_CAPABILITY in this context. */
    728 	uint8_t bDescriptorType;
    729 	/** Device Capability type */
    730 	uint8_t bDevCapabilityType;
    731 	/** Device Capability data (bLength - 3 bytes) */
    732 	uint8_t dev_capability_data
    733 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
    734 	[] /* valid C99 code */
    735 #else
    736 	[0] /* non-standard, but usually working code */
    737 #endif
    738 	;
    739 };
    740 
    741 /** \ingroup libusb_desc
    742  * A structure representing the Binary Device Object Store (BOS) descriptor.
    743  * This descriptor is documented in section 9.6.2 of the USB 3.0 specification.
    744  * All multiple-byte fields are represented in host-endian format.
    745  */
    746 struct libusb_bos_descriptor {
    747 	/** Size of this descriptor (in bytes) */
    748 	uint8_t  bLength;
    749 
    750 	/** Descriptor type. Will have value
    751 	 * \ref libusb_descriptor_type::LIBUSB_DT_BOS LIBUSB_DT_BOS
    752 	 * in this context. */
    753 	uint8_t  bDescriptorType;
    754 
    755 	/** Length of this descriptor and all of its sub descriptors */
    756 	uint16_t wTotalLength;
    757 
    758 	/** The number of separate device capability descriptors in
    759 	 * the BOS */
    760 	uint8_t  bNumDeviceCaps;
    761 
    762 	/** bNumDeviceCap Device Capability Descriptors */
    763 	struct libusb_bos_dev_capability_descriptor *dev_capability
    764 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
    765 	[] /* valid C99 code */
    766 #else
    767 	[0] /* non-standard, but usually working code */
    768 #endif
    769 	;
    770 };
    771 
    772 /** \ingroup libusb_desc
    773  * A structure representing the USB 2.0 Extension descriptor
    774  * This descriptor is documented in section 9.6.2.1 of the USB 3.0 specification.
    775  * All multiple-byte fields are represented in host-endian format.
    776  */
    777 struct libusb_usb_2_0_extension_descriptor {
    778 	/** Size of this descriptor (in bytes) */
    779 	uint8_t  bLength;
    780 
    781 	/** Descriptor type. Will have value
    782 	 * \ref libusb_descriptor_type::LIBUSB_DT_DEVICE_CAPABILITY
    783 	 * LIBUSB_DT_DEVICE_CAPABILITY in this context. */
    784 	uint8_t  bDescriptorType;
    785 
    786 	/** Capability type. Will have value
    787 	 * \ref libusb_capability_type::LIBUSB_BT_USB_2_0_EXTENSION
    788 	 * LIBUSB_BT_USB_2_0_EXTENSION in this context. */
    789 	uint8_t  bDevCapabilityType;
    790 
    791 	/** Bitmap encoding of supported device level features.
    792 	 * A value of one in a bit location indicates a feature is
    793 	 * supported; a value of zero indicates it is not supported.
    794 	 * See \ref libusb_usb_2_0_extension_attributes. */
    795 	uint32_t  bmAttributes;
    796 };
    797 
    798 /** \ingroup libusb_desc
    799  * A structure representing the SuperSpeed USB Device Capability descriptor
    800  * This descriptor is documented in section 9.6.2.2 of the USB 3.0 specification.
    801  * All multiple-byte fields are represented in host-endian format.
    802  */
    803 struct libusb_ss_usb_device_capability_descriptor {
    804 	/** Size of this descriptor (in bytes) */
    805 	uint8_t  bLength;
    806 
    807 	/** Descriptor type. Will have value
    808 	 * \ref libusb_descriptor_type::LIBUSB_DT_DEVICE_CAPABILITY
    809 	 * LIBUSB_DT_DEVICE_CAPABILITY in this context. */
    810 	uint8_t  bDescriptorType;
    811 
    812 	/** Capability type. Will have value
    813 	 * \ref libusb_capability_type::LIBUSB_BT_SS_USB_DEVICE_CAPABILITY
    814 	 * LIBUSB_BT_SS_USB_DEVICE_CAPABILITY in this context. */
    815 	uint8_t  bDevCapabilityType;
    816 
    817 	/** Bitmap encoding of supported device level features.
    818 	 * A value of one in a bit location indicates a feature is
    819 	 * supported; a value of zero indicates it is not supported.
    820 	 * See \ref libusb_ss_usb_device_capability_attributes. */
    821 	uint8_t  bmAttributes;
    822 
    823 	/** Bitmap encoding of the speed supported by this device when
    824 	 * operating in SuperSpeed mode. See \ref libusb_supported_speed. */
    825 	uint16_t wSpeedSupported;
    826 
    827 	/** The lowest speed at which all the functionality supported
    828 	 * by the device is available to the user. For example if the
    829 	 * device supports all its functionality when connected at
    830 	 * full speed and above then it sets this value to 1. */
    831 	uint8_t  bFunctionalitySupport;
    832 
    833 	/** U1 Device Exit Latency. */
    834 	uint8_t  bU1DevExitLat;
    835 
    836 	/** U2 Device Exit Latency. */
    837 	uint16_t bU2DevExitLat;
    838 };
    839 
    840 /** \ingroup libusb_desc
    841  * A structure representing the Container ID descriptor.
    842  * This descriptor is documented in section 9.6.2.3 of the USB 3.0 specification.
    843  * All multiple-byte fields, except UUIDs, are represented in host-endian format.
    844  */
    845 struct libusb_container_id_descriptor {
    846 	/** Size of this descriptor (in bytes) */
    847 	uint8_t  bLength;
    848 
    849 	/** Descriptor type. Will have value
    850 	 * \ref libusb_descriptor_type::LIBUSB_DT_DEVICE_CAPABILITY
    851 	 * LIBUSB_DT_DEVICE_CAPABILITY in this context. */
    852 	uint8_t  bDescriptorType;
    853 
    854 	/** Capability type. Will have value
    855 	 * \ref libusb_capability_type::LIBUSB_BT_CONTAINER_ID
    856 	 * LIBUSB_BT_CONTAINER_ID in this context. */
    857 	uint8_t  bDevCapabilityType;
    858 
    859 	/** Reserved field */
    860 	uint8_t bReserved;
    861 
    862 	/** 128 bit UUID */
    863 	uint8_t  ContainerID[16];
    864 };
    865 
    866 /** \ingroup libusb_asyncio
    867  * Setup packet for control transfers. */
    868 struct libusb_control_setup {
    869 	/** Request type. Bits 0:4 determine recipient, see
    870 	 * \ref libusb_request_recipient. Bits 5:6 determine type, see
    871 	 * \ref libusb_request_type. Bit 7 determines data transfer direction, see
    872 	 * \ref libusb_endpoint_direction.
    873 	 */
    874 	uint8_t  bmRequestType;
    875 
    876 	/** Request. If the type bits of bmRequestType are equal to
    877 	 * \ref libusb_request_type::LIBUSB_REQUEST_TYPE_STANDARD
    878 	 * "LIBUSB_REQUEST_TYPE_STANDARD" then this field refers to
    879 	 * \ref libusb_standard_request. For other cases, use of this field is
    880 	 * application-specific. */
    881 	uint8_t  bRequest;
    882 
    883 	/** Value. Varies according to request */
    884 	uint16_t wValue;
    885 
    886 	/** Index. Varies according to request, typically used to pass an index
    887 	 * or offset */
    888 	uint16_t wIndex;
    889 
    890 	/** Number of bytes to transfer */
    891 	uint16_t wLength;
    892 };
    893 
    894 #define LIBUSB_CONTROL_SETUP_SIZE (sizeof(struct libusb_control_setup))
    895 
    896 /* libusb */
    897 
    898 struct libusb_context;
    899 struct libusb_device;
    900 struct libusb_device_handle;
    901 
    902 /** \ingroup libusb_lib
    903  * Structure providing the version of the libusb runtime
    904  */
    905 struct libusb_version {
    906 	/** Library major version. */
    907 	const uint16_t major;
    908 
    909 	/** Library minor version. */
    910 	const uint16_t minor;
    911 
    912 	/** Library micro version. */
    913 	const uint16_t micro;
    914 
    915 	/** Library nano version. */
    916 	const uint16_t nano;
    917 
    918 	/** Library release candidate suffix string, e.g. "-rc4". */
    919 	const char *rc;
    920 
    921 	/** For ABI compatibility only. */
    922 	const char* describe;
    923 };
    924 
    925 /** \ingroup libusb_lib
    926  * Structure representing a libusb session. The concept of individual libusb
    927  * sessions allows for your program to use two libraries (or dynamically
    928  * load two modules) which both independently use libusb. This will prevent
    929  * interference between the individual libusb users - for example
    930  * libusb_set_debug() will not affect the other user of the library, and
    931  * libusb_exit() will not destroy resources that the other user is still
    932  * using.
    933  *
    934  * Sessions are created by libusb_init() and destroyed through libusb_exit().
    935  * If your application is guaranteed to only ever include a single libusb
    936  * user (i.e. you), you do not have to worry about contexts: pass NULL in
    937  * every function call where a context is required. The default context
    938  * will be used.
    939  *
    940  * For more information, see \ref libusb_contexts.
    941  */
    942 typedef struct libusb_context libusb_context;
    943 
    944 /** \ingroup libusb_dev
    945  * Structure representing a USB device detected on the system. This is an
    946  * opaque type for which you are only ever provided with a pointer, usually
    947  * originating from libusb_get_device_list().
    948  *
    949  * Certain operations can be performed on a device, but in order to do any
    950  * I/O you will have to first obtain a device handle using libusb_open().
    951  *
    952  * Devices are reference counted with libusb_ref_device() and
    953  * libusb_unref_device(), and are freed when the reference count reaches 0.
    954  * New devices presented by libusb_get_device_list() have a reference count of
    955  * 1, and libusb_free_device_list() can optionally decrease the reference count
    956  * on all devices in the list. libusb_open() adds another reference which is
    957  * later destroyed by libusb_close().
    958  */
    959 typedef struct libusb_device libusb_device;
    960 
    961 
    962 /** \ingroup libusb_dev
    963  * Structure representing a handle on a USB device. This is an opaque type for
    964  * which you are only ever provided with a pointer, usually originating from
    965  * libusb_open().
    966  *
    967  * A device handle is used to perform I/O and other operations. When finished
    968  * with a device handle, you should call libusb_close().
    969  */
    970 typedef struct libusb_device_handle libusb_device_handle;
    971 
    972 /** \ingroup libusb_dev
    973  * Speed codes. Indicates the speed at which the device is operating.
    974  */
    975 enum libusb_speed {
    976 	/** The OS doesn't report or know the device speed. */
    977 	LIBUSB_SPEED_UNKNOWN = 0,
    978 
    979 	/** The device is operating at low speed (1.5MBit/s). */
    980 	LIBUSB_SPEED_LOW = 1,
    981 
    982 	/** The device is operating at full speed (12MBit/s). */
    983 	LIBUSB_SPEED_FULL = 2,
    984 
    985 	/** The device is operating at high speed (480MBit/s). */
    986 	LIBUSB_SPEED_HIGH = 3,
    987 
    988 	/** The device is operating at super speed (5000MBit/s). */
    989 	LIBUSB_SPEED_SUPER = 4,
    990 };
    991 
    992 /** \ingroup libusb_dev
    993  * Supported speeds (wSpeedSupported) bitfield. Indicates what
    994  * speeds the device supports.
    995  */
    996 enum libusb_supported_speed {
    997 	/** Low speed operation supported (1.5MBit/s). */
    998 	LIBUSB_LOW_SPEED_OPERATION   = 1,
    999 
   1000 	/** Full speed operation supported (12MBit/s). */
   1001 	LIBUSB_FULL_SPEED_OPERATION  = 2,
   1002 
   1003 	/** High speed operation supported (480MBit/s). */
   1004 	LIBUSB_HIGH_SPEED_OPERATION  = 4,
   1005 
   1006 	/** Superspeed operation supported (5000MBit/s). */
   1007 	LIBUSB_SUPER_SPEED_OPERATION = 8,
   1008 };
   1009 
   1010 /** \ingroup libusb_dev
   1011  * Masks for the bits of the
   1012  * \ref libusb_usb_2_0_extension_descriptor::bmAttributes "bmAttributes" field
   1013  * of the USB 2.0 Extension descriptor.
   1014  */
   1015 enum libusb_usb_2_0_extension_attributes {
   1016 	/** Supports Link Power Management (LPM) */
   1017 	LIBUSB_BM_LPM_SUPPORT = 2,
   1018 };
   1019 
   1020 /** \ingroup libusb_dev
   1021  * Masks for the bits of the
   1022  * \ref libusb_ss_usb_device_capability_descriptor::bmAttributes "bmAttributes" field
   1023  * field of the SuperSpeed USB Device Capability descriptor.
   1024  */
   1025 enum libusb_ss_usb_device_capability_attributes {
   1026 	/** Supports Latency Tolerance Messages (LTM) */
   1027 	LIBUSB_BM_LTM_SUPPORT = 2,
   1028 };
   1029 
   1030 /** \ingroup libusb_dev
   1031  * USB capability types
   1032  */
   1033 enum libusb_bos_type {
   1034 	/** Wireless USB device capability */
   1035 	LIBUSB_BT_WIRELESS_USB_DEVICE_CAPABILITY	= 1,
   1036 
   1037 	/** USB 2.0 extensions */
   1038 	LIBUSB_BT_USB_2_0_EXTENSION			= 2,
   1039 
   1040 	/** SuperSpeed USB device capability */
   1041 	LIBUSB_BT_SS_USB_DEVICE_CAPABILITY		= 3,
   1042 
   1043 	/** Container ID type */
   1044 	LIBUSB_BT_CONTAINER_ID				= 4,
   1045 };
   1046 
   1047 /** \ingroup libusb_misc
   1048  * Error codes. Most libusb functions return 0 on success or one of these
   1049  * codes on failure.
   1050  * You can call libusb_error_name() to retrieve a string representation of an
   1051  * error code or libusb_strerror() to get an end-user suitable description of
   1052  * an error code.
   1053  */
   1054 enum libusb_error {
   1055 	/** Success (no error) */
   1056 	LIBUSB_SUCCESS = 0,
   1057 
   1058 	/** Input/output error */
   1059 	LIBUSB_ERROR_IO = -1,
   1060 
   1061 	/** Invalid parameter */
   1062 	LIBUSB_ERROR_INVALID_PARAM = -2,
   1063 
   1064 	/** Access denied (insufficient permissions) */
   1065 	LIBUSB_ERROR_ACCESS = -3,
   1066 
   1067 	/** No such device (it may have been disconnected) */
   1068 	LIBUSB_ERROR_NO_DEVICE = -4,
   1069 
   1070 	/** Entity not found */
   1071 	LIBUSB_ERROR_NOT_FOUND = -5,
   1072 
   1073 	/** Resource busy */
   1074 	LIBUSB_ERROR_BUSY = -6,
   1075 
   1076 	/** Operation timed out */
   1077 	LIBUSB_ERROR_TIMEOUT = -7,
   1078 
   1079 	/** Overflow */
   1080 	LIBUSB_ERROR_OVERFLOW = -8,
   1081 
   1082 	/** Pipe error */
   1083 	LIBUSB_ERROR_PIPE = -9,
   1084 
   1085 	/** System call interrupted (perhaps due to signal) */
   1086 	LIBUSB_ERROR_INTERRUPTED = -10,
   1087 
   1088 	/** Insufficient memory */
   1089 	LIBUSB_ERROR_NO_MEM = -11,
   1090 
   1091 	/** Operation not supported or unimplemented on this platform */
   1092 	LIBUSB_ERROR_NOT_SUPPORTED = -12,
   1093 
   1094 	/* NB: Remember to update LIBUSB_ERROR_COUNT below as well as the
   1095 	   message strings in strerror.c when adding new error codes here. */
   1096 
   1097 	/** Other error */
   1098 	LIBUSB_ERROR_OTHER = -99,
   1099 };
   1100 
   1101 /* Total number of error codes in enum libusb_error */
   1102 #define LIBUSB_ERROR_COUNT 14
   1103 
   1104 /** \ingroup libusb_asyncio
   1105  * Transfer status codes */
   1106 enum libusb_transfer_status {
   1107 	/** Transfer completed without error. Note that this does not indicate
   1108 	 * that the entire amount of requested data was transferred. */
   1109 	LIBUSB_TRANSFER_COMPLETED,
   1110 
   1111 	/** Transfer failed */
   1112 	LIBUSB_TRANSFER_ERROR,
   1113 
   1114 	/** Transfer timed out */
   1115 	LIBUSB_TRANSFER_TIMED_OUT,
   1116 
   1117 	/** Transfer was cancelled */
   1118 	LIBUSB_TRANSFER_CANCELLED,
   1119 
   1120 	/** For bulk/interrupt endpoints: halt condition detected (endpoint
   1121 	 * stalled). For control endpoints: control request not supported. */
   1122 	LIBUSB_TRANSFER_STALL,
   1123 
   1124 	/** Device was disconnected */
   1125 	LIBUSB_TRANSFER_NO_DEVICE,
   1126 
   1127 	/** Device sent more data than requested */
   1128 	LIBUSB_TRANSFER_OVERFLOW,
   1129 
   1130 	/* NB! Remember to update libusb_error_name()
   1131 	   when adding new status codes here. */
   1132 };
   1133 
   1134 /** \ingroup libusb_asyncio
   1135  * libusb_transfer.flags values */
   1136 enum libusb_transfer_flags {
   1137 	/** Report short frames as errors */
   1138 	LIBUSB_TRANSFER_SHORT_NOT_OK = 1<<0,
   1139 
   1140 	/** Automatically free() transfer buffer during libusb_free_transfer().
   1141 	 * Note that buffers allocated with libusb_dev_mem_alloc() should not
   1142 	 * be attempted freed in this way, since free() is not an appropriate
   1143 	 * way to release such memory. */
   1144 	LIBUSB_TRANSFER_FREE_BUFFER = 1<<1,
   1145 
   1146 	/** Automatically call libusb_free_transfer() after callback returns.
   1147 	 * If this flag is set, it is illegal to call libusb_free_transfer()
   1148 	 * from your transfer callback, as this will result in a double-free
   1149 	 * when this flag is acted upon. */
   1150 	LIBUSB_TRANSFER_FREE_TRANSFER = 1<<2,
   1151 
   1152 	/** Terminate transfers that are a multiple of the endpoint's
   1153 	 * wMaxPacketSize with an extra zero length packet. This is useful
   1154 	 * when a device protocol mandates that each logical request is
   1155 	 * terminated by an incomplete packet (i.e. the logical requests are
   1156 	 * not separated by other means).
   1157 	 *
   1158 	 * This flag only affects host-to-device transfers to bulk and interrupt
   1159 	 * endpoints. In other situations, it is ignored.
   1160 	 *
   1161 	 * This flag only affects transfers with a length that is a multiple of
   1162 	 * the endpoint's wMaxPacketSize. On transfers of other lengths, this
   1163 	 * flag has no effect. Therefore, if you are working with a device that
   1164 	 * needs a ZLP whenever the end of the logical request falls on a packet
   1165 	 * boundary, then it is sensible to set this flag on <em>every</em>
   1166 	 * transfer (you do not have to worry about only setting it on transfers
   1167 	 * that end on the boundary).
   1168 	 *
   1169 	 * This flag is currently only supported on Linux.
   1170 	 * On other systems, libusb_submit_transfer() will return
   1171 	 * LIBUSB_ERROR_NOT_SUPPORTED for every transfer where this flag is set.
   1172 	 *
   1173 	 * Available since libusb-1.0.9.
   1174 	 */
   1175 	LIBUSB_TRANSFER_ADD_ZERO_PACKET = 1 << 3,
   1176 };
   1177 
   1178 /** \ingroup libusb_asyncio
   1179  * Isochronous packet descriptor. */
   1180 struct libusb_iso_packet_descriptor {
   1181 	/** Length of data to request in this packet */
   1182 	unsigned int length;
   1183 
   1184 	/** Amount of data that was actually transferred */
   1185 	unsigned int actual_length;
   1186 
   1187 	/** Status code for this packet */
   1188 	enum libusb_transfer_status status;
   1189 };
   1190 
   1191 struct libusb_transfer;
   1192 
   1193 /** \ingroup libusb_asyncio
   1194  * Asynchronous transfer callback function type. When submitting asynchronous
   1195  * transfers, you pass a pointer to a callback function of this type via the
   1196  * \ref libusb_transfer::callback "callback" member of the libusb_transfer
   1197  * structure. libusb will call this function later, when the transfer has
   1198  * completed or failed. See \ref libusb_asyncio for more information.
   1199  * \param transfer The libusb_transfer struct the callback function is being
   1200  * notified about.
   1201  */
   1202 typedef void (LIBUSB_CALL *libusb_transfer_cb_fn)(struct libusb_transfer *transfer);
   1203 
   1204 /** \ingroup libusb_asyncio
   1205  * The generic USB transfer structure. The user populates this structure and
   1206  * then submits it in order to request a transfer. After the transfer has
   1207  * completed, the library populates the transfer with the results and passes
   1208  * it back to the user.
   1209  */
   1210 struct libusb_transfer {
   1211 	/** Handle of the device that this transfer will be submitted to */
   1212 	libusb_device_handle *dev_handle;
   1213 
   1214 	/** A bitwise OR combination of \ref libusb_transfer_flags. */
   1215 	uint8_t flags;
   1216 
   1217 	/** Address of the endpoint where this transfer will be sent. */
   1218 	unsigned char endpoint;
   1219 
   1220 	/** Type of the endpoint from \ref libusb_transfer_type */
   1221 	unsigned char type;
   1222 
   1223 	/** Timeout for this transfer in millseconds. A value of 0 indicates no
   1224 	 * timeout. */
   1225 	unsigned int timeout;
   1226 
   1227 	/** The status of the transfer. Read-only, and only for use within
   1228 	 * transfer callback function.
   1229 	 *
   1230 	 * If this is an isochronous transfer, this field may read COMPLETED even
   1231 	 * if there were errors in the frames. Use the
   1232 	 * \ref libusb_iso_packet_descriptor::status "status" field in each packet
   1233 	 * to determine if errors occurred. */
   1234 	enum libusb_transfer_status status;
   1235 
   1236 	/** Length of the data buffer */
   1237 	int length;
   1238 
   1239 	/** Actual length of data that was transferred. Read-only, and only for
   1240 	 * use within transfer callback function. Not valid for isochronous
   1241 	 * endpoint transfers. */
   1242 	int actual_length;
   1243 
   1244 	/** Callback function. This will be invoked when the transfer completes,
   1245 	 * fails, or is cancelled. */
   1246 	libusb_transfer_cb_fn callback;
   1247 
   1248 	/** User context data to pass to the callback function. */
   1249 	void *user_data;
   1250 
   1251 	/** Data buffer */
   1252 	unsigned char *buffer;
   1253 
   1254 	/** Number of isochronous packets. Only used for I/O with isochronous
   1255 	 * endpoints. */
   1256 	int num_iso_packets;
   1257 
   1258 	/** Isochronous packet descriptors, for isochronous transfers only. */
   1259 	struct libusb_iso_packet_descriptor iso_packet_desc
   1260 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
   1261 	[] /* valid C99 code */
   1262 #else
   1263 	[0] /* non-standard, but usually working code */
   1264 #endif
   1265 	;
   1266 };
   1267 
   1268 /** \ingroup libusb_misc
   1269  * Capabilities supported by an instance of libusb on the current running
   1270  * platform. Test if the loaded library supports a given capability by calling
   1271  * \ref libusb_has_capability().
   1272  */
   1273 enum libusb_capability {
   1274 	/** The libusb_has_capability() API is available. */
   1275 	LIBUSB_CAP_HAS_CAPABILITY = 0x0000,
   1276 	/** Hotplug support is available on this platform. */
   1277 	LIBUSB_CAP_HAS_HOTPLUG = 0x0001,
   1278 	/** The library can access HID devices without requiring user intervention.
   1279 	 * Note that before being able to actually access an HID device, you may
   1280 	 * still have to call additional libusb functions such as
   1281 	 * \ref libusb_detach_kernel_driver(). */
   1282 	LIBUSB_CAP_HAS_HID_ACCESS = 0x0100,
   1283 	/** The library supports detaching of the default USB driver, using
   1284 	 * \ref libusb_detach_kernel_driver(), if one is set by the OS kernel */
   1285 	LIBUSB_CAP_SUPPORTS_DETACH_KERNEL_DRIVER = 0x0101
   1286 };
   1287 
   1288 /** \ingroup libusb_lib
   1289  *  Log message levels.
   1290  *  - LIBUSB_LOG_LEVEL_NONE (0)    : no messages ever printed by the library (default)
   1291  *  - LIBUSB_LOG_LEVEL_ERROR (1)   : error messages are printed to stderr
   1292  *  - LIBUSB_LOG_LEVEL_WARNING (2) : warning and error messages are printed to stderr
   1293  *  - LIBUSB_LOG_LEVEL_INFO (3)    : informational messages are printed to stdout, warning
   1294  *    and error messages are printed to stderr
   1295  *  - LIBUSB_LOG_LEVEL_DEBUG (4)   : debug and informational messages are printed to stdout,
   1296  *    warnings and errors to stderr
   1297  */
   1298 enum libusb_log_level {
   1299 	LIBUSB_LOG_LEVEL_NONE = 0,
   1300 	LIBUSB_LOG_LEVEL_ERROR,
   1301 	LIBUSB_LOG_LEVEL_WARNING,
   1302 	LIBUSB_LOG_LEVEL_INFO,
   1303 	LIBUSB_LOG_LEVEL_DEBUG,
   1304 };
   1305 
   1306 int LIBUSB_CALL libusb_init(libusb_context **ctx);
   1307 void LIBUSB_CALL libusb_exit(libusb_context *ctx);
   1308 void LIBUSB_CALL libusb_set_debug(libusb_context *ctx, int level);
   1309 const struct libusb_version * LIBUSB_CALL libusb_get_version(void);
   1310 int LIBUSB_CALL libusb_has_capability(uint32_t capability);
   1311 const char * LIBUSB_CALL libusb_error_name(int errcode);
   1312 int LIBUSB_CALL libusb_setlocale(const char *locale);
   1313 const char * LIBUSB_CALL libusb_strerror(enum libusb_error errcode);
   1314 
   1315 ssize_t LIBUSB_CALL libusb_get_device_list(libusb_context *ctx,
   1316 	libusb_device ***list);
   1317 void LIBUSB_CALL libusb_free_device_list(libusb_device **list,
   1318 	int unref_devices);
   1319 libusb_device * LIBUSB_CALL libusb_ref_device(libusb_device *dev);
   1320 void LIBUSB_CALL libusb_unref_device(libusb_device *dev);
   1321 
   1322 int LIBUSB_CALL libusb_get_configuration(libusb_device_handle *dev,
   1323 	int *config);
   1324 int LIBUSB_CALL libusb_get_device_descriptor(libusb_device *dev,
   1325 	struct libusb_device_descriptor *desc);
   1326 int LIBUSB_CALL libusb_get_active_config_descriptor(libusb_device *dev,
   1327 	struct libusb_config_descriptor **config);
   1328 int LIBUSB_CALL libusb_get_config_descriptor(libusb_device *dev,
   1329 	uint8_t config_index, struct libusb_config_descriptor **config);
   1330 int LIBUSB_CALL libusb_get_config_descriptor_by_value(libusb_device *dev,
   1331 	uint8_t bConfigurationValue, struct libusb_config_descriptor **config);
   1332 void LIBUSB_CALL libusb_free_config_descriptor(
   1333 	struct libusb_config_descriptor *config);
   1334 int LIBUSB_CALL libusb_get_ss_endpoint_companion_descriptor(
   1335 	struct libusb_context *ctx,
   1336 	const struct libusb_endpoint_descriptor *endpoint,
   1337 	struct libusb_ss_endpoint_companion_descriptor **ep_comp);
   1338 void LIBUSB_CALL libusb_free_ss_endpoint_companion_descriptor(
   1339 	struct libusb_ss_endpoint_companion_descriptor *ep_comp);
   1340 int LIBUSB_CALL libusb_get_bos_descriptor(libusb_device_handle *dev_handle,
   1341 	struct libusb_bos_descriptor **bos);
   1342 void LIBUSB_CALL libusb_free_bos_descriptor(struct libusb_bos_descriptor *bos);
   1343 int LIBUSB_CALL libusb_get_usb_2_0_extension_descriptor(
   1344 	struct libusb_context *ctx,
   1345 	struct libusb_bos_dev_capability_descriptor *dev_cap,
   1346 	struct libusb_usb_2_0_extension_descriptor **usb_2_0_extension);
   1347 void LIBUSB_CALL libusb_free_usb_2_0_extension_descriptor(
   1348 	struct libusb_usb_2_0_extension_descriptor *usb_2_0_extension);
   1349 int LIBUSB_CALL libusb_get_ss_usb_device_capability_descriptor(
   1350 	struct libusb_context *ctx,
   1351 	struct libusb_bos_dev_capability_descriptor *dev_cap,
   1352 	struct libusb_ss_usb_device_capability_descriptor **ss_usb_device_cap);
   1353 void LIBUSB_CALL libusb_free_ss_usb_device_capability_descriptor(
   1354 	struct libusb_ss_usb_device_capability_descriptor *ss_usb_device_cap);
   1355 int LIBUSB_CALL libusb_get_container_id_descriptor(struct libusb_context *ctx,
   1356 	struct libusb_bos_dev_capability_descriptor *dev_cap,
   1357 	struct libusb_container_id_descriptor **container_id);
   1358 void LIBUSB_CALL libusb_free_container_id_descriptor(
   1359 	struct libusb_container_id_descriptor *container_id);
   1360 uint8_t LIBUSB_CALL libusb_get_bus_number(libusb_device *dev);
   1361 uint8_t LIBUSB_CALL libusb_get_port_number(libusb_device *dev);
   1362 int LIBUSB_CALL libusb_get_port_numbers(libusb_device *dev, uint8_t* port_numbers, int port_numbers_len);
   1363 LIBUSB_DEPRECATED_FOR(libusb_get_port_numbers)
   1364 int LIBUSB_CALL libusb_get_port_path(libusb_context *ctx, libusb_device *dev, uint8_t* path, uint8_t path_length);
   1365 libusb_device * LIBUSB_CALL libusb_get_parent(libusb_device *dev);
   1366 uint8_t LIBUSB_CALL libusb_get_device_address(libusb_device *dev);
   1367 int LIBUSB_CALL libusb_get_device_speed(libusb_device *dev);
   1368 int LIBUSB_CALL libusb_get_max_packet_size(libusb_device *dev,
   1369 	unsigned char endpoint);
   1370 int LIBUSB_CALL libusb_get_max_iso_packet_size(libusb_device *dev,
   1371 	unsigned char endpoint);
   1372 
   1373 int LIBUSB_CALL libusb_open(libusb_device *dev, libusb_device_handle **dev_handle);
   1374 void LIBUSB_CALL libusb_close(libusb_device_handle *dev_handle);
   1375 libusb_device * LIBUSB_CALL libusb_get_device(libusb_device_handle *dev_handle);
   1376 
   1377 int LIBUSB_CALL libusb_set_configuration(libusb_device_handle *dev_handle,
   1378 	int configuration);
   1379 int LIBUSB_CALL libusb_claim_interface(libusb_device_handle *dev_handle,
   1380 	int interface_number);
   1381 int LIBUSB_CALL libusb_release_interface(libusb_device_handle *dev_handle,
   1382 	int interface_number);
   1383 
   1384 libusb_device_handle * LIBUSB_CALL libusb_open_device_with_vid_pid(
   1385 	libusb_context *ctx, uint16_t vendor_id, uint16_t product_id);
   1386 
   1387 int LIBUSB_CALL libusb_set_interface_alt_setting(libusb_device_handle *dev_handle,
   1388 	int interface_number, int alternate_setting);
   1389 int LIBUSB_CALL libusb_clear_halt(libusb_device_handle *dev_handle,
   1390 	unsigned char endpoint);
   1391 int LIBUSB_CALL libusb_reset_device(libusb_device_handle *dev_handle);
   1392 
   1393 int LIBUSB_CALL libusb_alloc_streams(libusb_device_handle *dev_handle,
   1394 	uint32_t num_streams, unsigned char *endpoints, int num_endpoints);
   1395 int LIBUSB_CALL libusb_free_streams(libusb_device_handle *dev_handle,
   1396 	unsigned char *endpoints, int num_endpoints);
   1397 
   1398 unsigned char * LIBUSB_CALL libusb_dev_mem_alloc(libusb_device_handle *dev_handle,
   1399 	size_t length);
   1400 int LIBUSB_CALL libusb_dev_mem_free(libusb_device_handle *dev_handle,
   1401 	unsigned char *buffer, size_t length);
   1402 
   1403 int LIBUSB_CALL libusb_kernel_driver_active(libusb_device_handle *dev_handle,
   1404 	int interface_number);
   1405 int LIBUSB_CALL libusb_detach_kernel_driver(libusb_device_handle *dev_handle,
   1406 	int interface_number);
   1407 int LIBUSB_CALL libusb_attach_kernel_driver(libusb_device_handle *dev_handle,
   1408 	int interface_number);
   1409 int LIBUSB_CALL libusb_set_auto_detach_kernel_driver(
   1410 	libusb_device_handle *dev_handle, int enable);
   1411 
   1412 /* async I/O */
   1413 
   1414 /** \ingroup libusb_asyncio
   1415  * Get the data section of a control transfer. This convenience function is here
   1416  * to remind you that the data does not start until 8 bytes into the actual
   1417  * buffer, as the setup packet comes first.
   1418  *
   1419  * Calling this function only makes sense from a transfer callback function,
   1420  * or situations where you have already allocated a suitably sized buffer at
   1421  * transfer->buffer.
   1422  *
   1423  * \param transfer a transfer
   1424  * \returns pointer to the first byte of the data section
   1425  */
   1426 static inline unsigned char *libusb_control_transfer_get_data(
   1427 	struct libusb_transfer *transfer)
   1428 {
   1429 	return transfer->buffer + LIBUSB_CONTROL_SETUP_SIZE;
   1430 }
   1431 
   1432 /** \ingroup libusb_asyncio
   1433  * Get the control setup packet of a control transfer. This convenience
   1434  * function is here to remind you that the control setup occupies the first
   1435  * 8 bytes of the transfer data buffer.
   1436  *
   1437  * Calling this function only makes sense from a transfer callback function,
   1438  * or situations where you have already allocated a suitably sized buffer at
   1439  * transfer->buffer.
   1440  *
   1441  * \param transfer a transfer
   1442  * \returns a casted pointer to the start of the transfer data buffer
   1443  */
   1444 static inline struct libusb_control_setup *libusb_control_transfer_get_setup(
   1445 	struct libusb_transfer *transfer)
   1446 {
   1447 	return (struct libusb_control_setup *)(void *) transfer->buffer;
   1448 }
   1449 
   1450 /** \ingroup libusb_asyncio
   1451  * Helper function to populate the setup packet (first 8 bytes of the data
   1452  * buffer) for a control transfer. The wIndex, wValue and wLength values should
   1453  * be given in host-endian byte order.
   1454  *
   1455  * \param buffer buffer to output the setup packet into
   1456  * This pointer must be aligned to at least 2 bytes boundary.
   1457  * \param bmRequestType see the
   1458  * \ref libusb_control_setup::bmRequestType "bmRequestType" field of
   1459  * \ref libusb_control_setup
   1460  * \param bRequest see the
   1461  * \ref libusb_control_setup::bRequest "bRequest" field of
   1462  * \ref libusb_control_setup
   1463  * \param wValue see the
   1464  * \ref libusb_control_setup::wValue "wValue" field of
   1465  * \ref libusb_control_setup
   1466  * \param wIndex see the
   1467  * \ref libusb_control_setup::wIndex "wIndex" field of
   1468  * \ref libusb_control_setup
   1469  * \param wLength see the
   1470  * \ref libusb_control_setup::wLength "wLength" field of
   1471  * \ref libusb_control_setup
   1472  */
   1473 static inline void libusb_fill_control_setup(unsigned char *buffer,
   1474 	uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
   1475 	uint16_t wLength)
   1476 {
   1477 	struct libusb_control_setup *setup = (struct libusb_control_setup *)(void *) buffer;
   1478 	setup->bmRequestType = bmRequestType;
   1479 	setup->bRequest = bRequest;
   1480 	setup->wValue = libusb_cpu_to_le16(wValue);
   1481 	setup->wIndex = libusb_cpu_to_le16(wIndex);
   1482 	setup->wLength = libusb_cpu_to_le16(wLength);
   1483 }
   1484 
   1485 struct libusb_transfer * LIBUSB_CALL libusb_alloc_transfer(int iso_packets);
   1486 int LIBUSB_CALL libusb_submit_transfer(struct libusb_transfer *transfer);
   1487 int LIBUSB_CALL libusb_cancel_transfer(struct libusb_transfer *transfer);
   1488 void LIBUSB_CALL libusb_free_transfer(struct libusb_transfer *transfer);
   1489 void LIBUSB_CALL libusb_transfer_set_stream_id(
   1490 	struct libusb_transfer *transfer, uint32_t stream_id);
   1491 uint32_t LIBUSB_CALL libusb_transfer_get_stream_id(
   1492 	struct libusb_transfer *transfer);
   1493 
   1494 /** \ingroup libusb_asyncio
   1495  * Helper function to populate the required \ref libusb_transfer fields
   1496  * for a control transfer.
   1497  *
   1498  * If you pass a transfer buffer to this function, the first 8 bytes will
   1499  * be interpreted as a control setup packet, and the wLength field will be
   1500  * used to automatically populate the \ref libusb_transfer::length "length"
   1501  * field of the transfer. Therefore the recommended approach is:
   1502  * -# Allocate a suitably sized data buffer (including space for control setup)
   1503  * -# Call libusb_fill_control_setup()
   1504  * -# If this is a host-to-device transfer with a data stage, put the data
   1505  *    in place after the setup packet
   1506  * -# Call this function
   1507  * -# Call libusb_submit_transfer()
   1508  *
   1509  * It is also legal to pass a NULL buffer to this function, in which case this
   1510  * function will not attempt to populate the length field. Remember that you
   1511  * must then populate the buffer and length fields later.
   1512  *
   1513  * \param transfer the transfer to populate
   1514  * \param dev_handle handle of the device that will handle the transfer
   1515  * \param buffer data buffer. If provided, this function will interpret the
   1516  * first 8 bytes as a setup packet and infer the transfer length from that.
   1517  * This pointer must be aligned to at least 2 bytes boundary.
   1518  * \param callback callback function to be invoked on transfer completion
   1519  * \param user_data user data to pass to callback function
   1520  * \param timeout timeout for the transfer in milliseconds
   1521  */
   1522 static inline void libusb_fill_control_transfer(
   1523 	struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
   1524 	unsigned char *buffer, libusb_transfer_cb_fn callback, void *user_data,
   1525 	unsigned int timeout)
   1526 {
   1527 	struct libusb_control_setup *setup = (struct libusb_control_setup *)(void *) buffer;
   1528 	transfer->dev_handle = dev_handle;
   1529 	transfer->endpoint = 0;
   1530 	transfer->type = LIBUSB_TRANSFER_TYPE_CONTROL;
   1531 	transfer->timeout = timeout;
   1532 	transfer->buffer = buffer;
   1533 	if (setup)
   1534 		transfer->length = (int) (LIBUSB_CONTROL_SETUP_SIZE
   1535 			+ libusb_le16_to_cpu(setup->wLength));
   1536 	transfer->user_data = user_data;
   1537 	transfer->callback = callback;
   1538 }
   1539 
   1540 /** \ingroup libusb_asyncio
   1541  * Helper function to populate the required \ref libusb_transfer fields
   1542  * for a bulk transfer.
   1543  *
   1544  * \param transfer the transfer to populate
   1545  * \param dev_handle handle of the device that will handle the transfer
   1546  * \param endpoint address of the endpoint where this transfer will be sent
   1547  * \param buffer data buffer
   1548  * \param length length of data buffer
   1549  * \param callback callback function to be invoked on transfer completion
   1550  * \param user_data user data to pass to callback function
   1551  * \param timeout timeout for the transfer in milliseconds
   1552  */
   1553 static inline void libusb_fill_bulk_transfer(struct libusb_transfer *transfer,
   1554 	libusb_device_handle *dev_handle, unsigned char endpoint,
   1555 	unsigned char *buffer, int length, libusb_transfer_cb_fn callback,
   1556 	void *user_data, unsigned int timeout)
   1557 {
   1558 	transfer->dev_handle = dev_handle;
   1559 	transfer->endpoint = endpoint;
   1560 	transfer->type = LIBUSB_TRANSFER_TYPE_BULK;
   1561 	transfer->timeout = timeout;
   1562 	transfer->buffer = buffer;
   1563 	transfer->length = length;
   1564 	transfer->user_data = user_data;
   1565 	transfer->callback = callback;
   1566 }
   1567 
   1568 /** \ingroup libusb_asyncio
   1569  * Helper function to populate the required \ref libusb_transfer fields
   1570  * for a bulk transfer using bulk streams.
   1571  *
   1572  * Since version 1.0.19, \ref LIBUSB_API_VERSION >= 0x01000103
   1573  *
   1574  * \param transfer the transfer to populate
   1575  * \param dev_handle handle of the device that will handle the transfer
   1576  * \param endpoint address of the endpoint where this transfer will be sent
   1577  * \param stream_id bulk stream id for this transfer
   1578  * \param buffer data buffer
   1579  * \param length length of data buffer
   1580  * \param callback callback function to be invoked on transfer completion
   1581  * \param user_data user data to pass to callback function
   1582  * \param timeout timeout for the transfer in milliseconds
   1583  */
   1584 static inline void libusb_fill_bulk_stream_transfer(
   1585 	struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
   1586 	unsigned char endpoint, uint32_t stream_id,
   1587 	unsigned char *buffer, int length, libusb_transfer_cb_fn callback,
   1588 	void *user_data, unsigned int timeout)
   1589 {
   1590 	libusb_fill_bulk_transfer(transfer, dev_handle, endpoint, buffer,
   1591 				  length, callback, user_data, timeout);
   1592 	transfer->type = LIBUSB_TRANSFER_TYPE_BULK_STREAM;
   1593 	libusb_transfer_set_stream_id(transfer, stream_id);
   1594 }
   1595 
   1596 /** \ingroup libusb_asyncio
   1597  * Helper function to populate the required \ref libusb_transfer fields
   1598  * for an interrupt transfer.
   1599  *
   1600  * \param transfer the transfer to populate
   1601  * \param dev_handle handle of the device that will handle the transfer
   1602  * \param endpoint address of the endpoint where this transfer will be sent
   1603  * \param buffer data buffer
   1604  * \param length length of data buffer
   1605  * \param callback callback function to be invoked on transfer completion
   1606  * \param user_data user data to pass to callback function
   1607  * \param timeout timeout for the transfer in milliseconds
   1608  */
   1609 static inline void libusb_fill_interrupt_transfer(
   1610 	struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
   1611 	unsigned char endpoint, unsigned char *buffer, int length,
   1612 	libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
   1613 {
   1614 	transfer->dev_handle = dev_handle;
   1615 	transfer->endpoint = endpoint;
   1616 	transfer->type = LIBUSB_TRANSFER_TYPE_INTERRUPT;
   1617 	transfer->timeout = timeout;
   1618 	transfer->buffer = buffer;
   1619 	transfer->length = length;
   1620 	transfer->user_data = user_data;
   1621 	transfer->callback = callback;
   1622 }
   1623 
   1624 /** \ingroup libusb_asyncio
   1625  * Helper function to populate the required \ref libusb_transfer fields
   1626  * for an isochronous transfer.
   1627  *
   1628  * \param transfer the transfer to populate
   1629  * \param dev_handle handle of the device that will handle the transfer
   1630  * \param endpoint address of the endpoint where this transfer will be sent
   1631  * \param buffer data buffer
   1632  * \param length length of data buffer
   1633  * \param num_iso_packets the number of isochronous packets
   1634  * \param callback callback function to be invoked on transfer completion
   1635  * \param user_data user data to pass to callback function
   1636  * \param timeout timeout for the transfer in milliseconds
   1637  */
   1638 static inline void libusb_fill_iso_transfer(struct libusb_transfer *transfer,
   1639 	libusb_device_handle *dev_handle, unsigned char endpoint,
   1640 	unsigned char *buffer, int length, int num_iso_packets,
   1641 	libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
   1642 {
   1643 	transfer->dev_handle = dev_handle;
   1644 	transfer->endpoint = endpoint;
   1645 	transfer->type = LIBUSB_TRANSFER_TYPE_ISOCHRONOUS;
   1646 	transfer->timeout = timeout;
   1647 	transfer->buffer = buffer;
   1648 	transfer->length = length;
   1649 	transfer->num_iso_packets = num_iso_packets;
   1650 	transfer->user_data = user_data;
   1651 	transfer->callback = callback;
   1652 }
   1653 
   1654 /** \ingroup libusb_asyncio
   1655  * Convenience function to set the length of all packets in an isochronous
   1656  * transfer, based on the num_iso_packets field in the transfer structure.
   1657  *
   1658  * \param transfer a transfer
   1659  * \param length the length to set in each isochronous packet descriptor
   1660  * \see libusb_get_max_packet_size()
   1661  */
   1662 static inline void libusb_set_iso_packet_lengths(
   1663 	struct libusb_transfer *transfer, unsigned int length)
   1664 {
   1665 	int i;
   1666 	for (i = 0; i < transfer->num_iso_packets; i++)
   1667 		transfer->iso_packet_desc[i].length = length;
   1668 }
   1669 
   1670 /** \ingroup libusb_asyncio
   1671  * Convenience function to locate the position of an isochronous packet
   1672  * within the buffer of an isochronous transfer.
   1673  *
   1674  * This is a thorough function which loops through all preceding packets,
   1675  * accumulating their lengths to find the position of the specified packet.
   1676  * Typically you will assign equal lengths to each packet in the transfer,
   1677  * and hence the above method is sub-optimal. You may wish to use
   1678  * libusb_get_iso_packet_buffer_simple() instead.
   1679  *
   1680  * \param transfer a transfer
   1681  * \param packet the packet to return the address of
   1682  * \returns the base address of the packet buffer inside the transfer buffer,
   1683  * or NULL if the packet does not exist.
   1684  * \see libusb_get_iso_packet_buffer_simple()
   1685  */
   1686 static inline unsigned char *libusb_get_iso_packet_buffer(
   1687 	struct libusb_transfer *transfer, unsigned int packet)
   1688 {
   1689 	int i;
   1690 	size_t offset = 0;
   1691 	int _packet;
   1692 
   1693 	/* oops..slight bug in the API. packet is an unsigned int, but we use
   1694 	 * signed integers almost everywhere else. range-check and convert to
   1695 	 * signed to avoid compiler warnings. FIXME for libusb-2. */
   1696 	if (packet > INT_MAX)
   1697 		return NULL;
   1698 	_packet = (int) packet;
   1699 
   1700 	if (_packet >= transfer->num_iso_packets)
   1701 		return NULL;
   1702 
   1703 	for (i = 0; i < _packet; i++)
   1704 		offset += transfer->iso_packet_desc[i].length;
   1705 
   1706 	return transfer->buffer + offset;
   1707 }
   1708 
   1709 /** \ingroup libusb_asyncio
   1710  * Convenience function to locate the position of an isochronous packet
   1711  * within the buffer of an isochronous transfer, for transfers where each
   1712  * packet is of identical size.
   1713  *
   1714  * This function relies on the assumption that every packet within the transfer
   1715  * is of identical size to the first packet. Calculating the location of
   1716  * the packet buffer is then just a simple calculation:
   1717  * <tt>buffer + (packet_size * packet)</tt>
   1718  *
   1719  * Do not use this function on transfers other than those that have identical
   1720  * packet lengths for each packet.
   1721  *
   1722  * \param transfer a transfer
   1723  * \param packet the packet to return the address of
   1724  * \returns the base address of the packet buffer inside the transfer buffer,
   1725  * or NULL if the packet does not exist.
   1726  * \see libusb_get_iso_packet_buffer()
   1727  */
   1728 static inline unsigned char *libusb_get_iso_packet_buffer_simple(
   1729 	struct libusb_transfer *transfer, unsigned int packet)
   1730 {
   1731 	int _packet;
   1732 
   1733 	/* oops..slight bug in the API. packet is an unsigned int, but we use
   1734 	 * signed integers almost everywhere else. range-check and convert to
   1735 	 * signed to avoid compiler warnings. FIXME for libusb-2. */
   1736 	if (packet > INT_MAX)
   1737 		return NULL;
   1738 	_packet = (int) packet;
   1739 
   1740 	if (_packet >= transfer->num_iso_packets)
   1741 		return NULL;
   1742 
   1743 	return transfer->buffer + ((int) transfer->iso_packet_desc[0].length * _packet);
   1744 }
   1745 
   1746 /* sync I/O */
   1747 
   1748 int LIBUSB_CALL libusb_control_transfer(libusb_device_handle *dev_handle,
   1749 	uint8_t request_type, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
   1750 	unsigned char *data, uint16_t wLength, unsigned int timeout);
   1751 
   1752 int LIBUSB_CALL libusb_bulk_transfer(libusb_device_handle *dev_handle,
   1753 	unsigned char endpoint, unsigned char *data, int length,
   1754 	int *actual_length, unsigned int timeout);
   1755 
   1756 int LIBUSB_CALL libusb_interrupt_transfer(libusb_device_handle *dev_handle,
   1757 	unsigned char endpoint, unsigned char *data, int length,
   1758 	int *actual_length, unsigned int timeout);
   1759 
   1760 /** \ingroup libusb_desc
   1761  * Retrieve a descriptor from the default control pipe.
   1762  * This is a convenience function which formulates the appropriate control
   1763  * message to retrieve the descriptor.
   1764  *
   1765  * \param dev_handle a device handle
   1766  * \param desc_type the descriptor type, see \ref libusb_descriptor_type
   1767  * \param desc_index the index of the descriptor to retrieve
   1768  * \param data output buffer for descriptor
   1769  * \param length size of data buffer
   1770  * \returns number of bytes returned in data, or LIBUSB_ERROR code on failure
   1771  */
   1772 static inline int libusb_get_descriptor(libusb_device_handle *dev_handle,
   1773 	uint8_t desc_type, uint8_t desc_index, unsigned char *data, int length)
   1774 {
   1775 	return libusb_control_transfer(dev_handle, LIBUSB_ENDPOINT_IN,
   1776 		LIBUSB_REQUEST_GET_DESCRIPTOR, (uint16_t) ((desc_type << 8) | desc_index),
   1777 		0, data, (uint16_t) length, 1000);
   1778 }
   1779 
   1780 /** \ingroup libusb_desc
   1781  * Retrieve a descriptor from a device.
   1782  * This is a convenience function which formulates the appropriate control
   1783  * message to retrieve the descriptor. The string returned is Unicode, as
   1784  * detailed in the USB specifications.
   1785  *
   1786  * \param dev_handle a device handle
   1787  * \param desc_index the index of the descriptor to retrieve
   1788  * \param langid the language ID for the string descriptor
   1789  * \param data output buffer for descriptor
   1790  * \param length size of data buffer
   1791  * \returns number of bytes returned in data, or LIBUSB_ERROR code on failure
   1792  * \see libusb_get_string_descriptor_ascii()
   1793  */
   1794 static inline int libusb_get_string_descriptor(libusb_device_handle *dev_handle,
   1795 	uint8_t desc_index, uint16_t langid, unsigned char *data, int length)
   1796 {
   1797 	return libusb_control_transfer(dev_handle, LIBUSB_ENDPOINT_IN,
   1798 		LIBUSB_REQUEST_GET_DESCRIPTOR, (uint16_t)((LIBUSB_DT_STRING << 8) | desc_index),
   1799 		langid, data, (uint16_t) length, 1000);
   1800 }
   1801 
   1802 int LIBUSB_CALL libusb_get_string_descriptor_ascii(libusb_device_handle *dev_handle,
   1803 	uint8_t desc_index, unsigned char *data, int length);
   1804 
   1805 /* polling and timeouts */
   1806 
   1807 int LIBUSB_CALL libusb_try_lock_events(libusb_context *ctx);
   1808 void LIBUSB_CALL libusb_lock_events(libusb_context *ctx);
   1809 void LIBUSB_CALL libusb_unlock_events(libusb_context *ctx);
   1810 int LIBUSB_CALL libusb_event_handling_ok(libusb_context *ctx);
   1811 int LIBUSB_CALL libusb_event_handler_active(libusb_context *ctx);
   1812 void LIBUSB_CALL libusb_interrupt_event_handler(libusb_context *ctx);
   1813 void LIBUSB_CALL libusb_lock_event_waiters(libusb_context *ctx);
   1814 void LIBUSB_CALL libusb_unlock_event_waiters(libusb_context *ctx);
   1815 int LIBUSB_CALL libusb_wait_for_event(libusb_context *ctx, struct timeval *tv);
   1816 
   1817 int LIBUSB_CALL libusb_handle_events_timeout(libusb_context *ctx,
   1818 	struct timeval *tv);
   1819 int LIBUSB_CALL libusb_handle_events_timeout_completed(libusb_context *ctx,
   1820 	struct timeval *tv, int *completed);
   1821 int LIBUSB_CALL libusb_handle_events(libusb_context *ctx);
   1822 int LIBUSB_CALL libusb_handle_events_completed(libusb_context *ctx, int *completed);
   1823 int LIBUSB_CALL libusb_handle_events_locked(libusb_context *ctx,
   1824 	struct timeval *tv);
   1825 int LIBUSB_CALL libusb_pollfds_handle_timeouts(libusb_context *ctx);
   1826 int LIBUSB_CALL libusb_get_next_timeout(libusb_context *ctx,
   1827 	struct timeval *tv);
   1828 
   1829 /** \ingroup libusb_poll
   1830  * File descriptor for polling
   1831  */
   1832 struct libusb_pollfd {
   1833 	/** Numeric file descriptor */
   1834 	int fd;
   1835 
   1836 	/** Event flags to poll for from <poll.h>. POLLIN indicates that you
   1837 	 * should monitor this file descriptor for becoming ready to read from,
   1838 	 * and POLLOUT indicates that you should monitor this file descriptor for
   1839 	 * nonblocking write readiness. */
   1840 	short events;
   1841 };
   1842 
   1843 /** \ingroup libusb_poll
   1844  * Callback function, invoked when a new file descriptor should be added
   1845  * to the set of file descriptors monitored for events.
   1846  * \param fd the new file descriptor
   1847  * \param events events to monitor for, see \ref libusb_pollfd for a
   1848  * description
   1849  * \param user_data User data pointer specified in
   1850  * libusb_set_pollfd_notifiers() call
   1851  * \see libusb_set_pollfd_notifiers()
   1852  */
   1853 typedef void (LIBUSB_CALL *libusb_pollfd_added_cb)(int fd, short events,
   1854 	void *user_data);
   1855 
   1856 /** \ingroup libusb_poll
   1857  * Callback function, invoked when a file descriptor should be removed from
   1858  * the set of file descriptors being monitored for events. After returning
   1859  * from this callback, do not use that file descriptor again.
   1860  * \param fd the file descriptor to stop monitoring
   1861  * \param user_data User data pointer specified in
   1862  * libusb_set_pollfd_notifiers() call
   1863  * \see libusb_set_pollfd_notifiers()
   1864  */
   1865 typedef void (LIBUSB_CALL *libusb_pollfd_removed_cb)(int fd, void *user_data);
   1866 
   1867 const struct libusb_pollfd ** LIBUSB_CALL libusb_get_pollfds(
   1868 	libusb_context *ctx);
   1869 void LIBUSB_CALL libusb_free_pollfds(const struct libusb_pollfd **pollfds);
   1870 void LIBUSB_CALL libusb_set_pollfd_notifiers(libusb_context *ctx,
   1871 	libusb_pollfd_added_cb added_cb, libusb_pollfd_removed_cb removed_cb,
   1872 	void *user_data);
   1873 
   1874 /** \ingroup libusb_hotplug
   1875  * Callback handle.
   1876  *
   1877  * Callbacks handles are generated by libusb_hotplug_register_callback()
   1878  * and can be used to deregister callbacks. Callback handles are unique
   1879  * per libusb_context and it is safe to call libusb_hotplug_deregister_callback()
   1880  * on an already deregisted callback.
   1881  *
   1882  * Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
   1883  *
   1884  * For more information, see \ref libusb_hotplug.
   1885  */
   1886 typedef int libusb_hotplug_callback_handle;
   1887 
   1888 /** \ingroup libusb_hotplug
   1889  *
   1890  * Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
   1891  *
   1892  * Flags for hotplug events */
   1893 typedef enum {
   1894 	/** Default value when not using any flags. */
   1895 	LIBUSB_HOTPLUG_NO_FLAGS = 0,
   1896 
   1897 	/** Arm the callback and fire it for all matching currently attached devices. */
   1898 	LIBUSB_HOTPLUG_ENUMERATE = 1<<0,
   1899 } libusb_hotplug_flag;
   1900 
   1901 /** \ingroup libusb_hotplug
   1902  *
   1903  * Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
   1904  *
   1905  * Hotplug events */
   1906 typedef enum {
   1907 	/** A device has been plugged in and is ready to use */
   1908 	LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED = 0x01,
   1909 
   1910 	/** A device has left and is no longer available.
   1911 	 * It is the user's responsibility to call libusb_close on any handle associated with a disconnected device.
   1912 	 * It is safe to call libusb_get_device_descriptor on a device that has left */
   1913 	LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT    = 0x02,
   1914 } libusb_hotplug_event;
   1915 
   1916 /** \ingroup libusb_hotplug
   1917  * Wildcard matching for hotplug events */
   1918 #define LIBUSB_HOTPLUG_MATCH_ANY -1
   1919 
   1920 /** \ingroup libusb_hotplug
   1921  * Hotplug callback function type. When requesting hotplug event notifications,
   1922  * you pass a pointer to a callback function of this type.
   1923  *
   1924  * This callback may be called by an internal event thread and as such it is
   1925  * recommended the callback do minimal processing before returning.
   1926  *
   1927  * libusb will call this function later, when a matching event had happened on
   1928  * a matching device. See \ref libusb_hotplug for more information.
   1929  *
   1930  * It is safe to call either libusb_hotplug_register_callback() or
   1931  * libusb_hotplug_deregister_callback() from within a callback function.
   1932  *
   1933  * Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
   1934  *
   1935  * \param ctx            context of this notification
   1936  * \param device         libusb_device this event occurred on
   1937  * \param event          event that occurred
   1938  * \param user_data      user data provided when this callback was registered
   1939  * \returns bool whether this callback is finished processing events.
   1940  *                       returning 1 will cause this callback to be deregistered
   1941  */
   1942 typedef int (LIBUSB_CALL *libusb_hotplug_callback_fn)(libusb_context *ctx,
   1943 						libusb_device *device,
   1944 						libusb_hotplug_event event,
   1945 						void *user_data);
   1946 
   1947 /** \ingroup libusb_hotplug
   1948  * Register a hotplug callback function
   1949  *
   1950  * Register a callback with the libusb_context. The callback will fire
   1951  * when a matching event occurs on a matching device. The callback is
   1952  * armed until either it is deregistered with libusb_hotplug_deregister_callback()
   1953  * or the supplied callback returns 1 to indicate it is finished processing events.
   1954  *
   1955  * If the \ref LIBUSB_HOTPLUG_ENUMERATE is passed the callback will be
   1956  * called with a \ref LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED for all devices
   1957  * already plugged into the machine. Note that libusb modifies its internal
   1958  * device list from a separate thread, while calling hotplug callbacks from
   1959  * libusb_handle_events(), so it is possible for a device to already be present
   1960  * on, or removed from, its internal device list, while the hotplug callbacks
   1961  * still need to be dispatched. This means that when using \ref
   1962  * LIBUSB_HOTPLUG_ENUMERATE, your callback may be called twice for the arrival
   1963  * of the same device, once from libusb_hotplug_register_callback() and once
   1964  * from libusb_handle_events(); and/or your callback may be called for the
   1965  * removal of a device for which an arrived call was never made.
   1966  *
   1967  * Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
   1968  *
   1969  * \param[in] ctx context to register this callback with
   1970  * \param[in] events bitwise or of events that will trigger this callback. See \ref
   1971  *            libusb_hotplug_event
   1972  * \param[in] flags hotplug callback flags. See \ref libusb_hotplug_flag
   1973  * \param[in] vendor_id the vendor id to match or \ref LIBUSB_HOTPLUG_MATCH_ANY
   1974  * \param[in] product_id the product id to match or \ref LIBUSB_HOTPLUG_MATCH_ANY
   1975  * \param[in] dev_class the device class to match or \ref LIBUSB_HOTPLUG_MATCH_ANY
   1976  * \param[in] cb_fn the function to be invoked on a matching event/device
   1977  * \param[in] user_data user data to pass to the callback function
   1978  * \param[out] callback_handle pointer to store the handle of the allocated callback (can be NULL)
   1979  * \returns LIBUSB_SUCCESS on success LIBUSB_ERROR code on failure
   1980  */
   1981 int LIBUSB_CALL libusb_hotplug_register_callback(libusb_context *ctx,
   1982 						libusb_hotplug_event events,
   1983 						libusb_hotplug_flag flags,
   1984 						int vendor_id, int product_id,
   1985 						int dev_class,
   1986 						libusb_hotplug_callback_fn cb_fn,
   1987 						void *user_data,
   1988 						libusb_hotplug_callback_handle *callback_handle);
   1989 
   1990 /** \ingroup libusb_hotplug
   1991  * Deregisters a hotplug callback.
   1992  *
   1993  * Deregister a callback from a libusb_context. This function is safe to call from within
   1994  * a hotplug callback.
   1995  *
   1996  * Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
   1997  *
   1998  * \param[in] ctx context this callback is registered with
   1999  * \param[in] callback_handle the handle of the callback to deregister
   2000  */
   2001 void LIBUSB_CALL libusb_hotplug_deregister_callback(libusb_context *ctx,
   2002 						libusb_hotplug_callback_handle callback_handle);
   2003 
   2004 #ifdef __cplusplus
   2005 }
   2006 #endif
   2007 
   2008 #endif
   2009