libusb: Library initialization/deinitialization

| libusb 1.0.26 A cross-platform user library to access USB devices

Data Structures | Typedefs | Enumerations | Functions
Library initialization/deinitialization

This page details how to initialize and deinitialize libusb. More...

## Data Structures
struct | libusb_version
| Structure providing the version of the libusb runtime. More...

## Typedefs
typedef struct libusb_context | libusb_context
| Structure representing a libusb session. More...
typedef void(* | libusb_log_cb) (libusb_context *ctx, enum libusb_log_level level, const char *str)
| Callback function for handling log messages. More...

## Enumerations
enum | libusb_log_level { LIBUSB_LOG_LEVEL_NONE = 0 , LIBUSB_LOG_LEVEL_ERROR = 1 , LIBUSB_LOG_LEVEL_WARNING = 2 , LIBUSB_LOG_LEVEL_INFO = 3 , LIBUSB_LOG_LEVEL_DEBUG = 4 }
| Log message levels. More...
enum | libusb_log_cb_mode { LIBUSB_LOG_CB_GLOBAL = (1 << 0) , LIBUSB_LOG_CB_CONTEXT = (1 << 1) }
| Log callback mode. More...
enum | libusb_option { LIBUSB_OPTION_LOG_LEVEL = 0 , LIBUSB_OPTION_USE_USBDK = 1 , LIBUSB_OPTION_NO_DEVICE_DISCOVERY = 2 , LIBUSB_OPTION_MAX = 3 }
| Available option values for libusb_set_option(). More...

## Functions
void | libusb_set_debug (libusb_context *ctx, int level)
void | libusb_set_log_cb (libusb_context *ctx, libusb_log_cb cb, int mode)
| Set log handler. More...
int | libusb_set_option (libusb_context *ctx, enum libusb_option option,...)
| Set an option in the library. More...
int | libusb_init (libusb_context **ctx)
| Initialize libusb. More...
void | libusb_exit (libusb_context *ctx)
| Deinitialize libusb. More...

## Detailed Description

This page details how to initialize and deinitialize libusb.

Initialization must be performed before using any libusb functionality, and similarly you must not call any libusb functions after deinitialization.

## Typedef Documentation

## ◆ libusb_context

typedef struct libusb_context libusb_context

Structure representing a libusb session.

The concept of individual libusb sessions allows for your program to use two libraries (or dynamically load two modules) which both independently use libusb. This will prevent interference between the individual libusb users - for example libusb_set_option() will not affect the other user of the library, and libusb_exit() will not destroy resources that the other user is still using.

Sessions are created by libusb_init() and destroyed through libusb_exit(). If your application is guaranteed to only ever include a single libusb user (i.e. you), you do not have to worry about contexts: pass NULL in every function call where a context is required, and the default context will be used. Note that libusb_set_option(NULL, ...) is special, and adds an option to a list of default options for new contexts.

For more information, see Contexts.

## ◆ libusb_log_cb

typedef void(* libusb_log_cb) (libusb_context *ctx, enum libusb_log_level level, const char *str)

Callback function for handling log messages.

Parameters

  ctx | the context which is related to the log message, or NULL if it is a global log message
  level | the log level, see libusb_log_level for a description
  str | the log message

Since version 1.0.23, LIBUSB_API_VERSION >= 0x01000107

See also
  libusb_set_log_cb()

## Enumeration Type Documentation

## ◆ libusb_log_level

enum libusb_log_level

Log message levels.

Enumerator
LIBUSB_LOG_LEVEL_NONE | (0) : No messages ever emitted by the library (default)
LIBUSB_LOG_LEVEL_ERROR | (1) : Error messages are emitted
LIBUSB_LOG_LEVEL_WARNING | (2) : Warning and error messages are emitted
LIBUSB_LOG_LEVEL_INFO | (3) : Informational, warning and error messages are emitted
LIBUSB_LOG_LEVEL_DEBUG | (4) : All messages are emitted

## ◆ libusb_log_cb_mode

enum libusb_log_cb_mode

Log callback mode.

Since version 1.0.23, LIBUSB_API_VERSION >= 0x01000107

See also
  libusb_set_log_cb()

Enumerator
LIBUSB_LOG_CB_GLOBAL | Callback function handling all log messages.
LIBUSB_LOG_CB_CONTEXT | Callback function handling context related log messages.

## ◆ libusb_option

enum libusb_option

Available option values for libusb_set_option().

Enumerator
LIBUSB_OPTION_LOG_LEVEL | Set the log message verbosity. The default level is LIBUSB_LOG_LEVEL_NONE, which means no messages are ever printed. If you choose to increase the message verbosity level, ensure that your application does not close the stderr file descriptor. You are advised to use level LIBUSB_LOG_LEVEL_WARNING. libusb is conservative with its message logging and most of the time, will only log messages that explain error conditions and other oddities. This will help you debug your software. If the LIBUSB_DEBUG environment variable was set when libusb was initialized, this function does nothing: the message verbosity is fixed to the value in the environment variable. If libusb was compiled without any message logging, this function does nothing: you'll never get any messages. If libusb was compiled with verbose debug message logging, this function does nothing: you'll always get messages from all levels.
LIBUSB_OPTION_USE_USBDK | Use the UsbDk backend for a specific context, if available. This option should be set immediately after calling libusb_init(), otherwise unspecified behavior may occur. Only valid on Windows.
LIBUSB_OPTION_NO_DEVICE_DISCOVERY | Do not scan for devices. With this option set, libusb will skip scanning devices in libusb_init(). Must be set before calling libusb_init(). Hotplug functionality will also be deactivated. The option is useful in combination with libusb_wrap_sys_device(), which can access a device directly without prior device scanning. This is typically needed on Android, where access to USB devices is limited. For LIBUSB_API_VERSION 0x01000108 it was called LIBUSB_OPTION_WEAK_AUTHORITY Only valid on Linux.

## Function Documentation

## ◆ libusb_set_debug()

void libusb_set_debug | ( | libusb_context * | ctx,
|  | int | level
| ) |  |

Deprecated:
  Use libusb_set_option() instead using the LIBUSB_OPTION_LOG_LEVEL option.

## ◆ libusb_set_log_cb()

void libusb_set_log_cb | ( | libusb_context * | ctx,
|  | libusb_log_cb | cb,
|  | int | mode
| ) |  |

Set log handler.

libusb will redirect its log messages to the provided callback function. libusb supports redirection of per context and global log messages. Log messages sent to the context will be sent to the global log handler too.

If libusb is compiled without message logging or USE_SYSTEM_LOGGING_FACILITY is defined then global callback function will never be called. If ENABLE_DEBUG_LOGGING is defined then per context callback function will never be called.

Since version 1.0.23, LIBUSB_API_VERSION >= 0x01000107

Parameters

  ctx | context on which to assign log handler, or NULL for the default context. Parameter ignored if only LIBUSB_LOG_CB_GLOBAL mode is requested.
  cb | pointer to the callback function, or NULL to stop log messages redirection
  mode | mode of callback function operation. Several modes can be selected for a single callback function, see libusb_log_cb_mode for a description.

See also
  libusb_log_cb, libusb_log_cb_mode

## ◆ libusb_set_option()

int libusb_set_option | ( | libusb_context * | ctx,
|  | enum libusb_option | option,
|  |  | ...
| ) |  |

Set an option in the library.

Use this function to configure a specific option within the library.

Some options require one or more arguments to be provided. Consult each option's documentation for specific requirements.

If the context ctx is NULL, the option will be added to a list of default options that will be applied to all subsequently created contexts.

Since version 1.0.22, LIBUSB_API_VERSION >= 0x01000106

Parameters

  ctx | context on which to operate
  option | which option to set
  ... | any required arguments for the specified option

Returns
  LIBUSB_SUCCESS on success
  LIBUSB_ERROR_INVALID_PARAM if the option or arguments are invalid
  LIBUSB_ERROR_NOT_SUPPORTED if the option is valid but not supported on this platform
  LIBUSB_ERROR_NOT_FOUND if LIBUSB_OPTION_USE_USBDK is valid on this platform but UsbDk is not available

## ◆ libusb_init()

int libusb_init | ( | libusb_context ** | ctx | ) |

Initialize libusb.

This function must be called before calling any other libusb function.

If you do not provide an output location for a context pointer, a default context will be created. If there was already a default context, it will be reused (and nothing will be initialized/reinitialized).

Parameters

  ctx | Optional output location for context pointer. Only valid on return code 0.

Returns
  0 on success, or a LIBUSB_ERROR code on failure

See also
  libusb_contexts

## ◆ libusb_exit()

void libusb_exit | ( | libusb_context * | ctx | ) |

Deinitialize libusb.

Should be called after closing all open devices and before your application terminates.

Parameters

  ctx | the context to deinitialize, or NULL for the default context