\label{api_callbacks_md_doc_callbacks}%
\Hypertarget{api_callbacks_md_doc_callbacks}%
 librsync jobs use IO callbacks to read and write files in pull mode. It uses a \char`\"{}copy callback\char`\"{} to read data from the basis file for \char`\"{}patch\char`\"{} operations in both push and pull mode.

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.

Callbacks are passed a {\ttfamily void $\ast$} 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.

There are three types of callbacks, for input, output, and a special \char`\"{}copy callback\char`\"{} for random-\/access reads of the basis file when patching. ~\newline
\hypertarget{api_callbacks_autotoc_md50}{}\doxysubsection{Input and output callbacks}\label{api_callbacks_autotoc_md50}
Input and output callbacks are both of type \mbox{\hyperlink{librsync_8h_ae06d064f9f33a459a589d2eb1fb5b6bc}{rs\+\_\+driven\+\_\+cb}}. These are used for all operations in pull mode only (see \mbox{\hyperlink{api_pull}{Pull API}}).

The callbacks are passed to \mbox{\hyperlink{librsync_8h_a85d48e8216b848b9757a076f829ac4a8}{rs\+\_\+job\+\_\+drive()}} and are called repeatedly until the job completes, fails, or permanently blocks.

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\+:


\begin{DoxyItemize}
\item 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.
\item 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.
\item The input or output pointers might point into a mmap\textquotesingle{}d file.
\item The input and output buffers might be provided by some other library.
\end{DoxyItemize}

The caller is responsible for freeing the buffer, and for remembering where it previously asked librsync to write output.\hypertarget{api_callbacks_autotoc_md51}{}\doxysubsection{Input callbacks}\label{api_callbacks_autotoc_md51}
Input callbacks are passed a \mbox{\hyperlink{structrs__buffers__s}{rs\+\_\+buffers\+\_\+s}} 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 \mbox{\hyperlink{structrs__buffers__s_a6d5d12a1ced9a3a8891259e09c80ec20}{rs\+\_\+buffers\+\_\+s\+::next\+\_\+in}}, \mbox{\hyperlink{structrs__buffers__s_a7bd5f1ea3c26587bf1106c1594712735}{rs\+\_\+buffers\+\_\+s\+::avail\+\_\+in}}, and set \mbox{\hyperlink{structrs__buffers__s_aa6783da2d894c77178155759cd12d16f}{rs\+\_\+buffers\+\_\+s\+::eof\+\_\+in}} if it\textquotesingle{}s reached the end of the input.

When an input callback reaches end-\/of-\/file and can return no more data, it should return \mbox{\hyperlink{librsync_8h_a7feb858ceba3b8f3cf048d49be108253aa997432dc2d2c8256ad41f96267a5185}{RS\+\_\+\+INPUT\+\_\+\+ENDED}}. If the callback has just a little data left before end of file, then it should return that data with \mbox{\hyperlink{librsync_8h_a7feb858ceba3b8f3cf048d49be108253a739063053a289b5c3393d78cc77b41b2}{RS\+\_\+\+DONE}}. On the next call, unless the file has grown, it can return \mbox{\hyperlink{librsync_8h_a7feb858ceba3b8f3cf048d49be108253aa997432dc2d2c8256ad41f96267a5185}{RS\+\_\+\+INPUT\+\_\+\+ENDED}}.\hypertarget{api_callbacks_autotoc_md52}{}\doxysubsection{Output callbacks}\label{api_callbacks_autotoc_md52}
Output callbacks are also passed a \mbox{\hyperlink{structrs__buffers__s}{rs\+\_\+buffers\+\_\+s}} struct. On the first call, the output callback should store a pointer to its buffer into \mbox{\hyperlink{structrs__buffers__s_af3a6532c3e300a07783d61680cbdc11f}{rs\+\_\+buffers\+\_\+s\+::next\+\_\+out}}, and the length into \mbox{\hyperlink{structrs__buffers__s_ae60f3db2f518d74aee13a02b7c9619a2}{rs\+\_\+buffers\+\_\+s\+::avail\+\_\+out}}. 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.

If the callback processes only part of the requested data, it should still return \mbox{\hyperlink{librsync_8h_a7feb858ceba3b8f3cf048d49be108253a739063053a289b5c3393d78cc77b41b2}{RS\+\_\+\+DONE}}. In this case librsync will call the callback again later until it either completes, fails, or blocks.

The key thing to understand about \mbox{\hyperlink{structrs__buffers__s}{rs\+\_\+buffers\+\_\+s}} is that the counts and pointers are from librsync\textquotesingle{}s point of view\+: the next byte, and the number of bytes, that it should read or write.\hypertarget{api_callbacks_autotoc_md53}{}\doxysubsection{Copy callbacks}\label{api_callbacks_autotoc_md53}
Copy callbacks are used from both push-\/mode (\mbox{\hyperlink{librsync_8h_aede8e0f42424b9aa29093f94b59ea029}{rs\+\_\+job\+\_\+iter()}}) and pull-\/mode (\mbox{\hyperlink{librsync_8h_a85d48e8216b848b9757a076f829ac4a8}{rs\+\_\+job\+\_\+drive()}}) invocations, only when doing a \char`\"{}patch\char`\"{} operation started by \mbox{\hyperlink{librsync_8h_a15efa6e180d239fee2c195874618b0ea}{rs\+\_\+patch\+\_\+begin()}}.

Copy callbacks have type \mbox{\hyperlink{librsync_8h_afc4bc64a627d7ca181a7e813832313cc}{rs\+\_\+copy\+\_\+cb}}.

Copy callbacks are directly passed a buffer and length into which they should write the data read from the basis file.\hypertarget{api_callbacks_autotoc_md54}{}\doxysubsection{Callback lifecycle}\label{api_callbacks_autotoc_md54}
IO callbacks are only called from within \mbox{\hyperlink{librsync_8h_a85d48e8216b848b9757a076f829ac4a8}{rs\+\_\+job\+\_\+drive()}} or \mbox{\hyperlink{librsync_8h_aede8e0f42424b9aa29093f94b59ea029}{rs\+\_\+job\+\_\+iter()}}.

Different callbacks may be called several times in a single invocation of \mbox{\hyperlink{librsync_8h_aede8e0f42424b9aa29093f94b59ea029}{rs\+\_\+job\+\_\+iter()}} or \mbox{\hyperlink{librsync_8h_a85d48e8216b848b9757a076f829ac4a8}{rs\+\_\+job\+\_\+drive()}}.\hypertarget{api_callbacks_autotoc_md55}{}\doxysubsection{Return values}\label{api_callbacks_autotoc_md55}
Callbacks return a \mbox{\hyperlink{librsync_8h_adec85b529224f0240ae1afccff827462}{rs\+\_\+result}} value to indicate success, an error, or being blocked.

If the callbacks return an error, that error will typically be passed back to the application. 