The reasons for a new API
Libdar API (version 5.0.0) released with dar 2.4.0
provides a very different API compared to older releases.
The main reason for this major redesign of the API is that in the
past, each new feature added in libdar broke the backward compatibility
of the API, mainly because a new argument had to be added to a
particular method of class archive.
The new API makes use of new "option" classes that all have a
constructor without argument. Objects of theses classes carry all the
current and futur arguments used to manage dar archive through libdar
API. This way, if a new option has to be added in the future, no change
will be necessary to program that use the libdar API though an API version 5.x.x.
The class option's constructor will set this new parameter to its
default value, and a new method for that class will be added to change
manage this new parameter's value, available for programs that are aware of it.
Any program can then, at will, take into consideration new options or
simply ignore them (and use defaut values for them), while new feature keep getting added dar release after dar release.
The old API is kept available beside the new one
But to ease the transition to this new API, beside the libdar namespace
that contained in 2.3.x and older releases all the symbols for the API,
and which now contain the symbols for the API 5.0.x can be found the libdar_4_4 namespace.
As you guess it provides the API 4.4.x to libdar, which is the one used
from release 2.3.5. However some small changes have
still to be made for your program to compile and work with new libdar
using the old API. This is the object of this document to describe
them. This backward compatible API will disapear at next major release
(which will probably be version 2.5.0, while at that time the API
should still be under version 5.x.x and thus stay compatible with
current new API, if all work as expected).
Change to make to use the old API
- The first point is to no more include "libdar.hpp" but
"libdar_4_4.hpp" instead. This file contains the libdar_4_4 namespace
symbols.
- The second point of course is to no more use the libdar namespace but libdar_4_4 namespace.
The following table shows two code examples. On the left is placed the
original code, while on the right is placed the modified code with
changes in bold characters for the program to be used with old API of
new libdar library.
|