libusb/libusb.h

   1 /*
   2  * Public libusbx header file
   3  * Copyright © 2007-2008 Daniel Drake <dsd@gentoo.org>
   4  * Copyright © 2001 Johannes Erdfelt <johannes@erdfelt.com>
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  19  */
  20
  21 #ifndef LIBUSB_H
  22 #define LIBUSB_H
  23
  24 #ifdef _MSC_VER
  25 /* on MS environments, the inline keyword is available in C++ only */
  26 #define inline __inline
  27 /* ssize_t is also not available (copy/paste from MinGW) */
  28 #ifndef _SSIZE_T_DEFINED
  29 #define _SSIZE_T_DEFINED
  30 #undef ssize_t
  31 #ifdef _WIN64
  32   typedef __int64 ssize_t;
  33 #else
  34   typedef int ssize_t;
  35 #endif /* _WIN64 */
  36 #endif /* _SSIZE_T_DEFINED */
  37 #endif /* _MSC_VER */
  38
  39 /* stdint.h is also not usually available on MS */
  40 #if defined(_MSC_VER) && (_MSC_VER < 1600) && (!defined(_STDINT)) && (!defined(_STDINT_H))
  41 typedef unsigned __int8   uint8_t;
  42 typedef unsigned __int16  uint16_t;
  43 typedef unsigned __int32  uint32_t;
  44 #else
  45 #include <stdint.h>
  46 #endif
  47
  48 #include <sys/types.h>
  49 #include <time.h>
  50 #include <limits.h>
  51
  52 #if defined(__linux) || defined(__APPLE__) || defined(__CYGWIN__)
  53 #include <sys/time.h>
  54 #endif
  55
  56 /* 'interface' might be defined as a macro on Windows, so we need to
  57  * undefine it so as not to break the current libusbx API, because
  58  * libusb_config_descriptor has an 'interface' member
  59  * As this can be problematic if you include windows.h after libusb.h
  60  * in your sources, we force windows.h to be included first. */
  61 #if defined(_WIN32) || defined(__CYGWIN__)
  62 #include <windows.h>
  63 #if defined(interface)
  64 #undef interface
  65 #endif
  66 #endif
  67
  68 /** \def LIBUSB_CALL
  69  * \ingroup misc
  70  * libusbx's Windows calling convention.
  71  *
  72  * Under Windows, the selection of available compilers and configurations
  73  * means that, unlike other platforms, there is not <em>one true calling
  74  * convention</em> (calling convention: the manner in which parameters are
  75  * passed to funcions in the generated assembly code).
  76  *
  77  * Matching the Windows API itself, libusbx uses the WINAPI convention (which
  78  * translates to the <tt>stdcall</tt> convention) and guarantees that the
  79  * library is compiled in this way. The public header file also includes
  80  * appropriate annotations so that your own software will use the right
  81  * convention, even if another convention is being used by default within
  82  * your codebase.
  83  *
  84  * The one consideration that you must apply in your software is to mark
  85  * all functions which you use as libusbx callbacks with this LIBUSB_CALL
  86  * annotation, so that they too get compiled for the correct calling
  87  * convention.
  88  *
  89  * On non-Windows operating systems, this macro is defined as nothing. This
  90  * means that you can apply it to your code without worrying about
  91  * cross-platform compatibility.
  92  */
  93 /* LIBUSB_CALL must be defined on both definition and declaration of libusbx
  94  * functions. You'd think that declaration would be enough, but cygwin will
  95  * complain about conflicting types unless both are marked this way.
  96  * The placement of this macro is important too; it must appear after the
  97  * return type, before the function name. See internal documentation for
  98  * API_EXPORTED.
  99  */
 100 #if defined(_WIN32) || defined(__CYGWIN__)
 101 #define LIBUSB_CALL WINAPI
 102 #else
 103 #define LIBUSB_CALL
 104 #endif
 105
 106 #ifdef __cplusplus
 107 extern "C" {
 108 #endif
 109
 110 /** \def libusb_cpu_to_le16
 111  * \ingroup misc
 112  * Convert a 16-bit value from host-endian to little-endian format. On
 113  * little endian systems, this function does nothing. On big endian systems,
 114  * the bytes are swapped.
 115  * \param x the host-endian value to convert
 116  * \returns the value in little-endian byte order
 117  */
 118 static inline uint16_t libusb_cpu_to_le16(const uint16_t x)
 119 {
 120         union {
 121                 uint8_t  b8[2];
 122                 uint16_t b16;
 123         } _tmp;
 124         _tmp.b8[1] = x >> 8;
 125         _tmp.b8[0] = x & 0xff;
 126         return _tmp.b16;
 127 }
 128
 129 /** \def libusb_le16_to_cpu
 130  * \ingroup misc
 131  * Convert a 16-bit value from little-endian to host-endian format. On
 132  * little endian systems, this function does nothing. On big endian systems,
 133  * the bytes are swapped.
 134  * \param x the little-endian value to convert
 135  * \returns the value in host-endian byte order
 136  */
 137 #define libusb_le16_to_cpu libusb_cpu_to_le16
 138
 139 /* standard USB stuff */
 140
 141 /** \ingroup desc
 142  * Device and/or Interface Class codes */
 143 enum libusb_class_code {
 144         /** In the context of a \ref libusb_device_descriptor "device descriptor",
 145          * this bDeviceClass value indicates that each interface specifies its
 146          * own class information and all interfaces operate independently.
 147          */
 148         LIBUSB_CLASS_PER_INTERFACE = 0,
 149
 150         /** Audio class */
 151         LIBUSB_CLASS_AUDIO = 1,
 152
 153         /** Communications class */
 154         LIBUSB_CLASS_COMM = 2,
 155
 156         /** Human Interface Device class */
 157         LIBUSB_CLASS_HID = 3,
 158
 159         /** Physical */
 160         LIBUSB_CLASS_PHYSICAL = 5,
 161
 162         /** Printer class */
 163         LIBUSB_CLASS_PRINTER = 7,
 164
 165         /** Image class */
 166         LIBUSB_CLASS_PTP = 6, /* legacy name from libusb-0.1 usb.h */
 167         LIBUSB_CLASS_IMAGE = 6,
 168
 169         /** Mass storage class */
 170         LIBUSB_CLASS_MASS_STORAGE = 8,
 171
 172         /** Hub class */
 173         LIBUSB_CLASS_HUB = 9,
 174
 175         /** Data class */
 176         LIBUSB_CLASS_DATA = 10,
 177
 178         /** Smart Card */
 179         LIBUSB_CLASS_SMART_CARD = 0x0b,
 180
 181         /** Content Security */
 182         LIBUSB_CLASS_CONTENT_SECURITY = 0x0d,
 183
 184         /** Video */
 185         LIBUSB_CLASS_VIDEO = 0x0e,
 186
 187         /** Personal Healthcare */
 188         LIBUSB_CLASS_PERSONAL_HEALTHCARE = 0x0f,
 189
 190         /** Diagnostic Device */
 191         LIBUSB_CLASS_DIAGNOSTIC_DEVICE = 0xdc,
 192
 193         /** Wireless class */
 194         LIBUSB_CLASS_WIRELESS = 0xe0,
 195
 196         /** Application class */
 197         LIBUSB_CLASS_APPLICATION = 0xfe,
 198
 199         /** Class is vendor-specific */
 200         LIBUSB_CLASS_VENDOR_SPEC = 0xff
 201 };
 202
 203 /** \ingroup desc
 204  * Descriptor types as defined by the USB specification. */
 205 enum libusb_descriptor_type {
 206         /** Device descriptor. See libusb_device_descriptor. */
 207         LIBUSB_DT_DEVICE = 0x01,
 208
 209         /** Configuration descriptor. See libusb_config_descriptor. */
 210         LIBUSB_DT_CONFIG = 0x02,
 211
 212         /** String descriptor */
 213         LIBUSB_DT_STRING = 0x03,
 214
 215         /** Interface descriptor. See libusb_interface_descriptor. */
 216         LIBUSB_DT_INTERFACE = 0x04,
 217
 218         /** Endpoint descriptor. See libusb_endpoint_descriptor. */
 219         LIBUSB_DT_ENDPOINT = 0x05,
 220
 221         /** HID descriptor */
 222         LIBUSB_DT_HID = 0x21,
 223
 224         /** HID report descriptor */
 225         LIBUSB_DT_REPORT = 0x22,
 226
 227         /** Physical descriptor */
 228         LIBUSB_DT_PHYSICAL = 0x23,
 229
 230         /** Hub descriptor */
 231         LIBUSB_DT_HUB = 0x29,
 232 };
 233
 234 /* Descriptor sizes per descriptor type */
 235 #define LIBUSB_DT_DEVICE_SIZE                   18
 236 #define LIBUSB_DT_CONFIG_SIZE                   9
 237 #define LIBUSB_DT_INTERFACE_SIZE                9
 238 #define LIBUSB_DT_ENDPOINT_SIZE         7
 239 #define LIBUSB_DT_ENDPOINT_AUDIO_SIZE   9       /* Audio extension */
 240 #define LIBUSB_DT_HUB_NONVAR_SIZE               7
 241
 242 #define LIBUSB_ENDPOINT_ADDRESS_MASK    0x0f    /* in bEndpointAddress */
 243 #define LIBUSB_ENDPOINT_DIR_MASK                0x80
 244
 245 /** \ingroup desc
 246  * Endpoint direction. Values for bit 7 of the
 247  * \ref libusb_endpoint_descriptor::bEndpointAddress "endpoint address" scheme.
 248  */
 249 enum libusb_endpoint_direction {
 250         /** In: device-to-host */
 251         LIBUSB_ENDPOINT_IN = 0x80,
 252
 253         /** Out: host-to-device */
 254         LIBUSB_ENDPOINT_OUT = 0x00
 255 };
 256
 257 #define LIBUSB_TRANSFER_TYPE_MASK                       0x03    /* in bmAttributes */
 258
 259 /** \ingroup desc
 260  * Endpoint transfer type. Values for bits 0:1 of the
 261  * \ref libusb_endpoint_descriptor::bmAttributes "endpoint attributes" field.
 262  */
 263 enum libusb_transfer_type {
 264         /** Control endpoint */
 265         LIBUSB_TRANSFER_TYPE_CONTROL = 0,
 266
 267         /** Isochronous endpoint */
 268         LIBUSB_TRANSFER_TYPE_ISOCHRONOUS = 1,
 269
 270         /** Bulk endpoint */
 271         LIBUSB_TRANSFER_TYPE_BULK = 2,
 272
 273         /** Interrupt endpoint */
 274         LIBUSB_TRANSFER_TYPE_INTERRUPT = 3
 275 };
 276
 277 /** \ingroup misc
 278  * Standard requests, as defined in table 9-3 of the USB2 specifications */
 279 enum libusb_standard_request {
 280         /** Request status of the specific recipient */
 281         LIBUSB_REQUEST_GET_STATUS = 0x00,
 282
 283         /** Clear or disable a specific feature */
 284         LIBUSB_REQUEST_CLEAR_FEATURE = 0x01,
 285
 286         /* 0x02 is reserved */
 287
 288         /** Set or enable a specific feature */
 289         LIBUSB_REQUEST_SET_FEATURE = 0x03,
 290
 291         /* 0x04 is reserved */
 292
 293         /** Set device address for all future accesses */
 294         LIBUSB_REQUEST_SET_ADDRESS = 0x05,
 295
 296         /** Get the specified descriptor */
 297         LIBUSB_REQUEST_GET_DESCRIPTOR = 0x06,
 298
 299         /** Used to update existing descriptors or add new descriptors */
 300         LIBUSB_REQUEST_SET_DESCRIPTOR = 0x07,
 301
 302         /** Get the current device configuration value */
 303         LIBUSB_REQUEST_GET_CONFIGURATION = 0x08,
 304
 305         /** Set device configuration */
 306         LIBUSB_REQUEST_SET_CONFIGURATION = 0x09,
 307
 308         /** Return the selected alternate setting for the specified interface */
 309         LIBUSB_REQUEST_GET_INTERFACE = 0x0A,
 310
 311         /** Select an alternate interface for the specified interface */
 312         LIBUSB_REQUEST_SET_INTERFACE = 0x0B,
 313
 314         /** Set then report an endpoint's synchronization frame */
 315         LIBUSB_REQUEST_SYNCH_FRAME = 0x0C,
 316 };
 317
 318 /** \ingroup misc
 319  * Request type bits of the
 320  * \ref libusb_control_setup::bmRequestType "bmRequestType" field in control
 321  * transfers. */
 322 enum libusb_request_type {
 323         /** Standard */
 324         LIBUSB_REQUEST_TYPE_STANDARD = (0x00 << 5),
 325
 326         /** Class */
 327         LIBUSB_REQUEST_TYPE_CLASS = (0x01 << 5),
 328
 329         /** Vendor */
 330         LIBUSB_REQUEST_TYPE_VENDOR = (0x02 << 5),
 331
 332         /** Reserved */
 333         LIBUSB_REQUEST_TYPE_RESERVED = (0x03 << 5)
 334 };
 335
 336 /** \ingroup misc
 337  * Recipient bits of the
 338  * \ref libusb_control_setup::bmRequestType "bmRequestType" field in control
 339  * transfers. Values 4 through 31 are reserved. */
 340 enum libusb_request_recipient {
 341         /** Device */
 342         LIBUSB_RECIPIENT_DEVICE = 0x00,
 343
 344         /** Interface */
 345         LIBUSB_RECIPIENT_INTERFACE = 0x01,
 346
 347         /** Endpoint */
 348         LIBUSB_RECIPIENT_ENDPOINT = 0x02,
 349
 350         /** Other */
 351         LIBUSB_RECIPIENT_OTHER = 0x03,
 352 };
 353
 354 #define LIBUSB_ISO_SYNC_TYPE_MASK               0x0C
 355
 356 /** \ingroup desc
 357  * Synchronization type for isochronous endpoints. Values for bits 2:3 of the
 358  * \ref libusb_endpoint_descriptor::bmAttributes "bmAttributes" field in
 359  * libusb_endpoint_descriptor.
 360  */
 361 enum libusb_iso_sync_type {
 362         /** No synchronization */
 363         LIBUSB_ISO_SYNC_TYPE_NONE = 0,
 364
 365         /** Asynchronous */
 366         LIBUSB_ISO_SYNC_TYPE_ASYNC = 1,
 367
 368         /** Adaptive */
 369         LIBUSB_ISO_SYNC_TYPE_ADAPTIVE = 2,
 370
 371         /** Synchronous */
 372         LIBUSB_ISO_SYNC_TYPE_SYNC = 3
 373 };
 374
 375 #define LIBUSB_ISO_USAGE_TYPE_MASK 0x30
 376
 377 /** \ingroup desc
 378  * Usage type for isochronous endpoints. Values for bits 4:5 of the
 379  * \ref libusb_endpoint_descriptor::bmAttributes "bmAttributes" field in
 380  * libusb_endpoint_descriptor.
 381  */
 382 enum libusb_iso_usage_type {
 383         /** Data endpoint */
 384         LIBUSB_ISO_USAGE_TYPE_DATA = 0,
 385
 386         /** Feedback endpoint */
 387         LIBUSB_ISO_USAGE_TYPE_FEEDBACK = 1,
 388
 389         /** Implicit feedback Data endpoint */
 390         LIBUSB_ISO_USAGE_TYPE_IMPLICIT = 2,
 391 };
 392
 393 /** \ingroup desc
 394  * A structure representing the standard USB device descriptor. This
 395  * descriptor is documented in section 9.6.1 of the USB 2.0 specification.
 396  * All multiple-byte fields are represented in host-endian format.
 397  */
 398 struct libusb_device_descriptor {
 399         /** Size of this descriptor (in bytes) */
 400         uint8_t  bLength;
 401
 402         /** Descriptor type. Will have value
 403          * \ref libusb_descriptor_type::LIBUSB_DT_DEVICE LIBUSB_DT_DEVICE in this
 404          * context. */
 405         uint8_t  bDescriptorType;
 406
 407         /** USB specification release number in binary-coded decimal. A value of
 408          * 0x0200 indicates USB 2.0, 0x0110 indicates USB 1.1, etc. */
 409         uint16_t bcdUSB;
 410
 411         /** USB-IF class code for the device. See \ref libusb_class_code. */
 412         uint8_t  bDeviceClass;
 413
 414         /** USB-IF subclass code for the device, qualified by the bDeviceClass
 415          * value */
 416         uint8_t  bDeviceSubClass;
 417
 418         /** USB-IF protocol code for the device, qualified by the bDeviceClass and
 419          * bDeviceSubClass values */
 420         uint8_t  bDeviceProtocol;
 421
 422         /** Maximum packet size for endpoint 0 */
 423         uint8_t  bMaxPacketSize0;
 424
 425         /** USB-IF vendor ID */
 426         uint16_t idVendor;
 427
 428         /** USB-IF product ID */
 429         uint16_t idProduct;
 430
 431         /** Device release number in binary-coded decimal */
 432         uint16_t bcdDevice;
 433
 434         /** Index of string descriptor describing manufacturer */
 435         uint8_t  iManufacturer;
 436
 437         /** Index of string descriptor describing product */
 438         uint8_t  iProduct;
 439
 440         /** Index of string descriptor containing device serial number */
 441         uint8_t  iSerialNumber;
 442
 443         /** Number of possible configurations */
 444         uint8_t  bNumConfigurations;
 445 };
 446
 447 /** \ingroup desc
 448  * A structure representing the standard USB endpoint descriptor. This
 449  * descriptor is documented in section 9.6.3 of the USB 2.0 specification.
 450  * All multiple-byte fields are represented in host-endian format.
 451  */
 452 struct libusb_endpoint_descriptor {
 453         /** Size of this descriptor (in bytes) */
 454         uint8_t  bLength;
 455
 456         /** Descriptor type. Will have value
 457          * \ref libusb_descriptor_type::LIBUSB_DT_ENDPOINT LIBUSB_DT_ENDPOINT in
 458          * this context. */
 459         uint8_t  bDescriptorType;
 460
 461         /** The address of the endpoint described by this descriptor. Bits 0:3 are
 462          * the endpoint number. Bits 4:6 are reserved. Bit 7 indicates direction,
 463          * see \ref libusb_endpoint_direction.
 464          */
 465         uint8_t  bEndpointAddress;
 466
 467         /** Attributes which apply to the endpoint when it is configured using
 468          * the bConfigurationValue. Bits 0:1 determine the transfer type and
 469          * correspond to \ref libusb_transfer_type. Bits 2:3 are only used for
 470          * isochronous endpoints and correspond to \ref libusb_iso_sync_type.
 471          * Bits 4:5 are also only used for isochronous endpoints and correspond to
 472          * \ref libusb_iso_usage_type. Bits 6:7 are reserved.
 473          */
 474         uint8_t  bmAttributes;
 475
 476         /** Maximum packet size this endpoint is capable of sending/receiving. */
 477         uint16_t wMaxPacketSize;
 478
 479         /** Interval for polling endpoint for data transfers. */
 480         uint8_t  bInterval;
 481
 482         /** For audio devices only: the rate at which synchronization feedback
 483          * is provided. */
 484         uint8_t  bRefresh;
 485
 486         /** For audio devices only: the address if the synch endpoint */
 487         uint8_t  bSynchAddress;
 488
 489         /** Extra descriptors. If libusbx encounters unknown endpoint descriptors,
 490          * it will store them here, should you wish to parse them. */
 491         const unsigned char *extra;
 492
 493         /** Length of the extra descriptors, in bytes. */
 494         int extra_length;
 495 };
 496
 497 /** \ingroup desc
 498  * A structure representing the standard USB interface descriptor. This
 499  * descriptor is documented in section 9.6.5 of the USB 2.0 specification.
 500  * All multiple-byte fields are represented in host-endian format.
 501  */
 502 struct libusb_interface_descriptor {
 503         /** Size of this descriptor (in bytes) */
 504         uint8_t  bLength;
 505
 506         /** Descriptor type. Will have value
 507          * \ref libusb_descriptor_type::LIBUSB_DT_INTERFACE LIBUSB_DT_INTERFACE
 508          * in this context. */
 509         uint8_t  bDescriptorType;
 510
 511         /** Number of this interface */
 512         uint8_t  bInterfaceNumber;
 513
 514         /** Value used to select this alternate setting for this interface */
 515         uint8_t  bAlternateSetting;
 516
 517         /** Number of endpoints used by this interface (excluding the control
 518          * endpoint). */
 519         uint8_t  bNumEndpoints;
 520
 521         /** USB-IF class code for this interface. See \ref libusb_class_code. */
 522         uint8_t  bInterfaceClass;
 523
 524         /** USB-IF subclass code for this interface, qualified by the
 525          * bInterfaceClass value */
 526         uint8_t  bInterfaceSubClass;
 527
 528         /** USB-IF protocol code for this interface, qualified by the
 529          * bInterfaceClass and bInterfaceSubClass values */
 530         uint8_t  bInterfaceProtocol;
 531
 532         /** Index of string descriptor describing this interface */
 533         uint8_t  iInterface;
 534
 535         /** Array of endpoint descriptors. This length of this array is determined
 536          * by the bNumEndpoints field. */
 537         const struct libusb_endpoint_descriptor *endpoint;
 538
 539         /** Extra descriptors. If libusbx encounters unknown interface descriptors,
 540          * it will store them here, should you wish to parse them. */
 541         const unsigned char *extra;
 542
 543         /** Length of the extra descriptors, in bytes. */
 544         int extra_length;
 545 };
 546
 547 /** \ingroup desc
 548  * A collection of alternate settings for a particular USB interface.
 549  */
 550 struct libusb_interface {
 551         /** Array of interface descriptors. The length of this array is determined
 552          * by the num_altsetting field. */
 553         const struct libusb_interface_descriptor *altsetting;
 554
 555         /** The number of alternate settings that belong to this interface */
 556         int num_altsetting;
 557 };
 558
 559 /** \ingroup desc
 560  * A structure representing the standard USB configuration descriptor. This
 561  * descriptor is documented in section 9.6.3 of the USB 2.0 specification.
 562  * All multiple-byte fields are represented in host-endian format.
 563  */
 564 struct libusb_config_descriptor {
 565         /** Size of this descriptor (in bytes) */
 566         uint8_t  bLength;
 567
 568         /** Descriptor type. Will have value
 569          * \ref libusb_descriptor_type::LIBUSB_DT_CONFIG LIBUSB_DT_CONFIG
 570          * in this context. */
 571         uint8_t  bDescriptorType;
 572
 573         /** Total length of data returned for this configuration */
 574         uint16_t wTotalLength;
 575
 576         /** Number of interfaces supported by this configuration */
 577         uint8_t  bNumInterfaces;
 578
 579         /** Identifier value for this configuration */
 580         uint8_t  bConfigurationValue;
 581
 582         /** Index of string descriptor describing this configuration */
 583         uint8_t  iConfiguration;
 584
 585         /** Configuration characteristics */
 586         uint8_t  bmAttributes;
 587
 588         /** Maximum power consumption of the USB device from this bus in this
 589          * configuration when the device is fully opreation. Expressed in units
 590          * of 2 mA. */
 591         uint8_t  MaxPower;
 592
 593         /** Array of interfaces supported by this configuration. The length of
 594          * this array is determined by the bNumInterfaces field. */
 595         const struct libusb_interface *interface;
 596
 597         /** Extra descriptors. If libusbx encounters unknown configuration
 598          * descriptors, it will store them here, should you wish to parse them. */
 599         const unsigned char *extra;
 600
 601         /** Length of the extra descriptors, in bytes. */
 602         int extra_length;
 603 };
 604
 605 /** \ingroup asyncio
 606  * Setup packet for control transfers. */
 607 struct libusb_control_setup {
 608         /** Request type. Bits 0:4 determine recipient, see
 609          * \ref libusb_request_recipient. Bits 5:6 determine type, see
 610          * \ref libusb_request_type. Bit 7 determines data transfer direction, see
 611          * \ref libusb_endpoint_direction.
 612          */
 613         uint8_t  bmRequestType;
 614
 615         /** Request. If the type bits of bmRequestType are equal to
 616          * \ref libusb_request_type::LIBUSB_REQUEST_TYPE_STANDARD
 617          * "LIBUSB_REQUEST_TYPE_STANDARD" then this field refers to
 618          * \ref libusb_standard_request. For other cases, use of this field is
 619          * application-specific. */
 620         uint8_t  bRequest;
 621
 622         /** Value. Varies according to request */
 623         uint16_t wValue;
 624
 625         /** Index. Varies according to request, typically used to pass an index
 626          * or offset */
 627         uint16_t wIndex;
 628
 629         /** Number of bytes to transfer */
 630         uint16_t wLength;
 631 };
 632
 633 #define LIBUSB_CONTROL_SETUP_SIZE (sizeof(struct libusb_control_setup))
 634
 635 /* libusbx */
 636
 637 struct libusb_context;
 638 struct libusb_device;
 639 struct libusb_device_handle;
 640
 641 /** \ingroup lib
 642  * Structure providing the version of the libusbx runtime
 643  */
 644 struct libusb_version {
 645         /** Library major version. */
 646         const uint16_t major;
 647
 648         /** Library minor version. */
 649         const uint16_t minor;
 650
 651         /** Library micro version. */
 652         const uint16_t micro;
 653
 654         /** Library nano version. */
 655         const uint16_t nano;
 656
 657         /** Library release candidate suffix string, e.g. "-rc4". */
 658         const char *rc;
 659
 660         /** For ABI compatibility only. */
 661         const char* describe;
 662 };
 663
 664 /** \ingroup lib
 665  * Structure representing a libusbx session. The concept of individual libusbx
 666  * sessions allows for your program to use two libraries (or dynamically
 667  * load two modules) which both independently use libusb. This will prevent
 668  * interference between the individual libusbx users - for example
 669  * libusb_set_debug() will not affect the other user of the library, and
 670  * libusb_exit() will not destroy resources that the other user is still
 671  * using.
 672  *
 673  * Sessions are created by libusb_init() and destroyed through libusb_exit().
 674  * If your application is guaranteed to only ever include a single libusbx
 675  * user (i.e. you), you do not have to worry about contexts: pass NULL in
 676  * every function call where a context is required. The default context
 677  * will be used.
 678  *
 679  * For more information, see \ref contexts.
 680  */
 681 typedef struct libusb_context libusb_context;
 682
 683 /** \ingroup dev
 684  * Structure representing a USB device detected on the system. This is an
 685  * opaque type for which you are only ever provided with a pointer, usually
 686  * originating from libusb_get_device_list().
 687  *
 688  * Certain operations can be performed on a device, but in order to do any
 689  * I/O you will have to first obtain a device handle using libusb_open().
 690  *
 691  * Devices are reference counted with libusb_device_ref() and
 692  * libusb_device_unref(), and are freed when the reference count reaches 0.
 693  * New devices presented by libusb_get_device_list() have a reference count of
 694  * 1, and libusb_free_device_list() can optionally decrease the reference count
 695  * on all devices in the list. libusb_open() adds another reference which is
 696  * later destroyed by libusb_close().
 697  */
 698 typedef struct libusb_device libusb_device;
 699
 700
 701 /** \ingroup dev
 702  * Structure representing a handle on a USB device. This is an opaque type for
 703  * which you are only ever provided with a pointer, usually originating from
 704  * libusb_open().
 705  *
 706  * A device handle is used to perform I/O and other operations. When finished
 707  * with a device handle, you should call libusb_close().
 708  */
 709 typedef struct libusb_device_handle libusb_device_handle;
 710
 711 /** \ingroup dev
 712  * Speed codes. Indicates the speed at which the device is operating.
 713  */
 714 enum libusb_speed {
 715         /** The OS doesn't report or know the device speed. */
 716         LIBUSB_SPEED_UNKNOWN = 0,
 717
 718         /** The device is operating at low speed (1.5MBit/s). */
 719         LIBUSB_SPEED_LOW = 1,
 720
 721         /** The device is operating at full speed (12MBit/s). */
 722         LIBUSB_SPEED_FULL = 2,
 723
 724         /** The device is operating at high speed (480MBit/s). */
 725         LIBUSB_SPEED_HIGH = 3,
 726
 727         /** The device is operating at super speed (5000MBit/s). */
 728         LIBUSB_SPEED_SUPER = 4,
 729 };
 730
 731 /** \ingroup misc
 732  * Error codes. Most libusbx functions return 0 on success or one of these
 733  * codes on failure.
 734  * You can call \ref libusb_error_name() to retrieve a string representation
 735  * of an error code.
 736  */
 737 enum libusb_error {
 738         /** Success (no error) */
 739         LIBUSB_SUCCESS = 0,
 740
 741         /** Input/output error */
 742         LIBUSB_ERROR_IO = -1,
 743
 744         /** Invalid parameter */
 745         LIBUSB_ERROR_INVALID_PARAM = -2,
 746
 747         /** Access denied (insufficient permissions) */
 748         LIBUSB_ERROR_ACCESS = -3,
 749
 750         /** No such device (it may have been disconnected) */
 751         LIBUSB_ERROR_NO_DEVICE = -4,
 752
 753         /** Entity not found */
 754         LIBUSB_ERROR_NOT_FOUND = -5,
 755
 756         /** Resource busy */
 757         LIBUSB_ERROR_BUSY = -6,
 758
 759         /** Operation timed out */
 760         LIBUSB_ERROR_TIMEOUT = -7,
 761
 762         /** Overflow */
 763         LIBUSB_ERROR_OVERFLOW = -8,
 764
 765         /** Pipe error */
 766         LIBUSB_ERROR_PIPE = -9,
 767
 768         /** System call interrupted (perhaps due to signal) */
 769         LIBUSB_ERROR_INTERRUPTED = -10,
 770
 771         /** Insufficient memory */
 772         LIBUSB_ERROR_NO_MEM = -11,
 773
 774         /** Operation not supported or unimplemented on this platform */
 775         LIBUSB_ERROR_NOT_SUPPORTED = -12,
 776
 777         /* NB! Remember to update libusb_error_name()
 778            when adding new error codes here. */
 779
 780         /** Other error */
 781         LIBUSB_ERROR_OTHER = -99,
 782 };
 783
 784 /** \ingroup asyncio
 785  * Transfer status codes */
 786 enum libusb_transfer_status {
 787         /** Transfer completed without error. Note that this does not indicate
 788          * that the entire amount of requested data was transferred. */
 789         LIBUSB_TRANSFER_COMPLETED,
 790
 791         /** Transfer failed */
 792         LIBUSB_TRANSFER_ERROR,
 793
 794         /** Transfer timed out */
 795         LIBUSB_TRANSFER_TIMED_OUT,
 796
 797         /** Transfer was cancelled */
 798         LIBUSB_TRANSFER_CANCELLED,
 799
 800         /** For bulk/interrupt endpoints: halt condition detected (endpoint
 801          * stalled). For control endpoints: control request not supported. */
 802         LIBUSB_TRANSFER_STALL,
 803
 804         /** Device was disconnected */
 805         LIBUSB_TRANSFER_NO_DEVICE,
 806
 807         /** Device sent more data than requested */
 808         LIBUSB_TRANSFER_OVERFLOW,
 809 };
 810
 811 /** \ingroup asyncio
 812  * libusb_transfer.flags values */
 813 enum libusb_transfer_flags {
 814         /** Report short frames as errors */
 815         LIBUSB_TRANSFER_SHORT_NOT_OK = 1<<0,
 816
 817         /** Automatically free() transfer buffer during libusb_free_transfer() */
 818         LIBUSB_TRANSFER_FREE_BUFFER = 1<<1,
 819
 820         /** Automatically call libusb_free_transfer() after callback returns.
 821          * If this flag is set, it is illegal to call libusb_free_transfer()
 822          * from your transfer callback, as this will result in a double-free
 823          * when this flag is acted upon. */
 824         LIBUSB_TRANSFER_FREE_TRANSFER = 1<<2,
 825
 826         /** Terminate transfers that are a multiple of the endpoint's
 827          * wMaxPacketSize with an extra zero length packet. This is useful
 828          * when a device protocol mandates that each logical request is
 829          * terminated by an incomplete packet (i.e. the logical requests are
 830          * not separated by other means).
 831          *
 832          * This flag only affects host-to-device transfers to bulk and interrupt
 833          * endpoints. In other situations, it is ignored.
 834          *
 835          * This flag only affects transfers with a length that is a multiple of
 836          * the endpoint's wMaxPacketSize. On transfers of other lengths, this
 837          * flag has no effect. Therefore, if you are working with a device that
 838          * needs a ZLP whenever the end of the logical request falls on a packet
 839          * boundary, then it is sensible to set this flag on <em>every</em>
 840          * transfer (you do not have to worry about only setting it on transfers
 841          * that end on the boundary).
 842          *
 843          * This flag is currently only supported on Linux.
 844          * On other systems, libusb_submit_transfer() will return
 845          * LIBUSB_ERROR_NOT_SUPPORTED for every transfer where this flag is set.
 846          *
 847          * Available since libusb-1.0.9.
 848          */
 849         LIBUSB_TRANSFER_ADD_ZERO_PACKET = 1 << 3,
 850 };
 851
 852 /** \ingroup asyncio
 853  * Isochronous packet descriptor. */
 854 struct libusb_iso_packet_descriptor {
 855         /** Length of data to request in this packet */
 856         unsigned int length;
 857
 858         /** Amount of data that was actually transferred */
 859         unsigned int actual_length;
 860
 861         /** Status code for this packet */
 862         enum libusb_transfer_status status;
 863 };
 864
 865 struct libusb_transfer;
 866
 867 /** \ingroup asyncio
 868  * Asynchronous transfer callback function type. When submitting asynchronous
 869  * transfers, you pass a pointer to a callback function of this type via the
 870  * \ref libusb_transfer::callback "callback" member of the libusb_transfer
 871  * structure. libusbx will call this function later, when the transfer has
 872  * completed or failed. See \ref asyncio for more information.
 873  * \param transfer The libusb_transfer struct the callback function is being
 874  * notified about.
 875  */
 876 typedef void (LIBUSB_CALL *libusb_transfer_cb_fn)(struct libusb_transfer *transfer);
 877
 878 /** \ingroup asyncio
 879  * The generic USB transfer structure. The user populates this structure and
 880  * then submits it in order to request a transfer. After the transfer has
 881  * completed, the library populates the transfer with the results and passes
 882  * it back to the user.
 883  */
 884 struct libusb_transfer {
 885         /** Handle of the device that this transfer will be submitted to */
 886         libusb_device_handle *dev_handle;
 887
 888         /** A bitwise OR combination of \ref libusb_transfer_flags. */
 889         uint8_t flags;
 890
 891         /** Address of the endpoint where this transfer will be sent. */
 892         unsigned char endpoint;
 893
 894         /** Type of the endpoint from \ref libusb_transfer_type */
 895         unsigned char type;
 896
 897         /** Timeout for this transfer in millseconds. A value of 0 indicates no
 898          * timeout. */
 899         unsigned int timeout;
 900
 901         /** The status of the transfer. Read-only, and only for use within
 902          * transfer callback function.
 903          *
 904          * If this is an isochronous transfer, this field may read COMPLETED even
 905          * if there were errors in the frames. Use the
 906          * \ref libusb_iso_packet_descriptor::status "status" field in each packet
 907          * to determine if errors occurred. */
 908         enum libusb_transfer_status status;
 909
 910         /** Length of the data buffer */
 911         int length;
 912
 913         /** Actual length of data that was transferred. Read-only, and only for
 914          * use within transfer callback function. Not valid for isochronous
 915          * endpoint transfers. */
 916         int actual_length;
 917
 918         /** Callback function. This will be invoked when the transfer completes,
 919          * fails, or is cancelled. */
 920         libusb_transfer_cb_fn callback;
 921
 922         /** User context data to pass to the callback function. */
 923         void *user_data;
 924
 925         /** Data buffer */
 926         unsigned char *buffer;
 927
 928         /** Number of isochronous packets. Only used for I/O with isochronous
 929          * endpoints. */
 930         int num_iso_packets;
 931
 932         /** Isochronous packet descriptors, for isochronous transfers only. */
 933         struct libusb_iso_packet_descriptor iso_packet_desc
 934 #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
 935         [] /* valid C99 code */
 936 #else
 937         [0] /* non-standard, but usually working code */
 938 #endif
 939         ;
 940 };
 941
 942 /** \ingroup misc
 943  * Capabilities supported by this instance of libusb. Test if the loaded
 944  * library supports a given capability by calling
 945  * \ref libusb_has_capability().
 946  */
 947 enum libusb_capability {
 948         /** The libusb_has_capability() API is available. */
 949         LIBUSB_CAP_HAS_CAPABILITY = 0,
 950 };
 951
 952 int LIBUSB_CALL libusb_init(libusb_context **ctx);
 953 void LIBUSB_CALL libusb_exit(libusb_context *ctx);
 954 void LIBUSB_CALL libusb_set_debug(libusb_context *ctx, int level);
 955 const struct libusb_version * LIBUSB_CALL libusb_get_version(void);
 956 int LIBUSB_CALL libusb_has_capability(uint32_t capability);
 957 const char * LIBUSB_CALL libusb_error_name(int errcode);
 958
 959 ssize_t LIBUSB_CALL libusb_get_device_list(libusb_context *ctx,
 960         libusb_device ***list);
 961 void LIBUSB_CALL libusb_free_device_list(libusb_device **list,
 962         int unref_devices);
 963 libusb_device * LIBUSB_CALL libusb_ref_device(libusb_device *dev);
 964 void LIBUSB_CALL libusb_unref_device(libusb_device *dev);
 965
 966 int LIBUSB_CALL libusb_get_configuration(libusb_device_handle *dev,
 967         int *config);
 968 int LIBUSB_CALL libusb_get_device_descriptor(libusb_device *dev,
 969         struct libusb_device_descriptor *desc);
 970 int LIBUSB_CALL libusb_get_active_config_descriptor(libusb_device *dev,
 971         struct libusb_config_descriptor **config);
 972 int LIBUSB_CALL libusb_get_config_descriptor(libusb_device *dev,
 973         uint8_t config_index, struct libusb_config_descriptor **config);
 974 int LIBUSB_CALL libusb_get_config_descriptor_by_value(libusb_device *dev,
 975         uint8_t bConfigurationValue, struct libusb_config_descriptor **config);
 976 void LIBUSB_CALL libusb_free_config_descriptor(
 977         struct libusb_config_descriptor *config);
 978 uint8_t LIBUSB_CALL libusb_get_bus_number(libusb_device *dev);
 979 uint8_t LIBUSB_CALL libusb_get_port_number(libusb_device *dev);
 980 libusb_device * LIBUSB_CALL libusb_get_parent(libusb_device *dev);
 981 int LIBUSB_CALL libusb_get_port_path(libusb_context *ctx, libusb_device *dev, uint8_t* path, uint8_t path_length);
 982 uint8_t LIBUSB_CALL libusb_get_device_address(libusb_device *dev);
 983 int LIBUSB_CALL libusb_get_device_speed(libusb_device *dev);
 984 int LIBUSB_CALL libusb_get_max_packet_size(libusb_device *dev,
 985         unsigned char endpoint);
 986 int LIBUSB_CALL libusb_get_max_iso_packet_size(libusb_device *dev,
 987         unsigned char endpoint);
 988
 989 int LIBUSB_CALL libusb_open(libusb_device *dev, libusb_device_handle **handle);
 990 void LIBUSB_CALL libusb_close(libusb_device_handle *dev_handle);
 991 libusb_device * LIBUSB_CALL libusb_get_device(libusb_device_handle *dev_handle);
 992
 993 int LIBUSB_CALL libusb_set_configuration(libusb_device_handle *dev,
 994         int configuration);
 995 int LIBUSB_CALL libusb_claim_interface(libusb_device_handle *dev,
 996         int interface_number);
 997 int LIBUSB_CALL libusb_release_interface(libusb_device_handle *dev,
 998         int interface_number);
 999
1000 libusb_device_handle * LIBUSB_CALL libusb_open_device_with_vid_pid(
1001         libusb_context *ctx, uint16_t vendor_id, uint16_t product_id);
1002
1003 int LIBUSB_CALL libusb_set_interface_alt_setting(libusb_device_handle *dev,
1004         int interface_number, int alternate_setting);
1005 int LIBUSB_CALL libusb_clear_halt(libusb_device_handle *dev,
1006         unsigned char endpoint);
1007 int LIBUSB_CALL libusb_reset_device(libusb_device_handle *dev);
1008
1009 int LIBUSB_CALL libusb_kernel_driver_active(libusb_device_handle *dev,
1010         int interface_number);
1011 int LIBUSB_CALL libusb_detach_kernel_driver(libusb_device_handle *dev,
1012         int interface_number);
1013 int LIBUSB_CALL libusb_attach_kernel_driver(libusb_device_handle *dev,
1014         int interface_number);
1015
1016 /* async I/O */
1017
1018 /** \ingroup asyncio
1019  * Get the data section of a control transfer. This convenience function is here
1020  * to remind you that the data does not start until 8 bytes into the actual
1021  * buffer, as the setup packet comes first.
1022  *
1023  * Calling this function only makes sense from a transfer callback function,
1024  * or situations where you have already allocated a suitably sized buffer at
1025  * transfer->buffer.
1026  *
1027  * \param transfer a transfer
1028  * \returns pointer to the first byte of the data section
1029  */
1030 static inline unsigned char *libusb_control_transfer_get_data(
1031         struct libusb_transfer *transfer)
1032 {
1033         return transfer->buffer + LIBUSB_CONTROL_SETUP_SIZE;
1034 }
1035
1036 /** \ingroup asyncio
1037  * Get the control setup packet of a control transfer. This convenience
1038  * function is here to remind you that the control setup occupies the first
1039  * 8 bytes of the transfer data buffer.
1040  *
1041  * Calling this function only makes sense from a transfer callback function,
1042  * or situations where you have already allocated a suitably sized buffer at
1043  * transfer->buffer.
1044  *
1045  * \param transfer a transfer
1046  * \returns a casted pointer to the start of the transfer data buffer
1047  */
1048 static inline struct libusb_control_setup *libusb_control_transfer_get_setup(
1049         struct libusb_transfer *transfer)
1050 {
1051         return (struct libusb_control_setup *) transfer->buffer;
1052 }
1053
1054 /** \ingroup asyncio
1055  * Helper function to populate the setup packet (first 8 bytes of the data
1056  * buffer) for a control transfer. The wIndex, wValue and wLength values should
1057  * be given in host-endian byte order.
1058  *
1059  * \param buffer buffer to output the setup packet into
1060  * \param bmRequestType see the
1061  * \ref libusb_control_setup::bmRequestType "bmRequestType" field of
1062  * \ref libusb_control_setup
1063  * \param bRequest see the
1064  * \ref libusb_control_setup::bRequest "bRequest" field of
1065  * \ref libusb_control_setup
1066  * \param wValue see the
1067  * \ref libusb_control_setup::wValue "wValue" field of
1068  * \ref libusb_control_setup
1069  * \param wIndex see the
1070  * \ref libusb_control_setup::wIndex "wIndex" field of
1071  * \ref libusb_control_setup
1072  * \param wLength see the
1073  * \ref libusb_control_setup::wLength "wLength" field of
1074  * \ref libusb_control_setup
1075  */
1076 static inline void libusb_fill_control_setup(unsigned char *buffer,
1077         uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
1078         uint16_t wLength)
1079 {
1080         struct libusb_control_setup *setup = (struct libusb_control_setup *) buffer;
1081         setup->bmRequestType = bmRequestType;
1082         setup->bRequest = bRequest;
1083         setup->wValue = libusb_cpu_to_le16(wValue);
1084         setup->wIndex = libusb_cpu_to_le16(wIndex);
1085         setup->wLength = libusb_cpu_to_le16(wLength);
1086 }
1087
1088 struct libusb_transfer * LIBUSB_CALL libusb_alloc_transfer(int iso_packets);
1089 int LIBUSB_CALL libusb_submit_transfer(struct libusb_transfer *transfer);
1090 int LIBUSB_CALL libusb_cancel_transfer(struct libusb_transfer *transfer);
1091 void LIBUSB_CALL libusb_free_transfer(struct libusb_transfer *transfer);
1092
1093 /** \ingroup asyncio
1094  * Helper function to populate the required \ref libusb_transfer fields
1095  * for a control transfer.
1096  *
1097  * If you pass a transfer buffer to this function, the first 8 bytes will
1098  * be interpreted as a control setup packet, and the wLength field will be
1099  * used to automatically populate the \ref libusb_transfer::length "length"
1100  * field of the transfer. Therefore the recommended approach is:
1101  * -# Allocate a suitably sized data buffer (including space for control setup)
1102  * -# Call libusb_fill_control_setup()
1103  * -# If this is a host-to-device transfer with a data stage, put the data
1104  *    in place after the setup packet
1105  * -# Call this function
1106  * -# Call libusb_submit_transfer()
1107  *
1108  * It is also legal to pass a NULL buffer to this function, in which case this
1109  * function will not attempt to populate the length field. Remember that you
1110  * must then populate the buffer and length fields later.
1111  *
1112  * \param transfer the transfer to populate
1113  * \param dev_handle handle of the device that will handle the transfer
1114  * \param buffer data buffer. If provided, this function will interpret the
1115  * first 8 bytes as a setup packet and infer the transfer length from that.
1116  * \param callback callback function to be invoked on transfer completion
1117  * \param user_data user data to pass to callback function
1118  * \param timeout timeout for the transfer in milliseconds
1119  */
1120 static inline void libusb_fill_control_transfer(
1121         struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
1122         unsigned char *buffer, libusb_transfer_cb_fn callback, void *user_data,
1123         unsigned int timeout)
1124 {
1125         struct libusb_control_setup *setup = (struct libusb_control_setup *) buffer;
1126         transfer->dev_handle = dev_handle;
1127         transfer->endpoint = 0;
1128         transfer->type = LIBUSB_TRANSFER_TYPE_CONTROL;
1129         transfer->timeout = timeout;
1130         transfer->buffer = buffer;
1131         if (setup)
1132                 transfer->length = LIBUSB_CONTROL_SETUP_SIZE
1133                         + libusb_le16_to_cpu(setup->wLength);
1134         transfer->user_data = user_data;
1135         transfer->callback = callback;
1136 }
1137
1138 /** \ingroup asyncio
1139  * Helper function to populate the required \ref libusb_transfer fields
1140  * for a bulk transfer.
1141  *
1142  * \param transfer the transfer to populate
1143  * \param dev_handle handle of the device that will handle the transfer
1144  * \param endpoint address of the endpoint where this transfer will be sent
1145  * \param buffer data buffer
1146  * \param length length of data buffer
1147  * \param callback callback function to be invoked on transfer completion
1148  * \param user_data user data to pass to callback function
1149  * \param timeout timeout for the transfer in milliseconds
1150  */
1151 static inline void libusb_fill_bulk_transfer(struct libusb_transfer *transfer,
1152         libusb_device_handle *dev_handle, unsigned char endpoint,
1153         unsigned char *buffer, int length, libusb_transfer_cb_fn callback,
1154         void *user_data, unsigned int timeout)
1155 {
1156         transfer->dev_handle = dev_handle;
1157         transfer->endpoint = endpoint;
1158         transfer->type = LIBUSB_TRANSFER_TYPE_BULK;
1159         transfer->timeout = timeout;
1160         transfer->buffer = buffer;
1161         transfer->length = length;
1162         transfer->user_data = user_data;
1163         transfer->callback = callback;
1164 }
1165
1166 /** \ingroup asyncio
1167  * Helper function to populate the required \ref libusb_transfer fields
1168  * for an interrupt transfer.
1169  *
1170  * \param transfer the transfer to populate
1171  * \param dev_handle handle of the device that will handle the transfer
1172  * \param endpoint address of the endpoint where this transfer will be sent
1173  * \param buffer data buffer
1174  * \param length length of data buffer
1175  * \param callback callback function to be invoked on transfer completion
1176  * \param user_data user data to pass to callback function
1177  * \param timeout timeout for the transfer in milliseconds
1178  */
1179 static inline void libusb_fill_interrupt_transfer(
1180         struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
1181         unsigned char endpoint, unsigned char *buffer, int length,
1182         libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
1183 {
1184         transfer->dev_handle = dev_handle;
1185         transfer->endpoint = endpoint;
1186         transfer->type = LIBUSB_TRANSFER_TYPE_INTERRUPT;
1187         transfer->timeout = timeout;
1188         transfer->buffer = buffer;
1189         transfer->length = length;
1190         transfer->user_data = user_data;
1191         transfer->callback = callback;
1192 }
1193
1194 /** \ingroup asyncio
1195  * Helper function to populate the required \ref libusb_transfer fields
1196  * for an isochronous transfer.
1197  *
1198  * \param transfer the transfer to populate
1199  * \param dev_handle handle of the device that will handle the transfer
1200  * \param endpoint address of the endpoint where this transfer will be sent
1201  * \param buffer data buffer
1202  * \param length length of data buffer
1203  * \param num_iso_packets the number of isochronous packets
1204  * \param callback callback function to be invoked on transfer completion
1205  * \param user_data user data to pass to callback function
1206  * \param timeout timeout for the transfer in milliseconds
1207  */
1208 static inline void libusb_fill_iso_transfer(struct libusb_transfer *transfer,
1209         libusb_device_handle *dev_handle, unsigned char endpoint,
1210         unsigned char *buffer, int length, int num_iso_packets,
1211         libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
1212 {
1213         transfer->dev_handle = dev_handle;
1214         transfer->endpoint = endpoint;
1215         transfer->type = LIBUSB_TRANSFER_TYPE_ISOCHRONOUS;
1216         transfer->timeout = timeout;
1217         transfer->buffer = buffer;
1218         transfer->length = length;
1219         transfer->num_iso_packets = num_iso_packets;
1220         transfer->user_data = user_data;
1221         transfer->callback = callback;
1222 }
1223
1224 /** \ingroup asyncio
1225  * Convenience function to set the length of all packets in an isochronous
1226  * transfer, based on the num_iso_packets field in the transfer structure.
1227  *
1228  * \param transfer a transfer
1229  * \param length the length to set in each isochronous packet descriptor
1230  * \see libusb_get_max_packet_size()
1231  */
1232 static inline void libusb_set_iso_packet_lengths(
1233         struct libusb_transfer *transfer, unsigned int length)
1234 {
1235         int i;
1236         for (i = 0; i < transfer->num_iso_packets; i++)
1237                 transfer->iso_packet_desc[i].length = length;
1238 }
1239
1240 /** \ingroup asyncio
1241  * Convenience function to locate the position of an isochronous packet
1242  * within the buffer of an isochronous transfer.
1243  *
1244  * This is a thorough function which loops through all preceding packets,
1245  * accumulating their lengths to find the position of the specified packet.
1246  * Typically you will assign equal lengths to each packet in the transfer,
1247  * and hence the above method is sub-optimal. You may wish to use
1248  * libusb_get_iso_packet_buffer_simple() instead.
1249  *
1250  * \param transfer a transfer
1251  * \param packet the packet to return the address of
1252  * \returns the base address of the packet buffer inside the transfer buffer,
1253  * or NULL if the packet does not exist.
1254  * \see libusb_get_iso_packet_buffer_simple()
1255  */
1256 static inline unsigned char *libusb_get_iso_packet_buffer(
1257         struct libusb_transfer *transfer, unsigned int packet)
1258 {
1259         int i;
1260         size_t offset = 0;
1261         int _packet;
1262
1263         /* oops..slight bug in the API. packet is an unsigned int, but we use
1264          * signed integers almost everywhere else. range-check and convert to
1265          * signed to avoid compiler warnings. FIXME for libusb-2. */
1266         if (packet > INT_MAX)
1267                 return NULL;
1268         _packet = packet;
1269
1270         if (_packet >= transfer->num_iso_packets)
1271                 return NULL;
1272
1273         for (i = 0; i < _packet; i++)
1274                 offset += transfer->iso_packet_desc[i].length;
1275
1276         return transfer->buffer + offset;
1277 }
1278
1279 /** \ingroup asyncio
1280  * Convenience function to locate the position of an isochronous packet
1281  * within the buffer of an isochronous transfer, for transfers where each
1282  * packet is of identical size.
1283  *
1284  * This function relies on the assumption that every packet within the transfer
1285  * is of identical size to the first packet. Calculating the location of
1286  * the packet buffer is then just a simple calculation:
1287  * <tt>buffer + (packet_size * packet)</tt>
1288  *
1289  * Do not use this function on transfers other than those that have identical
1290  * packet lengths for each packet.
1291  *
1292  * \param transfer a transfer
1293  * \param packet the packet to return the address of
1294  * \returns the base address of the packet buffer inside the transfer buffer,
1295  * or NULL if the packet does not exist.
1296  * \see libusb_get_iso_packet_buffer()
1297  */
1298 static inline unsigned char *libusb_get_iso_packet_buffer_simple(
1299         struct libusb_transfer *transfer, unsigned int packet)
1300 {
1301         int _packet;
1302
1303         /* oops..slight bug in the API. packet is an unsigned int, but we use
1304          * signed integers almost everywhere else. range-check and convert to
1305          * signed to avoid compiler warnings. FIXME for libusb-2. */
1306         if (packet > INT_MAX)
1307                 return NULL;
1308         _packet = packet;
1309
1310         if (_packet >= transfer->num_iso_packets)
1311                 return NULL;
1312
1313         return transfer->buffer + (transfer->iso_packet_desc[0].length * _packet);
1314 }
1315
1316 /* sync I/O */
1317
1318 int LIBUSB_CALL libusb_control_transfer(libusb_device_handle *dev_handle,
1319         uint8_t request_type, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
1320         unsigned char *data, uint16_t wLength, unsigned int timeout);
1321
1322 int LIBUSB_CALL libusb_bulk_transfer(libusb_device_handle *dev_handle,
1323         unsigned char endpoint, unsigned char *data, int length,
1324         int *actual_length, unsigned int timeout);
1325
1326 int LIBUSB_CALL libusb_interrupt_transfer(libusb_device_handle *dev_handle,
1327         unsigned char endpoint, unsigned char *data, int length,
1328         int *actual_length, unsigned int timeout);
1329
1330 /** \ingroup desc
1331  * Retrieve a descriptor from the default control pipe.
1332  * This is a convenience function which formulates the appropriate control
1333  * message to retrieve the descriptor.
1334  *
1335  * \param dev a device handle
1336  * \param desc_type the descriptor type, see \ref libusb_descriptor_type
1337  * \param desc_index the index of the descriptor to retrieve
1338  * \param data output buffer for descriptor
1339  * \param length size of data buffer
1340  * \returns number of bytes returned in data, or LIBUSB_ERROR code on failure
1341  */
1342 static inline int libusb_get_descriptor(libusb_device_handle *dev,
1343         uint8_t desc_type, uint8_t desc_index, unsigned char *data, int length)
1344 {
1345         return libusb_control_transfer(dev, LIBUSB_ENDPOINT_IN,
1346                 LIBUSB_REQUEST_GET_DESCRIPTOR, (desc_type << 8) | desc_index, 0, data,
1347                 (uint16_t) length, 1000);
1348 }
1349
1350 /** \ingroup desc
1351  * Retrieve a descriptor from a device.
1352  * This is a convenience function which formulates the appropriate control
1353  * message to retrieve the descriptor. The string returned is Unicode, as
1354  * detailed in the USB specifications.
1355  *
1356  * \param dev a device handle
1357  * \param desc_index the index of the descriptor to retrieve
1358  * \param langid the language ID for the string descriptor
1359  * \param data output buffer for descriptor
1360  * \param length size of data buffer
1361  * \returns number of bytes returned in data, or LIBUSB_ERROR code on failure
1362  * \see libusb_get_string_descriptor_ascii()
1363  */
1364 static inline int libusb_get_string_descriptor(libusb_device_handle *dev,
1365         uint8_t desc_index, uint16_t langid, unsigned char *data, int length)
1366 {
1367         return libusb_control_transfer(dev, LIBUSB_ENDPOINT_IN,
1368                 LIBUSB_REQUEST_GET_DESCRIPTOR, (uint16_t)((LIBUSB_DT_STRING << 8) | desc_index),
1369                 langid, data, (uint16_t) length, 1000);
1370 }
1371
1372 int LIBUSB_CALL libusb_get_string_descriptor_ascii(libusb_device_handle *dev,
1373         uint8_t desc_index, unsigned char *data, int length);
1374
1375 /* polling and timeouts */
1376
1377 int LIBUSB_CALL libusb_try_lock_events(libusb_context *ctx);
1378 void LIBUSB_CALL libusb_lock_events(libusb_context *ctx);
1379 void LIBUSB_CALL libusb_unlock_events(libusb_context *ctx);
1380 int LIBUSB_CALL libusb_event_handling_ok(libusb_context *ctx);
1381 int LIBUSB_CALL libusb_event_handler_active(libusb_context *ctx);
1382 void LIBUSB_CALL libusb_lock_event_waiters(libusb_context *ctx);
1383 void LIBUSB_CALL libusb_unlock_event_waiters(libusb_context *ctx);
1384 int LIBUSB_CALL libusb_wait_for_event(libusb_context *ctx, struct timeval *tv);
1385
1386 int LIBUSB_CALL libusb_handle_events_timeout(libusb_context *ctx,
1387         struct timeval *tv);
1388 int LIBUSB_CALL libusb_handle_events_timeout_completed(libusb_context *ctx,
1389         struct timeval *tv, int *completed);
1390 int LIBUSB_CALL libusb_handle_events(libusb_context *ctx);
1391 int LIBUSB_CALL libusb_handle_events_completed(libusb_context *ctx, int *completed);
1392 int LIBUSB_CALL libusb_handle_events_locked(libusb_context *ctx,
1393         struct timeval *tv);
1394 int LIBUSB_CALL libusb_pollfds_handle_timeouts(libusb_context *ctx);
1395 int LIBUSB_CALL libusb_get_next_timeout(libusb_context *ctx,
1396         struct timeval *tv);
1397
1398 /** \ingroup poll
1399  * File descriptor for polling
1400  */
1401 struct libusb_pollfd {
1402         /** Numeric file descriptor */
1403         int fd;
1404
1405         /** Event flags to poll for from <poll.h>. POLLIN indicates that you
1406          * should monitor this file descriptor for becoming ready to read from,
1407          * and POLLOUT indicates that you should monitor this file descriptor for
1408          * nonblocking write readiness. */
1409         short events;
1410 };
1411
1412 /** \ingroup poll
1413  * Callback function, invoked when a new file descriptor should be added
1414  * to the set of file descriptors monitored for events.
1415  * \param fd the new file descriptor
1416  * \param events events to monitor for, see \ref libusb_pollfd for a
1417  * description
1418  * \param user_data User data pointer specified in
1419  * libusb_set_pollfd_notifiers() call
1420  * \see libusb_set_pollfd_notifiers()
1421  */
1422 typedef void (LIBUSB_CALL *libusb_pollfd_added_cb)(int fd, short events,
1423         void *user_data);
1424
1425 /** \ingroup poll
1426  * Callback function, invoked when a file descriptor should be removed from
1427  * the set of file descriptors being monitored for events. After returning
1428  * from this callback, do not use that file descriptor again.
1429  * \param fd the file descriptor to stop monitoring
1430  * \param user_data User data pointer specified in
1431  * libusb_set_pollfd_notifiers() call
1432  * \see libusb_set_pollfd_notifiers()
1433  */
1434 typedef void (LIBUSB_CALL *libusb_pollfd_removed_cb)(int fd, void *user_data);
1435
1436 const struct libusb_pollfd ** LIBUSB_CALL libusb_get_pollfds(
1437         libusb_context *ctx);
1438 void LIBUSB_CALL libusb_set_pollfd_notifiers(libusb_context *ctx,
1439         libusb_pollfd_added_cb added_cb, libusb_pollfd_removed_cb removed_cb,
1440         void *user_data);
1441
1442 #ifdef __cplusplus
1443 }
1444 #endif
1445
1446 #endif