libusb
1.0.27
A cross-platform user library to access USB devices
|
Macros | |
#define | LIBUSB_CALL |
libusb's Windows calling convention. More... | |
#define | LIBUSB_API_VERSION 0x0100010A |
libusb's API version. More... | |
#define | LIBUSBX_API_VERSION LIBUSB_API_VERSION |
This is the older spelling, kept for backwards compatibility of code needing to test for older library versions where the newer spelling did not exist. | |
#define | libusb_le16_to_cpu libusb_cpu_to_le16 |
Convert a 16-bit value from little-endian to host-endian format. 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_version * | libusb_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 (int 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 *const | usbi_locale_supported [] = { "en", "nl", "fr", "ru", "de", "hu" } |
How to add a new libusb_strerror() translation: More... | |
#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 functions 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 0x0100010A |
libusb's API version.
Since version 1.0.18, 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.
Between versions 1.0.13 and 1.0.17 (inclusive) the older spelling of LIBUSBX_API_VERSION was used.
The macro is typically used in an application as follows:
Internally, LIBUSB_API_VERSION is defined as follows: (libusb major << 24) | (libusb minor << 16) | (16 bit incremental)
The incremental component has changed as follows:
#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.
x | the little-endian value to convert |
Standard requests, as defined in table 9-5 of the USB 3.0 specifications.
enum libusb_request_type |
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. |
enum libusb_error |
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.
enum libusb_capability |
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. |
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_context(), to ensure the backend has updated its capability set.
capability | the libusb_capability to check for |
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.
error_code | The libusb_error or libusb_transfer_status code to return the name of. |
|
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.
x | the host-endian value to convert |
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_OPTION_LOG_LEVEL 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.
locale | locale-string in the form of lang[_country_region][.codeset] or lang[-region], where lang is a 2 letter ISO 639-1 code |
const char* libusb_strerror | ( | int | 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.
errcode | the error code whose description is desired |
|
static |
How to add a new libusb_strerror() translation:
strerror.c
from:usbi_locale_supported
[]{ / * English (en) * / ... }
section and add it at the end of usbi_localized_errors
usbi_localized_errors
could look like: libusb-devel@lists.sourceforge.net