DISCOVERED_DEVICES_SIZE_STEP macro

\mainpage libusb-1.0 API Reference \section intro Introduction libusb is an open source library that allows you to communicate with USB devices from user space. For more info, see the libusb homepage. This documentation is aimed at application developers wishing to communicate with USB peripherals from their own software. After reviewing this documentation, feedback and questions can be sent to the libusb-devel mailing list. This documentation assumes knowledge of how to operate USB devices from a software standpoint (descriptors, configurations, interfaces, endpoints, control/bulk/interrupt/isochronous transfers, etc). Full information can be found in the USB 3.0 Specification which is available for free download. You can probably find less verbose introductions by searching the web. \section API Application Programming Interface (API) See the libusb_api page for a complete list of the libusb functions. \section features Library features - All transfer types supported (control/bulk/interrupt/isochronous) - 2 transfer interfaces: -# Synchronous (simple) -# Asynchronous (more complicated, but more powerful) - Thread safe (although the asynchronous interface means that you usually won't need to thread) - Lightweight with lean API - Compatible with libusb-0.1 through the libusb-compat-0.1 translation layer - Hotplug support (on some platforms). See libusb_hotplug. \section gettingstarted Getting Started To begin reading the API documentation, start with the Modules page which links to the different categories of libusb's functionality. One decision you will have to make is whether to use the synchronous or the asynchronous data transfer interface. The libusb_io documentation provides some insight into this topic. Some example programs can be found in the libusb source distribution under the "examples" subdirectory. The libusb homepage includes a list of real-life project examples which use libusb. \section errorhandling Error handling libusb functions typically return 0 on success or a negative error code on failure. These negative error codes relate to LIBUSB_ERROR constants which are listed on the libusb_misc "miscellaneous" documentation page. \section msglog Debug message logging libusb uses stderr for all logging. By default, logging is set to NONE, which means that no output will be produced. However, unless the library has been compiled with logging disabled, then any application calls to libusb_set_option(ctx, LIBUSB_OPTION_LOG_LEVEL, level), libusb_init_context, or the setting of the environmental variable LIBUSB_DEBUG outside of the application, can result in logging being produced. Your application should therefore not close stderr, but instead direct it to the null device if its output is undesirable. The libusb_set_option(ctx, LIBUSB_OPTION_LOG_LEVEL, level) or libusb_init_context functions can be used to enable logging of certain messages. With the default configuration, libusb will not log much so if you are advised to use one of these functions to enable all error/warning/informational messages. It will help debug problems with your software. The logged messages are unstructured. There is no one-to-one correspondence between messages being logged and success or failure return codes from libusb functions. There is no format to the messages, so you should not try to capture or parse them. They are not and will not be localized. These messages are not intended to being passed to your application user; instead, you should interpret the error codes returned from libusb functions and provide appropriate notification to the user. The messages are simply there to aid you as a programmer, and if you're confused because you're getting a strange error code from a libusb function, enabling message logging may give you a suitable explanation. The LIBUSB_DEBUG environment variable can be used to enable message logging at run-time. This environment variable should be set to a log level number, which is interpreted the same as the libusb_set_option(ctx, LIBUSB_OPTION_LOG_LEVEL, level), or libusb_init_context(&ctx, &(struct libusb_init_option){.option = LIBUSB_OPTION_LOG_LEVEL, .value = {.ival = level}}, 0). When the environment variable is set, the message logging verbosity level is fixed and setting the LIBUSB_OPTION_LOG_LEVEL option has no effect. libusb can be compiled without any logging functions, useful for embedded systems. In this case, neither the LIBUSB_OPTION_LOG_LEVEL option, nor the LIBUSB_DEBUG environment variable will have any effect. libusb can also be compiled with verbose debugging messages always. When the library is compiled in this way, all messages of all verbosities are always logged. Again, in this case, neither the LIBUSB_OPTION_LOG_LEVEL option, nor the LIBUSB_DEBUG environment variable will have any effect. \section remarks Other remarks libusb does have imperfections. The libusb_caveats "caveats" page attempts to document these. \page libusb_caveats Caveats \section threadsafety Thread safety libusb is designed to be completely thread-safe, but as with any API it cannot prevent a user from sabotaging themselves, either intentionally or otherwise. Observe the following general guidelines: - Calls to functions that release a resource (e.g. libusb_close(), libusb_free_config_descriptor()) should not be called concurrently on the same resource. This is no different than concurrently calling free() on the same allocated pointer. - Each individual libusb_transfer should be prepared by a single thread. In other words, no two threads should ever be concurrently filling out the fields of a libusb_transfer . You can liken this to calling sprintf() with the same destination buffer from multiple threads. The results will likely not be what you want unless the input parameters are all the same, but its best to avoid this situation entirely. - Both the libusb_transfer structure and its associated data buffer should not be accessed between the time the transfer is submitted and the time the completion callback is invoked. You can think of "ownership" of these things as being transferred to libusb while the transfer is active. - The various "setter" functions (e.g. libusb_set_log_cb(), libusb_set_pollfd_notifiers()) should not be called concurrently on the resource. Though doing so will not lead to any undefined behavior, it will likely produce results that the application does not expect. Rules for multiple threads and asynchronous I/O are detailed libusb_mtasync "here". \section fork Fork considerations libusb is not designed to work across fork() calls. Depending on the platform, there may be resources in the parent process that are not available to the child (e.g. the hotplug monitor thread on Linux). In addition, since the parent and child will share libusb's internal file descriptors, using libusb in any way from the child could cause the parent process's libusb_context to get into an inconsistent state. On Linux, libusb's file descriptors will be marked as CLOEXEC, which means that it is safe to fork() and exec() without worrying about the child process needing to clean up state or having access to these file descriptors. Other platforms may not be so forgiving, so consider yourself warned! \section devresets Device resets The libusb_reset_device() function allows you to reset a device. If your program has to call such a function, it should obviously be aware that the reset will cause device state to change (e.g. register values may be reset). The problem is that any other program could reset the device your program is working with, at any time. libusb does not offer a mechanism to inform you when this has happened, so if someone else resets your device it will not be clear to your own program why the device state has changed. Ultimately, this is a limitation of writing drivers in user space. Separation from the USB stack in the underlying kernel makes it difficult for the operating system to deliver such notifications to your program. The Linux kernel USB stack allows such reset notifications to be delivered to in-kernel USB drivers, but it is not clear how such notifications could be delivered to second-class drivers that live in user space. \section blockonly Blocking-only functionality The functionality listed below is only available through synchronous, blocking functions. There are no asynchronous/non-blocking alternatives, and no clear ways of implementing these. - Configuration activation (libusb_set_configuration()) - Interface/alternate setting activation (libusb_set_interface_alt_setting()) - Releasing of interfaces (libusb_release_interface()) - Clearing of halt/stall condition (libusb_clear_halt()) - Device resets (libusb_reset_device()) \section configsel Configuration selection and handling When libusb presents a device handle to an application, there is a chance that the corresponding device may be in unconfigured state. For devices with multiple configurations, there is also a chance that the configuration currently selected is not the one that the application wants to use. The obvious solution is to add a call to libusb_set_configuration() early on during your device initialization routines, but there are caveats to be aware of: -# If the device is already in the desired configuration, calling libusb_set_configuration() using the same configuration value will cause a lightweight device reset. This may not be desirable behaviour. -# In the case where the desired configuration is already active, libusb may not even be able to perform a lightweight device reset. For example, take my USB keyboard with fingerprint reader: I'm interested in driving the fingerprint reader interface through libusb, but the kernel's USB-HID driver will almost always have claimed the keyboard interface. Because the kernel has claimed an interface, it is not even possible to perform the lightweight device reset, so libusb_set_configuration() will fail. (Luckily the device in question only has a single configuration.) -# libusb will be unable to set a configuration if other programs or drivers have claimed interfaces. In particular, this means that kernel drivers must be detached from all the interfaces before libusb_set_configuration() may succeed. One solution to some of the above problems is to consider the currently active configuration. If the configuration we want is already active, then we don't have to select any configuration: \code cfg = -1; libusb_get_configuration(dev, &cfg); if (cfg != desired) libusb_set_configuration(dev, desired); \endcode This is probably suitable for most scenarios, but is inherently racy: another application or driver may change the selected configuration after the libusb_get_configuration() call. Even in cases where libusb_set_configuration() succeeds, consider that other applications or drivers may change configuration after your application calls libusb_set_configuration(). One possible way to lock your device into a specific configuration is as follows: -# Set the desired configuration (or use the logic above to realise that it is already in the desired configuration) -# Claim the interface that you wish to use -# Check that the currently active configuration is the one that you want to use. The above method works because once an interface is claimed, no application or driver is able to select another configuration. \section earlycomp Early transfer completion NOTE: This section is currently Linux-centric. I am not sure if any of these considerations apply to Darwin or other platforms. When a transfer completes early (i.e. when less data is received/sent in any one packet than the transfer buffer allows for) then libusb is designed to terminate the transfer immediately, not transferring or receiving any more data unless other transfers have been queued by the user. On legacy platforms, libusb is unable to do this in all situations. After the incomplete packet occurs, "surplus" data may be transferred. For recent versions of libusb, this information is kept (the data length of the transfer is updated) and, for device-to-host transfers, any surplus data was added to the buffer. Still, this is not a nice solution because it loses the information about the end of the short packet, and the user probably wanted that surplus data to arrive in the next logical transfer. \section zlp Zero length packets - libusb is able to send a packet of zero length to an endpoint simply by submitting a transfer of zero length. - The libusb_transfer_flags ::LIBUSB_TRANSFER_ADD_ZERO_PACKET "LIBUSB_TRANSFER_ADD_ZERO_PACKET" flag is currently supported on Linux, Darwin and Windows (WinUSB). \page libusb_contexts Contexts It is possible that libusb may be used simultaneously from two independent libraries linked into the same executable. For example, if your application has a plugin-like system which allows the user to dynamically load a range of modules into your program, it is feasible that two independently developed modules may both use libusb. libusb is written to allow for these multiple user scenarios. The two "instances" of libusb will not interfere: an option set by one user will have no effect the same option for other users, other users can continue using libusb after one of them calls libusb_exit(), etc. This is made possible through libusb's context concept. When you call libusb_init_context(), you are (optionally) given a context. You can then pass this context pointer back into future libusb functions. In order to keep things simple for more simplistic applications, it is legal to pass NULL to all functions requiring a context pointer (as long as you're sure no other code will attempt to use libusb from the same process). When you pass NULL, the default context will be used. The default context is created the first time a process calls libusb_init_context() when no other context is alive. Contexts are destroyed during libusb_exit(). The default context is reference-counted and can be shared. That means that if libusb_init_context(NULL, x, y) is called twice within the same process, the two users end up sharing the same context. The deinitialization and freeing of the default context will only happen when the last user calls libusb_exit(). In other words, the default context is created and initialized when its reference count goes from 0 to 1, and is deinitialized and destroyed when its reference count goes from 1 to 0. You may be wondering why only a subset of libusb functions require a context pointer in their function definition. Internally, libusb stores context pointers in other objects (e.g. libusb_device instances) and hence can infer the context from those objects. \page libusb_api Application Programming Interface This is the complete list of libusb functions, structures and enumerations in alphabetical order. \section Functions - libusb_alloc_streams() - libusb_alloc_transfer() - libusb_attach_kernel_driver() - libusb_bulk_transfer() - libusb_cancel_transfer() - libusb_claim_interface() - libusb_clear_halt() - libusb_close() - libusb_control_transfer() - libusb_control_transfer_get_data() - libusb_control_transfer_get_setup() - libusb_cpu_to_le16() - libusb_detach_kernel_driver() - libusb_dev_mem_alloc() - libusb_dev_mem_free() - libusb_error_name() - libusb_event_handler_active() - libusb_event_handling_ok() - libusb_exit() - libusb_fill_bulk_stream_transfer() - libusb_fill_bulk_transfer() - libusb_fill_control_setup() - libusb_fill_control_transfer() - libusb_fill_interrupt_transfer() - libusb_fill_iso_transfer() - libusb_free_bos_descriptor() - libusb_free_config_descriptor() - libusb_free_container_id_descriptor() - libusb_free_device_list() - libusb_free_pollfds() - libusb_free_ss_endpoint_companion_descriptor() - libusb_free_ss_usb_device_capability_descriptor() - libusb_free_streams() - libusb_free_transfer() - libusb_free_usb_2_0_extension_descriptor() - libusb_get_active_config_descriptor() - libusb_get_bos_descriptor() - libusb_get_bus_number() - libusb_get_config_descriptor() - libusb_get_config_descriptor_by_value() - libusb_get_configuration() - libusb_get_container_id_descriptor() - libusb_get_descriptor() - libusb_get_device() - libusb_get_device_address() - libusb_get_device_descriptor() - libusb_get_device_list() - libusb_get_device_speed() - libusb_get_iso_packet_buffer() - libusb_get_iso_packet_buffer_simple() - libusb_get_max_alt_packet_size() - libusb_get_max_iso_packet_size() - libusb_get_max_packet_size() - libusb_get_next_timeout() - libusb_get_parent() - libusb_get_pollfds() - libusb_get_port_number() - libusb_get_port_numbers() - libusb_get_port_path() - libusb_get_ss_endpoint_companion_descriptor() - libusb_get_ss_usb_device_capability_descriptor() - libusb_get_string_descriptor() - libusb_get_string_descriptor_ascii() - libusb_get_usb_2_0_extension_descriptor() - libusb_get_version() - libusb_handle_events() - libusb_handle_events_completed() - libusb_handle_events_locked() - libusb_handle_events_timeout() - libusb_handle_events_timeout_completed() - libusb_has_capability() - libusb_hotplug_deregister_callback() - libusb_hotplug_register_callback() - libusb_init() - libusb_init_context() - libusb_interrupt_event_handler() - libusb_interrupt_transfer() - libusb_kernel_driver_active() - libusb_lock_events() - libusb_lock_event_waiters() - libusb_open() - libusb_open_device_with_vid_pid() - libusb_pollfds_handle_timeouts() - libusb_ref_device() - libusb_release_interface() - libusb_reset_device() - libusb_set_auto_detach_kernel_driver() - libusb_set_configuration() - libusb_set_debug() - libusb_set_log_cb() - libusb_set_interface_alt_setting() - libusb_set_iso_packet_lengths() - libusb_set_option() - libusb_setlocale() - libusb_set_pollfd_notifiers() - libusb_strerror() - libusb_submit_transfer() - libusb_transfer_get_stream_id() - libusb_transfer_set_stream_id() - libusb_try_lock_events() - libusb_unlock_events() - libusb_unlock_event_waiters() - libusb_unref_device() - libusb_wait_for_event() - libusb_wrap_sys_device() \section Structures - libusb_bos_descriptor - libusb_bos_dev_capability_descriptor - libusb_config_descriptor - libusb_container_id_descriptor - libusb_context - libusb_control_setup - libusb_device - libusb_device_descriptor - libusb_device_handle - libusb_endpoint_descriptor - libusb_interface - libusb_interface_descriptor - libusb_iso_packet_descriptor - libusb_pollfd - libusb_ss_endpoint_companion_descriptor - libusb_ss_usb_device_capability_descriptor - libusb_transfer - libusb_usb_2_0_extension_descriptor - libusb_version \section Enums - libusb_bos_type - libusb_capability - libusb_class_code - libusb_descriptor_type - libusb_endpoint_direction - libusb_endpoint_transfer_type - libusb_error - libusb_iso_sync_type - libusb_iso_usage_type - libusb_log_level - libusb_option - libusb_request_recipient - libusb_request_type - libusb_speed - libusb_ss_usb_device_capability_attributes - libusb_standard_request - libusb_supported_speed - libusb_transfer_flags - libusb_transfer_status - libusb_transfer_type - libusb_usb_2_0_extension_attributes 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. The functionality documented below is designed to help with the following operations: - Enumerating the USB devices currently attached to the system - Choosing a device to operate from your software - Opening and closing the chosen device \section nutshell In a nutshell... The description below really makes things sound more complicated than they actually are. The following sequence of function calls will be suitable for almost all scenarios and does not require you to have such a deep understanding of the resource management issues: \code // discover devices libusb_device **list; libusb_device *found = NULL; ssize_t cnt = libusb_get_device_list(NULL, &list); ssize_t i = 0; int err = 0; if (cnt < 0) error(); for (i = 0; i < cnt; i++) { libusb_device *device = list[i]; if (is_interesting(device)) { found = device; break; } } if (found) { libusb_device_handle *handle; err = libusb_open(found, &handle); if (err) error(); // etc } libusb_free_device_list(list, 1); \endcode The two important points: - You asked libusb_free_device_list() to unreference the devices (2nd parameter) - You opened the device before freeing the list and unreferencing the devices If you ended up with a handle, you can now proceed to perform I/O on the device. \section devshandles Devices and device handles libusb has a concept of a USB device, represented by the libusb_device opaque type. A device represents a USB device that is currently or was previously connected to the system. Using a reference to a device, you can determine certain information about the device (e.g. you can read the descriptor data). The libusb_get_device_list() function can be used to obtain a list of devices currently connected to the system. This is known as device discovery. Devices can also be discovered with the hotplug mechanism, whereby a callback function registered with libusb_hotplug_register_callback() will be called when a device of interest is connected or disconnected. Just because you have a reference to a device does not mean it is necessarily usable. The device may have been unplugged, you may not have permission to operate such device, or another program or driver may be using the device. When you've found a device that you'd like to operate, you must ask libusb to open the device using the libusb_open() function. Assuming success, libusb then returns you a device handle (a libusb_device_handle pointer). All "real" I/O operations then operate on the handle rather than the original device pointer. \section devref Device discovery and reference counting Device discovery (i.e. calling libusb_get_device_list()) returns a freshly-allocated list of devices. The list itself must be freed when you are done with it. libusb also needs to know when it is OK to free the contents of the list - the devices themselves. To handle these issues, libusb provides you with two separate items: - A function to free the list itself - A reference counting system for the devices inside New devices presented by the libusb_get_device_list() function all have a reference count of 1. You can increase and decrease reference count using libusb_ref_device() and libusb_unref_device(). A device is destroyed when its reference count reaches 0. With the above information in mind, the process of opening a device can be viewed as follows: -# Discover devices using libusb_get_device_list() or libusb_hotplug_register_callback(). -# Choose the device that you want to operate, and call libusb_open(). -# Unref all devices in the discovered device list. -# Free the discovered device list. The order is important - you must not unreference the device before attempting to open it, because unreferencing it may destroy the device. For convenience, the libusb_free_device_list() function includes a parameter to optionally unreference all the devices in the list before freeing the list itself. This combines steps 3 and 4 above. As an implementation detail, libusb_open() actually adds a reference to the device in question. This is because the device remains available through the handle via libusb_get_device(). The reference is deleted during libusb_close().