API redesign progress

[Jef Driesen]

On 2012-06-26 02:04, Artur Wroblewski wrote:
> For me, the functions like below would be more than enough[1]
>
> - iterate over dives from a device/file or stream/array of bytes 
> (return null
>   if no more dives)
> - iterate over samples from a dive (return null if no more samples)
> - get dive data field value (if you feel some universal data 
> structure is
>   not possible)
> - get additional dive sample data field value (assuming the basic 
> dive sample
>   is dive time and depth and that universal dive sample data 
> structure is
>   not possible)
>
> There is need for new parser, buffer or state machine - the library
> should deal
> with it internally.
>
> Also, above means that there shall be no parser callbacks - if my app
> needs them,
> then I can deal with callbacks between iterator calls. The same for 
> any state
> my app needs... but no artificial state, which is imposed on old API
> users due
> to callbacks being part of API.

At some point I do want to replace the callback based interface with an 
iterator based interface. The callback interface is ugly, and breaks the 
control flow of the application. An iterator based interface is much 
more elegant (on the application side), but also add extra complexity 
(on the library side) and is easier to misuse. The callbacks was simply 
the easiest option to get something working.

However since such a change can easily be implemented without breaking 
backwards compatibility (by reimplementing the callback interface on top 
of the iterator interface), I suggest we concentrate on the changes that 
are currently being discussed first. And once those are implemented, we 
can have a look at another round of improvements.

Anyway, a proposal for the iterator interface could be something like 
this:

dc_dive_t *dive= NULL;
dc_device_t *device = NULL;
dc_iterator_t *iterator = NULL;

dc_device_open (&device, ...);
dc_device_iterator (device, &iterator);
while (dc_iterator_next (iterator, &dive) == DC_STATUS_SUCCESS) {
    /* Do something with the dive here */
    dc_dive_free (dive);
}
dc_iterator_free (iterator);
dc_device_close (device);

With something similar for the parsing of the samples (e.g. replace 
"dive" with "sample").

Jef