libusb/libusb.h

   1 /*
   2  * Public libusb header file
   3  * Copyright (C) 2007-2008 Daniel Drake <dsd@gentoo.org>
   4  * Copyright (c) 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 #include <stdint.h>
  25 #include <sys/time.h>
  26 #include <sys/types.h>
  27 #include <time.h>
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /* standard USB stuff */
  34
  35 /** \ingroup desc
  36  * Device and/or Interface Class codes */
  37 enum libusb_class_code {
  38         /** In the context of a \ref libusb_device_descriptor "device descriptor",
  39          * this bDeviceClass value indicates that each interface specifies its
  40          * own class information and all interfaces operate independently.
  41          */
  42         LIBUSB_CLASS_PER_INTERFACE = 0,
  43
  44         /** Audio class */
  45         LIBUSB_CLASS_AUDIO = 1,
  46
  47         /** Communications class */
  48         LIBUSB_CLASS_COMM = 2,
  49
  50         /** Human Interface Device class */
  51         LIBUSB_CLASS_HID = 3,
  52
  53         /** Printer dclass */
  54         LIBUSB_CLASS_PRINTER = 7,
  55
  56         /** Picture transfer protocol class */
  57         LIBUSB_CLASS_PTP = 6,
  58
  59         /** Mass storage class */
  60         LIBUSB_CLASS_MASS_STORAGE = 8,
  61
  62         /** Hub class */
  63         LIBUSB_CLASS_HUB = 9,
  64
  65         /** Data class */
  66         LIBUSB_CLASS_DATA = 10,
  67
  68         /** Class is vendor-specific */
  69         LIBUSB_CLASS_VENDOR_SPEC = 0xff,
  70 };
  71
  72 /** \ingroup desc
  73  * Descriptor types as defined by the USB specification. */
  74 enum libusb_descriptor_type {
  75         /** Device descriptor. See libusb_device_descriptor. */
  76         LIBUSB_DT_DEVICE = 0x01,
  77
  78         /** Configuration descriptor. See libusb_config_descriptor. */
  79         LIBUSB_DT_CONFIG = 0x02,
  80
  81         /** String descriptor */
  82         LIBUSB_DT_STRING = 0x03,
  83
  84         /** Interface descriptor. See libusb_interface_descriptor. */
  85         LIBUSB_DT_INTERFACE = 0x04,
  86
  87         /** Endpoint descriptor. See libusb_endpoint_descriptor. */
  88         LIBUSB_DT_ENDPOINT = 0x05,
  89
  90         /** HID descriptor */
  91         LIBUSB_DT_HID = 0x21,
  92
  93         /** HID report descriptor */
  94         LIBUSB_DT_REPORT = 0x22,
  95
  96         /** Physical descriptor */
  97         LIBUSB_DT_PHYSICAL = 0x23,
  98
  99         /** Hub descriptor */
 100         LIBUSB_DT_HUB = 0x29,
 101 };
 102
 103 /* Descriptor sizes per descriptor type */
 104 #define LIBUSB_DT_DEVICE_SIZE                   18
 105 #define LIBUSB_DT_CONFIG_SIZE                   9
 106 #define LIBUSB_DT_INTERFACE_SIZE                9
 107 #define LIBUSB_DT_ENDPOINT_SIZE         7
 108 #define LIBUSB_DT_ENDPOINT_AUDIO_SIZE   9       /* Audio extension */
 109 #define LIBUSB_DT_HUB_NONVAR_SIZE               7
 110
 111 #define LIBUSB_ENDPOINT_ADDRESS_MASK    0x0f    /* in bEndpointAddress */
 112 #define LIBUSB_ENDPOINT_DIR_MASK                0x80
 113
 114 /** \ingroup desc
 115  * Endpoint direction. Values for bit 7 of the
 116  * \ref libusb_endpoint_descriptor::bEndpointAddress "endpoint address" scheme.
 117  */
 118 enum libusb_endpoint_direction {
 119         /** In: device-to-host */
 120         LIBUSB_ENDPOINT_IN = 0x80,
 121
 122         /** Out: host-to-device */
 123         LIBUSB_ENDPOINT_OUT = 0x00,
 124 };
 125
 126 #define LIBUSB_TRANSFER_TYPE_MASK                       0x03    /* in bmAttributes */
 127
 128 /** \ingroup desc
 129  * Endpoint transfer type. Values for bits 0:1 of the
 130  * \ref libusb_endpoint_descriptor::bmAttributes "endpoint attributes" field.
 131  */
 132 enum libusb_transfer_type {
 133         /** Control endpoint */
 134         LIBUSB_TRANSFER_TYPE_CONTROL = 0,
 135
 136         /** Isochronous endpoint */
 137         LIBUSB_TRANSFER_TYPE_ISOCHRONOUS = 1,
 138
 139         /** Bulk endpoint */
 140         LIBUSB_TRANSFER_TYPE_BULK = 2,
 141
 142         /** Interrupt endpoint */
 143         LIBUSB_TRANSFER_TYPE_INTERRUPT = 3,
 144 };
 145
 146 /** \ingroup misc
 147  * Standard requests, as defined in table 9-3 of the USB2 specifications */
 148 enum libusb_standard_request {
 149         /** Request status of the specific recipient */
 150         LIBUSB_REQUEST_GET_STATUS = 0x00,
 151
 152         /** Clear or disable a specific feature */
 153         LIBUSB_REQUEST_CLEAR_FEATURE = 0x01,
 154
 155         /* 0x02 is reserved */
 156
 157         /** Set or enable a specific feature */
 158         LIBUSB_REQUEST_SET_FEATURE = 0x03,
 159
 160         /* 0x04 is reserved */
 161
 162         /** Set device address for all future accesses */
 163         LIBUSB_REQUEST_SET_ADDRESS = 0x05,
 164
 165         /** Get the specified descriptor */
 166         LIBUSB_REQUEST_GET_DESCRIPTOR = 0x06,
 167
 168         /** Used to update existing descriptors or add new descriptors */
 169         LIBUSB_REQUEST_SET_DESCRIPTOR = 0x07,
 170
 171         /** Get the current device configuration value */
 172         LIBUSB_REQUEST_GET_CONFIGURATION = 0x08,
 173
 174         /** Set device configuration */
 175         LIBUSB_REQUEST_SET_CONFIGURATION = 0x09,
 176
 177         /** Return the selected alternate setting for the specified interface */
 178         LIBUSB_REQUEST_GET_INTERFACE = 0x0A,
 179
 180         /** Select an alternate interface for the specified interface */
 181         LIBUSB_REQUEST_SET_INTERFACE = 0x0B,
 182
 183         /** Set then report an endpoint's synchronization frame */
 184         LIBUSB_REQUEST_SYNCH_FRAME = 0x0C,
 185 };
 186
 187 /** \ingroup misc
 188  * Request type bits of the
 189  * \ref libusb_control_setup::bmRequestType "bmRequestType" field in control
 190  * transfers. */
 191 enum libusb_request_type {
 192         /** Standard */
 193         LIBUSB_REQUEST_TYPE_STANDARD = (0x00 << 5),
 194
 195         /** Class */
 196         LIBUSB_REQUEST_TYPE_CLASS = (0x01 << 5),
 197
 198         /** Vendor */
 199         LIBUSB_REQUEST_TYPE_VENDOR = (0x02 << 5),
 200
 201         /** Reserved */
 202         LIBUSB_REQUEST_TYPE_RESERVED = (0x03 << 5),
 203 };
 204
 205 /** \ingroup misc
 206  * Recipient bits of the
 207  * \ref libusb_control_setup::bmRequestType "bmRequestType" field in control
 208  * transfers. Values 4 through 31 are reserved. */
 209 enum libusb_request_recipient {
 210         /** Device */
 211         LIBUSB_RECIPIENT_DEVICE = 0x00,
 212
 213         /** Interface */
 214         LIBUSB_RECIPIENT_INTERFACE = 0x01,
 215
 216         /** Endpoint */
 217         LIBUSB_RECIPIENT_ENDPOINT = 0x02,
 218
 219         /** Other */
 220         LIBUSB_RECIPIENT_OTHER = 0x03,
 221 };
 222
 223 #define LIBUSB_ISO_SYNC_TYPE_MASK               0x0C
 224
 225 /** \ingroup desc
 226  * Synchronization type for isochronous endpoints. Values for bits 2:3 of the
 227  * \ref libusb_endpoint_descriptor::bmAttributes "bmAttributes" field in
 228  * libusb_endpoint_descriptor.
 229  */
 230 enum libusb_iso_sync_type {
 231         /** No synchronization */
 232         LIBUSB_ISO_SYNC_TYPE_NONE = 0,
 233
 234         /** Asynchronous */
 235         LIBUSB_ISO_SYNC_TYPE_ASYNC = 1,
 236
 237         /** Adaptive */
 238         LIBUSB_ISO_SYNC_TYPE_ADAPTIVE = 2,
 239
 240         /** Synchronous */
 241         LIBUSB_ISO_SYNC_TYPE_SYNC = 3,
 242 };
 243
 244 #define LIBUSB_ISO_USAGE_TYPE_MASK 0x30
 245
 246 /** \ingroup desc
 247  * Usage type for isochronous endpoints. Values for bits 4:5 of the
 248  * \ref libusb_endpoint_descriptor::bmAttributes "bmAttributes" field in
 249  * libusb_endpoint_descriptor.
 250  */
 251 enum libusb_iso_usage_type {
 252         /** Data endpoint */
 253         LIBUSB_ISO_USAGE_TYPE_DATA = 0,
 254
 255         /** Feedback endpoint */
 256         LIBUSB_ISO_USAGE_TYPE_FEEDBACK = 1,
 257
 258         /** Implicit feedback Data endpoint */
 259         LIBUSB_ISO_USAGE_TYPE_IMPLICIT = 2,
 260 };
 261
 262 /** \ingroup desc
 263  * A structure representing the standard USB device descriptor. This
 264  * descriptor is documented in section 9.6.1 of the USB 2.0 specification.
 265  * All multiple-byte fields are represented in host-endian format.
 266  */
 267 struct libusb_device_descriptor {
 268         /** Size of this descriptor (in bytes) */
 269         uint8_t  bLength;
 270
 271         /** Descriptor type. Will have value
 272          * \ref libusb_descriptor_type::LIBUSB_DT_DEVICE LIBUSB_DT_DEVICE in this
 273          * context. */
 274         uint8_t  bDescriptorType;
 275
 276         /** USB specification release number in binary-coded decimal. A value of
 277          * 0x0200 indicates USB 2.0, 0x0110 indicates USB 1.1, etc. */
 278         uint16_t bcdUSB;
 279
 280         /** USB-IF class code for the device. See \ref libusb_class_code. */
 281         uint8_t  bDeviceClass;
 282
 283         /** USB-IF subclass code for the device, qualified by the bDeviceClass
 284          * value */
 285         uint8_t  bDeviceSubClass;
 286
 287         /** USB-IF protocol code for the device, qualified by the bDeviceClass and
 288          * bDeviceSubClass values */
 289         uint8_t  bDeviceProtocol;
 290
 291         /** Maximum packet size for endpoint 0 */
 292         uint8_t  bMaxPacketSize0;
 293
 294         /** USB-IF vendor ID */
 295         uint16_t idVendor;
 296
 297         /** USB-IF product ID */
 298         uint16_t idProduct;
 299
 300         /** Device release number in binary-coded decimal */
 301         uint16_t bcdDevice;
 302
 303         /** Index of string descriptor describing manufacturer */
 304         uint8_t  iManufacturer;
 305
 306         /** Index of string descriptor describing product */
 307         uint8_t  iProduct;
 308
 309         /** Index of string descriptor containing device serial number */
 310         uint8_t  iSerialNumber;
 311
 312         /** Number of possible configurations */
 313         uint8_t  bNumConfigurations;
 314 };
 315
 316 /** \ingroup desc
 317  * A structure representing the standard USB endpoint descriptor. This
 318  * descriptor is documented in section 9.6.3 of the USB 2.0 specification.
 319  * All multiple-byte fields are represented in host-endian format.
 320  */
 321 struct libusb_endpoint_descriptor {
 322         /** Size of this descriptor (in bytes) */
 323         uint8_t  bLength;
 324
 325         /** Descriptor type. Will have value
 326          * \ref libusb_descriptor_type::LIBUSB_DT_ENDPOINT LIBUSB_DT_ENDPOINT in
 327          * this context. */
 328         uint8_t  bDescriptorType;
 329
 330         /** The address of the endpoint described by this descriptor. Bits 0:3 are
 331          * the endpoint number. Bits 4:6 are reserved. Bit 7 indicates direction,
 332          * see \ref libusb_endpoint_direction.
 333          */
 334         uint8_t  bEndpointAddress;
 335
 336         /** Attributes which apply to the endpoint when it is configured using
 337          * the bConfigurationValue. Bits 0:1 determine the transfer type and
 338          * correspond to \ref libusb_transfer_type. Bits 2:3 are only used for
 339          * isochronous endpoints and correspond to \ref libusb_iso_sync_type.
 340          * Bits 4:5 are also only used for isochronous endpoints and correspond to
 341          * \ref libusb_iso_usage_type. Bits 6:7 are reserved.
 342          */
 343         uint8_t  bmAttributes;
 344
 345         /** Maximum packet size this endpoint is capable of sending/receiving. */
 346         uint16_t wMaxPacketSize;
 347
 348         /** Interval for polling endpoint for data transfers. */
 349         uint8_t  bInterval;
 350
 351         /** For audio devices only: the rate at which synchronization feedback
 352          * is provided. */
 353         uint8_t  bRefresh;
 354
 355         /** For audio devices only: the address if the synch endpoint */
 356         uint8_t  bSynchAddress;
 357
 358         /** Extra descriptors. If libusb encounters unknown endpoint descriptors,
 359          * it will store them here, should you wish to parse them. */
 360         const unsigned char *extra;
 361
 362         /** Length of the extra descriptors, in bytes. */
 363         int extra_length;
 364 };
 365
 366 /** \ingroup desc
 367  * A structure representing the standard USB interface descriptor. This
 368  * descriptor is documented in section 9.6.5 of the USB 2.0 specification.
 369  * All multiple-byte fields are represented in host-endian format.
 370  */
 371 struct libusb_interface_descriptor {
 372         /** Size of this descriptor (in bytes) */
 373         uint8_t  bLength;
 374
 375         /** Descriptor type. Will have value
 376          * \ref libusb_descriptor_type::LIBUSB_DT_INTERFACE LIBUSB_DT_INTERFACE
 377          * in this context. */
 378         uint8_t  bDescriptorType;
 379
 380         /** Number of this interface */
 381         uint8_t  bInterfaceNumber;
 382
 383         /** Value used to select this alternate setting for this interface */
 384         uint8_t  bAlternateSetting;
 385
 386         /** Number of endpoints used by this interface (excluding the control
 387          * endpoint). */
 388         uint8_t  bNumEndpoints;
 389
 390         /** USB-IF class code for this interface. See \ref libusb_class_code. */
 391         uint8_t  bInterfaceClass;
 392
 393         /** USB-IF subclass code for this interface, qualified by the
 394          * bInterfaceClass value */
 395         uint8_t  bInterfaceSubClass;
 396
 397         /** USB-IF protocol code for this interface, qualified by the
 398          * bInterfaceClass and bInterfaceSubClass values */
 399         uint8_t  bInterfaceProtocol;
 400
 401         /** Index of string descriptor describing this interface */
 402         uint8_t  iInterface;
 403
 404         /** Array of endpoint descriptors. This length of this array is determined
 405          * by the bNumEndpoints field. */
 406         const struct libusb_endpoint_descriptor *endpoint;
 407
 408         /** Extra descriptors. If libusb encounters unknown interface descriptors,
 409          * it will store them here, should you wish to parse them. */
 410         const unsigned char *extra;
 411
 412         /** Length of the extra descriptors, in bytes. */
 413         int extra_length;
 414 };
 415
 416 /** \ingroup desc
 417  * A collection of alternate settings for a particular USB interface.
 418  */
 419 struct libusb_interface {
 420         /** Array of interface descriptors. The length of this array is determined
 421          * by the num_altsetting field. */
 422         const struct libusb_interface_descriptor *altsetting;
 423
 424         /** The number of alternate settings that belong to this interface */
 425         int num_altsetting;
 426 };
 427
 428 /** \ingroup desc
 429  * A structure representing the standard USB configuration descriptor. This
 430  * descriptor is documented in section 9.6.3 of the USB 2.0 specification.
 431  * All multiple-byte fields are represented in host-endian format.
 432  */
 433 struct libusb_config_descriptor {
 434         /** Size of this descriptor (in bytes) */
 435         uint8_t  bLength;
 436
 437         /** Descriptor type. Will have value
 438          * \ref libusb_descriptor_type::LIBUSB_DT_CONFIG LIBUSB_DT_CONFIG
 439          * in this context. */
 440         uint8_t  bDescriptorType;
 441
 442         /** Total length of data returned for this configuration */
 443         uint16_t wTotalLength;
 444
 445         /** Number of interfaces supported by this configuration */
 446         uint8_t  bNumInterfaces;
 447
 448         /** Identifier value for this configuration */
 449         uint8_t  bConfigurationValue;
 450
 451         /** Index of string descriptor describing this configuration */
 452         uint8_t  iConfiguration;
 453
 454         /** Configuration characteristics */
 455         uint8_t  bmAttributes;
 456
 457         /** Maximum power consumption of the USB device from this bus in this
 458          * configuration when the device is fully opreation. Expressed in units
 459          * of 2 mA. */
 460         uint8_t  MaxPower;
 461
 462         /** Array of interfaces supported by this configuration. The length of
 463          * this array is determined by the bNumInterfaces field. */
 464         const struct libusb_interface *interface;
 465
 466         /** Extra descriptors. If libusb encounters unknown configuration
 467          * descriptors, it will store them here, should you wish to parse them. */
 468         const unsigned char *extra;
 469
 470         /** Length of the extra descriptors, in bytes. */
 471         int extra_length;
 472 };
 473
 474 /** \ingroup asyncio
 475  * Setup packet for control transfers. */
 476 struct libusb_control_setup {
 477         /** Request type. Bits 0:4 determine recipient, see
 478          * \ref libusb_request_recipient. Bits 5:6 determine type, see
 479          * \ref libusb_request_type. Bit 7 determines data transfer direction, see
 480          * \ref libusb_endpoint_direction.
 481          */
 482         uint8_t  bmRequestType;
 483
 484         /** Request. If the type bits of bmRequestType are equal to
 485          * \ref libusb_request_type::LIBUSB_REQUEST_TYPE_STANDARD
 486          * "LIBUSB_REQUEST_TYPE_STANDARD" then this field refers to
 487          * \ref libusb_standard_request. For other cases, use of this field is
 488          * application-specific. */
 489         uint8_t  bRequest;
 490
 491         /** Value. Varies according to request */
 492         uint16_t wValue;
 493
 494         /** Index. Varies according to request, typically used to pass an index
 495          * or offset */
 496         uint16_t wIndex;
 497
 498         /** Number of bytes to transfer */
 499         uint16_t wLength;
 500 } __attribute__((packed));
 501
 502 #define LIBUSB_CONTROL_SETUP_SIZE (sizeof(struct libusb_control_setup))
 503
 504 /* libusb */
 505
 506 struct libusb_device;
 507 struct libusb_device_handle;
 508
 509 /** \ingroup dev
 510  * Structure representing a USB device detected on the system. This is an
 511  * opaque type for which you are only ever provided with a pointer, usually
 512  * originating from libusb_get_device_list().
 513  *
 514  * Certain operations can be performed on a device, but in order to do any
 515  * I/O you will have to first obtain a device handle using libusb_open().
 516  *
 517  * Devices are reference counted with libusb_device_ref() and
 518  * libusb_device_unref(), and are freed when the reference count reaches 0.
 519  * New devices presented by libusb_get_device_list() have a reference count of
 520  * 1, and libusb_free_device_list() can optionally decrease the reference count
 521  * on all devices in the list. libusb_open() adds another reference which is
 522  * later destroyed by libusb_close().
 523  */
 524 typedef struct libusb_device libusb_device;
 525
 526
 527 /** \ingroup dev
 528  * Structure representing a handle on a USB device. This is an opaque type for
 529  * which you are only ever provided with a pointer, usually originating from
 530  * libusb_open().
 531  *
 532  * A device handle is used to perform I/O and other operations. When finished
 533  * with a device handle, you should call libusb_close().
 534  */
 535 typedef struct libusb_device_handle libusb_device_handle;
 536
 537 enum libusb_error {
 538         LIBUSB_SUCCESS = 0,
 539         LIBUSB_ERROR_IO = -1,
 540         LIBUSB_ERROR_INVALID_PARAM = -2,
 541         LIBUSB_ERROR_ACCESS = -3,
 542         LIBUSB_ERROR_NOT_FOUND = -4,
 543         LIBUSB_ERROR_BUSY = -5,
 544         LIBUSB_ERROR_TIMEOUT = -6,
 545         LIBUSB_ERROR_PIPE = -7,
 546         LIBUSB_ERROR_NO_MEM = -8,
 547         LIBUSB_ERROR_NOT_SUPPORTED = -9,
 548         LIBUSB_ERROR_OTHER = -10,
 549 };
 550
 551 /** \ingroup asyncio
 552  * Transfer status codes */
 553 enum libusb_transfer_status {
 554         /** Transfer completed without error. Note that this does not indicate
 555          * that the entire amount of requested data was transferred. */
 556         LIBUSB_TRANSFER_COMPLETED,
 557
 558         /** Transfer failed */
 559         LIBUSB_TRANSFER_ERROR,
 560
 561         /** Transfer timed out */
 562         LIBUSB_TRANSFER_TIMED_OUT,
 563
 564         /** Transfer was cancelled */
 565         LIBUSB_TRANSFER_CANCELLED,
 566
 567         /** For bulk/interrupt endpoints: halt condition detected (endpoint
 568          * stalled). For control endpoints: control request not supported. */
 569         LIBUSB_TRANSFER_STALL,
 570 };
 571
 572 /** \ingroup asyncio
 573  * libusb_transfer.flags values */
 574 enum libusb_transfer_flags {
 575         /** Report short frames as errors */
 576         LIBUSB_TRANSFER_SHORT_NOT_OK = 1<<0,
 577
 578         /** Automatically free() transfer buffer during libusb_free_transfer() */
 579         LIBUSB_TRANSFER_FREE_BUFFER = 1<<1,
 580
 581         /** Automatically call libusb_free_transfer() after callback returns.
 582          * If this flag is set, it is illegal to call libusb_free_transfer()
 583          * from your transfer callback, as this will result in a double-free
 584          * when this flag is acted upon. */
 585         LIBUSB_TRANSFER_FREE_TRANSFER = 1<<2,
 586 };
 587
 588 /** \ingroup asyncio
 589  * Isochronous packet descriptor. */
 590 struct libusb_iso_packet_descriptor {
 591         /** Length of data to request in this packet */
 592         unsigned int length;
 593
 594         /** Amount of data that was actually transferred */
 595         unsigned int actual_length;
 596
 597         /** Status code for this packet */
 598         enum libusb_transfer_status status;
 599 };
 600
 601 struct libusb_transfer;
 602
 603 typedef void (*libusb_transfer_cb_fn)(struct libusb_transfer *transfer);
 604
 605 /** \ingroup asyncio
 606  * The generic USB transfer structure.
 607  */
 608 struct libusb_transfer {
 609         /** Handle of the device that this transfer will be submitted to */
 610         libusb_device_handle *dev_handle;
 611
 612         /** A bitwise OR combination of \ref libusb_transfer_flags. */
 613         uint8_t flags;
 614
 615         /** Address of the endpoint where this transfer will be sent. */
 616         unsigned char endpoint;
 617
 618         /** Type of the endpoint from \ref libusb_transfer_type */
 619         unsigned char type;
 620
 621         /** Timeout for this transfer in millseconds. A value of 0 indicates no
 622          * timeout. */
 623         unsigned int timeout;
 624
 625         /** The status of the transfer. Read-only, and only for use within
 626          * transfer callback function.
 627          *
 628          * If this is an isochronous transfer, this field may read COMPLETED even
 629          * if there were errors in the frames. Use the
 630          * \ref libusb_iso_packet_descriptor::status "status" field in each packet
 631          * to determine if errors occurred. */
 632         enum libusb_transfer_status status;
 633
 634         /** Length of the data buffer */
 635         int length;
 636
 637         /** Actual length of data that was transferred. Read-only, and only for
 638          * use within transfer callback function. Not valid for isochronous
 639          * endpoint transfers. */
 640         int actual_length;
 641
 642         /** Callback function. This will be invoked when the transfer completes,
 643          * fails, or is cancelled. */
 644         libusb_transfer_cb_fn callback;
 645
 646         /** User context data to pass to the callback function. */
 647         void *user_data;
 648
 649         /** Data buffer */
 650         unsigned char *buffer;
 651
 652         /** Number of isochronous packets. Only used for I/O with isochronous
 653          * endpoints. */
 654         int num_iso_packets;
 655
 656         /** Isochronous packet descriptors, for isochronous transfers only. */
 657         struct libusb_iso_packet_descriptor iso_packet_desc[0];
 658 };
 659
 660 int libusb_init(void);
 661 void libusb_exit(void);
 662
 663 ssize_t libusb_get_device_list(libusb_device ***list);
 664 void libusb_free_device_list(libusb_device **list, int unref_devices);
 665 libusb_device *libusb_ref_device(libusb_device *dev);
 666 void libusb_unref_device(libusb_device *dev);
 667
 668 int libusb_get_device_descriptor(libusb_device *dev,
 669         struct libusb_device_descriptor *desc);
 670 struct libusb_config_descriptor *libusb_get_active_config_descriptor(
 671         libusb_device *dev);
 672 struct libusb_config_descriptor *libusb_get_config_descriptor(
 673         libusb_device *dev, uint8_t config);
 674 void libusb_free_config_descriptor(struct libusb_config_descriptor *config);
 675 uint8_t libusb_get_bus_number(libusb_device *dev);
 676 uint8_t libusb_get_device_address(libusb_device *dev);
 677 int libusb_get_max_packet_size(libusb_device *dev, unsigned char endpoint);
 678
 679 libusb_device_handle *libusb_open(libusb_device *dev);
 680 void libusb_close(libusb_device_handle *dev_handle);
 681 libusb_device *libusb_get_device(libusb_device_handle *dev_handle);
 682
 683 int libusb_set_configuration(libusb_device_handle *dev, int configuration);
 684 int libusb_claim_interface(libusb_device_handle *dev, int iface);
 685 int libusb_release_interface(libusb_device_handle *dev, int iface);
 686
 687 libusb_device_handle *libusb_open_device_with_vid_pid(uint16_t vendor_id,
 688         uint16_t product_id);
 689
 690 int libusb_set_interface_alt_setting(libusb_device_handle *dev,
 691         int interface_number, int alternate_setting);
 692 int libusb_clear_halt(libusb_device_handle *dev, unsigned char endpoint);
 693 int libusb_reset_device(libusb_device_handle *dev);
 694
 695 int libusb_kernel_driver_active(libusb_device_handle *dev, int interface);
 696 int libusb_detach_kernel_driver(libusb_device_handle *dev, int interface);
 697
 698 /* async I/O */
 699
 700 /** \ingroup asyncio
 701  * Get the data section of a control transfer. This convenience function is here
 702  * to remind you that the data does not start until 8 bytes into the actual
 703  * buffer, as the setup packet comes first.
 704  *
 705  * Calling this function only makes sense from a transfer callback function,
 706  * or situations where you have already allocated a suitably sized buffer at
 707  * transfer->buffer.
 708  *
 709  * \param transfer a transfer
 710  * \returns pointer to the first byte of the data section
 711  */
 712 static inline unsigned char *libusb_control_transfer_get_data(
 713         struct libusb_transfer *transfer)
 714 {
 715         return transfer->buffer + LIBUSB_CONTROL_SETUP_SIZE;
 716 }
 717
 718 /** \ingroup asyncio
 719  * Get the control setup packet of a control transfer. This convenience
 720  * function is here to remind you that the control setup occupies the first
 721  * 8 bytes of the transfer data buffer.
 722  *
 723  * Calling this function only makes sense from a transfer callback function,
 724  * or situations where you have already allocated a suitably sized buffer at
 725  * transfer->buffer.
 726  *
 727  * \param transfer a transfer
 728  * \returns a casted pointer to the start of the transfer data buffer
 729  */
 730 static inline struct libusb_control_setup *libusb_control_transfer_get_setup(
 731         struct libusb_transfer *transfer)
 732 {
 733         return (struct libusb_control_setup *) transfer->buffer;
 734 }
 735
 736 /** \ingroup asyncio
 737  * Helper function to populate the setup packet (first 8 bytes of the data
 738  * buffer) for a control transfer.
 739  *
 740  * \param buffer buffer to output the setup packet into
 741  * \param bmRequestType see the
 742  * \ref libusb_control_setup::bmRequestType "bmRequestType" field of
 743  * \ref libusb_control_setup
 744  * \param bRequest see the
 745  * \ref libusb_control_setup::bRequest "bRequest" field of
 746  * \ref libusb_control_setup
 747  * \param wValue see the
 748  * \ref libusb_control_setup::wValue "wValue" field of
 749  * \ref libusb_control_setup
 750  * \param wIndex see the
 751  * \ref libusb_control_setup::wIndex "wIndex" field of
 752  * \ref libusb_control_setup
 753  * \param wLength see the
 754  * \ref libusb_control_setup::wLength "wLength" field of
 755  * \ref libusb_control_setup
 756  */
 757 static inline void libusb_fill_control_setup(unsigned char *buffer,
 758         uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
 759         uint16_t wLength)
 760 {
 761         struct libusb_control_setup *setup = (struct libusb_control_setup *) buffer;
 762         setup->bmRequestType = bmRequestType;
 763         setup->bRequest = bRequest;
 764         setup->wValue = wValue;
 765         setup->wIndex = wIndex;
 766         setup->wLength = wLength;
 767 }
 768
 769 struct libusb_transfer *libusb_alloc_transfer(int iso_packets);
 770 int libusb_submit_transfer(struct libusb_transfer *transfer);
 771 int libusb_cancel_transfer(struct libusb_transfer *transfer);
 772 void libusb_free_transfer(struct libusb_transfer *transfer);
 773
 774 /** \ingroup asyncio
 775  * Helper function to populate the required \ref libusb_transfer fields
 776  * for a control transfer.
 777  *
 778  * If you pass a transfer buffer to this function, the first 8 bytes will
 779  * be interpreted as a control setup packet, and the wLength field will be
 780  * used to automatically populate the \ref libusb_transfer::length "length"
 781  * field of the transfer. Therefore the recommended approach is:
 782  * -# Allocate a suitably sized data buffer (including space for control setup)
 783  * -# Call libusb_fill_control_setup()
 784  * -# If this is a host-to-device transfer with a data stage, put the data
 785  *    in place after the setup packet
 786  * -# Call this function
 787  * -# Call libusb_submit_transfer()
 788  *
 789  * It is also legal to pass a NULL buffer to this function, in which case this
 790  * function will not attempt to populate the length field. Remember that you
 791  * must populate the buffer and length fields later.
 792  *
 793  * \param transfer the transfer to populate
 794  * \param dev_handle handle of the device that will handle the transfer
 795  * \param buffer data buffer. If provided, this function will interpret the
 796  * first 8 bytes as a setup packet and infer the transfer length from that.
 797  * \param callback callback function to be invoked on transfer completion
 798  * \param user_data user data to pass to callback function
 799  * \param timeout timeout for the transfer in milliseconds
 800  */
 801 static inline void libusb_fill_control_transfer(
 802         struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
 803         unsigned char *buffer, libusb_transfer_cb_fn callback, void *user_data,
 804         unsigned int timeout)
 805 {
 806         struct libusb_control_setup *setup = (struct libusb_control_setup *) buffer;
 807         transfer->dev_handle = dev_handle;
 808         transfer->endpoint = 0;
 809         transfer->type = LIBUSB_TRANSFER_TYPE_CONTROL;
 810         transfer->timeout = timeout;
 811         transfer->buffer = buffer;
 812         if (setup)
 813                 transfer->length = LIBUSB_CONTROL_SETUP_SIZE + setup->wLength;
 814         transfer->user_data = user_data;
 815         transfer->callback = callback;
 816 }
 817
 818 /** \ingroup asyncio
 819  * Helper function to populate the required \ref libusb_transfer fields
 820  * for a bulk transfer.
 821  *
 822  * \param transfer the transfer to populate
 823  * \param dev_handle handle of the device that will handle the transfer
 824  * \param endpoint address of the endpoint where this transfer will be sent
 825  * \param buffer data buffer
 826  * \param length length of data buffer
 827  * \param callback callback function to be invoked on transfer completion
 828  * \param user_data user data to pass to callback function
 829  * \param timeout timeout for the transfer in milliseconds
 830  */
 831 static inline void libusb_fill_bulk_transfer(struct libusb_transfer *transfer,
 832         libusb_device_handle *dev_handle, unsigned char endpoint,
 833         unsigned char *buffer, int length, libusb_transfer_cb_fn callback,
 834         void *user_data, unsigned int timeout)
 835 {
 836         transfer->dev_handle = dev_handle;
 837         transfer->endpoint = endpoint;
 838         transfer->type = LIBUSB_TRANSFER_TYPE_BULK;
 839         transfer->timeout = timeout;
 840         transfer->buffer = buffer;
 841         transfer->length = length;
 842         transfer->user_data = user_data;
 843         transfer->callback = callback;
 844 }
 845
 846 /** \ingroup asyncio
 847  * Helper function to populate the required \ref libusb_transfer fields
 848  * for an interrupt transfer.
 849  *
 850  * \param transfer the transfer to populate
 851  * \param dev_handle handle of the device that will handle the transfer
 852  * \param endpoint address of the endpoint where this transfer will be sent
 853  * \param buffer data buffer
 854  * \param length length of data buffer
 855  * \param callback callback function to be invoked on transfer completion
 856  * \param user_data user data to pass to callback function
 857  * \param timeout timeout for the transfer in milliseconds
 858  */
 859 static inline void libusb_fill_interrupt_transfer(
 860         struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
 861         unsigned char endpoint, unsigned char *buffer, int length,
 862         libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
 863 {
 864         transfer->dev_handle = dev_handle;
 865         transfer->endpoint = endpoint;
 866         transfer->type = LIBUSB_TRANSFER_TYPE_INTERRUPT;
 867         transfer->timeout = timeout;
 868         transfer->buffer = buffer;
 869         transfer->length = length;
 870         transfer->user_data = user_data;
 871         transfer->callback = callback;
 872 }
 873
 874 /** \ingroup asyncio
 875  * Helper function to populate the required \ref libusb_transfer fields
 876  * for an isochronous transfer.
 877  *
 878  * \param transfer the transfer to populate
 879  * \param dev_handle handle of the device that will handle the transfer
 880  * \param endpoint address of the endpoint where this transfer will be sent
 881  * \param buffer data buffer
 882  * \param length length of data buffer
 883  * \param num_iso_packets the number of isochronous packets
 884  * \param callback callback function to be invoked on transfer completion
 885  * \param user_data user data to pass to callback function
 886  * \param timeout timeout for the transfer in milliseconds
 887  */
 888 static inline void libusb_fill_iso_transfer(struct libusb_transfer *transfer,
 889         libusb_device_handle *dev_handle, unsigned char endpoint,
 890         unsigned char *buffer, int length, int num_iso_packets,
 891         libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
 892 {
 893         transfer->dev_handle = dev_handle;
 894         transfer->endpoint = endpoint;
 895         transfer->type = LIBUSB_TRANSFER_TYPE_ISOCHRONOUS;
 896         transfer->timeout = timeout;
 897         transfer->buffer = buffer;
 898         transfer->length = length;
 899         transfer->num_iso_packets = num_iso_packets;
 900         transfer->user_data = user_data;
 901         transfer->callback = callback;
 902 }
 903
 904 /** \ingroup asyncio
 905  * Convenience function to set the length of all packets in an isochronous
 906  * transfer, based on the num_iso_packets field in the transfer structure.
 907  *
 908  * \param transfer a transfer
 909  * \param length the length to set in each isochronous packet descriptor
 910  * \see libusb_get_max_packet_size()
 911  */
 912 static inline void libusb_set_iso_packet_lengths(
 913         struct libusb_transfer *transfer, unsigned int length)
 914 {
 915         int i;
 916         for (i = 0; i < transfer->num_iso_packets; i++)
 917                 transfer->iso_packet_desc[i].length = length;
 918 }
 919
 920 /** \ingroup asyncio
 921  * Convenience function to locate the position of an isochronous packet
 922  * within the buffer of an isochronous transfer.
 923  *
 924  * This is a thorough function which loops through all preceding packets,
 925  * accumulating their lengths to find the position of the specified packet.
 926  * Typically you will assign equal lengths to each packet in the transfer,
 927  * and hence the above method is sub-optimal. You may wish to use
 928  * libusb_get_iso_packet_buffer_simple() instead.
 929  *
 930  * \param transfer a transfer
 931  * \param packet the packet to return the address of
 932  * \returns the base address of the packet buffer inside the transfer buffer,
 933  * or NULL if the packet does not exist.
 934  * \see libusb_get_iso_packet_buffer_simple()
 935  */
 936 static inline unsigned char *libusb_get_iso_packet_buffer(
 937         struct libusb_transfer *transfer, unsigned int packet)
 938 {
 939         int i;
 940         size_t offset = 0;
 941
 942         if (packet >= transfer->num_iso_packets)
 943                 return NULL;
 944
 945         for (i = 0; i < packet; i++)
 946                 offset += transfer->iso_packet_desc[i].length;
 947
 948         return transfer->buffer + offset;
 949 }
 950
 951 /** \ingroup asyncio
 952  * Convenience function to locate the position of an isochronous packet
 953  * within the buffer of an isochronous transfer, for transfers where each
 954  * packet is of identical size.
 955  *
 956  * This function relies on the assumption that every packet within the transfer
 957  * is of identical size to the first packet. Calculating the location of
 958  * the packet buffer is then just a simple calculation:
 959  * <tt>buffer + (packet_size * packet)</tt>
 960  *
 961  * Do not use this function on transfers other than those that have identical
 962  * packet lengths for each packet.
 963  *
 964  * \param transfer a transfer
 965  * \param packet the packet to return the address of
 966  * \returns the base address of the packet buffer inside the transfer buffer,
 967  * or NULL if the packet does not exist.
 968  * \see libusb_get_iso_packet_buffer()
 969  */
 970 static inline unsigned char *libusb_get_iso_packet_buffer_simple(
 971         struct libusb_transfer *transfer, unsigned int packet)
 972 {
 973         if (packet >= transfer->num_iso_packets)
 974                 return NULL;
 975
 976         return transfer->buffer + (transfer->iso_packet_desc[0].length * packet);
 977 }
 978
 979 /* sync I/O */
 980
 981 int libusb_control_transfer(libusb_device_handle *dev_handle,
 982         uint8_t request_type, uint8_t request, uint16_t value, uint16_t index,
 983         unsigned char *data, uint16_t length, unsigned int timeout);
 984
 985 int libusb_bulk_transfer(libusb_device_handle *dev_handle,
 986         unsigned char endpoint, unsigned char *data, int length,
 987         int *actual_length, unsigned int timeout);
 988
 989 int libusb_interrupt_transfer(libusb_device_handle *dev_handle,
 990         unsigned char endpoint, unsigned char *data, int length,
 991         int *actual_length, unsigned int timeout);
 992
 993 /** \ingroup desc
 994  * Retrieve a descriptor from the default control pipe.
 995  * This is a convenience function which formulates the appropriate control
 996  * message to retrieve the descriptor.
 997  *
 998  * \param dev a device handle
 999  * \param desc_type the descriptor type, see \ref libusb_descriptor_type
1000  * \param desc_index the index of the descriptor to retrieve
1001  * \param data output buffer for descriptor
1002  * \param length size of data buffer
1003  * \returns number of bytes returned in data, or LIBUSB_ERROR code on failure
1004  */
1005 static inline int libusb_get_descriptor(libusb_device_handle *dev,
1006         uint8_t desc_type, uint8_t desc_index, unsigned char *data, int length)
1007 {
1008         return libusb_control_transfer(dev, LIBUSB_ENDPOINT_IN,
1009                 LIBUSB_REQUEST_GET_DESCRIPTOR, (desc_type << 8) | desc_index, 0, data,
1010                 length, 1000);
1011 }
1012
1013 /** \ingroup desc
1014  * Retrieve a descriptor from a device.
1015  * This is a convenience function which formulates the appropriate control
1016  * message to retrieve the descriptor. The string returned is Unicode, as
1017  * detailed in the USB specifications.
1018  *
1019  * \param dev a device handle
1020  * \param desc_index the index of the descriptor to retrieve
1021  * \param langid the language ID for the string descriptor
1022  * \param data output buffer for descriptor
1023  * \param length size of data buffer
1024  * \returns number of bytes returned in data, or LIBUSB_ERROR code on failure
1025  * \see libusb_get_string_descriptor_ascii()
1026  */
1027 static inline int libusb_get_string_descriptor(libusb_device_handle *dev,
1028         uint8_t desc_index, uint16_t langid, unsigned char *data, int length)
1029 {
1030         return libusb_control_transfer(dev, LIBUSB_ENDPOINT_IN,
1031                 LIBUSB_REQUEST_GET_DESCRIPTOR, (LIBUSB_DT_STRING << 8) | desc_index,
1032                 langid, data, length, 1000);
1033 }
1034
1035 int libusb_get_string_descriptor_ascii(libusb_device_handle *dev,
1036         uint8_t index, unsigned char *data, int length);
1037
1038 /* polling and timeouts */
1039
1040 /** \ingroup poll
1041  * File descriptor for polling
1042  */
1043 struct libusb_pollfd {
1044         /** Numeric file descriptor */
1045         int fd;
1046
1047         /** Event flags to poll for from <poll.h>. POLLIN indicates that you
1048          * should monitor this file descriptor for becoming ready to read from,
1049          * and POLLOUT indicates that you should monitor this file descriptor for
1050          * nonblocking write readiness. */
1051         short events;
1052 };
1053
1054 int libusb_handle_events_timeout(struct timeval *tv);
1055 int libusb_handle_events(void);
1056 int libusb_get_next_timeout(struct timeval *tv);
1057 const struct libusb_pollfd **libusb_get_pollfds(void);
1058
1059 /** \ingroup poll
1060  * Callback function, invoked when a new file descriptor should be added
1061  * to the set of file descriptors monitored for events.
1062  * \param fd the new file descriptor
1063  * \param events events to monitor for, see \ref libusb_pollfd for a
1064  * description
1065  * \see libusb_set_pollfd_notifiers()
1066  */
1067 typedef void (*libusb_pollfd_added_cb)(int fd, short events);
1068
1069 /** \ingroup poll
1070  * Callback function, invoked when a file descriptor should be removed from
1071  * the set of file descriptors being monitored for events. After returning
1072  * from this callback, do not use that file descriptor again.
1073  * \param fd the file descriptor to stop monitoring
1074  * \see libusb_set_pollfd_notifiers()
1075  */
1076 typedef void (*libusb_pollfd_removed_cb)(int fd);
1077 void libusb_set_pollfd_notifiers(libusb_pollfd_added_cb added_cb,
1078         libusb_pollfd_removed_cb removed_cb);
1079
1080 #ifdef __cplusplus
1081 }
1082 #endif
1083
1084 #endif