Commit 32a3de0d authored by Thiago Santini's avatar Thiago Santini

Starts UVC engine

parents
Qt UVC Engine
=============
This plugin provides a backend for UVC camera access through Qt's QCamera on Windows,
which usually is provided through DirectShow or Microsoft Media Foundation.
It was mainly developed (and tested!) to allow for an uniform interface to Pupil Lab's eye tracker,
thus allowing [EyeRec] (http://www.ti.uni-tuebingen.de/EyeRec.1907.0.html) and EyeRecToo to make use of these devices.
Notes
------------
**This is beta software at the moment, in particular because of the poor libuvc/libusb support on Windows.**
Dependencies
------------
1. [Libusb with isochronous support] (http://github.com/pupil-labs/libusb)
2. [Libuvc] (http://github.com/pupil-labs/libuvc)
3. MSVS 2015
4. Developed with Qt 5.7.0 [(here for possible compatibility issues)] (http://doc.qt.io/qt-5/deployment-plugins.html)
all: libusb-1.0.la libusb-1.0.dll
AUTOMAKE_OPTIONS = subdir-objects
lib_LTLIBRARIES = libusb-1.0.la
POSIX_POLL_SRC = os/poll_posix.h os/poll_posix.c
POSIX_THREADS_SRC = os/threads_posix.h os/threads_posix.c
WINDOWS_POLL_SRC = os/poll_windows.h os/poll_windows.c
WINDOWS_THREADS_SRC = os/threads_windows.h os/threads_windows.c
LINUX_USBFS_SRC = os/linux_usbfs.h os/linux_usbfs.c
DARWIN_USB_SRC = os/darwin_usb.h os/darwin_usb.c
OPENBSD_USB_SRC = os/openbsd_usb.c
NETBSD_USB_SRC = os/netbsd_usb.c
SUNOS_USB_SRC = os/sunos_usb.c os/sunos_usb.h
WINDOWS_COMMON_SRC = os/windows_nt_common.h os/windows_nt_common.c \
os/windows_common.h libusb-1.0.rc libusb-1.0.def
WINDOWS_USB_SRC = os/windows_winusb.h os/windows_winusb.c
WINDOWS_USBDK_SRC = os/windows_usbdk.h os/windows_usbdk.c
WINCE_USB_SRC = os/wince_usb.h os/wince_usb.c
HAIKU_USB_SRC = os/haiku_usb.h os/haiku_usb_backend.cpp \
os/haiku_usb_raw.h os/haiku_usb_raw.cpp os/haiku_pollfs.cpp
EXTRA_DIST = $(POSIX_POLL_SRC) $(POSIX_THREADS_SRC) \
$(WINDOWS_POLL_SRC) $(WINDOWS_THREADS_SRC) \
$(LINUX_USBFS_SRC) $(DARWIN_USB_SRC) \
$(OPENBSD_USB_SRC) $(NETBSD_USB_SRC) \
$(WINDOWS_COMMON_SRC) $(WINDOWS_USB_SRC) $(WINDOWS_USBDK_SRC) \
$(WINCE_USB_SRC) $(HAIKU_USB_SRC) \
os/linux_udev.c os/linux_netlink.c
if OS_LINUX
if USE_UDEV
OS_SRC = $(LINUX_USBFS_SRC) os/linux_udev.c
else
OS_SRC = $(LINUX_USBFS_SRC) os/linux_netlink.c
endif
endif
if OS_DARWIN
OS_SRC = $(DARWIN_USB_SRC)
AM_CFLAGS_EXT = -no-cpp-precomp
endif
if OS_OPENBSD
OS_SRC = $(OPENBSD_USB_SRC)
endif
if OS_NETBSD
OS_SRC = $(NETBSD_USB_SRC)
endif
if OS_SUNOS
OS_SRC = $(SUNOS_USB_SRC)
endif
if OS_HAIKU
noinst_LTLIBRARIES = libusb_haiku.la
libusb_haiku_la_SOURCES = $(HAIKU_USB_SRC)
libusb_1_0_la_LIBADD = libusb_haiku.la
endif
if OS_WINDOWS
if USE_USBDK
OS_SRC = $(WINDOWS_USBDK_SRC) $(WINDOWS_COMMON_SRC)
else
OS_SRC = $(WINDOWS_USB_SRC) $(WINDOWS_COMMON_SRC)
endif
.rc.lo:
$(AM_V_GEN)$(LIBTOOL) $(AM_V_lt) $(AM_LIBTOOLFLAGS) $(LIBTOOLFLAGS) --tag=RC --mode=compile $(RC) $(RCFLAGS) -i $< -o $@
libusb-1.0.rc: version.h version_nano.h
endif
libusb-1.0.dll: libusb-1.0.def libusb-1.0.la
if CREATE_IMPORT_LIB
# Rebuild the import lib from the .def so that MS and MinGW DLLs can be interchanged
$(AM_V_GEN)$(DLLTOOL) $(DLLTOOLFLAGS) --kill-at --input-def $(srcdir)/libusb-1.0.def --dllname $@ --output-lib .libs/$@.a
endif
if OS_WINDOWS
POLL_SRC = $(WINDOWS_POLL_SRC)
else
POLL_SRC = $(POSIX_POLL_SRC)
endif
if THREADS_POSIX
THREADS_SRC = $(POSIX_THREADS_SRC)
else
THREADS_SRC = $(WINDOWS_THREADS_SRC)
endif
libusb_1_0_la_CFLAGS = $(AM_CFLAGS)
libusb_1_0_la_LDFLAGS = $(LTLDFLAGS)
libusb_1_0_la_SOURCES = libusbi.h libusb.h version.h version_nano.h \
core.c descriptor.c hotplug.h hotplug.c io.c strerror.c sync.c \
$(POLL_SRC) $(THREADS_SRC) $(OS_SRC)
hdrdir = $(includedir)/libusb-1.0
hdr_HEADERS = libusb.h
/* -*- Mode: C; indent-tabs-mode:t ; c-basic-offset:8 -*- */
/*
* Core functions for libusb
* Copyright © 2012-2013 Nathan Hjelm <hjelmn@cs.unm.edu>
* Copyright © 2007-2008 Daniel Drake <dsd@gentoo.org>
* Copyright © 2001 Johannes Erdfelt <johannes@erdfelt.com>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
#include "config.h"
#include <errno.h>
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#ifdef HAVE_SYS_TYPES_H
#include <sys/types.h>
#endif
#ifdef HAVE_SYS_TIME_H
#include <sys/time.h>
#endif
#ifdef HAVE_SYSLOG_H
#include <syslog.h>
#endif
#ifdef __ANDROID__
#include <android/log.h>
#endif
#include "libusbi.h"
#include "hotplug.h"
#if defined(OS_LINUX)
const struct usbi_os_backend * const usbi_backend = &linux_usbfs_backend;
#elif defined(OS_DARWIN)
const struct usbi_os_backend * const usbi_backend = &darwin_backend;
#elif defined(OS_OPENBSD)
const struct usbi_os_backend * const usbi_backend = &openbsd_backend;
#elif defined(OS_NETBSD)
const struct usbi_os_backend * const usbi_backend = &netbsd_backend;
#elif defined(OS_WINDOWS)
#if defined(USE_USBDK)
const struct usbi_os_backend * const usbi_backend = &usbdk_backend;
#else
const struct usbi_os_backend * const usbi_backend = &windows_backend;
#endif
#elif defined(OS_WINCE)
const struct usbi_os_backend * const usbi_backend = &wince_backend;
#elif defined(OS_HAIKU)
const struct usbi_os_backend * const usbi_backend = &haiku_usb_raw_backend;
#elif defined (OS_SUNOS)
const struct usbi_os_backend * const usbi_backend = &sunos_backend;
#else
#error "Unsupported OS"
#endif
struct libusb_context *usbi_default_context = NULL;
static const struct libusb_version libusb_version_internal =
{ LIBUSB_MAJOR, LIBUSB_MINOR, LIBUSB_MICRO, LIBUSB_NANO,
LIBUSB_RC, "http://libusb.info" };
static int default_context_refcnt = 0;
static usbi_mutex_static_t default_context_lock = USBI_MUTEX_INITIALIZER;
static struct timeval timestamp_origin = { 0, 0 };
usbi_mutex_static_t active_contexts_lock = USBI_MUTEX_INITIALIZER;
struct list_head active_contexts_list;
/**
* \mainpage libusb-1.0 API Reference
*
* \section intro Introduction
*
* libusb is an open source library that allows you to communicate with USB
* devices from userspace. For more info, see the
* <a href="http://libusb.info">libusb homepage</a>.
*
* 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
* <a href="http://mailing-list.libusb.info">libusb-devel mailing list</a>.
*
* 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 <a href="http://www.usb.org/developers/docs/">USB 3.0
* Specification</a> 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 \ref 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 \ref 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 \ref 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 \ref 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_debug(), 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_debug() function can be used to enable logging of certain
* messages. Under standard configuration, libusb doesn't really log much
* so you are advised to use this function 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_debug() parameter. When this
* environment variable is set, the message logging verbosity level is fixed
* and libusb_set_debug() effectively does nothing.
*
* libusb can be compiled without any logging functions, useful for embedded
* systems. In this case, libusb_set_debug() and the LIBUSB_DEBUG environment
* variable have no effects.
*
* 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. libusb_set_debug() and the LIBUSB_DEBUG environment variable
* have no effects.
*
* \section remarks Other remarks
*
* libusb does have imperfections. The \ref libusb_caveats "caveats" page attempts
* to document these.
*/
/**
* \page libusb_caveats Caveats
*
* \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 userspace.
* 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 userspace.
*
* \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
* <em>after</em> 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 \ref libusb_transfer_flags::LIBUSB_TRANSFER_ADD_ZERO_PACKET
* "LIBUSB_TRANSFER_ADD_ZERO_PACKET" flag is currently only supported on Linux.
*/
/**
* \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: libusb_set_debug() calls
* from one user will not affect the same settings for other users, other
* users can continue using libusb after one of them calls libusb_exit(), etc.
*
* This is made possible through libusb's <em>context</em> concept. When you
* call libusb_init(), 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() 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(NULL) 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_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_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_interface_alt_setting()
* - libusb_set_iso_packet_lengths()
* - 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()
*
* \section Structures
* - libusb_bos_descriptor
* - libusb_bos_dev_capability_descriptor
* - libusb_config_descriptor
* - libusb_container_id_descriptor
* - \ref libusb_context
* - libusb_control_setup
* - \ref libusb_device
* - libusb_device_descriptor
* - \ref 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
* - \ref libusb_bos_type
* - \ref libusb_capability
* - \ref libusb_class_code
* - \ref libusb_descriptor_type
* - \ref libusb_endpoint_direction
* - \ref libusb_error
* - \ref libusb_iso_sync_type
* - \ref libusb_iso_usage_type
* - \ref libusb_log_level
* - \ref libusb_request_recipient
* - \ref libusb_request_type
* - \ref libusb_speed
* - \ref libusb_ss_usb_device_capability_attributes
* - \ref libusb_standard_request
* - \ref libusb_supported_speed
* - \ref libusb_transfer_flags
* - \ref libusb_transfer_status
* - \ref libusb_transfer_type
* - \ref libusb_usb_2_0_extension_attributes
*/
/**
* @defgroup libusb_lib Library initialization/deinitialization
* 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.
*/
/**
* @defgroup libusb_dev Device handling and enumeration
* 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
* \ref 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.