Backwards incompatible API changes

[Jef Driesen]

Hi,

I'm going to make a few changes that will break backwards compatibility. The 
plan is to ship a new release in the next few days, and then introduce all those 
changes at once, to keep the impact as small as possible.

If you need to be able to build against both the new and old api, you'll be able 
to use a construct like this:

#if DC_VERSION_CHECK(0,9,0)
    /* New */
#else
    /* Old */
#endif

What follows is an overview of the planned changes:

1. The dc_parser_set_data() function will be removed. The only purpose of this 
function is to be able to re-use a parser object with new data. Since the state 
in the parser is typically very small, there is almost no advantage in doing 
that. It also adds unnecessary complexity in the implementation, because each 
backend needs to be able to reset its internal state. Keeping a reference to the 
data has also caused issues for applications in the past (especially those 
implemented in a garbage collected language). Therefore, the data and size 
parameters will be passed directly to the dc_parser_new() and dc_parser_new2() 
function, and the data will get copied internally:

/* Old */
dc_parser_new (&parser, device);
dc_parser_set_data (parser, data, size);

/* New */
dc_parser_new (&parser, device, data, size);

2. The devtime and systime arguments will be removed from the dc_parser_new2() 
function. Applications will have to call dc_parser_set_clock() to set those 
parameters:

/* Old */
dc_parser_new2 (&parser, context, descriptor, devtime, systime);
dc_parser_set_data (parser, data, size);

/* New */
dc_parser_new2 (&parser, context, descriptor, data, size);
dc_parser_set_clock (parser, devtime, systime);

3. The sample callback function will be changed to pass the sample by reference 
instead of by value. Passing by value means the size of the struct can't be 
changed without also changing the function signature and breaking backwards 
compatibility. This prevented adding some new features.

/* Old */
sample_cb (dc_sample_type_t type, dc_sample_value_t value, void *userdata)

/* New */
sample_cb (dc_sample_type_t type, const dc_sample_value_t *value, void *userdata)

Some examples of new features that will be added:

   * Add a TTS field to the deco sample.
   * Add a sensor index field to the ppO2 sample.
   * Add a tank/gasmix usage field, to indicate whether a tank or gasmix is used 
in a sidemount configuration or as oxygen/diluent on a rebreather.

4. Change the sample time units from seconds to milliseconds. This is necessary 
to support some freediving computers with a higher sample rate.

If your application doesn't support the millisecond resolution (yet), you can 
discard the extra resolution, and (optionally) skip the samples with a duplicate 
timestamp.

Jef