libusb.h   libusb.h 
/* /*
* Public libusb header file * Public libusb header file
* Copyright (C) 2007-2008 Daniel Drake <dsd@gentoo.org> * Copyright © 2001 Johannes Erdfelt <johannes@erdfelt.com>
* Copyright (c) 2001 Johannes Erdfelt <johannes@erdfelt.com> * Copyright © 2007-2008 Daniel Drake <dsd@gentoo.org>
* Copyright (C) 2012-2013 Nathan Hjelm <hjelmn@cs.unm.edu> * Copyright © 2012 Pete Batard <pete@akeo.ie>
* Copyright (C) 2012 Peter Stuge <peter@stuge.se> * Copyright © 2012 Nathan Hjelm <hjelmn@cs.unm.edu>
* For more information, please visit: http://libusb.info
* *
* This library is free software; you can redistribute it and/or * This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public * modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either * License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version. * version 2.1 of the License, or (at your option) any later version.
* *
* This library is distributed in the hope that it will be useful, * This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of * but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details. * Lesser General Public License for more details.
skipping to change at line 28 skipping to change at line 29
* You should have received a copy of the GNU Lesser General Public * You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software * License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/ */
#ifndef LIBUSB_H #ifndef LIBUSB_H
#define LIBUSB_H #define LIBUSB_H
#ifdef _MSC_VER #ifdef _MSC_VER
/* on MS environments, the inline keyword is available in C++ only */ /* on MS environments, the inline keyword is available in C++ only */
#if !defined(__cplusplus)
#define inline __inline #define inline __inline
#endif
/* ssize_t is also not available (copy/paste from MinGW) */ /* ssize_t is also not available (copy/paste from MinGW) */
#ifndef _SSIZE_T_DEFINED #ifndef _SSIZE_T_DEFINED
#define _SSIZE_T_DEFINED #define _SSIZE_T_DEFINED
#undef ssize_t #undef ssize_t
#ifdef _WIN64 #ifdef _WIN64
typedef __int64 ssize_t; typedef __int64 ssize_t;
#else #else
typedef int ssize_t; typedef int ssize_t;
#endif /* _WIN64 */ #endif /* _WIN64 */
#endif /* _SSIZE_T_DEFINED */ #endif /* _SSIZE_T_DEFINED */
#endif /* _MSC_VER */ #endif /* _MSC_VER */
/* stdint.h is also not usually available on MS */ /* stdint.h is not available on older MSVC */
#if defined(_MSC_VER) && (_MSC_VER < 1600) && (!defined(_STDINT)) && (!defi ned(_STDINT_H)) #if defined(_MSC_VER) && (_MSC_VER < 1600) && (!defined(_STDINT)) && (!defi ned(_STDINT_H))
typedef unsigned __int8 uint8_t; typedef unsigned __int8 uint8_t;
typedef unsigned __int16 uint16_t; typedef unsigned __int16 uint16_t;
typedef unsigned __int32 uint32_t; typedef unsigned __int32 uint32_t;
#else #else
#include <stdint.h> #include <stdint.h>
#endif #endif
#if !defined(_WIN32_WCE)
#include <sys/types.h> #include <sys/types.h>
#include <time.h> #endif
#include <limits.h>
#if defined(__linux) || defined(__APPLE__) || defined(__CYGWIN__) #if defined(__linux) || defined(__APPLE__) || defined(__CYGWIN__)
#include <sys/time.h> #include <sys/time.h>
#endif #endif
#include <time.h>
#include <limits.h>
/* 'interface' might be defined as a macro on Windows, so we need to /* 'interface' might be defined as a macro on Windows, so we need to
* undefine it so as not to break the current libusb API, because * undefine it so as not to break the current libusb API, because
* libusb_config_descriptor has an 'interface' member * libusb_config_descriptor has an 'interface' member
* As this can be problematic if you include windows.h after libusb.h * As this can be problematic if you include windows.h after libusb.h
* in your sources, we force windows.h to be included first. */ * in your sources, we force windows.h to be included first. */
#if defined(_WIN32) || defined(__CYGWIN__) #if defined(_WIN32) || defined(__CYGWIN__) || defined(_WIN32_WCE)
#include <windows.h> #include <windows.h>
#if defined(interface) #if defined(interface)
#undef interface #undef interface
#endif #endif
#if !defined(__CYGWIN__)
#include <winsock.h>
#endif
#endif #endif
#if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5)
#define LIBUSB_DEPRECATED_FOR(f) \
__attribute__((deprecated("Use " #f " instead")))
#else
#define LIBUSB_DEPRECATED_FOR(f)
#endif /* __GNUC__ */
/** \def LIBUSB_CALL /** \def LIBUSB_CALL
* \ingroup misc * \ingroup misc
* libusb's Windows calling convention. * libusb's Windows calling convention.
* *
* Under Windows, the selection of available compilers and configurations * Under Windows, the selection of available compilers and configurations
* means that, unlike other platforms, there is not <em>one true calling * means that, unlike other platforms, there is not <em>one true calling
* convention</em> (calling convention: the manner in which parameters are * convention</em> (calling convention: the manner in which parameters are
* passed to funcions in the generated assembly code). * passed to funcions in the generated assembly code).
* *
* Matching the Windows API itself, libusb uses the WINAPI convention (whic h * Matching the Windows API itself, libusb uses the WINAPI convention (whic h
skipping to change at line 102 skipping to change at line 118
* means that you can apply it to your code without worrying about * means that you can apply it to your code without worrying about
* cross-platform compatibility. * cross-platform compatibility.
*/ */
/* LIBUSB_CALL must be defined on both definition and declaration of libusb /* LIBUSB_CALL must be defined on both definition and declaration of libusb
* functions. You'd think that declaration would be enough, but cygwin will * functions. You'd think that declaration would be enough, but cygwin will
* complain about conflicting types unless both are marked this way. * complain about conflicting types unless both are marked this way.
* The placement of this macro is important too; it must appear after the * The placement of this macro is important too; it must appear after the
* return type, before the function name. See internal documentation for * return type, before the function name. See internal documentation for
* API_EXPORTED. * API_EXPORTED.
*/ */
#if defined(_WIN32) || defined(__CYGWIN__) #if defined(_WIN32) || defined(__CYGWIN__) || defined(_WIN32_WCE)
#define LIBUSB_CALL WINAPI #define LIBUSB_CALL WINAPI
#else #else
#define LIBUSB_CALL #define LIBUSB_CALL
#endif #endif
/** \def LIBUSB_API_VERSION
* \ingroup misc
* libusb's API version.
*
* Since version 1.0.13, to help with feature detection, libusb defines
* a LIBUSB_API_VERSION macro that gets increased every time there is a
* significant change to the API, such as the introduction of a new call,
* the definition of a new macro/enum member, or any other element that
* libusb applications may want to detect at compilation time.
*
* The macro is typically used in an application as follows:
* \code
* #if defined(LIBUSB_API_VERSION) && (LIBUSB_API_VERSION >= 0x01001234)
* // Use one of the newer features from the libusb API
* #endif
* \endcode
*
* Another feature of LIBUSB_API_VERSION is that it can be used to detect
* whether you are compiling against the libusb or the libusb library.
*
* Internally, LIBUSB_API_VERSION is defined as follows:
* (libusb major << 24) | (libusb minor << 16) | (16 bit incremental)
*/
#define LIBUSB_API_VERSION 0x01000102
/* The following is kept for compatibility, but will be deprecated in the f
uture */
#define LIBUSBX_API_VERSION LIBUSB_API_VERSION
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
/** \def libusb_cpu_to_le16 /**
* \ingroup misc * \ingroup misc
* Convert a 16-bit value from host-endian to little-endian format. On * Convert a 16-bit value from host-endian to little-endian format. On
* little endian systems, this function does nothing. On big endian systems , * little endian systems, this function does nothing. On big endian systems ,
* the bytes are swapped. * the bytes are swapped.
* \param x the host-endian value to convert * \param x the host-endian value to convert
* \returns the value in little-endian byte order * \returns the value in little-endian byte order
*/ */
static inline uint16_t libusb_cpu_to_le16(const uint16_t x) static inline uint16_t libusb_cpu_to_le16(const uint16_t x)
{ {
union { union {
uint8_t b8[2]; uint8_t b8[2];
uint16_t b16; uint16_t b16;
} _tmp; } _tmp;
_tmp.b8[1] = x >> 8; _tmp.b8[1] = (uint8_t) (x >> 8);
_tmp.b8[0] = x & 0xff; _tmp.b8[0] = (uint8_t) (x & 0xff);
return _tmp.b16; return _tmp.b16;
} }
/** \def libusb_le16_to_cpu /** \def libusb_le16_to_cpu
* \ingroup misc * \ingroup misc
* Convert a 16-bit value from little-endian to host-endian format. On * Convert a 16-bit value from little-endian to host-endian format. On
* little endian systems, this function does nothing. On big endian systems , * little endian systems, this function does nothing. On big endian systems ,
* the bytes are swapped. * the bytes are swapped.
* \param x the little-endian value to convert * \param x the little-endian value to convert
* \returns the value in host-endian byte order * \returns the value in host-endian byte order
skipping to change at line 223 skipping to change at line 267
/** String descriptor */ /** String descriptor */
LIBUSB_DT_STRING = 0x03, LIBUSB_DT_STRING = 0x03,
/** Interface descriptor. See libusb_interface_descriptor. */ /** Interface descriptor. See libusb_interface_descriptor. */
LIBUSB_DT_INTERFACE = 0x04, LIBUSB_DT_INTERFACE = 0x04,
/** Endpoint descriptor. See libusb_endpoint_descriptor. */ /** Endpoint descriptor. See libusb_endpoint_descriptor. */
LIBUSB_DT_ENDPOINT = 0x05, LIBUSB_DT_ENDPOINT = 0x05,
/** BOS descriptor */
LIBUSB_DT_BOS = 0x0f,
/** Device Capability descriptor */
LIBUSB_DT_DEVICE_CAPABILITY = 0x10,
/** HID descriptor */ /** HID descriptor */
LIBUSB_DT_HID = 0x21, LIBUSB_DT_HID = 0x21,
/** HID report descriptor */ /** HID report descriptor */
LIBUSB_DT_REPORT = 0x22, LIBUSB_DT_REPORT = 0x22,
/** Physical descriptor */ /** Physical descriptor */
LIBUSB_DT_PHYSICAL = 0x23, LIBUSB_DT_PHYSICAL = 0x23,
/** Hub descriptor */ /** Hub descriptor */
LIBUSB_DT_HUB = 0x29, LIBUSB_DT_HUB = 0x29,
/** BOS descriptor */ /** SuperSpeed Hub descriptor */
LIBUSB_DT_BOS = 0x0f, LIBUSB_DT_SUPERSPEED_HUB = 0x2a,
/** Device Capability descriptor */
LIBUSB_DT_DEVICE_CAPABILITY = 0x10,
/** SuperSpeed Endpoint Companion descriptor */ /** SuperSpeed Endpoint Companion descriptor */
LIBUSB_DT_SS_ENDPOINT_COMPANION = 0x30 LIBUSB_DT_SS_ENDPOINT_COMPANION = 0x30
}; };
/* Descriptor sizes per descriptor type */ /* Descriptor sizes per descriptor type */
#define LIBUSB_DT_DEVICE_SIZE 18 #define LIBUSB_DT_DEVICE_SIZE 18
#define LIBUSB_DT_CONFIG_SIZE 9 #define LIBUSB_DT_CONFIG_SIZE 9
#define LIBUSB_DT_INTERFACE_SIZE 9 #define LIBUSB_DT_INTERFACE_SIZE 9
#define LIBUSB_DT_ENDPOINT_SIZE 7 #define LIBUSB_DT_ENDPOINT_SIZE 7
#define LIBUSB_DT_ENDPOINT_AUDIO_SIZE 9 /* Audio extension */ #define LIBUSB_DT_ENDPOINT_AUDIO_SIZE 9 /* Audio extension *
/
#define LIBUSB_DT_HUB_NONVAR_SIZE 7 #define LIBUSB_DT_HUB_NONVAR_SIZE 7
#define LIBUSB_DT_SS_ENDPOINT_COMPANION_SIZE 6 #define LIBUSB_DT_SS_ENDPOINT_COMPANION_SIZE 6
#define LIBUSB_DT_BOS_SIZE 5 #define LIBUSB_DT_BOS_SIZE 5
#define LIBUSB_USB_2_0_EXTENSION_DEVICE_CAPABILITY_SIZE 7 #define LIBUSB_DT_DEVICE_CAPABILITY_SIZE 3
#define LIBUSB_SS_USB_DEVICE_CAPABILITY_SIZE 10
#define LIBUSB_DT_BOS_MAX_SIZE ((LIBUSB_DT_BOS_SIZE) + \ /* BOS descriptor sizes */
(LIBUSB_USB_2_0_EXTENSION_DEVICE_CAP #define LIBUSB_BT_USB_2_0_EXTENSION_SIZE 7
ABILITY_SIZE) + \ #define LIBUSB_BT_SS_USB_DEVICE_CAPABILITY_SIZE 10
(LIBUSB_SS_USB_DEVICE_CAPABILITY_SIZ #define LIBUSB_BT_CONTAINER_ID_SIZE 20
E))
/* We unwrap the BOS => define its max size */
#define LIBUSB_DT_BOS_MAX_SIZE ((LIBUSB_DT_BOS_SIZE) +\
(LIBUSB_BT_USB_2_0_EXTENSION_SIZE)
+\
(LIBUSB_BT_SS_USB_DEVICE_CAPABILITY_
SIZE) +\
(LIBUSB_BT_CONTAINER_ID_SIZE))
#define LIBUSB_ENDPOINT_ADDRESS_MASK 0x0f /* in bEndpointAddress */ #define LIBUSB_ENDPOINT_ADDRESS_MASK 0x0f /* in bEndpointAddress */
#define LIBUSB_ENDPOINT_DIR_MASK 0x80 #define LIBUSB_ENDPOINT_DIR_MASK 0x80
/** \ingroup desc /** \ingroup desc
* Endpoint direction. Values for bit 7 of the * Endpoint direction. Values for bit 7 of the
* \ref libusb_endpoint_descriptor::bEndpointAddress "endpoint address" sch eme. * \ref libusb_endpoint_descriptor::bEndpointAddress "endpoint address" sch eme.
*/ */
enum libusb_endpoint_direction { enum libusb_endpoint_direction {
/** In: device-to-host */ /** In: device-to-host */
skipping to change at line 296 skipping to change at line 350
LIBUSB_TRANSFER_TYPE_ISOCHRONOUS = 1, LIBUSB_TRANSFER_TYPE_ISOCHRONOUS = 1,
/** Bulk endpoint */ /** Bulk endpoint */
LIBUSB_TRANSFER_TYPE_BULK = 2, LIBUSB_TRANSFER_TYPE_BULK = 2,
/** Interrupt endpoint */ /** Interrupt endpoint */
LIBUSB_TRANSFER_TYPE_INTERRUPT = 3 LIBUSB_TRANSFER_TYPE_INTERRUPT = 3
}; };
/** \ingroup misc /** \ingroup misc
* Standard requests, as defined in table 9-3 of the USB2 specifications */ * Standard requests, as defined in table 9-5 of the USB 3.0 specifications */
enum libusb_standard_request { enum libusb_standard_request {
/** Request status of the specific recipient */ /** Request status of the specific recipient */
LIBUSB_REQUEST_GET_STATUS = 0x00, LIBUSB_REQUEST_GET_STATUS = 0x00,
/** Clear or disable a specific feature */ /** Clear or disable a specific feature */
LIBUSB_REQUEST_CLEAR_FEATURE = 0x01, LIBUSB_REQUEST_CLEAR_FEATURE = 0x01,
/* 0x02 is reserved */ /* 0x02 is reserved */
/** Set or enable a specific feature */ /** Set or enable a specific feature */
skipping to change at line 334 skipping to change at line 388
LIBUSB_REQUEST_SET_CONFIGURATION = 0x09, LIBUSB_REQUEST_SET_CONFIGURATION = 0x09,
/** Return the selected alternate setting for the specified interfac e */ /** Return the selected alternate setting for the specified interfac e */
LIBUSB_REQUEST_GET_INTERFACE = 0x0A, LIBUSB_REQUEST_GET_INTERFACE = 0x0A,
/** Select an alternate interface for the specified interface */ /** Select an alternate interface for the specified interface */
LIBUSB_REQUEST_SET_INTERFACE = 0x0B, LIBUSB_REQUEST_SET_INTERFACE = 0x0B,
/** Set then report an endpoint's synchronization frame */ /** Set then report an endpoint's synchronization frame */
LIBUSB_REQUEST_SYNCH_FRAME = 0x0C, LIBUSB_REQUEST_SYNCH_FRAME = 0x0C,
/** Sets both the U1 and U2 Exit Latency */
LIBUSB_REQUEST_SET_SEL = 0x30,
/** Delay from the time a host transmits a packet to the time it is
* received by the device. */
LIBUSB_SET_ISOCH_DELAY = 0x31,
}; };
/** \ingroup misc /** \ingroup misc
* Request type bits of the * Request type bits of the
* \ref libusb_control_setup::bmRequestType "bmRequestType" field in contro l * \ref libusb_control_setup::bmRequestType "bmRequestType" field in contro l
* transfers. */ * transfers. */
enum libusb_request_type { enum libusb_request_type {
/** Standard */ /** Standard */
LIBUSB_REQUEST_TYPE_STANDARD = (0x00 << 5), LIBUSB_REQUEST_TYPE_STANDARD = (0x00 << 5),
skipping to change at line 413 skipping to change at line 474
/** Feedback endpoint */ /** Feedback endpoint */
LIBUSB_ISO_USAGE_TYPE_FEEDBACK = 1, LIBUSB_ISO_USAGE_TYPE_FEEDBACK = 1,
/** Implicit feedback Data endpoint */ /** Implicit feedback Data endpoint */
LIBUSB_ISO_USAGE_TYPE_IMPLICIT = 2, LIBUSB_ISO_USAGE_TYPE_IMPLICIT = 2,
}; };
/** \ingroup desc /** \ingroup desc
* A structure representing the standard USB device descriptor. This * A structure representing the standard USB device descriptor. This
* descriptor is documented in section 9.6.1 of the USB 2.0 specification. * descriptor is documented in section 9.6.1 of the USB 3.0 specification.
* All multiple-byte fields are represented in host-endian format. * All multiple-byte fields are represented in host-endian format.
*/ */
struct libusb_device_descriptor { struct libusb_device_descriptor {
/** Size of this descriptor (in bytes) */ /** Size of this descriptor (in bytes) */
uint8_t bLength; uint8_t bLength;
/** Descriptor type. Will have value /** Descriptor type. Will have value
* \ref libusb_descriptor_type::LIBUSB_DT_DEVICE LIBUSB_DT_DEVICE in this * \ref libusb_descriptor_type::LIBUSB_DT_DEVICE LIBUSB_DT_DEVICE in this
* context. */ * context. */
uint8_t bDescriptorType; uint8_t bDescriptorType;
skipping to change at line 466 skipping to change at line 527
uint8_t iProduct; uint8_t iProduct;
/** Index of string descriptor containing device serial number */ /** Index of string descriptor containing device serial number */
uint8_t iSerialNumber; uint8_t iSerialNumber;
/** Number of possible configurations */ /** Number of possible configurations */
uint8_t bNumConfigurations; uint8_t bNumConfigurations;
}; };
/** \ingroup desc /** \ingroup desc
* A structure representing the superspeed endpoint companion
* descriptor. This descriptor is documented in section 9.6.7 of
* the USB 3.0 specification. All ultiple-byte fields are represented in
* host-endian format.
*/
struct libusb_ss_endpoint_companion_descriptor {
/** Size of this descriptor (in bytes) */
uint8_t bLength;
/** Descriptor type. Will have value
* \ref libusb_descriptor_type::LIBUSB_DT_SS_ENDPOINT_COMPANION in
* this context. */
uint8_t bDescriptorType;
/** The maximum number of packets the endpoint can send or
* recieve as part of a burst. */
uint8_t bMaxBurst;
/** In bulk EP: bits 4:0 represents the maximum number of
* streams the EP supports. In isochronous EP: bits 1:0
* represents the Mult - a zero based value that determines
* the maximum number of packets within a service interval */
uint8_t bmAttributes;
/** The total number of bytes this EP will transfer every
* service interval. valid only for periodic EPs. */
uint16_t wBytesPerInterval;
};
/** \ingroup desc
* A structure representing the standard USB endpoint descriptor. This * A structure representing the standard USB endpoint descriptor. This
* descriptor is documented in section 9.6.3 of the USB 2.0 specification. * descriptor is documented in section 9.6.6 of the USB 3.0 specification.
* All multiple-byte fields are represented in host-endian format. * All multiple-byte fields are represented in host-endian format.
*/ */
struct libusb_endpoint_descriptor { struct libusb_endpoint_descriptor {
/** Size of this descriptor (in bytes) */ /** Size of this descriptor (in bytes) */
uint8_t bLength; uint8_t bLength;
/** Descriptor type. Will have value /** Descriptor type. Will have value
* \ref libusb_descriptor_type::LIBUSB_DT_ENDPOINT LIBUSB_DT_ENDPOIN T in * \ref libusb_descriptor_type::LIBUSB_DT_ENDPOINT LIBUSB_DT_ENDPOIN T in
* this context. */ * this context. */
uint8_t bDescriptorType; uint8_t bDescriptorType;
skipping to change at line 548 skipping to change at line 578
/** Extra descriptors. If libusb encounters unknown endpoint descrip tors, /** Extra descriptors. If libusb encounters unknown endpoint descrip tors,
* it will store them here, should you wish to parse them. */ * it will store them here, should you wish to parse them. */
const unsigned char *extra; const unsigned char *extra;
/** Length of the extra descriptors, in bytes. */ /** Length of the extra descriptors, in bytes. */
int extra_length; int extra_length;
}; };
/** \ingroup desc /** \ingroup desc
* A structure representing the standard USB interface descriptor. This * A structure representing the standard USB interface descriptor. This
* descriptor is documented in section 9.6.5 of the USB 2.0 specification. * descriptor is documented in section 9.6.5 of the USB 3.0 specification.
* All multiple-byte fields are represented in host-endian format. * All multiple-byte fields are represented in host-endian format.
*/ */
struct libusb_interface_descriptor { struct libusb_interface_descriptor {
/** Size of this descriptor (in bytes) */ /** Size of this descriptor (in bytes) */
uint8_t bLength; uint8_t bLength;
/** Descriptor type. Will have value /** Descriptor type. Will have value
* \ref libusb_descriptor_type::LIBUSB_DT_INTERFACE LIBUSB_DT_INTERF ACE * \ref libusb_descriptor_type::LIBUSB_DT_INTERFACE LIBUSB_DT_INTERF ACE
* in this context. */ * in this context. */
uint8_t bDescriptorType; uint8_t bDescriptorType;
skipping to change at line 610 skipping to change at line 640
/** Array of interface descriptors. The length of this array is dete rmined /** Array of interface descriptors. The length of this array is dete rmined
* by the num_altsetting field. */ * by the num_altsetting field. */
const struct libusb_interface_descriptor *altsetting; const struct libusb_interface_descriptor *altsetting;
/** The number of alternate settings that belong to this interface * / /** The number of alternate settings that belong to this interface * /
int num_altsetting; int num_altsetting;
}; };
/** \ingroup desc /** \ingroup desc
* A structure representing the standard USB configuration descriptor. This * A structure representing the standard USB configuration descriptor. This
* descriptor is documented in section 9.6.3 of the USB 2.0 specification. * descriptor is documented in section 9.6.3 of the USB 3.0 specification.
* All multiple-byte fields are represented in host-endian format. * All multiple-byte fields are represented in host-endian format.
*/ */
struct libusb_config_descriptor { struct libusb_config_descriptor {
/** Size of this descriptor (in bytes) */ /** Size of this descriptor (in bytes) */
uint8_t bLength; uint8_t bLength;
/** Descriptor type. Will have value /** Descriptor type. Will have value
* \ref libusb_descriptor_type::LIBUSB_DT_CONFIG LIBUSB_DT_CONFIG * \ref libusb_descriptor_type::LIBUSB_DT_CONFIG LIBUSB_DT_CONFIG
* in this context. */ * in this context. */
uint8_t bDescriptorType; uint8_t bDescriptorType;
skipping to change at line 655 skipping to change at line 685
/** Extra descriptors. If libusb encounters unknown configuration /** Extra descriptors. If libusb encounters unknown configuration
* descriptors, it will store them here, should you wish to parse th em. */ * descriptors, it will store them here, should you wish to parse th em. */
const unsigned char *extra; const unsigned char *extra;
/** Length of the extra descriptors, in bytes. */ /** Length of the extra descriptors, in bytes. */
int extra_length; int extra_length;
}; };
/** \ingroup desc /** \ingroup desc
* A structure representing the BOS descriptor. This * A structure representing the superspeed endpoint companion
* descriptor is documented in section 9.6.2 of the USB 3.0 * descriptor. This descriptor is documented in section 9.6.7 of
* specification. All multiple-byte fields are represented in * the USB 3.0 specification. All multiple-byte fields are represented in
* host-endian format. * host-endian format.
*/ */
struct libusb_ss_endpoint_companion_descriptor {
/** Size of this descriptor (in bytes) */
uint8_t bLength;
/** Descriptor type. Will have value
* \ref libusb_descriptor_type::LIBUSB_DT_SS_ENDPOINT_COMPANION in
* this context. */
uint8_t bDescriptorType;
/** The maximum number of packets the endpoint can send or
* recieve as part of a burst. */
uint8_t bMaxBurst;
/** In bulk EP: bits 4:0 represents the maximum number of
* streams the EP supports. In isochronous EP: bits 1:0
* represents the Mult - a zero based value that determines
* the maximum number of packets within a service interval */
uint8_t bmAttributes;
/** The total number of bytes this EP will transfer every
* service interval. valid only for periodic EPs. */
uint16_t wBytesPerInterval;
};
/** \ingroup desc
* A generic representation of a BOS Device Capability descriptor. It is
* advised to check bDevCapabilityType and call the matching
* libusb_get_*_descriptor function to get a structure fully matching the t
ype.
*/
struct libusb_bos_dev_capability_descriptor {
/** Size of this descriptor (in bytes) */
uint8_t bLength;
/** Descriptor type. Will have value
* \ref libusb_descriptor_type::LIBUSB_DT_DEVICE_CAPABILITY
* LIBUSB_DT_DEVICE_CAPABILITY in this context. */
uint8_t bDescriptorType;
/** Device Capability type */
uint8_t bDevCapabilityType;
/** Device Capability data (bLength - 3 bytes) */
uint8_t dev_capability_data
#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
[] /* valid C99 code */
#else
[0] /* non-standard, but usually working code */
#endif
;
};
/** \ingroup desc
* A structure representing the Binary Device Object Store (BOS) descriptor
.
* This descriptor is documented in section 9.6.2 of the USB 3.0 specificat
ion.
* All multiple-byte fields are represented in host-endian format.
*/
struct libusb_bos_descriptor { struct libusb_bos_descriptor {
/** Size of this descriptor (in bytes) */ /** Size of this descriptor (in bytes) */
uint8_t bLength; uint8_t bLength;
/** Descriptor type. Will have value /** Descriptor type. Will have value
* \ref libusb_descriptor_type::LIBUSB_DT_BOS LIBUSB_DT_BOS * \ref libusb_descriptor_type::LIBUSB_DT_BOS LIBUSB_DT_BOS
* in this context. */ * in this context. */
uint8_t bDescriptorType; uint8_t bDescriptorType;
/** Length of this descriptor and all of its sub descriptors */ /** Length of this descriptor and all of its sub descriptors */
uint16_t wTotalLength; uint16_t wTotalLength;
/** The number of separate device capability descriptors in /** The number of separate device capability descriptors in
* the BOS */ * the BOS */
uint8_t bNumDeviceCaps; uint8_t bNumDeviceCaps;
/** USB 2.0 extension capability descriptor */ /** bNumDeviceCap Device Capability Descriptors */
struct libusb_usb_2_0_device_capability_descriptor *usb_2_0_ext_cap; struct libusb_bos_dev_capability_descriptor *dev_capability
#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
/** SuperSpeed capabilty descriptor */ [] /* valid C99 code */
struct libusb_ss_usb_device_capability_descriptor *ss_usb_cap; #else
[0] /* non-standard, but usually working code */
#endif
;
}; };
/** \ingroup desc /** \ingroup desc
* A structure representing the device capability descriptor for * A structure representing the USB 2.0 Extension descriptor
* USB 2.0. This descriptor is documented in section 9.6.2.1 of * This descriptor is documented in section 9.6.2.1 of the USB 3.0 specific
* the USB 3.0 specification. All mutiple-byte fields are represented ation.
* in host-endian format. * All multiple-byte fields are represented in host-endian format.
*/ */
struct libusb_usb_2_0_device_capability_descriptor { struct libusb_usb_2_0_extension_descriptor {
/** Size of this descriptor (in bytes) */ /** Size of this descriptor (in bytes) */
uint8_t bLength; uint8_t bLength;
/** Descriptor type. Will have value /** Descriptor type. Will have value
* \ref libusb_descriptor_type::LIBUSB_DT_DEVICE_CAPABILITY * \ref libusb_descriptor_type::LIBUSB_DT_DEVICE_CAPABILITY
* LIBUSB_DT_DEVICE_CAPABILITY in this context. */ * LIBUSB_DT_DEVICE_CAPABILITY in this context. */
uint8_t bDescriptorType; uint8_t bDescriptorType;
/** Capability type. Will have value /** Capability type. Will have value
* \ref libusb_capability_type::LIBUSB_USB_CAP_TYPE_EXT * \ref libusb_capability_type::LIBUSB_BT_USB_2_0_EXTENSION
* LIBUSB_USB_CAP_TYPE_EXT in this context. */ * LIBUSB_BT_USB_2_0_EXTENSION in this context. */
uint8_t bDevCapabilityType; uint8_t bDevCapabilityType;
/** Bitmap encoding of supported device level features. /** Bitmap encoding of supported device level features.
* A value of one in a bit location indicates a feature is * A value of one in a bit location indicates a feature is
* supported; a value of zero indicates it is not supported. * supported; a value of zero indicates it is not supported.
* See \ref libusb_capability_attributes. */ * See \ref libusb_usb_2_0_extension_attributes. */
uint32_t bmAttributes; uint32_t bmAttributes;
}; };
/** \ingroup desc /** \ingroup desc
* A structure representing the device capability descriptor for * A structure representing the SuperSpeed USB Device Capability descriptor
* USB 3.0. This descriptor is documented in section 9.6.2.2 of * This descriptor is documented in section 9.6.2.2 of the USB 3.0 specific
* the USB 3.0 specification. All mutiple-byte fields are represented ation.
* in host-endian format. * All multiple-byte fields are represented in host-endian format.
*/ */
struct libusb_ss_usb_device_capability_descriptor { struct libusb_ss_usb_device_capability_descriptor {
/** Size of this descriptor (in bytes) */ /** Size of this descriptor (in bytes) */
uint8_t bLength; uint8_t bLength;
/** Descriptor type. Will have value /** Descriptor type. Will have value
* \ref libusb_descriptor_type::LIBUSB_DT_DEVICE_CAPABILITY * \ref libusb_descriptor_type::LIBUSB_DT_DEVICE_CAPABILITY
* LIBUSB_DT_DEVICE_CAPABILITY in this context. */ * LIBUSB_DT_DEVICE_CAPABILITY in this context. */
uint8_t bDescriptorType; uint8_t bDescriptorType;
/** Capability type. Will have value /** Capability type. Will have value
* \ref libusb_capability_type::LIBUSB_SS_USB_CAP_TYPE * \ref libusb_capability_type::LIBUSB_BT_SS_USB_DEVICE_CAPABILITY
* LIBUSB_SS_USB_CAP_TYPE in this context. */ * LIBUSB_BT_SS_USB_DEVICE_CAPABILITY in this context. */
uint8_t bDevCapabilityType; uint8_t bDevCapabilityType;
/** Bitmap encoding of supported device level features. /** Bitmap encoding of supported device level features.
* A value of one in a bit location indicates a feature is * A value of one in a bit location indicates a feature is
* supported; a value of zero indicates it is not supported. * supported; a value of zero indicates it is not supported.
* See \ref libusb_capability_attributes. */ * See \ref libusb_ss_usb_device_capability_attributes. */
uint8_t bmAttributes; uint8_t bmAttributes;
/** Bitmap encoding of the speed supported by this device when /** Bitmap encoding of the speed supported by this device when
* operating in SuperSpeed mode. See \ref libusb_supported_speed. */ * operating in SuperSpeed mode. See \ref libusb_supported_speed. */
uint16_t wSpeedSupported; uint16_t wSpeedSupported;
/** The lowest speed at which all the functionality supported /** The lowest speed at which all the functionality supported
* by the device is available to the user. For example if the * by the device is available to the user. For example if the
* device supports all its functionality when connected at * device supports all its functionality when connected at
* full speed and above then it sets this value to 1. */ * full speed and above then it sets this value to 1. */
uint8_t bFunctionalitySupport; uint8_t bFunctionalitySupport;
/** U1 Device Exit Latency. */ /** U1 Device Exit Latency. */
uint8_t bU1DevExitLat; uint8_t bU1DevExitLat;
/** U2 Device Exit Latency. */ /** U2 Device Exit Latency. */
uint16_t bU2DevExitLat; uint16_t bU2DevExitLat;
}; };
/** \ingroup desc
* A structure representing the Container ID descriptor.
* This descriptor is documented in section 9.6.2.3 of the USB 3.0 specific
ation.
* All multiple-byte fields, except UUIDs, are represented in host-endian f
ormat.
*/
struct libusb_container_id_descriptor {
/** Size of this descriptor (in bytes) */
uint8_t bLength;
/** Descriptor type. Will have value
* \ref libusb_descriptor_type::LIBUSB_DT_DEVICE_CAPABILITY
* LIBUSB_DT_DEVICE_CAPABILITY in this context. */
uint8_t bDescriptorType;
/** Capability type. Will have value
* \ref libusb_capability_type::LIBUSB_BT_CONTAINER_ID
* LIBUSB_BT_CONTAINER_ID in this context. */
uint8_t bDevCapabilityType;
/** Reserved field */
uint8_t bReserved;
/** 128 bit UUID */
uint8_t ContainerID[16];
};
/** \ingroup asyncio /** \ingroup asyncio
* Setup packet for control transfers. */ * Setup packet for control transfers. */
struct libusb_control_setup { struct libusb_control_setup {
/** Request type. Bits 0:4 determine recipient, see /** Request type. Bits 0:4 determine recipient, see
* \ref libusb_request_recipient. Bits 5:6 determine type, see * \ref libusb_request_recipient. Bits 5:6 determine type, see
* \ref libusb_request_type. Bit 7 determines data transfer directio n, see * \ref libusb_request_type. Bit 7 determines data transfer directio n, see
* \ref libusb_endpoint_direction. * \ref libusb_endpoint_direction.
*/ */
uint8_t bmRequestType; uint8_t bmRequestType;
skipping to change at line 791 skipping to change at line 902
#define LIBUSB_CONTROL_SETUP_SIZE (sizeof(struct libusb_control_setup)) #define LIBUSB_CONTROL_SETUP_SIZE (sizeof(struct libusb_control_setup))
/* libusb */ /* libusb */
struct libusb_context; struct libusb_context;
struct libusb_device; struct libusb_device;
struct libusb_device_handle; struct libusb_device_handle;
struct libusb_hotplug_callback; struct libusb_hotplug_callback;
/** \ingroup lib /** \ingroup lib
* Structure representing the libusb version. * Structure providing the version of the libusb runtime
*/ */
struct libusb_version { struct libusb_version {
/** Library major version. */ /** Library major version. */
const uint16_t major; const uint16_t major;
/** Library minor version. */ /** Library minor version. */
const uint16_t minor; const uint16_t minor;
/** Library micro version. */ /** Library micro version. */
const uint16_t micro; const uint16_t micro;
/** Library nano version. This field is only nonzero on Windows. */ /** Library nano version. */
const uint16_t nano; const uint16_t nano;
/** Library release candidate suffix string, e.g. "-rc4". */ /** Library release candidate suffix string, e.g. "-rc4". */
const char *rc; const char *rc;
/** Output of `git describe --tags` at library build time. */ /** For ABI compatibility only. */
const char *describe; const char* describe;
}; };
/** \ingroup lib /** \ingroup lib
* Structure representing a libusb session. The concept of individual libus b * Structure representing a libusb session. The concept of individual libus b
* sessions allows for your program to use two libraries (or dynamically * sessions allows for your program to use two libraries (or dynamically
* load two modules) which both independently use libusb. This will prevent * load two modules) which both independently use libusb. This will prevent
* interference between the individual libusb users - for example * interference between the individual libusb users - for example
* libusb_set_debug() will not affect the other user of the library, and * libusb_set_debug() will not affect the other user of the library, and
* libusb_exit() will not destroy resources that the other user is still * libusb_exit() will not destroy resources that the other user is still
* using. * using.
skipping to change at line 863 skipping to change at line 974
* *
* A device handle is used to perform I/O and other operations. When finish ed * A device handle is used to perform I/O and other operations. When finish ed
* with a device handle, you should call libusb_close(). * with a device handle, you should call libusb_close().
*/ */
typedef struct libusb_device_handle libusb_device_handle; typedef struct libusb_device_handle libusb_device_handle;
/** \ingroup dev /** \ingroup dev
* Speed codes. Indicates the speed at which the device is operating. * Speed codes. Indicates the speed at which the device is operating.
*/ */
enum libusb_speed { enum libusb_speed {
/** The OS doesn't report or know the device speed. */ /** The OS doesn't report or know the device speed. */
LIBUSB_SPEED_UNKNOWN = 0, LIBUSB_SPEED_UNKNOWN = 0,
/** The device is operating at low speed (1.5MBit/s). */ /** The device is operating at low speed (1.5MBit/s). */
LIBUSB_SPEED_LOW = 1, LIBUSB_SPEED_LOW = 1,
/** The device is operating at full speed (12MBit/s). */ /** The device is operating at full speed (12MBit/s). */
LIBUSB_SPEED_FULL = 2, LIBUSB_SPEED_FULL = 2,
/** The device is operating at high speed (480MBit/s). */ /** The device is operating at high speed (480MBit/s). */
LIBUSB_SPEED_HIGH = 3, LIBUSB_SPEED_HIGH = 3,
/** The device is operating at super speed (5000MBit/s). */ /** The device is operating at super speed (5000MBit/s). */
LIBUSB_SPEED_SUPER = 4, LIBUSB_SPEED_SUPER = 4,
}; };
/** \ingroup dev /** \ingroup dev
* Supported speeds (wSpeedSupported) bitfield. Indicates what * Supported speeds (wSpeedSupported) bitfield. Indicates what
* speeds the device supports. * speeds the device supports.
*/ */
enum libusb_supported_speed { enum libusb_supported_speed {
/** Low speed operation supported (1.5MBit/s). */ /** Low speed operation supported (1.5MBit/s). */
LIBUSB_LOW_SPEED_OPERATION = 1, LIBUSB_LOW_SPEED_OPERATION = 1,
/** Full speed operation supported (12MBit/s). */ /** Full speed operation supported (12MBit/s). */
LIBUSB_FULL_SPEED_OPERATION = 2, LIBUSB_FULL_SPEED_OPERATION = 2,
/** High speed operation supported (480MBit/s). */ /** High speed operation supported (480MBit/s). */
LIBUSB_HIGH_SPEED_OPERATION = 4, LIBUSB_HIGH_SPEED_OPERATION = 4,
/** Superspeed operation supported (5000MBit/s). */ /** Superspeed operation supported (5000MBit/s). */
LIBUSB_5GBPS_OPERATION = 8, LIBUSB_SUPER_SPEED_OPERATION = 8,
}; };
/** \ingroup dev /** \ingroup dev
* Capability attributes * Masks for the bits of the
* \ref libusb_usb_2_0_extension_descriptor::bmAttributes "bmAttributes" fi
eld
* of the USB 2.0 Extension descriptor.
*/ */
enum libusb_capability_attributes { enum libusb_usb_2_0_extension_attributes {
/** Supports Link Power Management (LPM) */ /** Supports Link Power Management (LPM) */
LIBUSB_LPM_SUPPORT = 2, LIBUSB_BM_LPM_SUPPORT = 2,
};
/** \ingroup dev
* Masks for the bits of the
* \ref libusb_ss_usb_device_capability_descriptor::bmAttributes "bmAttribu
tes" field
* field of the SuperSpeed USB Device Capability descriptor.
*/
enum libusb_ss_usb_device_capability_attributes {
/** Supports Latency Tolerance Messages (LTM) */
LIBUSB_BM_LTM_SUPPORT = 2,
}; };
/** \ingroup dev /** \ingroup dev
* USB capability types * USB capability types
*/ */
enum libusb_capability_type { enum libusb_bos_type {
/** USB 2.0 extension capability type */ /** Wireless USB device capability */
LIBUSB_USB_CAP_TYPE_EXT = 2, LIBUSB_BT_WIRELESS_USB_DEVICE_CAPABILITY = 1,
/** SuperSpeed capability type */ /** USB 2.0 extensions */
LIBUSB_SS_USB_CAP_TYPE = 3, LIBUSB_BT_USB_2_0_EXTENSION = 2,
/** SuperSpeed USB device capability */
LIBUSB_BT_SS_USB_DEVICE_CAPABILITY = 3,
/** Container ID type */
LIBUSB_BT_CONTAINER_ID = 4,
}; };
/** \ingroup misc /** \ingroup misc
* Error codes. Most libusb functions return 0 on success or one of these * Error codes. Most libusb functions return 0 on success or one of these
* codes on failure. * codes on failure.
* You can call \ref libusb_error_name() to retrieve a string representatio * You can call libusb_error_name() to retrieve a string representation of
n an
* of an error code or \ret libusb_strerror() to get an english description * error code or libusb_strerror() to get an end-user suitable description
* of an error code. of
* an error code.
*/ */
enum libusb_error { enum libusb_error {
/** Success (no error) */ /** Success (no error) */
LIBUSB_SUCCESS = 0, LIBUSB_SUCCESS = 0,
/** Input/output error */ /** Input/output error */
LIBUSB_ERROR_IO = -1, LIBUSB_ERROR_IO = -1,
/** Invalid parameter */ /** Invalid parameter */
LIBUSB_ERROR_INVALID_PARAM = -2, LIBUSB_ERROR_INVALID_PARAM = -2,
skipping to change at line 963 skipping to change at line 1092
/** System call interrupted (perhaps due to signal) */ /** System call interrupted (perhaps due to signal) */
LIBUSB_ERROR_INTERRUPTED = -10, LIBUSB_ERROR_INTERRUPTED = -10,
/** Insufficient memory */ /** Insufficient memory */
LIBUSB_ERROR_NO_MEM = -11, LIBUSB_ERROR_NO_MEM = -11,
/** Operation not supported or unimplemented on this platform */ /** Operation not supported or unimplemented on this platform */
LIBUSB_ERROR_NOT_SUPPORTED = -12, LIBUSB_ERROR_NOT_SUPPORTED = -12,
/* NB! Remember to update libusb_error_name() and /* NB: Remember to update LIBUSB_ERROR_COUNT below as well as the
libusb_strerror() when adding new error codes here. */ message strings in strerror.c when adding new error codes here. *
/
/** Other error */ /** Other error */
LIBUSB_ERROR_OTHER = -99, LIBUSB_ERROR_OTHER = -99,
}; };
/* Total number of error codes in enum libusb_error */
#define LIBUSB_ERROR_COUNT 14
/** \ingroup asyncio /** \ingroup asyncio
* Transfer status codes */ * Transfer status codes */
enum libusb_transfer_status { enum libusb_transfer_status {
/** Transfer completed without error. Note that this does not indica te /** Transfer completed without error. Note that this does not indica te
* that the entire amount of requested data was transferred. */ * that the entire amount of requested data was transferred. */
LIBUSB_TRANSFER_COMPLETED, LIBUSB_TRANSFER_COMPLETED,
/** Transfer failed */ /** Transfer failed */
LIBUSB_TRANSFER_ERROR, LIBUSB_TRANSFER_ERROR,
skipping to change at line 995 skipping to change at line 1127
/** For bulk/interrupt endpoints: halt condition detected (endpoint /** For bulk/interrupt endpoints: halt condition detected (endpoint
* stalled). For control endpoints: control request not supported. * / * stalled). For control endpoints: control request not supported. * /
LIBUSB_TRANSFER_STALL, LIBUSB_TRANSFER_STALL,
/** Device was disconnected */ /** Device was disconnected */
LIBUSB_TRANSFER_NO_DEVICE, LIBUSB_TRANSFER_NO_DEVICE,
/** Device sent more data than requested */ /** Device sent more data than requested */
LIBUSB_TRANSFER_OVERFLOW, LIBUSB_TRANSFER_OVERFLOW,
/* NB! Remember to update libusb_error_name()
when adding new status codes here. */
}; };
/** \ingroup asyncio /** \ingroup asyncio
* libusb_transfer.flags values */ * libusb_transfer.flags values */
enum libusb_transfer_flags { enum libusb_transfer_flags {
/** Report short frames as errors */ /** Report short frames as errors */
LIBUSB_TRANSFER_SHORT_NOT_OK = 1<<0, LIBUSB_TRANSFER_SHORT_NOT_OK = 1<<0,
/** Automatically free() transfer buffer during libusb_free_transfer () */ /** Automatically free() transfer buffer during libusb_free_transfer () */
LIBUSB_TRANSFER_FREE_BUFFER = 1<<1, LIBUSB_TRANSFER_FREE_BUFFER = 1<<1,
skipping to change at line 1129 skipping to change at line 1264
struct libusb_iso_packet_descriptor iso_packet_desc struct libusb_iso_packet_descriptor iso_packet_desc
#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) #if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L)
[] /* valid C99 code */ [] /* valid C99 code */
#else #else
[0] /* non-standard, but usually working code */ [0] /* non-standard, but usually working code */
#endif #endif
; ;
}; };
/** \ingroup misc /** \ingroup misc
* Capabilities supported by this instance of libusb. Test if the loaded * Capabilities supported by an instance of libusb on the current running
* library supports a given capability by calling * platform. Test if the loaded library supports a given capability by call
ing
* \ref libusb_has_capability(). * \ref libusb_has_capability().
*/ */
enum libusb_capability { enum libusb_capability {
/** The libusb_has_capability() API is available. */ /** The libusb_has_capability() API is available. */
LIBUSB_CAP_HAS_CAPABILITY = 0, LIBUSB_CAP_HAS_CAPABILITY = 0x0000,
/** The libusb hotplug API is available. */ /** Hotplug support is available on this platform. */
LIBUSB_CAP_HAS_HOTPLUG = 1, LIBUSB_CAP_HAS_HOTPLUG = 0x0001,
/** The library can access HID devices without requiring user interv
ention.
* Note that before being able to actually access an HID device, you
may
* still have to call additional libusb functions such as
* \ref libusb_detach_kernel_driver(). */
LIBUSB_CAP_HAS_HID_ACCESS = 0x0100,
/** The library supports detaching of the default USB driver, using
* \ref libusb_detach_kernel_driver(), if one is set by the OS kerne
l */
LIBUSB_CAP_SUPPORTS_DETACH_KERNEL_DRIVER = 0x0101
};
/** \ingroup lib
* Log message levels.
* - LIBUSB_LOG_LEVEL_NONE (0) : no messages ever printed by the librar
y (default)
* - LIBUSB_LOG_LEVEL_ERROR (1) : error messages are printed to stderr
* - LIBUSB_LOG_LEVEL_WARNING (2) : warning and error messages are printed
to stderr
* - LIBUSB_LOG_LEVEL_INFO (3) : informational messages are printed to
stdout, warning
* and error messages are printed to stderr
* - LIBUSB_LOG_LEVEL_DEBUG (4) : debug and informational messages are p
rinted to stdout,
* warnings and errors to stderr
*/
enum libusb_log_level {
LIBUSB_LOG_LEVEL_NONE = 0,
LIBUSB_LOG_LEVEL_ERROR,
LIBUSB_LOG_LEVEL_WARNING,
LIBUSB_LOG_LEVEL_INFO,
LIBUSB_LOG_LEVEL_DEBUG,
}; };
int LIBUSB_CALL libusb_init(libusb_context **ctx); int LIBUSB_CALL libusb_init(libusb_context **ctx);
void LIBUSB_CALL libusb_exit(libusb_context *ctx); void LIBUSB_CALL libusb_exit(libusb_context *ctx);
void LIBUSB_CALL libusb_set_debug(libusb_context *ctx, int level); void LIBUSB_CALL libusb_set_debug(libusb_context *ctx, int level);
const struct libusb_version * LIBUSB_CALL libusb_get_version(void); const struct libusb_version * LIBUSB_CALL libusb_get_version(void);
int LIBUSB_CALL libusb_has_capability(uint32_t capability); int LIBUSB_CALL libusb_has_capability(uint32_t capability);
const char * LIBUSB_CALL libusb_error_name(int errcode); const char * LIBUSB_CALL libusb_error_name(int errcode);
int LIBUSB_CALL libusb_setlocale(const char *locale);
const char * LIBUSB_CALL libusb_strerror(enum libusb_error errcode); const char * LIBUSB_CALL libusb_strerror(enum libusb_error errcode);
ssize_t LIBUSB_CALL libusb_get_device_list(libusb_context *ctx, ssize_t LIBUSB_CALL libusb_get_device_list(libusb_context *ctx,
libusb_device ***list); libusb_device ***list);
void LIBUSB_CALL libusb_free_device_list(libusb_device **list, void LIBUSB_CALL libusb_free_device_list(libusb_device **list,
int unref_devices); int unref_devices);
libusb_device * LIBUSB_CALL libusb_ref_device(libusb_device *dev); libusb_device * LIBUSB_CALL libusb_ref_device(libusb_device *dev);
void LIBUSB_CALL libusb_unref_device(libusb_device *dev); void LIBUSB_CALL libusb_unref_device(libusb_device *dev);
int LIBUSB_CALL libusb_get_configuration(libusb_device_handle *dev, int LIBUSB_CALL libusb_get_configuration(libusb_device_handle *dev,
skipping to change at line 1167 skipping to change at line 1329
int LIBUSB_CALL libusb_get_device_descriptor(libusb_device *dev, int LIBUSB_CALL libusb_get_device_descriptor(libusb_device *dev,
struct libusb_device_descriptor *desc); struct libusb_device_descriptor *desc);
int LIBUSB_CALL libusb_get_active_config_descriptor(libusb_device *dev, int LIBUSB_CALL libusb_get_active_config_descriptor(libusb_device *dev,
struct libusb_config_descriptor **config); struct libusb_config_descriptor **config);
int LIBUSB_CALL libusb_get_config_descriptor(libusb_device *dev, int LIBUSB_CALL libusb_get_config_descriptor(libusb_device *dev,
uint8_t config_index, struct libusb_config_descriptor **config); uint8_t config_index, struct libusb_config_descriptor **config);
int LIBUSB_CALL libusb_get_config_descriptor_by_value(libusb_device *dev, int LIBUSB_CALL libusb_get_config_descriptor_by_value(libusb_device *dev,
uint8_t bConfigurationValue, struct libusb_config_descriptor **confi g); uint8_t bConfigurationValue, struct libusb_config_descriptor **confi g);
void LIBUSB_CALL libusb_free_config_descriptor( void LIBUSB_CALL libusb_free_config_descriptor(
struct libusb_config_descriptor *config); struct libusb_config_descriptor *config);
int LIBUSB_CALL libusb_get_ss_endpoint_companion_descriptor(
struct libusb_context *ctx,
const struct libusb_endpoint_descriptor *endpoint,
struct libusb_ss_endpoint_companion_descriptor **ep_comp);
void LIBUSB_CALL libusb_free_ss_endpoint_companion_descriptor(
struct libusb_ss_endpoint_companion_descriptor *ep_comp);
int LIBUSB_CALL libusb_get_bos_descriptor(libusb_device_handle *handle,
struct libusb_bos_descriptor **bos);
void LIBUSB_CALL libusb_free_bos_descriptor(struct libusb_bos_descriptor *b
os);
int LIBUSB_CALL libusb_get_usb_2_0_extension_descriptor(
struct libusb_context *ctx,
struct libusb_bos_dev_capability_descriptor *dev_cap,
struct libusb_usb_2_0_extension_descriptor **usb_2_0_extension);
void LIBUSB_CALL libusb_free_usb_2_0_extension_descriptor(
struct libusb_usb_2_0_extension_descriptor *usb_2_0_extension);
int LIBUSB_CALL libusb_get_ss_usb_device_capability_descriptor(
struct libusb_context *ctx,
struct libusb_bos_dev_capability_descriptor *dev_cap,
struct libusb_ss_usb_device_capability_descriptor **ss_usb_device_ca
p);
void LIBUSB_CALL libusb_free_ss_usb_device_capability_descriptor(
struct libusb_ss_usb_device_capability_descriptor *ss_usb_device_cap
);
int LIBUSB_CALL libusb_get_container_id_descriptor(struct libusb_context *c
tx,
struct libusb_bos_dev_capability_descriptor *dev_cap,
struct libusb_container_id_descriptor **container_id);
void LIBUSB_CALL libusb_free_container_id_descriptor(
struct libusb_container_id_descriptor *container_id);
uint8_t LIBUSB_CALL libusb_get_bus_number(libusb_device *dev); uint8_t LIBUSB_CALL libusb_get_bus_number(libusb_device *dev);
uint8_t LIBUSB_CALL libusb_get_port_number(libusb_device *dev);
int LIBUSB_CALL libusb_get_port_numbers(libusb_device *dev, uint8_t* port_n
umbers, int port_numbers_len);
LIBUSB_DEPRECATED_FOR(libusb_get_port_numbers)
int LIBUSB_CALL libusb_get_port_path(libusb_context *ctx, libusb_device *de
v, uint8_t* path, uint8_t path_length);
libusb_device * LIBUSB_CALL libusb_get_parent(libusb_device *dev);
uint8_t LIBUSB_CALL libusb_get_device_address(libusb_device *dev); uint8_t LIBUSB_CALL libusb_get_device_address(libusb_device *dev);
int LIBUSB_CALL libusb_get_device_speed(libusb_device *dev); int LIBUSB_CALL libusb_get_device_speed(libusb_device *dev);
int LIBUSB_CALL libusb_get_max_packet_size(libusb_device *dev, int LIBUSB_CALL libusb_get_max_packet_size(libusb_device *dev,
unsigned char endpoint); unsigned char endpoint);
int LIBUSB_CALL libusb_get_max_iso_packet_size(libusb_device *dev, int LIBUSB_CALL libusb_get_max_iso_packet_size(libusb_device *dev,
unsigned char endpoint); unsigned char endpoint);
int LIBUSB_CALL libusb_open(libusb_device *dev, libusb_device_handle **hand le); int LIBUSB_CALL libusb_open(libusb_device *dev, libusb_device_handle **hand le);
void LIBUSB_CALL libusb_close(libusb_device_handle *dev_handle); void LIBUSB_CALL libusb_close(libusb_device_handle *dev_handle);
libusb_device * LIBUSB_CALL libusb_get_device(libusb_device_handle *dev_han dle); libusb_device * LIBUSB_CALL libusb_get_device(libusb_device_handle *dev_han dle);
skipping to change at line 1201 skipping to change at line 1394
int LIBUSB_CALL libusb_clear_halt(libusb_device_handle *dev, int LIBUSB_CALL libusb_clear_halt(libusb_device_handle *dev,
unsigned char endpoint); unsigned char endpoint);
int LIBUSB_CALL libusb_reset_device(libusb_device_handle *dev); int LIBUSB_CALL libusb_reset_device(libusb_device_handle *dev);
int LIBUSB_CALL libusb_kernel_driver_active(libusb_device_handle *dev, int LIBUSB_CALL libusb_kernel_driver_active(libusb_device_handle *dev,
int interface_number); int interface_number);
int LIBUSB_CALL libusb_detach_kernel_driver(libusb_device_handle *dev, int LIBUSB_CALL libusb_detach_kernel_driver(libusb_device_handle *dev,
int interface_number); int interface_number);
int LIBUSB_CALL libusb_attach_kernel_driver(libusb_device_handle *dev, int LIBUSB_CALL libusb_attach_kernel_driver(libusb_device_handle *dev,
int interface_number); int interface_number);
int LIBUSB_CALL libusb_set_auto_detach_kernel_driver(
libusb_device_handle *dev, int enable);
/* async I/O */ /* async I/O */
/** \ingroup asyncio /** \ingroup asyncio
* Get the data section of a control transfer. This convenience function is here * Get the data section of a control transfer. This convenience function is here
* to remind you that the data does not start until 8 bytes into the actual * to remind you that the data does not start until 8 bytes into the actual
* buffer, as the setup packet comes first. * buffer, as the setup packet comes first.
* *
* Calling this function only makes sense from a transfer callback function , * Calling this function only makes sense from a transfer callback function ,
* or situations where you have already allocated a suitably sized buffer a t * or situations where you have already allocated a suitably sized buffer a t
skipping to change at line 1237 skipping to change at line 1432
* Calling this function only makes sense from a transfer callback function , * Calling this function only makes sense from a transfer callback function ,
* or situations where you have already allocated a suitably sized buffer a t * or situations where you have already allocated a suitably sized buffer a t
* transfer->buffer. * transfer->buffer.
* *
* \param transfer a transfer * \param transfer a transfer
* \returns a casted pointer to the start of the transfer data buffer * \returns a casted pointer to the start of the transfer data buffer
*/ */
static inline struct libusb_control_setup *libusb_control_transfer_get_setu p( static inline struct libusb_control_setup *libusb_control_transfer_get_setu p(
struct libusb_transfer *transfer) struct libusb_transfer *transfer)
{ {
return (struct libusb_control_setup *) transfer->buffer; return (struct libusb_control_setup *)(void *) transfer->buffer;
} }
/** \ingroup asyncio /** \ingroup asyncio
* Helper function to populate the setup packet (first 8 bytes of the data * Helper function to populate the setup packet (first 8 bytes of the data
* buffer) for a control transfer. The wIndex, wValue and wLength values sh ould * buffer) for a control transfer. The wIndex, wValue and wLength values sh ould
* be given in host-endian byte order. * be given in host-endian byte order.
* *
* \param buffer buffer to output the setup packet into * \param buffer buffer to output the setup packet into
* This pointer must be aligned to at least 2 bytes boundary.
* \param bmRequestType see the * \param bmRequestType see the
* \ref libusb_control_setup::bmRequestType "bmRequestType" field of * \ref libusb_control_setup::bmRequestType "bmRequestType" field of
* \ref libusb_control_setup * \ref libusb_control_setup
* \param bRequest see the * \param bRequest see the
* \ref libusb_control_setup::bRequest "bRequest" field of * \ref libusb_control_setup::bRequest "bRequest" field of
* \ref libusb_control_setup * \ref libusb_control_setup
* \param wValue see the * \param wValue see the
* \ref libusb_control_setup::wValue "wValue" field of * \ref libusb_control_setup::wValue "wValue" field of
* \ref libusb_control_setup * \ref libusb_control_setup
* \param wIndex see the * \param wIndex see the
* \ref libusb_control_setup::wIndex "wIndex" field of * \ref libusb_control_setup::wIndex "wIndex" field of
* \ref libusb_control_setup * \ref libusb_control_setup
* \param wLength see the * \param wLength see the
* \ref libusb_control_setup::wLength "wLength" field of * \ref libusb_control_setup::wLength "wLength" field of
* \ref libusb_control_setup * \ref libusb_control_setup
*/ */
static inline void libusb_fill_control_setup(unsigned char *buffer, static inline void libusb_fill_control_setup(unsigned char *buffer,
uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t w Index, uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t w Index,
uint16_t wLength) uint16_t wLength)
{ {
struct libusb_control_setup *setup = (struct libusb_control_setup *) buffer; struct libusb_control_setup *setup = (struct libusb_control_setup *) (void *) buffer;
setup->bmRequestType = bmRequestType; setup->bmRequestType = bmRequestType;
setup->bRequest = bRequest; setup->bRequest = bRequest;
setup->wValue = libusb_cpu_to_le16(wValue); setup->wValue = libusb_cpu_to_le16(wValue);
setup->wIndex = libusb_cpu_to_le16(wIndex); setup->wIndex = libusb_cpu_to_le16(wIndex);
setup->wLength = libusb_cpu_to_le16(wLength); setup->wLength = libusb_cpu_to_le16(wLength);
} }
struct libusb_transfer * LIBUSB_CALL libusb_alloc_transfer(int iso_packets) ; struct libusb_transfer * LIBUSB_CALL libusb_alloc_transfer(int iso_packets) ;
int LIBUSB_CALL libusb_submit_transfer(struct libusb_transfer *transfer); int LIBUSB_CALL libusb_submit_transfer(struct libusb_transfer *transfer);
int LIBUSB_CALL libusb_cancel_transfer(struct libusb_transfer *transfer); int LIBUSB_CALL libusb_cancel_transfer(struct libusb_transfer *transfer);
skipping to change at line 1302 skipping to change at line 1498
* -# Call libusb_submit_transfer() * -# Call libusb_submit_transfer()
* *
* It is also legal to pass a NULL buffer to this function, in which case t his * It is also legal to pass a NULL buffer to this function, in which case t his
* function will not attempt to populate the length field. Remember that yo u * function will not attempt to populate the length field. Remember that yo u
* must then populate the buffer and length fields later. * must then populate the buffer and length fields later.
* *
* \param transfer the transfer to populate * \param transfer the transfer to populate
* \param dev_handle handle of the device that will handle the transfer * \param dev_handle handle of the device that will handle the transfer
* \param buffer data buffer. If provided, this function will interpret the * \param buffer data buffer. If provided, this function will interpret the
* first 8 bytes as a setup packet and infer the transfer length from that. * first 8 bytes as a setup packet and infer the transfer length from that.
* This pointer must be aligned to at least 2 bytes boundary.
* \param callback callback function to be invoked on transfer completion * \param callback callback function to be invoked on transfer completion
* \param user_data user data to pass to callback function * \param user_data user data to pass to callback function
* \param timeout timeout for the transfer in milliseconds * \param timeout timeout for the transfer in milliseconds
*/ */
static inline void libusb_fill_control_transfer( static inline void libusb_fill_control_transfer(
struct libusb_transfer *transfer, libusb_device_handle *dev_handle, struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
unsigned char *buffer, libusb_transfer_cb_fn callback, void *user_da ta, unsigned char *buffer, libusb_transfer_cb_fn callback, void *user_da ta,
unsigned int timeout) unsigned int timeout)
{ {
struct libusb_control_setup *setup = (struct libusb_control_setup *) buffer; struct libusb_control_setup *setup = (struct libusb_control_setup *) (void *) buffer;
transfer->dev_handle = dev_handle; transfer->dev_handle = dev_handle;
transfer->endpoint = 0; transfer->endpoint = 0;
transfer->type = LIBUSB_TRANSFER_TYPE_CONTROL; transfer->type = LIBUSB_TRANSFER_TYPE_CONTROL;
transfer->timeout = timeout; transfer->timeout = timeout;
transfer->buffer = buffer; transfer->buffer = buffer;
if (setup) if (setup)
transfer->length = LIBUSB_CONTROL_SETUP_SIZE transfer->length = (int) (LIBUSB_CONTROL_SETUP_SIZE
+ libusb_le16_to_cpu(setup->wLength); + libusb_le16_to_cpu(setup->wLength));
transfer->user_data = user_data; transfer->user_data = user_data;
transfer->callback = callback; transfer->callback = callback;
} }
/** \ingroup asyncio /** \ingroup asyncio
* Helper function to populate the required \ref libusb_transfer fields * Helper function to populate the required \ref libusb_transfer fields
* for a bulk transfer. * for a bulk transfer.
* *
* \param transfer the transfer to populate * \param transfer the transfer to populate
* \param dev_handle handle of the device that will handle the transfer * \param dev_handle handle of the device that will handle the transfer
skipping to change at line 1454 skipping to change at line 1651
{ {
int i; int i;
size_t offset = 0; size_t offset = 0;
int _packet; int _packet;
/* oops..slight bug in the API. packet is an unsigned int, but we us e /* oops..slight bug in the API. packet is an unsigned int, but we us e
* signed integers almost everywhere else. range-check and convert t o * signed integers almost everywhere else. range-check and convert t o
* signed to avoid compiler warnings. FIXME for libusb-2. */ * signed to avoid compiler warnings. FIXME for libusb-2. */
if (packet > INT_MAX) if (packet > INT_MAX)
return NULL; return NULL;
_packet = packet; _packet = (int) packet;
if (_packet >= transfer->num_iso_packets) if (_packet >= transfer->num_iso_packets)
return NULL; return NULL;
for (i = 0; i < _packet; i++) for (i = 0; i < _packet; i++)
offset += transfer->iso_packet_desc[i].length; offset += transfer->iso_packet_desc[i].length;
return transfer->buffer + offset; return transfer->buffer + offset;
} }
skipping to change at line 1494 skipping to change at line 1691
static inline unsigned char *libusb_get_iso_packet_buffer_simple( static inline unsigned char *libusb_get_iso_packet_buffer_simple(
struct libusb_transfer *transfer, unsigned int packet) struct libusb_transfer *transfer, unsigned int packet)
{ {
int _packet; int _packet;
/* oops..slight bug in the API. packet is an unsigned int, but we us e /* oops..slight bug in the API. packet is an unsigned int, but we us e
* signed integers almost everywhere else. range-check and convert t o * signed integers almost everywhere else. range-check and convert t o
* signed to avoid compiler warnings. FIXME for libusb-2. */ * signed to avoid compiler warnings. FIXME for libusb-2. */
if (packet > INT_MAX) if (packet > INT_MAX)
return NULL; return NULL;
_packet = packet; _packet = (int) packet;
if (_packet >= transfer->num_iso_packets) if (_packet >= transfer->num_iso_packets)
return NULL; return NULL;
return transfer->buffer + (transfer->iso_packet_desc[0].length * _pa cket); return transfer->buffer + ((int) transfer->iso_packet_desc[0].length * _packet);
} }
/* sync I/O */ /* sync I/O */
int LIBUSB_CALL libusb_control_transfer(libusb_device_handle *dev_handle, int LIBUSB_CALL libusb_control_transfer(libusb_device_handle *dev_handle,
uint8_t request_type, uint8_t bRequest, uint16_t wValue, uint16_t wI ndex, uint8_t request_type, uint8_t bRequest, uint16_t wValue, uint16_t wI ndex,
unsigned char *data, uint16_t wLength, unsigned int timeout); unsigned char *data, uint16_t wLength, unsigned int timeout);
int LIBUSB_CALL libusb_bulk_transfer(libusb_device_handle *dev_handle, int LIBUSB_CALL libusb_bulk_transfer(libusb_device_handle *dev_handle,
unsigned char endpoint, unsigned char *data, int length, unsigned char endpoint, unsigned char *data, int length,
skipping to change at line 1532 skipping to change at line 1729
* \param desc_type the descriptor type, see \ref libusb_descriptor_type * \param desc_type the descriptor type, see \ref libusb_descriptor_type
* \param desc_index the index of the descriptor to retrieve * \param desc_index the index of the descriptor to retrieve
* \param data output buffer for descriptor * \param data output buffer for descriptor
* \param length size of data buffer * \param length size of data buffer
* \returns number of bytes returned in data, or LIBUSB_ERROR code on failu re * \returns number of bytes returned in data, or LIBUSB_ERROR code on failu re
*/ */
static inline int libusb_get_descriptor(libusb_device_handle *dev, static inline int libusb_get_descriptor(libusb_device_handle *dev,
uint8_t desc_type, uint8_t desc_index, unsigned char *data, int leng th) uint8_t desc_type, uint8_t desc_index, unsigned char *data, int leng th)
{ {
return libusb_control_transfer(dev, LIBUSB_ENDPOINT_IN, return libusb_control_transfer(dev, LIBUSB_ENDPOINT_IN,
LIBUSB_REQUEST_GET_DESCRIPTOR, (desc_type << 8) | desc_index LIBUSB_REQUEST_GET_DESCRIPTOR, (uint16_t) ((desc_type << 8)
, 0, data, | desc_index),
(uint16_t) length, 1000); 0, data, (uint16_t) length, 1000);
} }
/** \ingroup desc /** \ingroup desc
* Retrieve a descriptor from a device. * Retrieve a descriptor from a device.
* This is a convenience function which formulates the appropriate control * This is a convenience function which formulates the appropriate control
* message to retrieve the descriptor. The string returned is Unicode, as * message to retrieve the descriptor. The string returned is Unicode, as
* detailed in the USB specifications. * detailed in the USB specifications.
* *
* \param dev a device handle * \param dev a device handle
* \param desc_index the index of the descriptor to retrieve * \param desc_index the index of the descriptor to retrieve
skipping to change at line 1628 skipping to change at line 1825
* \see libusb_set_pollfd_notifiers() * \see libusb_set_pollfd_notifiers()
*/ */
typedef void (LIBUSB_CALL *libusb_pollfd_removed_cb)(int fd, void *user_dat a); typedef void (LIBUSB_CALL *libusb_pollfd_removed_cb)(int fd, void *user_dat a);
const struct libusb_pollfd ** LIBUSB_CALL libusb_get_pollfds( const struct libusb_pollfd ** LIBUSB_CALL libusb_get_pollfds(
libusb_context *ctx); libusb_context *ctx);
void LIBUSB_CALL libusb_set_pollfd_notifiers(libusb_context *ctx, void LIBUSB_CALL libusb_set_pollfd_notifiers(libusb_context *ctx,
libusb_pollfd_added_cb added_cb, libusb_pollfd_removed_cb removed_cb , libusb_pollfd_added_cb added_cb, libusb_pollfd_removed_cb removed_cb ,
void *user_data); void *user_data);
/** \ingroup desc
* Parse a USB 3.0 endpoint companion descriptor.
*
* \param[in] buf the buffer containing the endpoint companion descriptor
* \param[in] len the length of the buffer
* \param[out] ep_comp a parsed endpoint companion descriptor. must be free
d by
* libusb_free_ss_endpoint_comp()
*
* \returns LIBUSB_SUCCESS on success
* \returns LIBUSB_ERROR code on error
*/
int LIBUSB_CALL libusb_parse_ss_endpoint_comp(const void *buf, int len,
struct libusb_ss_endpoint_comp
anion_descriptor **ep_comp);
/** \ingroup desc
* Free a USB 3.0 endpoint companion descriptor.
*
* \param[in] ep_comp the descriptor to free
*/
void LIBUSB_CALL libusb_free_ss_endpoint_comp(struct libusb_ss_endpoint_com
panion_descriptor *ep_comp);
/** \ingroup desc
* Parse a Binary Object Store (BOS) descriptor.
*
* \param[in] buf the buffer containing the BOS descriptor
* \param[in] len the length of the buffer
* \param[out] bos a parsed BOS descriptor. must be freed by
* libusb_free_bos_descriptor()
*
* \returns LIBUSB_SUCCESS on success
* \returns LIBUSB_ERROR code on error
*/
int LIBUSB_CALL libusb_parse_bos_descriptor(const void *buf, int len,
struct libusb_bos_descriptor **b
os);
/** \ingroup desc
* Free a Binary Object Store (BOS) descriptor.
*
* \param[in] bos the descriptor to free
*/
void LIBUSB_CALL libusb_free_bos_descriptor(struct libusb_bos_descriptor *b
os);
/** \ingroup hotplug /** \ingroup hotplug
* Callback handle. * Callback handle.
* *
* Callbacks handles are generated by libusb_hotplug_register_callback() * Callbacks handles are generated by libusb_hotplug_register_callback()
* and can be used to deregister callbacks. Callback handles are unique * and can be used to deregister callbacks. Callback handles are unique
* per libusb_context and it is safe to call libusb_hotplug_deregister_call back() * per libusb_context and it is safe to call libusb_hotplug_deregister_call back()
* on an already deregisted callback. * on an already deregisted callback.
* *
* Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
*
* For more information, see \ref hotplug. * For more information, see \ref hotplug.
*/ */
typedef int libusb_hotplug_callback_handle; typedef int libusb_hotplug_callback_handle;
/** \ingroup hotplug /** \ingroup hotplug
*
* Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
*
* Flags for hotplug events */ * Flags for hotplug events */
typedef enum { typedef enum {
/** Arm the callback and fire it for all matching currently attached devices. */ /** Arm the callback and fire it for all matching currently attached devices. */
LIBUSB_HOTPLUG_ENUMERATE = 1, LIBUSB_HOTPLUG_ENUMERATE = 1,
} libusb_hotplug_flag; } libusb_hotplug_flag;
/** \ingroup hotplug /** \ingroup hotplug
*
* Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
*
* Hotplug events */ * Hotplug events */
typedef enum { typedef enum {
/** A device has been plugged in and is ready to use */ /** A device has been plugged in and is ready to use */
LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED = 0x01, LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED = 0x01,
/** A device has left and is no longer available. /** A device has left and is no longer available.
* It is the user's responsibility to call libusb_close on any handl e associated with a disconnected device. * It is the user's responsibility to call libusb_close on any handl e associated with a disconnected device.
* It is safe to call libusb_get_device_descriptor on a device that has left */ * It is safe to call libusb_get_device_descriptor on a device that has left */
LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT = 0x02, LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT = 0x02,
} libusb_hotplug_event; } libusb_hotplug_event;
skipping to change at line 1718 skipping to change at line 1881
* *
* This callback may be called by an internal event thread and as such it i s * This callback may be called by an internal event thread and as such it i s
* recommended the callback do minimal processing before returning. * recommended the callback do minimal processing before returning.
* *
* libusb will call this function later, when a matching event had happened on * libusb will call this function later, when a matching event had happened on
* a matching device. See \ref hotplug for more information. * a matching device. See \ref hotplug for more information.
* *
* It is safe to call either libusb_hotplug_register_callback() or * It is safe to call either libusb_hotplug_register_callback() or
* libusb_hotplug_deregister_callback() from within a callback function. * libusb_hotplug_deregister_callback() from within a callback function.
* *
* \param libusb_context context of this notification * Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
*
* \param ctx context of this notification
* \param device libusb_device this event occurred on * \param device libusb_device this event occurred on
* \param event event that occurred * \param event event that occurred
* \param user_data user data provided when this callback was register ed * \param user_data user data provided when this callback was register ed
* \returns bool whether this callback is finished processing events. * \returns bool whether this callback is finished processing events.
* returning 1 will cause this callback to be deregis tered * returning 1 will cause this callback to be deregis tered
*/ */
typedef int (LIBUSB_CALL *libusb_hotplug_callback_fn)(libusb_context *ctx, typedef int (LIBUSB_CALL *libusb_hotplug_callback_fn)(libusb_context *ctx,
libusb_device *device, libusb_device *device,
libusb_hotplug_event e libusb_hotplug_event event,
vent, void *user_data);
void *user_data);
/** \ingroup hotplug /** \ingroup hotplug
* Register a hotplug callback function * Register a hotplug callback function
* *
* Register a callback with the libusb_context. The callback will fire * Register a callback with the libusb_context. The callback will fire
* when a matching event occurs on a matching device. The callback is * when a matching event occurs on a matching device. The callback is
* armed until either it is deregistered with libusb_hotplug_deregister_cal lback() * armed until either it is deregistered with libusb_hotplug_deregister_cal lback()
* or the supplied callback returns 1 to indicate it is finished processing events. * or the supplied callback returns 1 to indicate it is finished processing events.
* *
* If the \ref LIBUSB_HOTPLUG_ENUMERATE is passed the callback will be
* called with a \ref LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED for all devices
* already plugged into the machine. Note that libusb modifies its internal
* device list from a separate thread, while calling hotplug callbacks from
* libusb_handle_events(), so it is possible for a device to already be pre
sent
* on, or removed from, its internal device list, while the hotplug callbac
ks
* still need to be dispatched. This means that when using \ref
* LIBUSB_HOTPLUG_ENUMERATE, your callback may be called twice for the arri
val
* of the same device, once from libusb_hotplug_register_callback() and onc
e
* from libusb_handle_events(); and/or your callback may be called for the
* removal of a device for which an arrived call was never made.
*
* Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
*
* \param[in] ctx context to register this callback with * \param[in] ctx context to register this callback with
* \param[in] events bitwise or of events that will trigger this callback. See \ref * \param[in] events bitwise or of events that will trigger this callback. See \ref
* libusb_hotplug_event * libusb_hotplug_event
* \param[in] flags hotplug callback flags. See \ref libusb_hotplug_flag * \param[in] flags hotplug callback flags. See \ref libusb_hotplug_flag
* \param[in] vendor_id the vendor id to match or \ref LIBUSB_HOTPLUG_MATCH _ANY * \param[in] vendor_id the vendor id to match or \ref LIBUSB_HOTPLUG_MATCH _ANY
* \param[in] product_id the product id to match or \ref LIBUSB_HOTPLUG_MAT CH_ANY * \param[in] product_id the product id to match or \ref LIBUSB_HOTPLUG_MAT CH_ANY
* \param[in] dev_class the device class to match or \ref LIBUSB_HOTPLUG_MA TCH_ANY * \param[in] dev_class the device class to match or \ref LIBUSB_HOTPLUG_MA TCH_ANY
* \param[in] cb_fn the function to be invoked on a matching event/device * \param[in] cb_fn the function to be invoked on a matching event/device
* \param[in] user_data user data to pass to the callback function * \param[in] user_data user data to pass to the callback function
* \param[out] handle pointer to store the handle of the allocated callback (can be NULL) * \param[out] handle pointer to store the handle of the allocated callback (can be NULL)
* \returns LIBUSB_SUCCESS on success LIBUSB_ERROR code on failure * \returns LIBUSB_SUCCESS on success LIBUSB_ERROR code on failure
*/ */
int LIBUSB_CALL libusb_hotplug_register_callback(libusb_context *ctx, int LIBUSB_CALL libusb_hotplug_register_callback(libusb_context *ctx,
libusb_hotplug_event events libusb_hotplug_event events,
, libusb_hotplug_flag flags,
libusb_hotplug_flag flags, int vendor_id, int product_i
int vendor_id, int product_ d,
id, int dev_class,
int dev_class, libusb_hotplug_callback_fn c
libusb_hotplug_callback_fn b_fn,
cb_fn, void *user_data,
void *user_data, libusb_hotplug_callback_hand
libusb_hotplug_callback_han le *handle);
dle *handle);
/** \ingroup hotplug /** \ingroup hotplug
* Deregisters a hotplug callback. * Deregisters a hotplug callback.
* *
* Deregister a callback from a libusb_context. This function is safe to ca ll from within * Deregister a callback from a libusb_context. This function is safe to ca ll from within
* a hotplug callback. * a hotplug callback.
* *
* Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
*
* \param[in] ctx context this callback is registered with * \param[in] ctx context this callback is registered with
* \param[in] handle the handle of the callback to deregister * \param[in] handle the handle of the callback to deregister
*/ */
void LIBUSB_CALL libusb_hotplug_deregister_callback(libusb_context *ctx, void LIBUSB_CALL libusb_hotplug_deregister_callback(libusb_context *ctx,
libusb_hotplug_callback_ handle handle); libusb_hotplug_callback_hand le handle);
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif
#endif #endif
 End of changes. 84 change blocks. 
198 lines changed or deleted 403 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/