1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head>
<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"><title>DAR's FEATURES</title></head><body style="background-color: rgb(221, 221, 221); color: rgb(0, 0, 170);" alink="#ff0000" link="#0000ff" vlink="#000055">
<center>
<table style="width: 90%; text-align: left; margin-left: auto; margin-right: auto;" border="0" cellpadding="2" cellspacing="2">
<tbody>
<tr>
<td style="vertical-align: top; width: 161px;"><a href="index.html"><img style="border: 0px solid ; width: 160px; height: 120px;" alt="Dar Documentation" src="dar_s_doc.jpg"></a><br>
</td>
<td style="vertical-align: top;">
<h1 style="text-align: center;"><br>
</h1>
<h1 style="text-align: center;">Compatible API 4.4.x within libdar 5.0.x<br>
</h1>
</td>
</tr>
</tbody>
</table>
<br>
<br>
<div style="text-align: justify;">
<hr style="width: 100%; height: 2px;"><br>
<br>
<table style="width: 90%; margin-right: auto; margin-left: auto; text-align: left;" border="0" cellpadding="2" cellspacing="2">
<tbody>
<tr>
<td style="vertical-align: top;" align="justify">
<h3>The reasons for a new API<br>
</h3>
<br>
<div style="margin-left: 40px;">
<div style="text-align: justify;">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.<br>
</div>
<br>
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 future 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 manage
this new parameter's value, available for programs that are aware of it.<br>
<br>
Any program can then, at will, take into consideration the new options or
simply ignore them (and use default values for them), while new features keep getting added to libdar release after release.<br>
</div>
<br>
<h3>The old API is kept available beside the new one</h3>
<div style="margin-left: 40px;">But to ease the transition to this new API, beside the <span style="font-weight: bold;">libdar namespace</span>
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 <span style="font-weight: bold;">libdar_4_4 namespace</span>.
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 probably disappear at next major release
(which will probably be version 2.5.0. In the meanwhile, the API
should still be available under versions 5.x.x and thus stay compatible with
current new API).<br>
<br>
</div>
<div style="text-align: justify;">
<h3><span style="font-weight: bold;">Change to make to use the old API</span></h3>
<div style="margin-left: 40px;">
<ol>
<li>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.</li>
<li>The second point, of course is to no more use the <span style="font-weight: bold;">libdar</span> namespace but instead the <span style="font-weight: bold;">libdar_4_4</span> namespace.<br>
</li>
</ol>
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.<br>
<br>
</div>
</div>
</td>
</tr>
</tbody>
</table>
<br>
</div>
<table style="text-align: left; width: 90%;" border="1" cellpadding="2" cellspacing="2">
<tbody>
<tr>
<td style="vertical-align: top; text-align: center; font-weight: bold;">Old program using Old libdar<br>
</td>
<td style="vertical-align: top; text-align: center; font-weight: bold;">Old program using libdar 5.0.x<br>
</td>
</tr>
<tr>
<td style="vertical-align: top; font-family: monospace;">#include "libdar.hpp"<br>
<br>
using namespace libdar;<br>
<br>
int example()<br>
{<br>
archive *arch = new archive(....);<br>
[...]<br>
}<br>
</td>
<td style="vertical-align: top; font-family: monospace;">#include "<span style="font-weight: bold;">libdar_4_4.hpp</span>"<br>
<br>
using namespace <span style="font-weight: bold;">libdar_4_4</span>;<br>
<br>
int example()<br>
{<br>
archive *arch = new archive(....);<br>
[...]<br>
}</td>
</tr>
<tr>
<td style="vertical-align: top; font-family: monospace;">#include "libdar.hpp"<br>
<br>
int example()<br>
{<br>
libdar::archive *arch = new libdar::archive(....);<br>
[...]<br>
}</td>
<td style="vertical-align: top; font-family: monospace;">#include "<span style="font-weight: bold;">libdar_4_4.hpp</span>"<br>
<br>
int example()<br>
{<br>
<span style="font-weight: bold;">libdar_4_4::</span>archive *arch = new <span style="font-weight: bold;">libdar_4_4</span>::archive(....);<br>
[...]<br>
}</td>
</tr>
</tbody>
</table>
<br>
<table style="text-align: left; width: 90%; margin-left: 40px;" border="0" cellpadding="2" cellspacing="2">
<tbody>
<tr>
<td style="vertical-align: top;">Compilation and linking stay unchanged, thus running <span style="font-style: italic;">sed</span> on your code using the following script-like code should do the trick:<br>
<br>
<br>
<div style="margin-left: 40px;"><span style="font-family: monospace;">for file in *.c *.h *.cpp *.hpp ; do</span><br style="font-family: monospace;">
<span style="font-family: monospace;"> mv "$file" "$file.bak"</span><br style="font-family: monospace;">
<span style="font-family: monospace;"> sed -r
-e 's/libdar::/libdar_4_4::/g' -e 's/using namespace libdar/using
namespace libdar_4_4/' -e 's|#include <dar/libdar.hpp>|#include
<dar/libdar_4_4.hpp>|' "$file.bak" > "$file"</span><br style="font-family: monospace;">
<span style="font-family: monospace;">done</span><br>
</div>
<h3>Want to try the new API instead ?</h3>
<div style="margin-left: 40px;">
<div style="text-align: justify;">If
you want to go one step further and instead of using the backward
compatible API, directly use the new libdar API, the first step is to
read the <a href="api_tutorial.html">API Tutorial</a>. Then, if more detailed information is required, check the <a href="man/index.html">API documentation</a>. Finaly you can subscribe to <a href="https://lists.sourceforge.net/lists/listinfo/dar-libdar_api">libdar-api mailing-list</a> for any problem, questions or suggestions about the API.<br>
</div>
<br>
<br>
</div>
<br>
<div style="margin-left: 40px;">
</div>
</td>
</tr>
</tbody>
</table>
<br>
</center>
</body></html>
|
