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#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)) 41typedef unsigned __int8 uint8_t; 42typedef unsigned __int16 uint16_t; 43typedef 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 libusb 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 * libusb'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, libusb 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 libusb 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 libusb 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 107extern "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 */ 118static 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 */ 143enum 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. */ 205enum 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 */ 249enum 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 */ 263enum 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 */ 279enum 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. */ 322enum 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. */ 340enum 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 */ 361enum 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 */ 382enum 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 */ 398struct 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 */ 452struct 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 libusb 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 */ 502struct 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 libusb 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 */ 550struct 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 */ 564struct 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 libusb 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. */ 607struct 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/* libusb */ 636 637struct libusb_context; 638struct libusb_device; 639struct libusb_device_handle; 640 641/** \ingroup lib 642 * Structure representing the libusb version. 643 */ 644struct 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. This field is only nonzero on Windows. */ 655 const uint16_t nano; 656 657 /** Library release candidate suffix string, e.g. "-rc4". */ 658 const char *rc; 659 660 /** Output of `git describe --tags` at library build time. */ 661 const char *describe; 662}; 663 664/** \ingroup lib 665 * Structure representing a libusb session. The concept of individual libusb 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 libusb 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 libusb 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 */ 681typedef 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 */ 698typedef 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 */ 709typedef struct libusb_device_handle libusb_device_handle; 710 711/** \ingroup dev 712 * Speed codes. Indicates the speed at which the device is operating. 713 */ 714enum 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 libusb 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 */ 737enum 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 */ 786enum 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 */ 813enum 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. */ 854struct 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 865struct 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. libusb 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 */ 876typedef 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 */ 884struct 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 */ 947enum libusb_capability { 948 /** The libusb_has_capability() API is available. */ 949 LIBUSB_CAP_HAS_CAPABILITY = 0, 950}; 951 952int LIBUSB_CALL libusb_init(libusb_context **ctx); 953void LIBUSB_CALL libusb_exit(libusb_context *ctx); 954void LIBUSB_CALL libusb_set_debug(libusb_context *ctx, int level); 955const struct libusb_version * LIBUSB_CALL libusb_get_version(void); 956int LIBUSB_CALL libusb_has_capability(uint32_t capability); 957const char * LIBUSB_CALL libusb_error_name(int errcode); 958 959ssize_t LIBUSB_CALL libusb_get_device_list(libusb_context *ctx, 960 libusb_device ***list); 961void LIBUSB_CALL libusb_free_device_list(libusb_device **list, 962 int unref_devices); 963libusb_device * LIBUSB_CALL libusb_ref_device(libusb_device *dev); 964void LIBUSB_CALL libusb_unref_device(libusb_device *dev); 965 966int LIBUSB_CALL libusb_get_configuration(libusb_device_handle *dev, 967 int *config); 968int LIBUSB_CALL libusb_get_device_descriptor(libusb_device *dev, 969 struct libusb_device_descriptor *desc); 970int LIBUSB_CALL libusb_get_active_config_descriptor(libusb_device *dev, 971 struct libusb_config_descriptor **config); 972int LIBUSB_CALL libusb_get_config_descriptor(libusb_device *dev, 973 uint8_t config_index, struct libusb_config_descriptor **config); 974int LIBUSB_CALL libusb_get_config_descriptor_by_value(libusb_device *dev, 975 uint8_t bConfigurationValue, struct libusb_config_descriptor **config); 976void LIBUSB_CALL libusb_free_config_descriptor( 977 struct libusb_config_descriptor *config); 978uint8_t LIBUSB_CALL libusb_get_bus_number(libusb_device *dev); 979uint8_t LIBUSB_CALL libusb_get_device_address(libusb_device *dev); 980int LIBUSB_CALL libusb_get_device_speed(libusb_device *dev); 981int LIBUSB_CALL libusb_get_max_packet_size(libusb_device *dev, 982 unsigned char endpoint); 983int LIBUSB_CALL libusb_get_max_iso_packet_size(libusb_device *dev, 984 unsigned char endpoint); 985 986int LIBUSB_CALL libusb_open(libusb_device *dev, libusb_device_handle **handle); 987void LIBUSB_CALL libusb_close(libusb_device_handle *dev_handle); 988libusb_device * LIBUSB_CALL libusb_get_device(libusb_device_handle *dev_handle); 989 990int LIBUSB_CALL libusb_set_configuration(libusb_device_handle *dev, 991 int configuration); 992int LIBUSB_CALL libusb_claim_interface(libusb_device_handle *dev, 993 int interface_number); 994int LIBUSB_CALL libusb_release_interface(libusb_device_handle *dev, 995 int interface_number); 996 997libusb_device_handle * LIBUSB_CALL libusb_open_device_with_vid_pid( 998 libusb_context *ctx, uint16_t vendor_id, uint16_t product_id); 999 1000int LIBUSB_CALL libusb_set_interface_alt_setting(libusb_device_handle *dev, 1001 int interface_number, int alternate_setting); 1002int LIBUSB_CALL libusb_clear_halt(libusb_device_handle *dev, 1003 unsigned char endpoint); 1004int LIBUSB_CALL libusb_reset_device(libusb_device_handle *dev); 1005 1006int LIBUSB_CALL libusb_kernel_driver_active(libusb_device_handle *dev, 1007 int interface_number); 1008int LIBUSB_CALL libusb_detach_kernel_driver(libusb_device_handle *dev, 1009 int interface_number); 1010int LIBUSB_CALL libusb_attach_kernel_driver(libusb_device_handle *dev, 1011 int interface_number); 1012 1013/* async I/O */ 1014 1015/** \ingroup asyncio 1016 * Get the data section of a control transfer. This convenience function is here 1017 * to remind you that the data does not start until 8 bytes into the actual 1018 * buffer, as the setup packet comes first. 1019 * 1020 * Calling this function only makes sense from a transfer callback function, 1021 * or situations where you have already allocated a suitably sized buffer at 1022 * transfer->buffer. 1023 * 1024 * \param transfer a transfer 1025 * \returns pointer to the first byte of the data section 1026 */ 1027static inline unsigned char *libusb_control_transfer_get_data( 1028 struct libusb_transfer *transfer) 1029{ 1030 return transfer->buffer + LIBUSB_CONTROL_SETUP_SIZE; 1031} 1032 1033/** \ingroup asyncio 1034 * Get the control setup packet of a control transfer. This convenience 1035 * function is here to remind you that the control setup occupies the first 1036 * 8 bytes of the transfer data buffer. 1037 * 1038 * Calling this function only makes sense from a transfer callback function, 1039 * or situations where you have already allocated a suitably sized buffer at 1040 * transfer->buffer. 1041 * 1042 * \param transfer a transfer 1043 * \returns a casted pointer to the start of the transfer data buffer 1044 */ 1045static inline struct libusb_control_setup *libusb_control_transfer_get_setup( 1046 struct libusb_transfer *transfer) 1047{ 1048 return (struct libusb_control_setup *) transfer->buffer; 1049} 1050 1051/** \ingroup asyncio 1052 * Helper function to populate the setup packet (first 8 bytes of the data 1053 * buffer) for a control transfer. The wIndex, wValue and wLength values should 1054 * be given in host-endian byte order. 1055 * 1056 * \param buffer buffer to output the setup packet into 1057 * \param bmRequestType see the 1058 * \ref libusb_control_setup::bmRequestType "bmRequestType" field of 1059 * \ref libusb_control_setup 1060 * \param bRequest see the 1061 * \ref libusb_control_setup::bRequest "bRequest" field of 1062 * \ref libusb_control_setup 1063 * \param wValue see the 1064 * \ref libusb_control_setup::wValue "wValue" field of 1065 * \ref libusb_control_setup 1066 * \param wIndex see the 1067 * \ref libusb_control_setup::wIndex "wIndex" field of 1068 * \ref libusb_control_setup 1069 * \param wLength see the 1070 * \ref libusb_control_setup::wLength "wLength" field of 1071 * \ref libusb_control_setup 1072 */ 1073static inline void libusb_fill_control_setup(unsigned char *buffer, 1074 uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, 1075 uint16_t wLength) 1076{ 1077 struct libusb_control_setup *setup = (struct libusb_control_setup *) buffer; 1078 setup->bmRequestType = bmRequestType; 1079 setup->bRequest = bRequest; 1080 setup->wValue = libusb_cpu_to_le16(wValue); 1081 setup->wIndex = libusb_cpu_to_le16(wIndex); 1082 setup->wLength = libusb_cpu_to_le16(wLength); 1083} 1084 1085struct libusb_transfer * LIBUSB_CALL libusb_alloc_transfer(int iso_packets); 1086int LIBUSB_CALL libusb_submit_transfer(struct libusb_transfer *transfer); 1087int LIBUSB_CALL libusb_cancel_transfer(struct libusb_transfer *transfer); 1088void LIBUSB_CALL libusb_free_transfer(struct libusb_transfer *transfer); 1089 1090/** \ingroup asyncio 1091 * Helper function to populate the required \ref libusb_transfer fields 1092 * for a control transfer. 1093 * 1094 * If you pass a transfer buffer to this function, the first 8 bytes will 1095 * be interpreted as a control setup packet, and the wLength field will be 1096 * used to automatically populate the \ref libusb_transfer::length "length" 1097 * field of the transfer. Therefore the recommended approach is: 1098 * -# Allocate a suitably sized data buffer (including space for control setup) 1099 * -# Call libusb_fill_control_setup() 1100 * -# If this is a host-to-device transfer with a data stage, put the data 1101 * in place after the setup packet 1102 * -# Call this function 1103 * -# Call libusb_submit_transfer() 1104 * 1105 * It is also legal to pass a NULL buffer to this function, in which case this 1106 * function will not attempt to populate the length field. Remember that you 1107 * must then populate the buffer and length fields later. 1108 * 1109 * \param transfer the transfer to populate 1110 * \param dev_handle handle of the device that will handle the transfer 1111 * \param buffer data buffer. If provided, this function will interpret the 1112 * first 8 bytes as a setup packet and infer the transfer length from that. 1113 * \param callback callback function to be invoked on transfer completion 1114 * \param user_data user data to pass to callback function 1115 * \param timeout timeout for the transfer in milliseconds 1116 */ 1117static inline void libusb_fill_control_transfer( 1118 struct libusb_transfer *transfer, libusb_device_handle *dev_handle, 1119 unsigned char *buffer, libusb_transfer_cb_fn callback, void *user_data, 1120 unsigned int timeout) 1121{ 1122 struct libusb_control_setup *setup = (struct libusb_control_setup *) buffer; 1123 transfer->dev_handle = dev_handle; 1124 transfer->endpoint = 0; 1125 transfer->type = LIBUSB_TRANSFER_TYPE_CONTROL; 1126 transfer->timeout = timeout; 1127 transfer->buffer = buffer; 1128 if (setup) 1129 transfer->length = LIBUSB_CONTROL_SETUP_SIZE 1130 + libusb_le16_to_cpu(setup->wLength); 1131 transfer->user_data = user_data; 1132 transfer->callback = callback; 1133} 1134 1135/** \ingroup asyncio 1136 * Helper function to populate the required \ref libusb_transfer fields 1137 * for a bulk transfer. 1138 * 1139 * \param transfer the transfer to populate 1140 * \param dev_handle handle of the device that will handle the transfer 1141 * \param endpoint address of the endpoint where this transfer will be sent 1142 * \param buffer data buffer 1143 * \param length length of data buffer 1144 * \param callback callback function to be invoked on transfer completion 1145 * \param user_data user data to pass to callback function 1146 * \param timeout timeout for the transfer in milliseconds 1147 */ 1148static inline void libusb_fill_bulk_transfer(struct libusb_transfer *transfer, 1149 libusb_device_handle *dev_handle, unsigned char endpoint, 1150 unsigned char *buffer, int length, libusb_transfer_cb_fn callback, 1151 void *user_data, unsigned int timeout) 1152{ 1153 transfer->dev_handle = dev_handle; 1154 transfer->endpoint = endpoint; 1155 transfer->type = LIBUSB_TRANSFER_TYPE_BULK; 1156 transfer->timeout = timeout; 1157 transfer->buffer = buffer; 1158 transfer->length = length; 1159 transfer->user_data = user_data; 1160 transfer->callback = callback; 1161} 1162 1163/** \ingroup asyncio 1164 * Helper function to populate the required \ref libusb_transfer fields 1165 * for an interrupt transfer. 1166 * 1167 * \param transfer the transfer to populate 1168 * \param dev_handle handle of the device that will handle the transfer 1169 * \param endpoint address of the endpoint where this transfer will be sent 1170 * \param buffer data buffer 1171 * \param length length of data buffer 1172 * \param callback callback function to be invoked on transfer completion 1173 * \param user_data user data to pass to callback function 1174 * \param timeout timeout for the transfer in milliseconds 1175 */ 1176static inline void libusb_fill_interrupt_transfer( 1177 struct libusb_transfer *transfer, libusb_device_handle *dev_handle, 1178 unsigned char endpoint, unsigned char *buffer, int length, 1179 libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout) 1180{ 1181 transfer->dev_handle = dev_handle; 1182 transfer->endpoint = endpoint; 1183 transfer->type = LIBUSB_TRANSFER_TYPE_INTERRUPT; 1184 transfer->timeout = timeout; 1185 transfer->buffer = buffer; 1186 transfer->length = length; 1187 transfer->user_data = user_data; 1188 transfer->callback = callback; 1189} 1190 1191/** \ingroup asyncio 1192 * Helper function to populate the required \ref libusb_transfer fields 1193 * for an isochronous transfer. 1194 * 1195 * \param transfer the transfer to populate 1196 * \param dev_handle handle of the device that will handle the transfer 1197 * \param endpoint address of the endpoint where this transfer will be sent 1198 * \param buffer data buffer 1199 * \param length length of data buffer 1200 * \param num_iso_packets the number of isochronous packets 1201 * \param callback callback function to be invoked on transfer completion 1202 * \param user_data user data to pass to callback function 1203 * \param timeout timeout for the transfer in milliseconds 1204 */ 1205static inline void libusb_fill_iso_transfer(struct libusb_transfer *transfer, 1206 libusb_device_handle *dev_handle, unsigned char endpoint, 1207 unsigned char *buffer, int length, int num_iso_packets, 1208 libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout) 1209{ 1210 transfer->dev_handle = dev_handle; 1211 transfer->endpoint = endpoint; 1212 transfer->type = LIBUSB_TRANSFER_TYPE_ISOCHRONOUS; 1213 transfer->timeout = timeout; 1214 transfer->buffer = buffer; 1215 transfer->length = length; 1216 transfer->num_iso_packets = num_iso_packets; 1217 transfer->user_data = user_data; 1218 transfer->callback = callback; 1219} 1220 1221/** \ingroup asyncio 1222 * Convenience function to set the length of all packets in an isochronous 1223 * transfer, based on the num_iso_packets field in the transfer structure. 1224 * 1225 * \param transfer a transfer 1226 * \param length the length to set in each isochronous packet descriptor 1227 * \see libusb_get_max_packet_size() 1228 */ 1229static inline void libusb_set_iso_packet_lengths( 1230 struct libusb_transfer *transfer, unsigned int length) 1231{ 1232 int i; 1233 for (i = 0; i < transfer->num_iso_packets; i++) 1234 transfer->iso_packet_desc[i].length = length; 1235} 1236 1237/** \ingroup asyncio 1238 * Convenience function to locate the position of an isochronous packet 1239 * within the buffer of an isochronous transfer. 1240 * 1241 * This is a thorough function which loops through all preceding packets, 1242 * accumulating their lengths to find the position of the specified packet. 1243 * Typically you will assign equal lengths to each packet in the transfer, 1244 * and hence the above method is sub-optimal. You may wish to use 1245 * libusb_get_iso_packet_buffer_simple() instead. 1246 * 1247 * \param transfer a transfer 1248 * \param packet the packet to return the address of 1249 * \returns the base address of the packet buffer inside the transfer buffer, 1250 * or NULL if the packet does not exist. 1251 * \see libusb_get_iso_packet_buffer_simple() 1252 */ 1253static inline unsigned char *libusb_get_iso_packet_buffer( 1254 struct libusb_transfer *transfer, unsigned int packet) 1255{ 1256 int i; 1257 size_t offset = 0; 1258 int _packet; 1259 1260 /* oops..slight bug in the API. packet is an unsigned int, but we use 1261 * signed integers almost everywhere else. range-check and convert to 1262 * signed to avoid compiler warnings. FIXME for libusb-2. */ 1263 if (packet > INT_MAX) 1264 return NULL; 1265 _packet = packet; 1266 1267 if (_packet >= transfer->num_iso_packets) 1268 return NULL; 1269 1270 for (i = 0; i < _packet; i++) 1271 offset += transfer->iso_packet_desc[i].length; 1272 1273 return transfer->buffer + offset; 1274} 1275 1276/** \ingroup asyncio 1277 * Convenience function to locate the position of an isochronous packet 1278 * within the buffer of an isochronous transfer, for transfers where each 1279 * packet is of identical size. 1280 * 1281 * This function relies on the assumption that every packet within the transfer 1282 * is of identical size to the first packet. Calculating the location of 1283 * the packet buffer is then just a simple calculation: 1284 * <tt>buffer + (packet_size * packet)</tt> 1285 * 1286 * Do not use this function on transfers other than those that have identical 1287 * packet lengths for each packet. 1288 * 1289 * \param transfer a transfer 1290 * \param packet the packet to return the address of 1291 * \returns the base address of the packet buffer inside the transfer buffer, 1292 * or NULL if the packet does not exist. 1293 * \see libusb_get_iso_packet_buffer() 1294 */ 1295static inline unsigned char *libusb_get_iso_packet_buffer_simple( 1296 struct libusb_transfer *transfer, unsigned int packet) 1297{ 1298 int _packet; 1299 1300 /* oops..slight bug in the API. packet is an unsigned int, but we use 1301 * signed integers almost everywhere else. range-check and convert to 1302 * signed to avoid compiler warnings. FIXME for libusb-2. */ 1303 if (packet > INT_MAX) 1304 return NULL; 1305 _packet = packet; 1306 1307 if (_packet >= transfer->num_iso_packets) 1308 return NULL; 1309 1310 return transfer->buffer + (transfer->iso_packet_desc[0].length * _packet); 1311} 1312 1313/* sync I/O */ 1314 1315int LIBUSB_CALL libusb_control_transfer(libusb_device_handle *dev_handle, 1316 uint8_t request_type, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, 1317 unsigned char *data, uint16_t wLength, unsigned int timeout); 1318 1319int LIBUSB_CALL libusb_bulk_transfer(libusb_device_handle *dev_handle, 1320 unsigned char endpoint, unsigned char *data, int length, 1321 int *actual_length, unsigned int timeout); 1322 1323int LIBUSB_CALL libusb_interrupt_transfer(libusb_device_handle *dev_handle, 1324 unsigned char endpoint, unsigned char *data, int length, 1325 int *actual_length, unsigned int timeout); 1326 1327/** \ingroup desc 1328 * Retrieve a descriptor from the default control pipe. 1329 * This is a convenience function which formulates the appropriate control 1330 * message to retrieve the descriptor. 1331 * 1332 * \param dev a device handle 1333 * \param desc_type the descriptor type, see \ref libusb_descriptor_type 1334 * \param desc_index the index of the descriptor to retrieve 1335 * \param data output buffer for descriptor 1336 * \param length size of data buffer 1337 * \returns number of bytes returned in data, or LIBUSB_ERROR code on failure 1338 */ 1339static inline int libusb_get_descriptor(libusb_device_handle *dev, 1340 uint8_t desc_type, uint8_t desc_index, unsigned char *data, int length) 1341{ 1342 return libusb_control_transfer(dev, LIBUSB_ENDPOINT_IN, 1343 LIBUSB_REQUEST_GET_DESCRIPTOR, (desc_type << 8) | desc_index, 0, data, 1344 (uint16_t) length, 1000); 1345} 1346 1347/** \ingroup desc 1348 * Retrieve a descriptor from a device. 1349 * This is a convenience function which formulates the appropriate control 1350 * message to retrieve the descriptor. The string returned is Unicode, as 1351 * detailed in the USB specifications. 1352 * 1353 * \param dev a device handle 1354 * \param desc_index the index of the descriptor to retrieve 1355 * \param langid the language ID for the string descriptor 1356 * \param data output buffer for descriptor 1357 * \param length size of data buffer 1358 * \returns number of bytes returned in data, or LIBUSB_ERROR code on failure 1359 * \see libusb_get_string_descriptor_ascii() 1360 */ 1361static inline int libusb_get_string_descriptor(libusb_device_handle *dev, 1362 uint8_t desc_index, uint16_t langid, unsigned char *data, int length) 1363{ 1364 return libusb_control_transfer(dev, LIBUSB_ENDPOINT_IN, 1365 LIBUSB_REQUEST_GET_DESCRIPTOR, (uint16_t)((LIBUSB_DT_STRING << 8) | desc_index), 1366 langid, data, (uint16_t) length, 1000); 1367} 1368 1369int LIBUSB_CALL libusb_get_string_descriptor_ascii(libusb_device_handle *dev, 1370 uint8_t desc_index, unsigned char *data, int length); 1371 1372/* polling and timeouts */ 1373 1374int LIBUSB_CALL libusb_try_lock_events(libusb_context *ctx); 1375void LIBUSB_CALL libusb_lock_events(libusb_context *ctx); 1376void LIBUSB_CALL libusb_unlock_events(libusb_context *ctx); 1377int LIBUSB_CALL libusb_event_handling_ok(libusb_context *ctx); 1378int LIBUSB_CALL libusb_event_handler_active(libusb_context *ctx); 1379void LIBUSB_CALL libusb_lock_event_waiters(libusb_context *ctx); 1380void LIBUSB_CALL libusb_unlock_event_waiters(libusb_context *ctx); 1381int LIBUSB_CALL libusb_wait_for_event(libusb_context *ctx, struct timeval *tv); 1382 1383int LIBUSB_CALL libusb_handle_events_timeout(libusb_context *ctx, 1384 struct timeval *tv); 1385int LIBUSB_CALL libusb_handle_events_timeout_completed(libusb_context *ctx, 1386 struct timeval *tv, int *completed); 1387int LIBUSB_CALL libusb_handle_events(libusb_context *ctx); 1388int LIBUSB_CALL libusb_handle_events_completed(libusb_context *ctx, int *completed); 1389int LIBUSB_CALL libusb_handle_events_locked(libusb_context *ctx, 1390 struct timeval *tv); 1391int LIBUSB_CALL libusb_pollfds_handle_timeouts(libusb_context *ctx); 1392int LIBUSB_CALL libusb_get_next_timeout(libusb_context *ctx, 1393 struct timeval *tv); 1394 1395/** \ingroup poll 1396 * File descriptor for polling 1397 */ 1398struct libusb_pollfd { 1399 /** Numeric file descriptor */ 1400 int fd; 1401 1402 /** Event flags to poll for from <poll.h>. POLLIN indicates that you 1403 * should monitor this file descriptor for becoming ready to read from, 1404 * and POLLOUT indicates that you should monitor this file descriptor for 1405 * nonblocking write readiness. */ 1406 short events; 1407}; 1408 1409/** \ingroup poll 1410 * Callback function, invoked when a new file descriptor should be added 1411 * to the set of file descriptors monitored for events. 1412 * \param fd the new file descriptor 1413 * \param events events to monitor for, see \ref libusb_pollfd for a 1414 * description 1415 * \param user_data User data pointer specified in 1416 * libusb_set_pollfd_notifiers() call 1417 * \see libusb_set_pollfd_notifiers() 1418 */ 1419typedef void (LIBUSB_CALL *libusb_pollfd_added_cb)(int fd, short events, 1420 void *user_data); 1421 1422/** \ingroup poll 1423 * Callback function, invoked when a file descriptor should be removed from 1424 * the set of file descriptors being monitored for events. After returning 1425 * from this callback, do not use that file descriptor again. 1426 * \param fd the file descriptor to stop monitoring 1427 * \param user_data User data pointer specified in 1428 * libusb_set_pollfd_notifiers() call 1429 * \see libusb_set_pollfd_notifiers() 1430 */ 1431typedef void (LIBUSB_CALL *libusb_pollfd_removed_cb)(int fd, void *user_data); 1432 1433const struct libusb_pollfd ** LIBUSB_CALL libusb_get_pollfds( 1434 libusb_context *ctx); 1435void LIBUSB_CALL libusb_set_pollfd_notifiers(libusb_context *ctx, 1436 libusb_pollfd_added_cb added_cb, libusb_pollfd_removed_cb removed_cb, 1437 void *user_data); 1438 1439#ifdef __cplusplus 1440} 1441#endif 1442 1443#endif 1444