summaryrefslogtreecommitdiff
path: root/xdelta3/www/xdelta3-api-guide.html
diff options
context:
space:
mode:
Diffstat (limited to 'xdelta3/www/xdelta3-api-guide.html')
-rwxr-xr-xxdelta3/www/xdelta3-api-guide.html212
1 files changed, 212 insertions, 0 deletions
diff --git a/xdelta3/www/xdelta3-api-guide.html b/xdelta3/www/xdelta3-api-guide.html
new file mode 100755
index 0000000..b3513ea
--- /dev/null
+++ b/xdelta3/www/xdelta3-api-guide.html
@@ -0,0 +1,212 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3<head>
4 <title>Xdelta3 API guide (BETA)</title>
5 <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
6 <link rel="stylesheet" type="text/css" href="xdelta3.css"/>
7</head>
8<body>
9
10<!-- $Format: "$WWWLeftNavBar$" $ --!>
11<table cellpadding="20px" width=700> <tr> <td class="leftbdr" valign=top height=600 width=100> <div class="leftbody"> <h1>Xdelta</h1> <a href="xdelta3.html">overview</a><br> <a href="xdelta3-cmdline.html">command&nbsp;line</a><br> <a href="xdelta3-api-guide.html">api&nbsp;guide</a><br> <br><a href="http://xdelta.org">xdelta.org</a></h2> </div> </td> <td valign=top width=500>
12
13
14<!-- Copyright (C) 2003 and onward. Joshua P. MacDonald --!>
15
16<h1>api guide</h1>
17
18<p>This guide intends to give you a quick start to the Xdelta3 programming
19interface. This is not a complete reference, the comments inside source file
20<code>xdelta3.h</code> and the command-line application,
21<code>xdelta3-main.h</code> offer more complete information.</p>
22
23<p>Have you read the <a href="xdelta3-cmdline.html">command-line interface</a>?</p>
24
25<h1>stream interface</h1>
26
27<p>
28To begin with, there are three external structures, only two of which are
29discussed here. The <code>xd3_stream</code> struct plays the main role, one
30of these contains the state necessary to encode or decode one stream of data.
31An <code>xd3_source</code> struct maintains state about the (optional) source
32file, against which differences are computed. The third structure,
33<code>xd3_config</code> deals with configuring various encoder parameters.</p>
34
35<p>
36At a glance, the interface resembles Zlib. The program puts data in, which
37the xd3_stream consumes. After computing over the data, the xd3_stream in
38turn generates output for the application to consume, or it requests more
39input. The xd3_stream also issues requests to the application to read a block
40of source data. The request to read a source block may be handled in one of
41two ways, according to application preference. If a <code>xd3_getblk</code>
42callback function is provided, the application handler will be called from
43within the library, suspending computation until the request completes. If no
44callback function is provided the library returns a special code
45(XD3_GETSRCBLK), allowing the application to issue the request and resume
46computation whenever it likes. In both cases, the xd3_source struct contains
47the requested block number and a place to store the result.</p>
48
49<h1>setup</h1>
50<p>The code to declare and initialize the xd3_stream:</p>
51<div class="example">
52<pre>
53int ret;
54xd3_stream stream;
55xd3_config config;
56
57xd3_init_config (&config, 0 /* flags */);
58config.winsize = 32768;
59ret = xd3_config_stream (&stream, &config);
60
61if (ret != 0) { /* error */ }
62</pre>
63</div>
64
65<p>
66<code>xd3_init_config()</code> initializes the <code>xd3_config</code> struct
67with default values. Many settings remain undocumented in the beta release.
68The most relevant setting, <code>xd3_config.winsize</code>, sets the encoder
69window size. The encoder allocates a buffer of this size if the program
70supplies input in smaller units (unless the <code>XD3_FLUSH</code> flag is
71set). <code>xd3_config_stream()</code> initializes the <code>xd3_stream</code>
72object with the supplied configuration.
73</p>
74
75<h1>setting the source</h1>
76<p>
77The stream is ready for input at this point, though for encoding the source
78data must be supplied now. To declare an initialize the xd3_source:</p>
79
80<div class="example">
81<pre>
82xd3_source source;
83void *IO_handle = ...;
84
85source.name = "...";
86source.size = file_size;
87source.ioh= IO_handle;
88source.blksize= 32768;
89source.curblkno = (xoff_t) -1;
90source.curblk = NULL;
91
92ret = xd3_set_source (&stream, &source);
93
94if (ret != 0) { /* error */ }
95</pre>
96</div>
97
98<p>
99The decoder sets source data in the same manner, but it may delay this step
100until the application header has been received (<code>XD3_GOTHEADER</code>).
101The application can also check whether source data is required for decoding
102with the <code>xd3_decoder_needs_source()</code>.</p>
103
104<p>
105<code>xd3_source.blksize</code> determines the block size used for requesting
106source blocks. If the first source block (or the entire source) is already in
107memory, set <code>curblkno</code> to 0 and <code>curblk</code> to that block
108of data.</p>
109
110<h1>input/output loop</h1>
111
112<p>The stream is now ready for input, which the application provides by
113calling <code>xd3_avail_input()</code>. The application initiates
114encoding or decoding at this point by calling one of two functions:</p>
115
116<div class="example">
117<pre>
118int xd3_encode_input (xd3_stream *stream)
119int xd3_decode_input (xd3_stream *stream)
120</pre>
121</div>
122
123<p>Unless there is an error, these routines return one of six result
124codes which the application must handle. In many cases, all or most
125of the handler code is shared between encoding and decoding. The
126codes are:</p>
127
128<ul>
129<li> <code>XD3_INPUT</code>: The stream is ready for (or requires) more input. The
130application should call xd3_avail_input when (if) more data is
131available.
132
133<li> <code>XD3_OUTPUT</code>: The stream has pending output. The application
134should write or otherwise consume the block of data found in the
135xd3_stream fields <code>next_out</code> and <code>avail_out</code>,
136then call <code>xd3_consume_output</code>.
137
138<li> <code>XD3_GETSRCBLK</code>: The stream is requesting a source block be read,
139as described above. This is only ever returned if the xd3_getblk
140callback was not provided.
141
142<li> <code>XD3_GOTHEADER</code>: This decoder-specific code indicates that the
143first VCDIFF window header has been received. This gives the
144application a chance to inspect the application header before
145encoding the first window.
146
147<li> <code>XD3_WINSTART</code>: This is returned by both encoder and decoder prior to
148processing a window. For encoding, this code is returned once there is enough
149available input. For decoding, this is returned following each window header
150(except the first, when XD3_GOTHEADER is returned instead).
151
152<li> <code>XD3_WINFINISH</code>: This is called when the output from a single
153window has been fully consumed.
154</ul>
155
156<p>An application could be structured something like this:</p>
157
158<div class="example">
159<pre>
160do {
161 read (&indata, &insize);
162 if (reached_EOF) {
163 xd3_set_flags (&stream, XD3_FLUSH);
164 }
165 xd3_avail_input (&stream, indata, insize);
166process:
167 ret = xd3_xxcode_input (&stream);
168 switch (ret) {
169 case XD3_INPUT:
170 continue;
171 case XD3_OUTPUT:
172 /* write data */
173 goto process;
174 case XD3_GETSRCBLK:
175 /* set source block */
176 goto process;
177 case XD3_GOTHEADER:
178 case XD3_WINSTART:
179 case XD3_WINFINISH:
180 /* no action necessary */
181 goto process;
182 default:
183 /* error */
184 }
185} while (! reached_EOF);
186</pre>
187</div>
188
189<p>
190All that remains is to close the stream and free its resources. The
191<code>xd3_close_stream()</code> checks several error conditions but otherwise
192involves no input or output. The <code>xd3_free_stream()</code> routine frees
193all memory allocated by the stream.</p>
194
195<h1>misc</h1>
196
197<p>
198There are two convenience functions for encoding to and decoding from
199in-memory buffers. See the <code>xd3_encode_completely</code> and
200<code>xd3_decode_completely</code> interfaces.</p>
201
202<p>
203There are two routines to get and set the application header. When
204encoding, sthe application header must be set before the first
205<code>XD3_WINSTART</code>. When decoding, the application header is available
206after after the first <code>XD3_GOTHEADER</code>.</p>
207
208</td>
209</tr>
210</table>
211</body>
212</html>
generated by cgit v1.2.3 (git 2.39.1) at 2024-06-30 05:38:31 +0000