Disallow libusb_get_string_descriptor_ascii() with index 0

String descriptor 0 is the list of supported language IDs in the device,
which can't have an ASCII representation. Calling the function with
index 0 is thus not really useful. Fixes #43.

Use const for the usbi_parse_descriptor() format string

Constant strings should be "const char *" instead of "char *". Silence
"discards qualifiers from pointer target type" warnings. Fixes #61.

Linux: Fix usbfs/sysfs config descriptor handling on big-endian

usbfs endian-swaps, sysfs doesn't, not the other way around. Fixes #51;
descriptor endian parsing is backwards using sysfs on big-endian hosts.
usbfs is untested.

Signed-off-by: Hector Martin <hector@marcansoft.com>
[stuge: checked against Documentation/usb/proc_usb_info.txt]

examples: #include <libusb.h> without directory name

The libusb-1.0 directory name belongs in the compile command, e.g.
via pkg-config --cflags. Fixes #58.

Add missing argument to libusb_wait_for_event() documentation, fix #55

In the libusb_wait_for_event() sample code in the section "Letting other
threads do the work for you" the call to libusb_wait_for_event() was not
updated by commit 1df713d622ab4f0b03aad72d903ac7beb8fb3b90, which added
the libusb_context *ctx parameter to the function, so the sample code
was broken until now.

examples: Silence warnings about return value of fwrite()

Linux: Don't free() URBs prematurely on hardware error; fix #54

When an URB in a multi-URB transfer had an error, handle_bulk_completion()
would free all URBs and segfault once the next one completed, instead of
cancelling the remaining URBs and cleaning up as usual.

This is basically the patch from the ticket, plus some restructuring
for increased readability of the function.

Many thanks to Brian Shirley and National Instruments for finding and
fixing this!

Windows: add support for filter drivers

* precedence is driver > upper filter > lower filter, and defined
  in struct driver_lookup lookup from set_device_paths()

Windows: fix errcode shadow warning, and string and DLL_DECLARE fixes

* use FormatMessageA, and overall improvement of windows_error_str()
* use safe_strlen() always
* better typing/init default
* more explicit debug message for devices with no driver

Windows: use IOCTLs for HID input, output and feature reports

* fixes feature reports not providing actual read size
  (reported by Axel Rohde http://marc.info/?m=127033070021994)
* removes the USE_HIDD_FOR_REPORTS macro
* IOCTL usage inspired from HIDAPI by Alan Ott

Fix libtool version setting

This was being set too early to take effect.

Populate the pkg-config Libs.private field

Linux: fix build failure when CLOCK_MONOTONIC does not exist

This is not available on all platforms.

Update libtool version info

With input from various people on the mailing list, update the libtool
versioning info and start to update this on every release.

The next libusb release will not need a change here. All following ones
will.

Updated documentation for unsupported Darwin/Windows calls

Windows: Make libusb_pollfd() return error

Windows does not have numerical file descriptors but does have the
concept of event sources. Exposing these event sources will require
some careful thought and design, to be completed later.

MinGW: Use --add-stdcall-alias linker option

Naming of symbols inside the library is inconsistent on Windows:
http://wyw.dcweb.cn/stdcall.htm

Use this linker option to add aliases which add compatibility with
the "MSVC DLL" platform when a DEF file is used. It also better matches
the appearance of the Windows API itself.

Introduced calling convention (for Windows)

Under Windows, a variety of compilers and configurations are available,
meaning that the manner of parameter passing (e.g. registers vs stack)
can vary.

Match the Windows API calling convention and document this appropriately.
This calling convention will be used regardless of the configuration of
the user's development platform.

The only user-level complication is that all functions used as libusb
callbacks must use the same calling convention as libusb. The
LIBUSB_CALL macro is provided to make this easy.

Signed-off-by: Michael Plante <michael.plante@gmail.com>
Signed-off-by: Pete Batard <pbatard@gmail.com>
[dsd: slight change of strategy, add documentation]

Windows: fix string copy in sanitize_path

The NULL byte was not being copied.

Windows: DuplicateHandle failure is not a warning

This is because WinUSB handles are not duplicable, and generate a
lot of these warnings.

removed trailing whitespaces

Windows: Mark interfaces as unused when releasing

Without this important cleanup, the autoclaim code could attempt to
reuse an unclaimed interface as if it were already claimed.

Windows: fix device path string duplication

Darwin: Cache device configuration value

Cache device configuration value to bring the Darwin backend more in
line with the libusb spec. To handle buggy devices GetConfiguration is
not called unless the device has more than one configuration.

Fix inconsistencies between prototypes and definitions

This removes some warnings on cygwin regarding a name clash against
the standard library "index" function.

Darwin: handle kIOReturnUnderrun

This return code indicates that the device returned a data packet
less than the max packet size. In libusb backend terms, this is
a successful transfer.

Add Windows support

Via Cygwin/MinGW, libusb now has windows support.
Thanks to contributors: Michael Plante, Orin Eman, Peter Stuge,
Stephan Meyer, Xiaofan Chen.

Darwin: write iso transfer details into correct packets

Darwin: fix interface object leak

Darwin: clean up some debug messages

Darwin: Don't open devices during scan unless we have to unsuspend

Linux: Handle early complete of multi-URB transfer

Only compile dpfp examples when sigaction is available

It's not available on MinGW.

configure.ac: fix bashisms

Only include sys/time.h on appropriate platforms

This header doesn't exist on windows.
For libusb, determine at configure-time if the header is available.
For libusb.h, use gcc predefined macros to only include the header
on platforms that need it.

Linux: Fix log message commit

Forgot to test this.

Only initialize the default context when it is requested

Linux: fix log message that was being unconditionally sent to stderr (#44)

This message was put in place to aid libusb-compat-0.1 users, who
may run into the change that libusb-0.1 allowed you to usb_open() a
device that you don't have write access to, but libusb-1.0 does not.

As explained on the ticket this change is dangerous so it should go through
the usual logging mechanism. I also added a similar regular log message
to libusb-compat-0.1.

Fix 2 documentation typos

add AM_MAINTAINER_MODE

Factorize event handler interruption code

This will be additionally used by the windows backend which modifies
the fd set frequently.

Abstract low-level event handler operations

The Windows backend uses something other than UNIX file descriptors
for event handling. Abstract out the operations to allow for this.

fixes the possibility of using a broken timercmp on Windows

Microsoft's implementation of timercmp does not work for >= or <=.

Switched to standard int pointer type for windows 64-bit compat

On 64-bit Windows a pointer is 64 bit, but long is still 32 bit for
backwards compatibility.
uintptr_t nicely hides this difference and also works on Linux.

[dsd: add appropriate include]

added doxygen, dpfp, msvc, and xusb stuff to gitignore

Add reference counting to default context

Michael Plante pointed out that if 2 users call libusb_init(NULL) within
a process, we end up creating 2 default contexts, one of which is lost.

Add reference counting so that the default context is reused and
destroyed only after the last user.

Fix libusb_init() error handling

9996ccaed7 introduced a problem in that mutexes could be destroyed
in the error handling codepath before they had been created.
Pointed out by Michael Plante.

Modify log functions to compile with MSVC6

MSVC6 does not support variadics.

Add type parameter to the list_for_each_entry() and _safe() macros

typeof() is a GCC extension, not supported by target compilers such
as MSVC.

Fix a usbi_pollfd leak in error path

I accidently missed this when applying Pete Batard's earlier patch.
Pointed out by Michael Plante.

Rename all interface parameters to usb_interface or interface_number

Remove the use of the ambiguous "interface" where possible without
breaking the API.
'interface' is a preprocessor #define already associated with COM on Windows,
that can cause a conflict as soon as windows.h is included.

There are a few more places where interface is still used, which should
be changed for libusb-2.0

Stricter types and casts

Fixes to error handling and exit codepaths

Various locks and things were being leaked/left open when handling
errors and during deinitialization.

[dsd: small tweaks]

Darwin: Define IO_OBJECT_NULL if not already defined

Needed on Mac OSX 10.3

libusb_cpu_to_le16: macro->static inline function

The libusb_cpu_to_le16 macro was a ({ ... }) expression, which
generates the following compiler warning every time it is used,
(and that is several times for every #include <libusb.h>):

libusb.h:880: warning: ISO C forbids braced-groups within expressions

With this patch, #include <libusb.h> stops generating compiler
warnings on gcc 4.4.

As libusb.h heavily relies on the use of static inline functions
those can be relied on to work properly, and there should not be
any significant difference in the code the compiler generates.

Add libusb_strerror() to get short error message in English from enum

[dsd: small tweaks]

Fix libusb_device::lock memory leak

Whitespace cleanup

Add internal abstraction for POSIX Threads

This prepares for a Windows backend without dependency on pthreads-w32.

pthread_* is renamed to usbi_* and PTHREAD_* to USBI_*.

A usbi_mutex_static_t and usbi_mutex_static_lock() and _unlock() are
introduced for statically initialized mutexes, since they may be
implemented using other types when pthreads mutexes aren't used.

Move -pthread from libusb/Makefile.am to host-specific THREAD_CFLAGS in
configure.ac. This will enable optional use of -lpthread for cygwin.

[dsd: minor tweaks, and roll in a change based on patches from Pete
Batard to only build dpfp_threaded example when we're using pthreads]

v1.0.8 release

Linux: don't set SHORT_NOT_OK on bulk out URBs (#20

Setting this flag is illegal, and the behaviour we're looking for
is already in place for host-to-device transfers without this flag.

Linux: Handle failure to read active configuration during enumeration

Darwin: don't reuse cached descriptors during enumeration

Descriptor reuse was causing scans to return invalid information when
the device at a location has changed.

v1.0.7 release

Document that fd set contents are an internal implementation detail (#36)

Linux: correct config descriptor endianness fix

The seek_to_next_config codepath deals with both sysfs and usbfs;
make sure we only convert values in the usbfs path.

Linux: Fix endianness handling of usbfs config descriptors (#27)

driver/usb/core/devio.c function usbdev_read translate the follwing files
to CPU endianess:

le16_to_cpus(&temp_desc.bcdUSB);
le16_to_cpus(&temp_desc.idVendor);
le16_to_cpus(&temp_desc.idProduct);
le16_to_cpus(&temp_desc.bcdDevice);

All other data is passed without any change.

libusb/os/linux_usbfs.c calls usbi_parse_descriptor with host_endian=1
for config descriptors. According to the kernel code, they must be
processed with host_endian=0, as they are not translated by the kernel.

Signed-off-by: Martin Koegler <mkoegler@auto.tuwien.ac.at>

Darwin: fix enumeration of devices with non-consecutive addresses (#23)

Add more interface classes

As used in bluez.

Darwin: Cleanup async callback code, catch request timeouts

Darwin: fix endianness of control setup packet

IOUSBLib expects the control request to be in host byte order.
Swap the request into host byte order.

Darwin: fix memory leak in process_device

Credit to Mike Colagrosso for finding this bug.

Darwin: use logging functions

Use usbi_warn, usbi_err, and usbi_info instead of _usbi_log.

Darwin: support multiple calls to libusb_init

Credit to Orin Eman for finding this bug.

v1.0.6 release

lsusb example: make print_devs() static

lsusb.c:26: warning: no previous prototype for ‘print_devs’

Darwin: fix warning in darwin_error_str()

os/darwin_usb.c:63: warning: return discards qualifiers from pointer
target type

Darwin: allow devices to be opened multiple times

Allows libusb applications to access multiple interfaces of the same
device in the same application.

Also fixes a set alt interface bug.

Increase libusb_handle_events() timeout to 60 seconds

The internal timing seems to be working, this will be a better test of
it before we make this timeout unlimited.

Refine timerfd header check (#18)

Require glibc-2.9 for the working timerfd support.

v1.0.5 release

Update documentation about early completion caveats

Add libusb_get_max_iso_packet_size() to libusb.h

core.c:777: warning: no previous prototype for 'libusb_get_max_iso_packet_size'

Use timerfd for timeout handling

Use a new file descriptor from the timerfd system calls to handle
timeouts. On supported systems, this means that there is less hassle
figuring out when the poll() timeout should be, since
libusb_get_next_timeout() will always return 0 and the timeout events will
be triggered as regular activity on the file descriptor set.

Add API function libusb_pollfds_handle_timeouts() to detect whether
you're on a platform with the timing headache, and flesh out the
surrounding documentation.

Use AM_SILENT_RULES for building

v1.0.4 release

Linux: Add support for the new URB_BULK_CONTINUATION flag

Add support for the new USBDEVFS_URB_BULK_CONTINUATION flag to libusb.

This flag, which is expected to be available in usbfs starting with
kernel 2.6.32, allows the kernel to cancel multiple URBs upon receipt
of a short packet.  This capability allows libusb to preserve data
integrity of large bulk transfers that are split into multiple URBs.
Without this support, these URBs must be canceled in userspace upon
receipt of a short packet, a race condition against future transfers
which might partially fill these canceled URBs.

This patch automatically detects whether a supported kernel is present
and enables the use of the flag when possible.

[dsd: tweaks to supported kernel detection, and some inline
 documentation of this mechanism]

Transfer locking

At least on Linux, there were some possible races that could occur if
a transfer is cancelled from one thread while another thread is handling
an event for that transfer, or for if a transfer completes while it is
still being submitted from another thread, etc.

On the global level, transfers could be submitted and cancelled at the
same time.

Fix those issues with transfer-level locks.

Clarify that timeout 0 means unlimited timeout

Linux: more flexibility with monotonic clock

Some users have reported that CLOCK_MONOTONIC does not work on their
systems - I suspect it is available on x86 but perhaps not some
of the more uncommon architectures. We should fall back on
CLOCK_REALTIME in these cases.

Also, CLOCK_MONOTONIC_RAW seems even more monotonic, so we should use
that if it is available.

We now test different clock IDs during initialization to find the
best one that works.

Darwin: handle overflows

v1.0.3 release

Darwin: 64-bit type fixes

Darwin: fix crash when reading descriptors after close

Fix a crash which occurs if the user does the following sequence on a
device: open, close, get_configuration_descriptor.

move bug info to bug tracker

Protection needed: http://www.libusb.org/ticket/4
Losing data: fixed in previous commit

Linux: try harder not to lose any data

We would previously lose any data that was present on a cancelled URB.
Work harder to make sure this doesn't happen.

Add libusb_get_max_iso_packet_size()

As pointed out by Dennis Muhlestein, libusb_get_max_packet_size()
doesn't really do what the documentation might suggest because it
does not consider the number of transaction opportunities per
microframe.

Add a new function to do what is useful for isochronous I/O.

Linux: fix sending of zero length bulk packets

Note that there are is a kernel bug preventing this from working
properly at the moment, even after this fix.

Darwin: Don't cancel transfers on timeout

...because the OS does this for us.

Don't terminate enums with commas

g++ -pedantic doesn't like this
Reported by Eberhard Mattes