Changes between Version 3 and Version 4 of APIs


Ignore:
Timestamp:
01/05/14 19:10:06 (3 years ago)
Author:
stuge
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • APIs

    v3 v4  
    11[[PageOutline(2-5, Table of Contents, floated)]] 
    22 
    3 == Version overview == 
     3== API version overview == 
    44There are two libusb API versions: 
    5  * [wiki:libusb-1.0] is the current version, under active development 
     5 * [wiki:libusb-1.0] is the current API version under active development 
     6  * libusb-1.0 API symbols begin with '''libusb_''' or '''LIBUSB_'''. 
     7 
    68 * libusb-0.1 is the original version which is deprecated and unmaintained since many years 
    7   * libusb-compat-0.1 is a compatibility library which provides the libusb-0.1 API by using libusb-1.0 
     9  * libusb-0.1 API symbols begin with '''usb_''' or '''USB_'''. 
    810 
    9 The different API versions do not conflict, so they can be installed in parallell on a system. However, if you have installed libusb-1.0 then we strongly recommend to use libusb-compat-0.1 instead of the ancient libusb-0.1 code, so that programs which use both the 0.1 API and the 1.0 API in different parts of the program, or in different libraries used by the program, will both end up using libusb-1.0 for actual device access. This is important to avoid potential conflicts between libusb-1.0 and libusb-0.1 being used ''by the same process''. 
     11== API implementation overview == 
     12There are many different implementations of the two libusb APIs, each developed by a different community. This is unfortunately a frequent cause of confusion for libusb users. 
    1013 
    11 In addition to the above libraries by the libusb project there is also a separate project which provides the libusb-0.1 API on Windows: 
     14There are three libusb-1.0 API implementations: 
     15 * '''libusb''' is the implementation developed here on libusb.org by successors of the original libusb authors. 
     16 * '''libusbx''' describes itself as a ''hostile fork'' of libusb and uses the same SONAMEs and filenames as libusb. Many Linux distributions currently ship libusbx. It was created by developers who disagree with libusb's high quality standards and the resulting moderate development pace. libusbx development takes place outside of libusb.org. 
     17 * FreeBSD ships their own implementation of the libusb-1.0 API as part of their system libraries. 
    1218 
    13 * [wiki:libusb-win32] (It is a separate project, but several contributors participate in both libusb and libusb-win32.) 
     19There are several libusb-0.1 API implementations: 
     20 * libusb-0.1 is the very first libusb implementation. 
     21 * libusb-compat-0.1 is a compatibility library which provides the libusb-0.1 API by using the libusb-1.0 API. 
     22 * [wiki:libusb-win32] is a Windows-only implementation of the libusb-0.1 API. The libusb-win32 project has also created the open source libusb0.sys Windows kernel driver, which exposes a userspace API that allows USB devices to be accessed outside of the Windows kernel. 
     23 * FreeBSD ships their own implementation of the libusb-0.1 API as part of their system libraries. 
    1424 
    15 == libusb-1.0 (current API) == 
     25Because the 0.1 and 1.0 APIs use different prefixes they are compatible with each other. It is common that both are installed in parallel on a system. We strongly recommend using libusb-1.0 together with libusb-compat-0.1 instead of the ancient libusb-0.1 code, so that programs which use both the 0.1 API and the 1.0 API in different parts of the program, or in different libraries used by the program, will all use libusb-1.0 for the actual device access. This is important to avoid potential conflicts between libusb-1.0 and libusb-0.1 being used ''in the same process''. 
    1626 
    17 Daniel Drake adopted the project in January 2008 and worked on the [wiki:libusb-1.0] API and implementation, which adds several features missing in the 0.1 API. libusb-1.0 is the recommended version to use for all new development. Developers are encouraged to port existing applications which use libusb-0.1 to use the new API. 
     27 
     28== libusb-1.0 (current API and implementation) == 
     29 
     30Daniel Drake adopted the project in January 2008 and worked on the [wiki:libusb-1.0] API and implementation, which adds several features missing from the 0.1 API. libusb-1.0 is recommended for all new development. Developers are encouraged to port existing applications which use libusb-0.1 to use the new API. 
    1831 
    1932 * '''[http://sourceforge.net/projects/libusb/files/libusb-1.0/ Download sources]''' 
    2033 * ''See the [wiki:libusb-1.0] page for more detailed information about libusb-1.0'' 
    2134 * [api-1.0: libusb-1.0 API documentation] 
    22  * Linux, Mac OS X, [wiki:windows_backend Windows], OpenBSD and NetBSD are currently supported. 
     35 * Linux, Mac OS X, Windows, OpenBSD and NetBSD are currently supported. 
    2336 * FreeBSD includes a separate implementation of the libusb-0.1 and libusb-1.0 APIs in the system libc. 
    24  * The [wiki:windows_backend Windows backend] currently depends on the generic USB device driver WinUSB.sys by Microsoft, which is included with all Windows versions starting with Windows Vista. There is [ticket:49 a ticket] about support for the libusb0.sys kernel driver developed by the libusb-win32 project. 
     37 * The Windows backend currently uses the generic USB device driver WinUSB.sys by Microsoft, which is included with all Windows versions starting with Windows Vista. There is [ticket:49 a ticket] about supporting the libusb0.sys kernel driver created by the [wiki:libusb-win32] project. 
    2538 
    26 A device driver which supports libusb must always be used for the device on every operating system. Each operating system has different rules for device drivers. On Mac OS X, if an interface driver included with the OS matches the characteristics of a device, that driver will seize the interface, and the driver cannot be detached by libusb, so libusb will not be able to use that interface. In the case of OpenBSD and NetBSD, libusb-1.0 can be used only for device with ugen driver. For Windows, if you need to read from or write to the USB device, currently only devices with WinUSB driver are supported. 
     39A kernel driver which supports using libusb in userspace is always required, on every operating system. Each operating system has different rules for device drivers. On Mac OS X, if an interface driver included with the OS matches the characteristics of a USB device's interface then that driver seizes the interface and the driver cannot be detached by libusb, so libusb can not access that interface. In the case of OpenBSD and NetBSD libusb-1.0 can be used only for devices with the ugen driver. For Windows currently only the WinUSB driver is supported. 
    2740 
    28 libusb is not well suited for accessing HID class devices. It is possible to use libusb with HID device though if the original driver is replaced by a supported driver but this is usually not easy on non-Linux platforms. It is recommended to use [http://www.signal11.us/oss/hidapi/ HIDAPI] instead, for convenient and cross-platform access to HID class devices. 
     41libusb is not suited for HID class devices. While it is possible to use libusb with HID class devices it requires the original HID class driver to be replaced by a driver which supports libusb, and this leads to a quite poor user experience on any platform other than Linux. It is recommended to use [http://www.signal11.us/oss/hidapi/ HIDAPI] instead. HIDAPI provides convenient cross-platform access to HID class devices and can do so without any kernel driver concerns across all supported platforms. 
    2942 
    3043== libusb-0.1 (legacy API) ==