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...
struct	libusb_init_option
	Structure used for setting options through libusb_init_context. 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_LOG_CB = 3 ,   LIBUSB_OPTION_MAX = 4 }
	Available option values for libusb_set_option() and libusb_init_context(). More...

Functions
void	libusb_set_debug (libusb_context *ctx, int level)
	Deprecated. More...
void	libusb_set_log_cb (libusb_context *ctx, libusb_log_cb cb, int mode)
	Set log handler. More...
int API_EXPORTEDV	libusb_set_option (libusb_context *ctx, enum libusb_option option,...)
	Set an option in the library. More...
int	libusb_init (libusb_context **ctx)
	Deprecated initialization function. More...
int	libusb_init_context (libusb_context **ctx, const struct libusb_init_option options[], int num_options)
	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_context() 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() and libusb_init_context().

Enumerator
LIBUSB_OPTION_LOG_LEVEL	Set the log message verbosity. This option must be provided an argument of type libusb_log_level. 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 option does nothing: the message verbosity is fixed to the value in the environment variable. If libusb was compiled without any message logging, this option does nothing: you'll never get any messages. If libusb was compiled with verbose debug message logging, this option 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 at initialization with libusb_init_context() otherwise unspecified behavior may occur. Only valid on Windows. Ignored on all other platforms.
LIBUSB_OPTION_NO_DEVICE_DISCOVERY	Do not scan for devices. With this option set, libusb will skip scanning devices in libusb_init_context(). 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. This option should only be used with libusb_init_context() otherwise unspecified behavior may occur. Only valid on Linux. Ignored on all other platforms.
LIBUSB_OPTION_LOG_CB	Set the context log callback function. Set the log callback function either on a context or globally. This option must be provided an argument of type libusb_log_cb. Using this option with a NULL context is equivalent to calling libusb_set_log_cb() with mode LIBUSB_LOG_CB_GLOBAL. Using it with a non-NULL context is equivalent to calling libusb_set_log_cb() with mode LIBUSB_LOG_CB_CONTEXT.

Function Documentation

libusb_set_debug()

void libusb_set_debug	(	libusb_context *	ctx,
		int	level
	)

Deprecated.

Use libusb_set_option() or libusb_init_context() instead, with 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 API_EXPORTEDV 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

)

Deprecated initialization function.

Equivalent to calling libusb_init_context with no options.

See also

libusb_init_context

libusb_init_context()

int libusb_init_context	(	libusb_context **	ctx,
		const struct libusb_init_option	options[],
		int	num_options
	)

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 and options will be ignored). If num_options is 0 then options is ignored and may be NULL.

Since version 1.0.27, LIBUSB_API_VERSION >= 0x0100010A

Parameters

ctx	Optional output location for context pointer. Only valid on return code 0.
options	Optional array of options to set on the new context.
num_options	Number of elements in the options array.

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