The vendor_product_parser_create() and vendor_product_device_open()
functions should be called indirectly, through the generic
dc_device_open() and dc_parser_new() functions. And the
vendor_product_extract_dives() functions are internal functions that
should never have been part of the public api in the first place.
Both the allocation and initialization of the object data structure is
now moved to a single function. The corresponding deallocation function
is intended to free objects that have been allocated, but are not fully
initialized yet. The public cleanup function shouldn't be used in such
case, because it may try to release resources that haven't been
initialized yet.
Instead of freeing the object data structure in the backend specific
cleanup function, the memory is now freed automatically in the base
class function. This reduces the amount of boilerplate code in the
backends. Backends that don't allocate any additional resources, do no
longer require a cleanup function at all.
Dives are downloaded using bulk transfers with an 8K buffer. Normally
the 2 second timeout is more than sufficient, and the timeout should
never expire, unless there is some serious communcation problem. But
nevertheless, users are reporting timeouts for dives having a length
that is an exact multiple of the USB packet size (64 bytes). In that
case, libusb reports a timeout with an non-zero amount of bytes
received. Despite the timeout, the received data contains a complete
dive.
I suspect libusb is somehow unable to determine whether the transfer is
complete and therefore waits until the timeout expires. For transfers
that are not a multiple of the USB packet size, the end of the transfer
is indicated by the last incomplete packet. This is not the case if the
length is an exact multiple of the USB packet size. This problem is
usually solved by sending a zero-length packet. Maybe the USB stack of
the Cobalt is not sending such a zero-length packet?
Atomics will address the problem with a Coblat 2 firmware upgrade, that
will simply append two zero bytes if the length is a multiple of 64
bytes. As a workaround for older firmware versions, we ignore the
timeout and process all received data. This shouldn't have any
disadvantages. An incomplete dive, for example due to a real timeout,
will now be detected by means of the minimum length and/or the checksum.
The Atomics Cobalt backend uses libusb directly, without going through
an internal I/O layer that support logging. Therefore the logging needs
to be done in the backend itself.
Currently, each backend has it's own function to verify whether the
object vtable pointer is the expected one. All these functions can be
removed in favor of a single isintance function in the base class,
which takes the expected vtable pointer as a parameter.
Functions which are called through the vtable, don't need to verify the
vtable pointer, and those checks are removed.
The term "backend" can be confusing because it can refer to both the
virtual function table and the device/parser backends. The use of the
term "vtable" avoids this.
The new vendor event provides a mechanism to deliver auxiliary data,
which is automatically retrieved during the data transfer, but not
accessible through the library interface otherwise. Possible examples
include handshake data and/or device identification data.
This event is mainly intended for diagnostic purposes, in combination
with the memory dumping support. Very few applications will actually
need it for anything else.
Apparantly, the windows wingdi.h header file already defines the
ERROR macro. By defining the NOGDI macro before including the
windows.h header file, we can prevent the wingdi.h file from being
included and thus avoid the warning. We don't need that header for
anything anyway.
Because the libusb header file includes the windows.h file
explicitly, it needs the same fix.
The version function requires device specific knowledge to use it (at
least the required buffer size), it is already called internally when
necessary, and only a few backends support it. Thus there is no good
reason to keep it in the high-level public api.
I forgot to update the device and parser initialization functions to
store the context pointer into the objects. As a result, the internal
context pointers were always NULL.
The status codes in the new EXITCODE macro were not updated to use the
new constants with the namespace prefix. As a result building fails when
compiling with libusb support.
The public api is changed to require a context object for all
operations. Because other library objects store the context pointer
internally, only the constructor functions need an explicit context
object as a parameter.
A bulk transfer of more than 8K of data takes about one second with the
Cobalt. Because we use a one second timeout combined with a 10K buffer,
such a transfer can easily exceed the timeout. Normally this shouldn't
be a problem because the leftover data is supposed to be received with
the next transfer. However to break out of the loop we check the actual
number of bytes received, and ignore the libusb LIBUSB_ERROR_TIMEOUT
return code.
To fix this problem, the internal buffer is reduced to 8K, and the
timeout is increased to 2 seconds. This should avoid hitting the timeout
and allows to consider LIBUSB_ERROR_TIMEOUT a fatal error.
Adding the "dc_" namespace prefix (which is of course an abbreviation
for libdivecomputer) should avoid conflicts with other libraries. For
the time being, only the high-level device and parser layers are
changed.
The public header files are moved to a new subdirectory, to separate
the definition of the public interface from the actual implementation.
Using an identical directory layout as the final installation has the
advantage that the example code can be build outside the project tree
without any modifications to the #include statements.
Some of the older firmware versions contain a critical bug that can
possibly crash the device when trying to download dives, and also a bug
in the checksum calculation. To avoid these problems we simply refuse to
download when an old firmware is detected and require the user to
upgrade the firmware first.
The detection is performed by means of a new version command which
allows to retrieve the device information prior to downloading the
dives, but is only supported by recent firmware versions.
As a side effect, we gain access to the current firmware version, which
may be different from the one recorded during the last dive. And we can
get the info even if there are no dives present.
