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