A cross-platform user library to access USB devices
Macros | Enumerations | Functions | Variables
Miscellaneous

Macros

#define LIBUSB_CALL
 libusb's Windows calling convention. More...
 
#define LIBUSB_API_VERSION   0x01000103
 libusb's API version. More...
 
#define libusb_le16_to_cpu   libusb_cpu_to_le16
 Convert a 16-bit value from little-endian to host-endian format. More...
 

Enumerations

enum  libusb_standard_request {
  LIBUSB_REQUEST_GET_STATUS = 0x00, LIBUSB_REQUEST_CLEAR_FEATURE = 0x01, LIBUSB_REQUEST_SET_FEATURE = 0x03, LIBUSB_REQUEST_SET_ADDRESS = 0x05,
  LIBUSB_REQUEST_GET_DESCRIPTOR = 0x06, LIBUSB_REQUEST_SET_DESCRIPTOR = 0x07, LIBUSB_REQUEST_GET_CONFIGURATION = 0x08, LIBUSB_REQUEST_SET_CONFIGURATION = 0x09,
  LIBUSB_REQUEST_GET_INTERFACE = 0x0A, LIBUSB_REQUEST_SET_INTERFACE = 0x0B, LIBUSB_REQUEST_SYNCH_FRAME = 0x0C, LIBUSB_REQUEST_SET_SEL = 0x30,
  LIBUSB_SET_ISOCH_DELAY = 0x31
}
 Standard requests, as defined in table 9-5 of the USB 3.0 specifications. More...
 
enum  libusb_request_type { LIBUSB_REQUEST_TYPE_STANDARD = (0x00 << 5), LIBUSB_REQUEST_TYPE_CLASS = (0x01 << 5), LIBUSB_REQUEST_TYPE_VENDOR = (0x02 << 5), LIBUSB_REQUEST_TYPE_RESERVED = (0x03 << 5) }
 Request type bits of the bmRequestType field in control transfers. More...
 
enum  libusb_request_recipient { LIBUSB_RECIPIENT_DEVICE = 0x00, LIBUSB_RECIPIENT_INTERFACE = 0x01, LIBUSB_RECIPIENT_ENDPOINT = 0x02, LIBUSB_RECIPIENT_OTHER = 0x03 }
 Recipient bits of the bmRequestType field in control transfers. More...
 
enum  libusb_error {
  LIBUSB_SUCCESS = 0, LIBUSB_ERROR_IO = -1, LIBUSB_ERROR_INVALID_PARAM = -2, LIBUSB_ERROR_ACCESS = -3,
  LIBUSB_ERROR_NO_DEVICE = -4, LIBUSB_ERROR_NOT_FOUND = -5, LIBUSB_ERROR_BUSY = -6, LIBUSB_ERROR_TIMEOUT = -7,
  LIBUSB_ERROR_OVERFLOW = -8, LIBUSB_ERROR_PIPE = -9, LIBUSB_ERROR_INTERRUPTED = -10, LIBUSB_ERROR_NO_MEM = -11,
  LIBUSB_ERROR_NOT_SUPPORTED = -12, LIBUSB_ERROR_OTHER = -99
}
 Error codes. More...
 
enum  libusb_capability { LIBUSB_CAP_HAS_CAPABILITY = 0x0000, LIBUSB_CAP_HAS_HOTPLUG = 0x0001, LIBUSB_CAP_HAS_HID_ACCESS = 0x0100, LIBUSB_CAP_SUPPORTS_DETACH_KERNEL_DRIVER = 0x0101 }
 Capabilities supported by an instance of libusb on the current running platform. More...
 

Functions

int libusb_has_capability (uint32_t capability)
 Check at runtime if the loaded library has a given capability. More...
 
const char * libusb_error_name (int error_code)
 Returns a constant NULL-terminated string with the ASCII name of a libusb error or transfer status code. More...
 
const struct libusb_versionlibusb_get_version (void)
 Returns a pointer to const struct libusb_version with the version (major, minor, micro, nano and rc) of the running library.
 
static uint16_t libusb_cpu_to_le16 (const uint16_t x)
 Convert a 16-bit value from host-endian to little-endian format. More...
 
int libusb_setlocale (const char *locale)
 Set the language, and only the language, not the encoding! used for translatable libusb messages. More...
 
const char * libusb_strerror (enum libusb_error errcode)
 Returns a constant string with a short description of the given error code, this description is intended for displaying to the end user and will be in the language set by libusb_setlocale(). More...
 

Variables

static const char * usbi_locale_supported [] = { "en", "nl", "fr", "ru" }
 How to add a new libusb_strerror() translation: More...
 

Detailed Description

Macro Definition Documentation

#define LIBUSB_CALL

libusb's Windows calling convention.

Under Windows, the selection of available compilers and configurations means that, unlike other platforms, there is not one true calling convention (calling convention: the manner in which parameters are passed to funcions in the generated assembly code).

Matching the Windows API itself, libusb uses the WINAPI convention (which translates to the stdcall convention) and guarantees that the library is compiled in this way. The public header file also includes appropriate annotations so that your own software will use the right convention, even if another convention is being used by default within your codebase.

The one consideration that you must apply in your software is to mark all functions which you use as libusb callbacks with this LIBUSB_CALL annotation, so that they too get compiled for the correct calling convention.

On non-Windows operating systems, this macro is defined as nothing. This means that you can apply it to your code without worrying about cross-platform compatibility.

#define LIBUSB_API_VERSION   0x01000103

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:

#if defined(LIBUSB_API_VERSION) && (LIBUSB_API_VERSION >= 0x01001234)
// Use one of the newer features from the libusb API
#endif

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_le16_to_cpu   libusb_cpu_to_le16

Convert a 16-bit value from little-endian to host-endian format.

On little endian systems, this function does nothing. On big endian systems, the bytes are swapped.

Parameters
xthe little-endian value to convert
Returns
the value in host-endian byte order

Enumeration Type Documentation

Standard requests, as defined in table 9-5 of the USB 3.0 specifications.

Enumerator
LIBUSB_REQUEST_GET_STATUS 

Request status of the specific recipient.

LIBUSB_REQUEST_CLEAR_FEATURE 

Clear or disable a specific feature.

LIBUSB_REQUEST_SET_FEATURE 

Set or enable a specific feature.

LIBUSB_REQUEST_SET_ADDRESS 

Set device address for all future accesses.

LIBUSB_REQUEST_GET_DESCRIPTOR 

Get the specified descriptor.

LIBUSB_REQUEST_SET_DESCRIPTOR 

Used to update existing descriptors or add new descriptors.

LIBUSB_REQUEST_GET_CONFIGURATION 

Get the current device configuration value.

LIBUSB_REQUEST_SET_CONFIGURATION 

Set device configuration.

LIBUSB_REQUEST_GET_INTERFACE 

Return the selected alternate setting for the specified interface.

LIBUSB_REQUEST_SET_INTERFACE 

Select an alternate interface for the specified interface.

LIBUSB_REQUEST_SYNCH_FRAME 

Set then report an endpoint's synchronization frame.

LIBUSB_REQUEST_SET_SEL 

Sets both the U1 and U2 Exit Latency.

LIBUSB_SET_ISOCH_DELAY 

Delay from the time a host transmits a packet to the time it is received by the device.

Request type bits of the bmRequestType field in control transfers.

Enumerator
LIBUSB_REQUEST_TYPE_STANDARD 

Standard.

LIBUSB_REQUEST_TYPE_CLASS 

Class.

LIBUSB_REQUEST_TYPE_VENDOR 

Vendor.

LIBUSB_REQUEST_TYPE_RESERVED 

Reserved.

Recipient bits of the bmRequestType field in control transfers.

Values 4 through 31 are reserved.

Enumerator
LIBUSB_RECIPIENT_DEVICE 

Device.

LIBUSB_RECIPIENT_INTERFACE 

Interface.

LIBUSB_RECIPIENT_ENDPOINT 

Endpoint.

LIBUSB_RECIPIENT_OTHER 

Other.

Error codes.

Most libusb functions return 0 on success or one of these codes on failure. You can call libusb_error_name() to retrieve a string representation of an error code or libusb_strerror() to get an end-user suitable description of an error code.

Enumerator
LIBUSB_SUCCESS 

Success (no error)

LIBUSB_ERROR_IO 

Input/output error.

LIBUSB_ERROR_INVALID_PARAM 

Invalid parameter.

LIBUSB_ERROR_ACCESS 

Access denied (insufficient permissions)

LIBUSB_ERROR_NO_DEVICE 

No such device (it may have been disconnected)

LIBUSB_ERROR_NOT_FOUND 

Entity not found.

LIBUSB_ERROR_BUSY 

Resource busy.

LIBUSB_ERROR_TIMEOUT 

Operation timed out.

LIBUSB_ERROR_OVERFLOW 

Overflow.

LIBUSB_ERROR_PIPE 

Pipe error.

LIBUSB_ERROR_INTERRUPTED 

System call interrupted (perhaps due to signal)

LIBUSB_ERROR_NO_MEM 

Insufficient memory.

LIBUSB_ERROR_NOT_SUPPORTED 

Operation not supported or unimplemented on this platform.

LIBUSB_ERROR_OTHER 

Other error.

Capabilities supported by an instance of libusb on the current running platform.

Test if the loaded library supports a given capability by calling libusb_has_capability().

Enumerator
LIBUSB_CAP_HAS_CAPABILITY 

The libusb_has_capability() API is available.

LIBUSB_CAP_HAS_HOTPLUG 

Hotplug support is available on this platform.

LIBUSB_CAP_HAS_HID_ACCESS 

The library can access HID devices without requiring user intervention.

Note that before being able to actually access an HID device, you may still have to call additional libusb functions such as libusb_detach_kernel_driver().

LIBUSB_CAP_SUPPORTS_DETACH_KERNEL_DRIVER 

The library supports detaching of the default USB driver, using libusb_detach_kernel_driver(), if one is set by the OS kernel.

Function Documentation

int libusb_has_capability ( uint32_t  capability)

Check at runtime if the loaded library has a given capability.

This call should be performed after libusb_init(), to ensure the backend has updated its capability set.

Parameters
capabilitythe libusb_capability to check for
Returns
nonzero if the running library has the capability, 0 otherwise
const char* libusb_error_name ( int  error_code)

Returns a constant NULL-terminated string with the ASCII name of a libusb error or transfer status code.

The caller must not free() the returned string.

Parameters
error_codeThe libusb_error or libusb_transfer_status code to return the name of.
Returns
The error name, or the string UNKNOWN if the value of error_code is not a known error / status code.
static uint16_t libusb_cpu_to_le16 ( const uint16_t  x)
inlinestatic

Convert a 16-bit value from host-endian to little-endian format.

On little endian systems, this function does nothing. On big endian systems, the bytes are swapped.

Parameters
xthe host-endian value to convert
Returns
the value in little-endian byte order
int libusb_setlocale ( const char *  locale)

Set the language, and only the language, not the encoding! used for translatable libusb messages.

This takes a locale string in the default setlocale format: lang[-region] or lang[_country_region][.codeset]. Only the lang part of the string is used, and only 2 letter ISO 639-1 codes are accepted for it, such as "de". The optional region, country_region or codeset parts are ignored. This means that functions which return translatable strings will NOT honor the specified encoding. All strings returned are encoded as UTF-8 strings.

If libusb_setlocale() is not called, all messages will be in English.

The following functions return translatable strings: libusb_strerror(). Note that the libusb log messages controlled through libusb_set_debug() are not translated, they are always in English.

For POSIX UTF-8 environments if you want libusb to follow the standard locale settings, call libusb_setlocale(setlocale(LC_MESSAGES, NULL)), after your app has done its locale setup.

Parameters
localelocale-string in the form of lang[_country_region][.codeset] or lang[-region], where lang is a 2 letter ISO 639-1 code
Returns
LIBUSB_SUCCESS on success
LIBUSB_ERROR_INVALID_PARAM if the locale doesn't meet the requirements
LIBUSB_ERROR_NOT_FOUND if the requested language is not supported
a LIBUSB_ERROR code on other errors
const char* libusb_strerror ( enum libusb_error  errcode)

Returns a constant string with a short description of the given error code, this description is intended for displaying to the end user and will be in the language set by libusb_setlocale().

The returned string is encoded in UTF-8.

The messages always start with a capital letter and end without any dot. The caller must not free() the returned string.

Parameters
errcodethe error code whose description is desired
Returns
a short description of the error code in UTF-8 encoding

Variable Documentation

const char* usbi_locale_supported[] = { "en", "nl", "fr", "ru" }
static

How to add a new libusb_strerror() translation:

  1. Download the latest strerror.c from:
    https://raw.github.com/libusb/libusb/master/libusb/sterror.c
  2. Open the file in an UTF-8 capable editor
  3. Add the 2 letter ISO 639-1 code for your locale at the end of usbi_locale_supported[]
    Eg. for Chinese, you would add "zh" so that:
    ... usbi_locale_supported[] = { "en", "nl", "fr" };
    becomes:
    ... usbi_locale_supported[] = { "en", "nl", "fr", "zh" };
  4. Copy the { / * English (en) * / ... } section and add it at the end of usbi_localized_errors
    Eg. for Chinese, the last section of usbi_localized_errors could look like:
    }, { / * Chinese (zh) * /
    "Success",
    ...
    "Other error",
    }
    };
  5. Translate each of the English messages from the section you copied into your language
  6. Save the file (in UTF-8 format) and send it to libusb-devel@lists.sourceforge.net