When two or more identical (or very similar) dive computers are
connected, the USB VID/PID can be ambiguous. That's because the VID/PID
identifies the type of the USB device, and not the individual device.
But each USB HID device descriptor returned by the device discovery
represents a single connected device, and thus guarantees to open the
correct USB device.
To obtain the same behaviour as before, an application can simply open
the first discovered device.
Replace the global USB library context with a reference counted session
to manage the lifetime of the USB library context. For the libusb based
implementation, this is actually a much better match for the underlying
libusb api, and allows to eliminate the global state. For the hidapi
based implementation, the global state is unavoidable because the hidapi
doesn't support multiple sessions. Therefore we use a singleton session.
Add a function to query the underlying transport type. This allows the
dive computer backends to implement transport specific behaviour where
necessary.
For the built-in I/O implementations, the transport type is obviously
always hardcoded, but for a custom I/O implementation the application
needs to provide the correct type. Hence the transport type can't be
hardcoded in the vtable and needs to be passed as a parameter.
The device descriptors are extended with a filter function. During the
device discovery, this filter function is used to return only devices
that match a known dive computer.
The filtering is optional, and can be disabled by passing a NULL pointer
for the device descriptor when creating the iterator with one of the
dc_xxx_iterator_new() functions.
Replacing the callback based interface with an iterator based interface,
results in a more extensible abstraction with a common interface for
each of the built-in I/O implementations (serial, usbhid, irda and
bluetooth).
Perform the initialization inside a critical section.
Unfortunately Windows critical sections, which are the simplest
synchronization mechanism available on Windows, do not support static
initialization. A call to InitializeCriticalSection is required.
Therefore a simple spinlock, with an implementation based on atomic
operations, is used as a workaround.
Initializing the hidapi library more than once is tricky. The hid_init()
function can be called multiple times, but the the hid_exit() function
will free the resources unconditionally, regardless of how many times
the hid_init() function has been called. The consequence is a premature
termination of the library.
To avoid this problem, the calls are reference counted. Note that this
workaround can't protect against calls made outside the libdivecomputer
code!
The libusb library doesn't suffer from this problem, because each
initialization returns a new context pointer. But for consistency, we
now also use a single reference counted libusb context.
When libusb uses the Windows HID api internally, it does automatically
prepend a zero report ID to the data for devices which support only a
single report. But apparently it also returns a size of one byte extra!
As a workaround, the number of bytes is limited to the actual size.
See commit c9ed92d3f55c259931527a27d018eb5791a176dd for a similar issue
in the hidapi library.
On Windows, the hidapi library uses the standard Microsoft USB HID
driver, while libusb requires the installation of a different driver
(WinUSB or libusbK). But installing one of the libusb drivers breaks
compatibility with other applications using hidapi (Scubapro LogTRAK and
Suunto DM5) because only one driver can be active. Switching
libdivecomputer to hidapi avoids this problem.
On Linux, the hidapi library doesn't seem to offer any advantages over
libusb. Most distributions don't even have the hidapi library installed
by default. Because there are usually two variants of the hidapi library
available on Linux (hidapi-libusb and hidapi-hidraw), the autotools
build system won't be able to detect it out-of-the-box, and will
automatically fallback to the libusb implementation.
On Mac OS X, hidapi is already the default (and also the only option).
The Windows HID api always expects to receive a fixed size buffer
(corresponding to the largest report supported by the device). Therefore
the hidapi library internally pads the buffer with zeros to the expected
size, but apparently it also returns the size of the padded buffer! As a
workaround the number of bytes is limited to the actual size.
The hidapi read and write functions return a negative value if an error
occurs. Those negative values should not be returned to the caller as
the actual number of bytes (or used in the logging). The value is reset
to zero instead.
The hidapi library requires that the first byte contains the report ID.
For devices which support only a single report, the report ID byte
should be zero. The remaining bytes contain the actual report data.
Now, when hidapi uses libusb internally, it strips the zero report ID
byte again before passing the data to libusb. Thus in order to remain
compatible with the hidapi based implementation, our libusb based
implementation should do the same.
On Mac OS X, libusb doesn't work for USB HID devices. We can use the
hidapi library instead. Although the hidapi library supports Linux and
Windows too, we keep using libusb there to avoid the extra dependency.
