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
