Next round of api improvements.

[Dirk Hohndel]

Jef Driesen <jefdriesen at telenet.be> writes:
>> Are there any legitimate error conditions other than that piece of 
>> data
>> not being present in the sample?  I try to avoid out parameters due 
>> to
>> the greater amount of scaffolding required in calling code when 
>> compared
>> to using the return value, but then again I mostly write C++ which
>> provides out-of-band error handling with exceptions.
>
> Real errors are rare, but they can happen. For the majority of the 
> devices our knowledge is based on reverse engineering, so there is 
> always a possibility that their are errors in our knowledge. Thus the 
> most common parsing error is that we encounter some data that doesn't 
> match our expectations (e.g. DC_STATUS_DATAFORMAT).

And that is a frequent thing as DC vendors often have no regard for
backward compatibility when they make incompatible changes in new
versions of a product. So libdivecomputer's resilliance to that
happening is a FEATURE and something we should strive for.

> In theory we could catch some of those errors when constructing the 
> dive/sample object, but then the error is pretty much fatal. I mean if 
> the dc_xxx_foreach (or dc_iterator_next) function fails, there is no way 
> to proceed anymore with the downloading or parsing. But in many cases 
> it's still possible to move to the next dive or sample.
>
> Take for example the Suunto data format. The dives are stored in a 
> linked list, so you need zero knowledge of the actual dive format to 
> locate and download the dives. Even if some of the dives will fail to 
> parse correctly (for example when the data format has been changed to 
> support a new feature), that has no impact on the ability to download 
> the dives. If this data format error is detected by the parser while 
> constructing the dive object, we have two options:
>
> 1. Fail to construct the dive object. This leaves the foreach() 
> function no other option than to abort the downloading. The result is 
> that a minor problem with just one dive will cause the entire download 
> to fail.
>
> 2. Construct the dive object anyway in an error state. The application 
> will still get the dive, and downloading will continue. It may not be 
> able to parse this dive completely, but depending on the severity of the 
> error you may still be able to get some info. For example the raw dive 
> data will always be available. Some of the fields may still be 
> parse-able too. But this only works if the individual accessor functions 
> can return an error.

And if we are lucky we can still get at least the basics (depth and
time) and do a somewhat useful download even if more advanced
information can't be processed.

> Note that in the current design this is less of a problem, because 
> downloading the dives and creating a parser are completely decoupled. A 
> failure in creating a parser will never affect the downloading.

And that's a property we should maintain.

>>> 3. Supported dive and sample data
>>> ==================================
>>>
>>>    * airtime
>>
>> Does some computer actually report this?  If tank pressure is also
>> reported, airtime can be calculated from that.  In my experience it's
>> not too stable over the course of the dive, so it would be of little
>> value, but perhaps others disagree.
>
> There are several devices which support it. Uwatec, Oceanic, and 
> probably a few other too. It may not be the most critical piece of 
> information, but I do get requests for it. So while it's not on my 
> must-have list, it's something we can consider adding.

I like having it - but struggle with how to visualize it in the dive log
application. I tried a few things that all ended up looking kinda odd
:-)

> You would be surprised what all those dive computers support. We 
> definitely won't support everything, but we want to make a good 
> trade-off between what we consider important and what is available.

As I mentioned before - we should standardize everything where we can
create some well defined semantic (and possible variations) that we can
provide to the application. The less needs to be parsed from raw data
the better (but we should still maintain the ability for the app to
parse the raw data itself if all else fails).

So while I don't know how I'd visualize the airtime, I definitely
encourage you to have this as a field that you support - and if
different DCs have different semantics (is this to "tank empty" or to a
threshold pressure? What's that pressure? Does it include the ascend
(with or without safety stop) or does it assume you stay at this depth
until your tank is empty (brilliant plan...)... this should be handled
by flags to make sure that the meaning of the value is well defined.

/D