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

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_option { LIBUSB_OPTION_LOG_LEVEL, LIBUSB_OPTION_USE_USBDK }
 Available option values for libusb_set_option(). More...
 

Functions

void libusb_set_debug (libusb_context *ctx, int level)
 
int libusb_set_option (libusb_context *ctx, enum libusb_option option,...)
 Set an option in the library. More...
 
int libusb_init (libusb_context **context)
 Initialize libusb. More...
 
void libusb_exit (struct 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

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.

Enumeration Type Documentation

Log message levels.

  • LIBUSB_LOG_LEVEL_NONE (0) : no messages ever printed by the library (default)
  • LIBUSB_LOG_LEVEL_ERROR (1) : error messages are printed to stderr
  • LIBUSB_LOG_LEVEL_WARNING (2) : warning and error messages are printed to stderr
  • LIBUSB_LOG_LEVEL_INFO (3) : informational messages are printed to stderr
  • LIBUSB_LOG_LEVEL_DEBUG (4) : debug and informational messages are printed to stderr

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

void libusb_set_debug ( libusb_context ctx,
int  level 
)
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.

Since version 1.0.22, LIBUSB_API_VERSION >= 0x01000106

Parameters
ctxcontext on which to operate
optionwhich 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
int 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
contextOptional 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
void libusb_exit ( struct libusb_context ctx)

Deinitialize libusb.

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

Parameters
ctxthe context to deinitialize, or NULL for the default context