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 <time.h>
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 /* standard USB stuff */
  33
  34 /** \ingroup desc
  35  * Device and/or Interface Class codes */
  36 enum libusb_class_code {
  37         /** In the context of a \ref libusb_device_descriptor "device descriptor",
  38          * this bDeviceClass value indicates that each interface specifies its
  39          * own class information and all interfaces operate independently.
  40          */
  41         LIBUSB_CLASS_PER_INTERFACE = 0,
  42
  43         /** Audio class */
  44         LIBUSB_CLASS_AUDIO = 1,
  45
  46         /** Communications class */
  47         LIBUSB_CLASS_COMM = 2,
  48
  49         /** Human Interface Device class */
  50         LIBUSB_CLASS_HID = 3,
  51
  52         /** Printer dclass */
  53         LIBUSB_CLASS_PRINTER = 7,
  54
  55         /** Picture transfer protocol class */
  56         LIBUSB_CLASS_PTP = 6,
  57
  58         /** Mass storage class */
  59         LIBUSB_CLASS_MASS_STORAGE = 8,
  60
  61         /** Hub class */
  62         LIBUSB_CLASS_HUB = 9,
  63
  64         /** Data class */
  65         LIBUSB_CLASS_DATA = 10,
  66
  67         /** Class is vendor-specific */
  68         LIBUSB_CLASS_VENDOR_SPEC = 0xff,
  69 };
  70
  71 /** \ingroup desc
  72  * Descriptor types as defined by the USB specification. */
  73 enum libusb_descriptor_type {
  74         /** Device descriptor. See libusb_device_descriptor. */
  75         LIBUSB_DT_DEVICE = 0x01,
  76
  77         /** Configuration descriptor. See libusb_config_descriptor. */
  78         LIBUSB_DT_CONFIG = 0x02,
  79
  80         /** String descriptor */
  81         LIBUSB_DT_STRING = 0x03,
  82
  83         /** Interface descriptor. See libusb_interface_descriptor. */
  84         LIBUSB_DT_INTERFACE = 0x04,
  85
  86         /** Endpoint descriptor. See libusb_endpoint_descriptor. */
  87         LIBUSB_DT_ENDPOINT = 0x05,
  88
  89         /** HID descriptor */
  90         LIBUSB_DT_HID = 0x21,
  91
  92         /** HID report descriptor */
  93         LIBUSB_DT_REPORT = 0x22,
  94
  95         /** Physical descriptor */
  96         LIBUSB_DT_PHYSICAL = 0x23,
  97
  98         /** Hub descriptor */
  99         LIBUSB_DT_HUB = 0x29,
 100 };
 101
 102 /* Descriptor sizes per descriptor type */
 103 #define LIBUSB_DT_DEVICE_SIZE                   18
 104 #define LIBUSB_DT_CONFIG_SIZE                   9
 105 #define LIBUSB_DT_INTERFACE_SIZE                9
 106 #define LIBUSB_DT_ENDPOINT_SIZE         7
 107 #define LIBUSB_DT_ENDPOINT_AUDIO_SIZE   9       /* Audio extension */
 108 #define LIBUSB_DT_HUB_NONVAR_SIZE               7
 109
 110 #define LIBUSB_ENDPOINT_ADDRESS_MASK    0x0f    /* in bEndpointAddress */
 111 #define LIBUSB_ENDPOINT_DIR_MASK                0x80
 112
 113 /** \ingroup desc
 114  * Endpoint direction. Values for bit 7 of the
 115  * \ref libusb_endpoint_descriptor::bEndpointAddress "endpoint address" scheme.
 116  */
 117 enum libusb_endpoint_direction {
 118         /** In: device-to-host */
 119         LIBUSB_ENDPOINT_IN = 0x80,
 120
 121         /** Out: host-to-device */
 122         LIBUSB_ENDPOINT_OUT = 0x00,
 123 };
 124
 125 /* FIXME: 9.6.6 calls these "transfer types", not endpoint types. */
 126 #define LIBUSB_ENDPOINT_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_endpoint_type {
 133         /** Control endpoint */
 134         LIBUSB_ENDPOINT_TYPE_CONTROL = 0,
 135
 136         /** Isochronous endpoint */
 137         LIBUSB_ENDPOINT_TYPE_ISOCHRONOUS = 1,
 138
 139         /** Bulk endpoint */
 140         LIBUSB_ENDPOINT_TYPE_BULK = 2,
 141
 142         /** Interrupt endpoint */
 143         LIBUSB_ENDPOINT_TYPE_INTERRUPT = 3,
 144 };
 145
 146 /** Standard requests, as defined in table 9-3 of the USB2 specifications */
 147 enum libusb_standard_request {
 148         /** Request status of the specific recipient */
 149         LIBUSB_REQUEST_GET_STATUS = 0x00,
 150
 151         /** Clear or disable a specific feature */
 152         LIBUSB_REQUEST_CLEAR_FEATURE = 0x01,
 153
 154         /* 0x02 is reserved */
 155
 156         /** Set or enable a specific feature */
 157         LIBUSB_REQUEST_SET_FEATURE = 0x03,
 158
 159         /* 0x04 is reserved */
 160
 161         /** Set device address for all future accesses */
 162         LIBUSB_REQUEST_SET_ADDRESS = 0x05,
 163
 164         /** Get the specified descriptor */
 165         LIBUSB_REQUEST_GET_DESCRIPTOR = 0x06,
 166
 167         /** Used to update existing descriptors or add new descriptors */
 168         LIBUSB_REQUEST_SET_DESCRIPTOR = 0x07,
 169
 170         /** Get the current device configuration value */
 171         LIBUSB_REQUEST_GET_CONFIGURATION = 0x08,
 172
 173         /** Set device configuration */
 174         LIBUSB_REQUEST_SET_CONFIGURATION = 0x09,
 175
 176         /** Return the selected alternate setting for the specified interface */
 177         LIBUSB_REQUEST_GET_INTERFACE = 0x0A,
 178
 179         /** Select an alternate interface for the specified interface */
 180         LIBUSB_REQUEST_SET_INTERFACE = 0x0B,
 181
 182         /** Set then report an endpoint's synchronization frame */
 183         LIBUSB_REQUEST_SYNCH_FRAME = 0x0C,
 184 };
 185
 186 /** \ingroup misc
 187  * Request type bits of the
 188  * \ref libusb_control_setup::bRequestType "bRequestType" field in control
 189  * transfers. */
 190 enum libusb_request_type {
 191         /** Standard */
 192         LIBUSB_REQUEST_TYPE_STANDARD = (0x00 << 5),
 193
 194         /** Class */
 195         LIBUSB_REQUEST_TYPE_CLASS = (0x01 << 5),
 196
 197         /** Vendor */
 198         LIBUSB_REQUEST_TYPE_VENDOR = (0x02 << 5),
 199
 200         /** Reserved */
 201         LIBUSB_REQUEST_TYPE_RESERVED = (0x03 << 5),
 202 };
 203
 204 /** \ingroup misc
 205  * Recipient bits of the
 206  * \ref libusb_control_setup::bRequestType "bRequestType" field in control
 207  * transfers. Values 4 through 31 are reserved. */
 208 enum libusb_request_recipient {
 209         /** Device */
 210         LIBUSB_RECIPIENT_DEVICE = 0x00,
 211
 212         /** Interface */
 213         LIBUSB_RECIPIENT_INTERFACE = 0x01,
 214
 215         /** Endpoint */
 216         LIBUSB_RECIPIENT_ENDPOINT = 0x02,
 217
 218         /** Other */
 219         LIBUSB_RECIPIENT_OTHER = 0x03,
 220 };
 221
 222 #define LIBUSB_ISO_SYNC_TYPE_MASK               0x0C
 223
 224 /** \ingroup desc
 225  * Synchronization type for isochronous endpoints. Values for bits 2:3 of the
 226  * \ref libusb_endpoint_descriptor::bmAttributes "bmAttributes" field in
 227  * libusb_endpoint_descriptor.
 228  */
 229 enum libusb_iso_sync_type {
 230         /** No synchronization */
 231         LIBUSB_ISO_SYNC_TYPE_NONE = 0,
 232
 233         /** Asynchronous */
 234         LIBUSB_ISO_SYNC_TYPE_ASYNC = 1,
 235
 236         /** Adaptive */
 237         LIBUSB_ISO_SYNC_TYPE_ADAPTIVE = 2,
 238
 239         /** Synchronous */
 240         LIBUSB_ISO_SYNC_TYPE_SYNC = 3,
 241 };
 242
 243 #define LIBUSB_ISO_USAGE_TYPE_MASK 0x30
 244
 245 /** \ingroup desc
 246  * Usage type for isochronous endpoints. Values for bits 4:5 of the
 247  * \ref libusb_endpoint_descriptor::bmAttributes "bmAttributes" field in
 248  * libusb_endpoint_descriptor.
 249  */
 250 enum libusb_iso_usage_type {
 251         /** Data endpoint */
 252         LIBUSB_ISO_USAGE_TYPE_DATA = 0,
 253
 254         /** Feedback endpoint */
 255         LIBUSB_ISO_USAGE_TYPE_FEEDBACK = 1,
 256
 257         /** Implicit feedback Data endpoint */
 258         LIBUSB_ISO_USAGE_TYPE_IMPLICIT = 2,
 259 };
 260
 261 /** \ingroup desc
 262  * A structure representing the standard USB device descriptor. This
 263  * descriptor is documented in section 9.6.1 of the USB 2.0 specification.
 264  * All multiple-byte fields are represented in host-endian format.
 265  */
 266 struct libusb_device_descriptor {
 267         /** Size of this descriptor (in bytes) */
 268         uint8_t  bLength;
 269
 270         /** Descriptor type. Will have value
 271          * \ref libusb_descriptor_type::LIBUSB_DT_DEVICE LIBUSB_DT_DEVICE in this
 272          * context. */
 273         uint8_t  bDescriptorType;
 274
 275         /** USB specification release number in binary-coded decimal. A value of
 276          * 0x0200 indicates USB 2.0, 0x0110 indicates USB 1.1, etc. */
 277         uint16_t bcdUSB;
 278
 279         /** USB-IF class code for the device. See \ref libusb_class_code. */
 280         uint8_t  bDeviceClass;
 281
 282         /** USB-IF subclass code for the device, qualified by the bDeviceClass
 283          * value */
 284         uint8_t  bDeviceSubClass;
 285
 286         /** USB-IF protocol code for the device, qualified by the bDeviceClass and
 287          * bDeviceSubClass values */
 288         uint8_t  bDeviceProtocol;
 289
 290         /** Maximum packet size for endpoint 0 */
 291         uint8_t  bMaxPacketSize0;
 292
 293         /** USB-IF vendor ID */
 294         uint16_t idVendor;
 295
 296         /** USB-IF product ID */
 297         uint16_t idProduct;
 298
 299         /** Device release number in binary-coded decimal */
 300         uint16_t bcdDevice;
 301
 302         /** Index of string descriptor describing manufacturer */
 303         uint8_t  iManufacturer;
 304
 305         /** Index of string descriptor describing product */
 306         uint8_t  iProduct;
 307
 308         /** Index of string descriptor containing device serial number */
 309         uint8_t  iSerialNumber;
 310
 311         /** Number of possible configurations */
 312         uint8_t  bNumConfigurations;
 313 };
 314
 315 /** \ingroup desc
 316  * A structure representing the standard USB endpoint descriptor. This
 317  * descriptor is documented in section 9.6.3 of the USB 2.0 specification.
 318  * All multiple-byte fields are represented in host-endian format.
 319  */
 320 struct libusb_endpoint_descriptor {
 321         /** Size of this descriptor (in bytes) */
 322         uint8_t  bLength;
 323
 324         /** Descriptor type. Will have value
 325          * \ref libusb_descriptor_type::LIBUSB_DT_ENDPOINT LIBUSB_DT_ENDPOINT in
 326          * this context. */
 327         uint8_t  bDescriptorType;
 328
 329         /** The address of the endpoint described by this descriptor. Bits 0:3 are
 330          * the endpoint number. Bits 4:6 are reserved. Bit 7 indicates direction,
 331          * see \ref libusb_endpoint_direction.
 332          */
 333         uint8_t  bEndpointAddress;
 334
 335         /** Attributes which apply to the endpoint when it is configured using
 336          * the bConfigurationValue. Bits 0:1 determine the transfer type and
 337          * correspond to \ref libusb_endpoint_type. Bits 2:3 are only used for
 338          * isochronous endpoints and correspond to \ref libusb_iso_sync_type.
 339          * Bits 4:5 are also only used for isochronous endpoints and correspond to
 340          * \ref libusb_iso_usage_type. Bits 6:7 are reserved.
 341          */
 342         uint8_t  bmAttributes;
 343
 344         /** Maximum packet size this endpoint is capable of sending/receiving. */
 345         uint16_t wMaxPacketSize;
 346
 347         /** Interval for polling endpoint for data transfers. */
 348         uint8_t  bInterval;
 349
 350         uint8_t  bRefresh;
 351         uint8_t  bSynchAddress;
 352
 353         unsigned char *extra;   /* Extra descriptors */
 354         int extralen;
 355 };
 356
 357 /** \ingroup desc
 358  * A structure representing the standard USB interface descriptor. This
 359  * descriptor is documented in section 9.6.5 of the USB 2.0 specification.
 360  * All multiple-byte fields are represented in host-endian format.
 361  */
 362 struct libusb_interface_descriptor {
 363         /** Size of this descriptor (in bytes) */
 364         uint8_t  bLength;
 365
 366         /** Descriptor type. Will have value
 367          * \ref libusb_descriptor_type::LIBUSB_DT_INTERFACE LIBUSB_DT_INTERFACE
 368          * in this context. */
 369         uint8_t  bDescriptorType;
 370
 371         /** Number of this interface */
 372         uint8_t  bInterfaceNumber;
 373
 374         /** Value used to select this alternate setting for this interface */
 375         uint8_t  bAlternateSetting;
 376
 377         /** Number of endpoints used by this interface (excluding the control
 378          * endpoint). */
 379         uint8_t  bNumEndpoints;
 380
 381         /** USB-IF class code for this interface. See \ref libusb_class_code. */
 382         uint8_t  bInterfaceClass;
 383
 384         /** USB-IF subclass code for this interface, qualified by the
 385          * bInterfaceClass value */
 386         uint8_t  bInterfaceSubClass;
 387
 388         /** USB-IF protocol code for this interface, qualified by the
 389          * bInterfaceClass and bInterfaceSubClass values */
 390         uint8_t  bInterfaceProtocol;
 391
 392         /** Index of string descriptor describing this interface */
 393         uint8_t  iInterface;
 394
 395         /** Array of endpoint descriptors. This length of this array is determined
 396          * by the bNumEndpoints field. */
 397         struct libusb_endpoint_descriptor *endpoint;
 398
 399         unsigned char *extra;   /* Extra descriptors */
 400         int extralen;
 401 };
 402
 403 /** \ingroup desc
 404  * A collection of alternate settings for a particular USB interface.
 405  */
 406 struct libusb_interface {
 407         /** Array of interface descriptors. The length of this array is determined
 408          * by the num_altsetting field. */
 409         struct libusb_interface_descriptor *altsetting;
 410
 411         /** The number of alternate settings that belong to this interface */
 412         int num_altsetting;
 413 };
 414
 415 /** \ingroup desc
 416  * A structure representing the standard USB configuration descriptor. This
 417  * descriptor is documented in section 9.6.3 of the USB 2.0 specification.
 418  * All multiple-byte fields are represented in host-endian format.
 419  */
 420 struct libusb_config_descriptor {
 421         /** Size of this descriptor (in bytes) */
 422         uint8_t  bLength;
 423
 424         /** Descriptor type. Will have value
 425          * \ref libusb_descriptor_type::LIBUSB_DT_CONFIG LIBUSB_DT_CONFIG
 426          * in this context. */
 427         uint8_t  bDescriptorType;
 428
 429         /** Total length of data returned for this configuration */
 430         uint16_t wTotalLength;
 431
 432         /** Number of interfaces supported by this configuration */
 433         uint8_t  bNumInterfaces;
 434
 435         /** Identifier value for this configuration */
 436         uint8_t  bConfigurationValue;
 437
 438         /** Index of string descriptor describing this configuration */
 439         uint8_t  iConfiguration;
 440
 441         /** Configuration characteristics */
 442         uint8_t  bmAttributes;
 443
 444         /** Maximum power consumption of the USB device from this bus in this
 445          * configuration when the device is fully opreation. Expressed in units
 446          * of 2 mA. */
 447         uint8_t  MaxPower;
 448
 449         /** Array of interfaces supported by this configuration. The length of
 450          * this array is determined by the bNumInterfaces field. */
 451         struct libusb_interface *interface;
 452
 453         unsigned char *extra;   /* Extra descriptors */
 454         int extralen;
 455 };
 456
 457 /** \ingroup asyncio
 458  * Setup packet for control transfers. */
 459 struct libusb_control_setup {
 460         /** Request type. Bits 0:4 determine recipient, see
 461          * \ref libusb_request_recipient. Bits 5:6 determine type, see
 462          * \ref libusb_request_type. Bit 7 determines data transfer direction, see
 463          * \ref libusb_endpoint_direction.
 464          */
 465         uint8_t  bRequestType;
 466
 467         /** Request. If the type bits of bRequestType are equal to
 468          * \ref libusb_request_type::LIBUSB_REQUEST_TYPE_STANDARD
 469          * "LIBUSB_REQUEST_TYPE_STANDARD" then this field refers to
 470          * \ref libusb_standard_request. For other cases, use of this field is
 471          * application-specific. */
 472         uint8_t  bRequest;
 473
 474         /** Value. Varies according to request */
 475         uint16_t wValue;
 476
 477         /** Index. Varies according to request, typically used to pass an index
 478          * or offset */
 479         uint16_t wIndex;
 480
 481         /** Number of bytes to transfer */
 482         uint16_t wLength;
 483 } __attribute__((packed));
 484
 485 #define LIBUSB_CONTROL_SETUP_SIZE (sizeof(struct libusb_control_setup))
 486
 487 /* libusb */
 488
 489 struct libusb_device;
 490 typedef struct libusb_device libusb_device;
 491
 492 struct libusb_device_handle;
 493 typedef struct libusb_device_handle libusb_device_handle;
 494
 495 /** \ingroup asyncio
 496  * Transfer status codes */
 497 enum libusb_transfer_status {
 498         /* FIXME: make this internal */
 499         LIBUSB_TRANSFER_SILENT_COMPLETION = 0,
 500
 501         /** Transfer completed without error. Note that this does not indicate
 502          * that the entire amount of requested data was transferred. */
 503         LIBUSB_TRANSFER_COMPLETED,
 504
 505         /** Transfer failed */
 506         LIBUSB_TRANSFER_ERROR,
 507
 508         /** Transfer timed out */
 509         LIBUSB_TRANSFER_TIMED_OUT,
 510
 511         /** Transfer was cancelled */
 512         LIBUSB_TRANSFER_CANCELLED,
 513 };
 514
 515 /** \ingroup asyncio
 516  * libusb_transfer.flags values */
 517 enum libusb_transfer_flags {
 518         /** Report short frames as errors */
 519         LIBUSB_TRANSFER_SHORT_NOT_OK = 1<<0,
 520
 521         /** Automatically free() transfer buffer during libusb_free_transfer() */
 522         LIBUSB_TRANSFER_FREE_BUFFER = 1<<1,
 523
 524         /** Automatically call libusb_free_transfer() after callback returns.
 525          * If this flag is set, it is illegal to call libusb_free_transfer()
 526          * from your transfer callback, as this will result in a double-free
 527          * when this flag is acted upon. */
 528         LIBUSB_TRANSFER_FREE_TRANSFER = 1<<2,
 529 };
 530
 531 struct libusb_transfer;
 532
 533 typedef void (*libusb_transfer_cb_fn)(struct libusb_transfer *transfer);
 534
 535 /** \ingroup asyncio
 536  * The generic USB transfer structure.
 537  */
 538 struct libusb_transfer {
 539         /** Handle of the device that this transfer will be submitted to */
 540         libusb_device_handle *dev_handle;
 541
 542         /** A bitwise OR combination of \ref libusb_transfer_flags. */
 543         uint8_t flags;
 544
 545         /** Address of the endpoint where this transfer will be sent. */
 546         unsigned char endpoint;
 547
 548         /* FIXME can this be inferred from endpoint address bits? */
 549         /** Type of the endpoint from \ref libusb_endpoint_type */
 550         unsigned char endpoint_type;
 551
 552         /** Timeout for this transfer in millseconds. A value of 0 indicates no
 553          * timeout. */
 554         unsigned int timeout;
 555
 556         /* FIXME: make const? */
 557         /** The status of the transfer. Read-only, and only for use within
 558          * transfer callback function. */
 559         enum libusb_transfer_status status;
 560
 561         /** Length of the data buffer */
 562         int length;
 563
 564         /** Actual length of data that was transferred. Read-only, and only for
 565          * use within transfer callback function. */
 566         int actual_length;
 567
 568         /** Callback function. This will be invoked when the transfer completes,
 569          * fails, or is cancelled. */
 570         libusb_transfer_cb_fn callback;
 571
 572         /** User context data to pass to the callback function. */
 573         void *user_data;
 574
 575         /** Data buffer */
 576         unsigned char *buffer;
 577 };
 578
 579 int libusb_init(void);
 580 void libusb_exit(void);
 581
 582 int libusb_get_device_list(libusb_device ***list);
 583 void libusb_free_device_list(libusb_device **list, int unref_devices);
 584 struct libusb_device_descriptor *libusb_get_device_descriptor(
 585         libusb_device *dev);
 586 struct libusb_config_descriptor *libusb_get_config_descriptor(
 587         libusb_device *dev);
 588 libusb_device *libusb_device_ref(libusb_device *dev);
 589 void libusb_device_unref(libusb_device *dev);
 590
 591 libusb_device_handle *libusb_open(libusb_device *dev);
 592 void libusb_close(libusb_device_handle *dev_handle);
 593 libusb_device *libusb_get_device(libusb_device_handle *dev_handle);
 594 int libusb_claim_interface(libusb_device_handle *dev, int iface);
 595 int libusb_release_interface(libusb_device_handle *dev, int iface);
 596
 597 libusb_device_handle *libusb_open_device_with_vid_pid(uint16_t vendor_id,
 598         uint16_t product_id);
 599
 600 /* async I/O */
 601
 602 /** \ingroup asyncio
 603  * Get the data section of a control transfer. This convenience function is here
 604  * to remind you that the data does not start until 8 bytes into the actual
 605  * buffer, as the setup packet comes first.
 606  *
 607  * Calling this function only makes sense from a transfer callback function,
 608  * or situations where you have already allocated a suitably sized buffer at
 609  * transfer->buffer.
 610  *
 611  * \param transfer a transfer
 612  * \returns pointer to the first byte of the data section
 613  */
 614 static inline unsigned char *libusb_control_transfer_get_data(
 615         struct libusb_transfer *transfer)
 616 {
 617         return transfer->buffer + LIBUSB_CONTROL_SETUP_SIZE;
 618 }
 619
 620 /** \ingroup asyncio
 621  * Get the control setup packet of a control transfer. This convenience
 622  * function is here to remind you that the control setup occupies the first
 623  * 8 bytes of the transfer data buffer.
 624  *
 625  * Calling this function only makes sense from a transfer callback function,
 626  * or situations where you have already allocated a suitably sized buffer at
 627  * transfer->buffer.
 628  *
 629  * \param transfer a transfer
 630  * \returns a casted pointer to the start of the transfer data buffer
 631  */
 632 static inline struct libusb_control_setup *libusb_control_transfer_get_setup(
 633         struct libusb_transfer *transfer)
 634 {
 635         return (struct libusb_control_setup *) transfer->buffer;
 636 }
 637
 638 /** \ingroup asyncio
 639  * Helper function to populate the setup packet (first 8 bytes of the data
 640  * buffer) for a control transfer.
 641  *
 642  * \param buffer buffer to output the setup packet into
 643  * \param bRequestType see the
 644  * \ref libusb_control_setup::bRequestType "bRequestType" field of
 645  * \ref libusb_control_setup
 646  * \param bRequest see the
 647  * \ref libusb_control_setup::bRequest "bRequest" field of
 648  * \ref libusb_control_setup
 649  * \param wValue see the
 650  * \ref libusb_control_setup::wValue "wValue" field of
 651  * \ref libusb_control_setup
 652  * \param wIndex see the
 653  * \ref libusb_control_setup::wIndex "wIndex" field of
 654  * \ref libusb_control_setup
 655  * \param wLength see the
 656  * \ref libusb_control_setup::wLength "wLength" field of
 657  * \ref libusb_control_setup
 658  */
 659 static inline void libusb_fill_control_setup(unsigned char *buffer,
 660         uint8_t bRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
 661         uint16_t wLength)
 662 {
 663         struct libusb_control_setup *setup = (struct libusb_control_setup *) buffer;
 664         setup->bRequestType = bRequestType;
 665         setup->bRequest = bRequest;
 666         setup->wValue = wValue;
 667         setup->wIndex = wIndex;
 668         setup->wLength = wLength;
 669 }
 670
 671 size_t libusb_get_transfer_alloc_size(void);
 672 void libusb_init_transfer(struct libusb_transfer *transfer);
 673
 674 struct libusb_transfer *libusb_alloc_transfer(void);
 675 int libusb_submit_transfer(struct libusb_transfer *transfer);
 676 int libusb_cancel_transfer(struct libusb_transfer *transfer);
 677 int libusb_cancel_transfer_sync(struct libusb_transfer *transfer);
 678 void libusb_free_transfer(struct libusb_transfer *transfer);
 679
 680 /** \ingroup asyncio
 681  * Helper function to populate the required \ref libusb_transfer fields
 682  * for a control transfer.
 683  *
 684  * If you pass a transfer buffer to this function, the first 8 bytes will
 685  * be interpreted as a control setup packet, and the wLength field will be
 686  * used to automatically populate the \ref libusb_transfer::length "length"
 687  * field of the transfer. Therefore the recommended approach is:
 688  * -# Allocate a suitably sized data buffer (including space for control setup)
 689  * -# Call libusb_fill_control_setup()
 690  * -# If this is a host-to-device transfer with a data stage, put the data
 691  *    in place after the setup packet
 692  * -# Call this function
 693  * -# Call libusb_submit_transfer()
 694  *
 695  * It is also legal to pass a NULL buffer to this function, in which case this
 696  * function will not attempt to populate the length field. Remember that you
 697  * must populate the buffer and length fields later.
 698  *
 699  * \param transfer the transfer to populate
 700  * \param dev_handle handle of the device that will handle the transfer
 701  * \param buffer data buffer. If provided, this function will interpret the
 702  * first 8 bytes as a setup packet and infer the transfer length from that.
 703  * \param callback callback function to be invoked on transfer completion
 704  * \param user_data user data to pass to callback function
 705  * \param timeout timeout for the transfer in milliseconds
 706  */
 707 static inline void libusb_fill_control_transfer(
 708         struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
 709         unsigned char *buffer, libusb_transfer_cb_fn callback, void *user_data,
 710         unsigned int timeout)
 711 {
 712         struct libusb_control_setup *setup = (struct libusb_control_setup *) buffer;
 713         transfer->dev_handle = dev_handle;
 714         transfer->endpoint = 0;
 715         transfer->endpoint_type = LIBUSB_ENDPOINT_TYPE_CONTROL;
 716         transfer->timeout = timeout;
 717         transfer->buffer = buffer;
 718         if (setup)
 719                 transfer->length = LIBUSB_CONTROL_SETUP_SIZE + setup->wLength;
 720         transfer->user_data = user_data;
 721         transfer->callback = callback;
 722 }
 723
 724 /** \ingroup asyncio
 725  * Helper function to populate the required \ref libusb_transfer fields
 726  * for a bulk transfer.
 727  *
 728  * \param transfer the transfer to populate
 729  * \param dev_handle handle of the device that will handle the transfer
 730  * \param endpoint address of the endpoint where this transfer will be sent
 731  * \param buffer data buffer
 732  * \param length length of data buffer
 733  * \param callback callback function to be invoked on transfer completion
 734  * \param user_data user data to pass to callback function
 735  * \param timeout timeout for the transfer in milliseconds
 736  */
 737 static inline void libusb_fill_bulk_transfer(struct libusb_transfer *transfer,
 738         libusb_device_handle *dev_handle, unsigned char endpoint,
 739         unsigned char *buffer, int length, libusb_transfer_cb_fn callback,
 740         void *user_data, unsigned int timeout)
 741 {
 742         transfer->dev_handle = dev_handle;
 743         transfer->endpoint = endpoint;
 744         transfer->endpoint_type = LIBUSB_ENDPOINT_TYPE_BULK;
 745         transfer->timeout = timeout;
 746         transfer->buffer = buffer;
 747         transfer->length = length;
 748         transfer->user_data = user_data;
 749         transfer->callback = callback;
 750 }
 751
 752 /** \ingroup asyncio
 753  * Helper function to populate the required \ref libusb_transfer fields
 754  * for an interrupt transfer.
 755  *
 756  * \param transfer the transfer to populate
 757  * \param dev_handle handle of the device that will handle the transfer
 758  * \param endpoint address of the endpoint where this transfer will be sent
 759  * \param buffer data buffer
 760  * \param length length of data buffer
 761  * \param callback callback function to be invoked on transfer completion
 762  * \param user_data user data to pass to callback function
 763  * \param timeout timeout for the transfer in milliseconds
 764  */
 765 static inline void libusb_fill_interrupt_transfer(
 766         struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
 767         unsigned char endpoint, unsigned char *buffer, int length,
 768         libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)
 769 {
 770         transfer->dev_handle = dev_handle;
 771         transfer->endpoint = endpoint;
 772         transfer->endpoint_type = LIBUSB_ENDPOINT_TYPE_INTERRUPT;
 773         transfer->timeout = timeout;
 774         transfer->buffer = buffer;
 775         transfer->length = length;
 776         transfer->user_data = user_data;
 777         transfer->callback = callback;
 778 }
 779
 780 /* sync I/O */
 781
 782 int libusb_control_transfer(libusb_device_handle *dev_handle,
 783         uint8_t request_type, uint8_t request, uint16_t value, uint16_t index,
 784         unsigned char *data, uint16_t length, unsigned int timeout);
 785
 786 int libusb_bulk_transfer(libusb_device_handle *dev_handle,
 787         unsigned char endpoint, unsigned char *data, int length,
 788         int *actual_length, unsigned int timeout);
 789
 790 int libusb_interrupt_transfer(libusb_device_handle *dev_handle,
 791         unsigned char endpoint, unsigned char *data, int length,
 792         int *actual_length, unsigned int timeout);
 793
 794 /* polling and timeouts */
 795
 796 /** \ingroup poll
 797  * File descriptor for polling
 798  */
 799 struct libusb_pollfd {
 800         /** Numeric file descriptor */
 801         int fd;
 802
 803         /** Event flags to poll for from <poll.h>. POLLIN indicates that you
 804          * should monitor this file descriptor for becoming ready to read from,
 805          * and POLLOUT indicates that you should monitor this file descriptor for
 806          * nonblocking write readiness. */
 807         short events;
 808 };
 809
 810 int libusb_poll_timeout(struct timeval *tv);
 811 int libusb_poll(void);
 812 int libusb_get_next_timeout(struct timeval *tv);
 813 struct libusb_pollfd **libusb_get_pollfds(void);
 814
 815 typedef void (*libusb_pollfd_added_cb)(int fd, short events);
 816 typedef void (*libusb_pollfd_removed_cb)(int fd);
 817 void libusb_set_pollfd_notifiers(libusb_pollfd_added_cb added_cb,
 818         libusb_pollfd_removed_cb removed_cb);
 819
 820 #ifdef __cplusplus
 821 }
 822 #endif
 823
 824 #endif