New features

[Jef Driesen]

Hi,

I made some important changes to the libdivecomputer api, to support a 
number of new features. Some of them break backwards compatibility. The 
remainder of this email is an overview of the changes.

I believe we are now reaching a status where all must-have functionality 
for downloading is available, but maybe not yet in the best possible 
way. Anyway, the current version is definitely the one you should be using!

1. CLOCK EVENT

A new clock event was added to solve the clock synchronization problem 
for the reefnet and uwatec devices. As soon as the device and system 
timestamps to adjust the internal clock become available, you'll receive 
them in this event.

2. FINGERPRINTS

In the foreach callback function, not only the dive data but also its 
fingerprint is provided. You should store the fingerprint (of the most 
recent dive) somewhere and pass it to the device_set_fingerprint() 
function during the next download to retrieve only the new dives. You 
could already do that before, but until now there was no way to get at 
the fingerprint of each dive.

Note: The legacy xxx_device_set_timestamp() functions of the uwatec and 
reefnet backends are deprecated and might be removed at some time later.

3. CANCELLATION

You can now cancel an operation by registering a cancellation callback 
function. This callback function should return a non-zero value whenever 
the active operaton should be cancelled, and zero when it should 
continue. A backend can invoke this callback function to query the 
application for a pending cancellation request.

Note that there is NO guarantee that the operation will actually be 
cancelled. Not all backends support safe cancellation, and those that do 
may not always notice a cancellation request in time.

4. OTHER

The Uwatec Smart backend breaks backwards compatibility by removing the 
uwatec_smart_device_handshake and uwatec_smart_device_version functions. 
The first one is done automatically during initialization and the second 
one is replaced with the device_version function. The format of the 
version data has changed too (the content remains the same, but the 
order of the fields has changed into: model number, serial number, 
timestamp). But you shouldn't need this info anymore because the same 
info is delivered in the devinfo and clock events.

For systems without IrDA support (e.g. Mac OS X), a dummy IrDa backend 
is used, which will always return an error at runtime.

The universal example application was update to use the new features. 
One of the major additions is that it can now also parse the downloaded 
dives and export them into a very simple xml file. You may find it 
useful for testing.

Jef