Library initialization/deinitialization

Classes
struct	libusb_version

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

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 }
enum	libusb_log_cb_mode { LIBUSB_LOG_CB_GLOBAL = (1 << 0), LIBUSB_LOG_CB_CONTEXT = (1 << 1) }
enum	libusb_option { LIBUSB_OPTION_LOG_LEVEL = 0, LIBUSB_OPTION_USE_USBDK = 1 }

Functions
void API_EXPORTED	libusb_set_debug (libusb_context *ctx, int level)
void API_EXPORTED	libusb_set_log_cb (libusb_context *ctx, libusb_log_cb cb, int mode)
int API_EXPORTED	libusb_set_option (libusb_context *ctx, enum libusb_option option,...)
int API_EXPORTED	libusb_init (libusb_context **context)
void API_EXPORTED	libusb_exit (libusb_context *ctx)

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. The default context will be used.

For more information, see Contexts.

libusb_log_cb

typedef void(LIBUSB_CALL * 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

See also

libusb_set_log_cb()

Enumeration Type Documentation

libusb_log_cb_mode

enum libusb_log_cb_mode

Log callback mode.

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_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_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.

Function Documentation

libusb_exit()

void API_EXPORTED 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

libusb_init()

int API_EXPORTED libusb_init

(

libusb_context **

context

)

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

context

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_set_debug()

void API_EXPORTED 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 API_EXPORTED 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.

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_EXPORTED 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.

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