-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathapi_callbacks.html
126 lines (126 loc) · 10.9 KB
/
api_callbacks.html
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
<!-- HTML header for doxygen 1.8.10-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.4"/>
<title>librsync: IO callbacks</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<!-- ad -->
<script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
<!-- librsync -->
<ins class="adsbygoogle"
style="display:block"
data-ad-client="ca-pub-3547096055927362"
data-ad-slot="8322976738"
data-ad-format="auto"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">librsync
 <span id="projectnumber">2.3.4</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.4 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(function() {
initMenu('',false,false,'search.php','Search');
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div><div class="header">
<div class="headertitle"><div class="title">IO callbacks </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p ><a class="anchor" id="md_doc_callbacks"></a> librsync jobs use IO callbacks to read and write files in pull mode. It uses a "copy callback" to read data from the basis file for "patch" operations in both push and pull mode.</p>
<p >These callbacks might write the data directly to a file or network connection, or they can do some additional work such as compression or encryption.</p>
<p >Callbacks are passed a <code>void *</code> baton, which is chosen by the application when setting up the job. The baton can hold context or state for the callback, such as a file handle or descriptor.</p>
<p >There are three types of callbacks, for input, output, and a special "copy callback" for random-access reads of the basis file when patching. <br />
</p>
<h1><a class="anchor" id="autotoc_md50"></a>
Input and output callbacks</h1>
<p >Input and output callbacks are both of type <a class="el" href="librsync_8h.html#ae06d064f9f33a459a589d2eb1fb5b6bc" title="Type of application-supplied function for rs_job_drive().">rs_driven_cb</a>. These are used for all operations in pull mode only (see <a class="el" href="api_pull.html">Pull API</a>).</p>
<p >The callbacks are passed to <a class="el" href="librsync_8h.html#a85d48e8216b848b9757a076f829ac4a8" title="Actively process a job, by making callbacks to fill and empty the buffers until the job is done.">rs_job_drive()</a> and are called repeatedly until the job completes, fails, or permanently blocks.</p>
<p >Input and output callbacks can and must choose their own buffers, which they provide as pointers to librsync as the job proceeds. There are many possibilities:</p>
<ul>
<li>The application may allocate a buffer when starting the job, and shuffle data in and out of it as the job proceeds. As librsync produces data in the output buffer, it is written out e.g. to a socket, and the output pointer is then reset.</li>
<li>The application may allocate a single output buffer adequate to hold all the output, and then the output callback need do nothing but let librsync gradually consume it.</li>
<li>The input or output pointers might point into a mmap'd file.</li>
<li>The input and output buffers might be provided by some other library.</li>
</ul>
<p >The caller is responsible for freeing the buffer, and for remembering where it previously asked librsync to write output.</p>
<h1><a class="anchor" id="autotoc_md51"></a>
Input callbacks</h1>
<p >Input callbacks are passed a <a class="el" href="structrs__buffers__s.html" title="Description of input and output buffers.">rs_buffers_s</a> struct into which they can store a pointer to the data they have read. Note that librsync does not allocate the buffer, the caller must do so. The input callback should update <a class="el" href="structrs__buffers__s.html#a6d5d12a1ced9a3a8891259e09c80ec20" title="Next input byte.">rs_buffers_s::next_in</a>, <a class="el" href="structrs__buffers__s.html#a7bd5f1ea3c26587bf1106c1594712735" title="Number of bytes available at next_in.">rs_buffers_s::avail_in</a>, and set <a class="el" href="structrs__buffers__s.html#aa6783da2d894c77178155759cd12d16f" title="True if there is no more data after this.">rs_buffers_s::eof_in</a> if it's reached the end of the input.</p>
<p >When an input callback reaches end-of-file and can return no more data, it should return <a class="el" href="librsync_8h.html#a7feb858ceba3b8f3cf048d49be108253aa997432dc2d2c8256ad41f96267a5185" title="Unexpected end of input file, perhaps due to a truncated file or dropped network connection.">RS_INPUT_ENDED</a>. If the callback has just a little data left before end of file, then it should return that data with <a class="el" href="librsync_8h.html#a7feb858ceba3b8f3cf048d49be108253a739063053a289b5c3393d78cc77b41b2" title="Completed successfully.">RS_DONE</a>. On the next call, unless the file has grown, it can return <a class="el" href="librsync_8h.html#a7feb858ceba3b8f3cf048d49be108253aa997432dc2d2c8256ad41f96267a5185" title="Unexpected end of input file, perhaps due to a truncated file or dropped network connection.">RS_INPUT_ENDED</a>.</p>
<h1><a class="anchor" id="autotoc_md52"></a>
Output callbacks</h1>
<p >Output callbacks are also passed a <a class="el" href="structrs__buffers__s.html" title="Description of input and output buffers.">rs_buffers_s</a> struct. On the first call, the output callback should store a pointer to its buffer into <a class="el" href="structrs__buffers__s.html#af3a6532c3e300a07783d61680cbdc11f" title="Next output byte should be put there.">rs_buffers_s::next_out</a>, and the length into <a class="el" href="structrs__buffers__s.html#ae60f3db2f518d74aee13a02b7c9619a2" title="Remaining free space at next_out.">rs_buffers_s::avail_out</a>. On subsequent calls, librsync will have used some of this buffer and updated those fields. The caller should then write out the used buffer space, and possibly update the buffer to the place it wants new output to go.</p>
<p >If the callback processes only part of the requested data, it should still return <a class="el" href="librsync_8h.html#a7feb858ceba3b8f3cf048d49be108253a739063053a289b5c3393d78cc77b41b2" title="Completed successfully.">RS_DONE</a>. In this case librsync will call the callback again later until it either completes, fails, or blocks.</p>
<p >The key thing to understand about <a class="el" href="structrs__buffers__s.html" title="Description of input and output buffers.">rs_buffers_s</a> is that the counts and pointers are from librsync's point of view: the next byte, and the number of bytes, that it should read or write.</p>
<h1><a class="anchor" id="autotoc_md53"></a>
Copy callbacks</h1>
<p >Copy callbacks are used from both push-mode (<a class="el" href="librsync_8h.html#aede8e0f42424b9aa29093f94b59ea029" title="Run a rs_job state machine until it blocks (RS_BLOCKED), returns an error, or completes (RS_DONE).">rs_job_iter()</a>) and pull-mode (<a class="el" href="librsync_8h.html#a85d48e8216b848b9757a076f829ac4a8" title="Actively process a job, by making callbacks to fill and empty the buffers until the job is done.">rs_job_drive()</a>) invocations, only when doing a "patch" operation started by <a class="el" href="librsync_8h.html#a15efa6e180d239fee2c195874618b0ea" title="Apply a delta to a basis file to recreate the new file.">rs_patch_begin()</a>.</p>
<p >Copy callbacks have type <a class="el" href="librsync_8h.html#afc4bc64a627d7ca181a7e813832313cc" title="Callback used to retrieve parts of the basis file.">rs_copy_cb</a>.</p>
<p >Copy callbacks are directly passed a buffer and length into which they should write the data read from the basis file.</p>
<h1><a class="anchor" id="autotoc_md54"></a>
Callback lifecycle</h1>
<p >IO callbacks are only called from within <a class="el" href="librsync_8h.html#a85d48e8216b848b9757a076f829ac4a8" title="Actively process a job, by making callbacks to fill and empty the buffers until the job is done.">rs_job_drive()</a> or <a class="el" href="librsync_8h.html#aede8e0f42424b9aa29093f94b59ea029" title="Run a rs_job state machine until it blocks (RS_BLOCKED), returns an error, or completes (RS_DONE).">rs_job_iter()</a>.</p>
<p >Different callbacks may be called several times in a single invocation of <a class="el" href="librsync_8h.html#aede8e0f42424b9aa29093f94b59ea029" title="Run a rs_job state machine until it blocks (RS_BLOCKED), returns an error, or completes (RS_DONE).">rs_job_iter()</a> or <a class="el" href="librsync_8h.html#a85d48e8216b848b9757a076f829ac4a8" title="Actively process a job, by making callbacks to fill and empty the buffers until the job is done.">rs_job_drive()</a>.</p>
<h1><a class="anchor" id="autotoc_md55"></a>
Return values</h1>
<p >Callbacks return a <a class="el" href="librsync_8h.html#adec85b529224f0240ae1afccff827462" title="Return codes from nonblocking rsync operations.">rs_result</a> value to indicate success, an error, or being blocked.</p>
<p >If the callbacks return an error, that error will typically be passed back to the application. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- HTML footer for doxygen 1.8.10-->
<!-- start footer part -->
<!-- ad -->
<script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
<!-- librsync -->
<ins class="adsbygoogle"
style="display:block"
data-ad-client="ca-pub-3547096055927362"
data-ad-slot="8322976738"
data-ad-format="auto"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>
<!-- analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-71109100-1', 'auto');
ga('send', 'pageview');
</script>
<hr class="footer"/><address class="footer"><small>
Generated on Sun Feb 19 2023 16:26:51 for librsync by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.9.4
</small></address>
</body>
</html>