\doxysubsection{scoop.\+h}
\label{scoop_8h_source}\index{scoop.h@{scoop.h}}
\mbox{\hyperlink{scoop_8h}{Go to the documentation of this file.}}
\begin{DoxyCode}{0}
\DoxyCodeLine{00001 \textcolor{comment}{/*= -\/*-\/ c-\/basic-\/offset: 4; indent-\/tabs-\/mode: nil; -\/*-\/}}
\DoxyCodeLine{00002 \textcolor{comment}{ *}}
\DoxyCodeLine{00003 \textcolor{comment}{ * librsync -\/-\/ library for network deltas}}
\DoxyCodeLine{00004 \textcolor{comment}{ *}}
\DoxyCodeLine{00005 \textcolor{comment}{ * Copyright (C) 2000, 2001 by Martin Pool <mbp@sourcefrog.net>}}
\DoxyCodeLine{00006 \textcolor{comment}{ *}}
\DoxyCodeLine{00007 \textcolor{comment}{ * This program is free software; you can redistribute it and/or}}
\DoxyCodeLine{00008 \textcolor{comment}{ * modify it under the terms of the GNU Lesser General Public License}}
\DoxyCodeLine{00009 \textcolor{comment}{ * as published by the Free Software Foundation; either version 2.1 of}}
\DoxyCodeLine{00010 \textcolor{comment}{ * the License, or (at your option) any later version.}}
\DoxyCodeLine{00011 \textcolor{comment}{ *}}
\DoxyCodeLine{00012 \textcolor{comment}{ * This program is distributed in the hope that it will be useful, but}}
\DoxyCodeLine{00013 \textcolor{comment}{ * WITHOUT ANY WARRANTY; without even the implied warranty of}}
\DoxyCodeLine{00014 \textcolor{comment}{ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU}}
\DoxyCodeLine{00015 \textcolor{comment}{ * Lesser General Public License for more details.}}
\DoxyCodeLine{00016 \textcolor{comment}{ *}}
\DoxyCodeLine{00017 \textcolor{comment}{ * You should have received a copy of the GNU Lesser General Public}}
\DoxyCodeLine{00018 \textcolor{comment}{ * License along with this program; if not, write to the Free Software}}
\DoxyCodeLine{00019 \textcolor{comment}{ * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.}}
\DoxyCodeLine{00020 \textcolor{comment}{ */}}
\DoxyCodeLine{00021 }
\DoxyCodeLine{00022                 \textcolor{comment}{/*=}}
\DoxyCodeLine{00023 \textcolor{comment}{                 | Two wars in a lifetime bear hard on the little places.}}
\DoxyCodeLine{00024 \textcolor{comment}{                 | In winter when storms come rushing out of the dark,}}
\DoxyCodeLine{00025 \textcolor{comment}{                 | And the bay boils like a cauldron of sharks,}}
\DoxyCodeLine{00026 \textcolor{comment}{                 | The old remember the trenches at Paschendale}}
\DoxyCodeLine{00027 \textcolor{comment}{                 | And sons who died on the Burma Railway.}}
\DoxyCodeLine{00028 \textcolor{comment}{                 */}}
\DoxyCodeLine{00029 \textcolor{comment}{}}
\DoxyCodeLine{00030 \textcolor{comment}{/** \(\backslash\)file scoop.h}}
\DoxyCodeLine{00031 \textcolor{comment}{ * Manage librsync streams of IO.}}
\DoxyCodeLine{00032 \textcolor{comment}{ *}}
\DoxyCodeLine{00033 \textcolor{comment}{ * See \(\backslash\)sa scoop.c and \(\backslash\)sa tube.c for related code for input and output}}
\DoxyCodeLine{00034 \textcolor{comment}{ * respectively.}}
\DoxyCodeLine{00035 \textcolor{comment}{ *}}
\DoxyCodeLine{00036 \textcolor{comment}{ * OK, so I'll admit IO here is a little complex. The most important player}}
\DoxyCodeLine{00037 \textcolor{comment}{ * here is the stream, which is an object for managing filter operations. It}}
\DoxyCodeLine{00038 \textcolor{comment}{ * has both input and output sides, both of which is just a (pointer,len) pair}}
\DoxyCodeLine{00039 \textcolor{comment}{ * into a buffer provided by the client. The code controlling the stream}}
\DoxyCodeLine{00040 \textcolor{comment}{ * handles however much data it wants, and the client provides or accepts}}
\DoxyCodeLine{00041 \textcolor{comment}{ * however much is convenient.}}
\DoxyCodeLine{00042 \textcolor{comment}{ *}}
\DoxyCodeLine{00043 \textcolor{comment}{ * At the same time as being friendly to the client, we also try to be very}}
\DoxyCodeLine{00044 \textcolor{comment}{ * friendly to the internal code. It wants to be able to ask for arbitrary}}
\DoxyCodeLine{00045 \textcolor{comment}{ * amounts of input or output and get it without having to keep track of}}
\DoxyCodeLine{00046 \textcolor{comment}{ * partial completion. So there are functions which either complete, or queue}}
\DoxyCodeLine{00047 \textcolor{comment}{ * whatever was not sent and return RS\_BLOCKED.}}
\DoxyCodeLine{00048 \textcolor{comment}{ *}}
\DoxyCodeLine{00049 \textcolor{comment}{ * The output buffer is a little more clever than simply a data buffer. Instead}}
\DoxyCodeLine{00050 \textcolor{comment}{ * it knows that we can send either literal data, or data copied through from}}
\DoxyCodeLine{00051 \textcolor{comment}{ * the input of the stream.}}
\DoxyCodeLine{00052 \textcolor{comment}{ *}}
\DoxyCodeLine{00053 \textcolor{comment}{ * In buf.c you will find functions that then map buffers onto stdio files.}}
\DoxyCodeLine{00054 \textcolor{comment}{ *}}
\DoxyCodeLine{00055 \textcolor{comment}{ * On return from an encoding function, some input will have been consumed}}
\DoxyCodeLine{00056 \textcolor{comment}{ * and/or some output produced, but either the input or the output or possibly}}
\DoxyCodeLine{00057 \textcolor{comment}{ * both could have some remaining bytes available.}}
\DoxyCodeLine{00058 \textcolor{comment}{ *}}
\DoxyCodeLine{00059 \textcolor{comment}{ * librsync never does IO or memory allocation for stream input, but relies on}}
\DoxyCodeLine{00060 \textcolor{comment}{ * the caller. This is very nice for integration, but means that we have to be}}
\DoxyCodeLine{00061 \textcolor{comment}{ * fairly flexible as to when we can `read' or `write' stuff internally.}}
\DoxyCodeLine{00062 \textcolor{comment}{ *}}
\DoxyCodeLine{00063 \textcolor{comment}{ * librsync basically does two types of IO. It reads network integers of}}
\DoxyCodeLine{00064 \textcolor{comment}{ * various lengths which encode command and control information such as}}
\DoxyCodeLine{00065 \textcolor{comment}{ * versions and signatures. It also does bulk data transfer.}}
\DoxyCodeLine{00066 \textcolor{comment}{ *}}
\DoxyCodeLine{00067 \textcolor{comment}{ * IO of network integers is internally buffered, because higher levels of the}}
\DoxyCodeLine{00068 \textcolor{comment}{ * code need to see them transmitted atomically: it's no good to read half of a}}
\DoxyCodeLine{00069 \textcolor{comment}{ * uint32. So there is a small and fixed length internal buffer which}}
\DoxyCodeLine{00070 \textcolor{comment}{ * accumulates these. Unlike previous versions of the library, we don't require}}
\DoxyCodeLine{00071 \textcolor{comment}{ * that the caller hold the start until the whole thing has arrived, which}}
\DoxyCodeLine{00072 \textcolor{comment}{ * guarantees that we can always make progress.}}
\DoxyCodeLine{00073 \textcolor{comment}{ *}}
\DoxyCodeLine{00074 \textcolor{comment}{ * On each call into a stream iterator, it should begin by trying to flush}}
\DoxyCodeLine{00075 \textcolor{comment}{ * output. This may well use up all the remaining stream space, in which case}}
\DoxyCodeLine{00076 \textcolor{comment}{ * nothing else can be done. */}}
\DoxyCodeLine{00077 \textcolor{preprocessor}{\#ifndef SCOOP\_H}}
\DoxyCodeLine{00078 \textcolor{preprocessor}{\#  define SCOOP\_H}}
\DoxyCodeLine{00079 \textcolor{preprocessor}{\#  include <stdbool.h>}}
\DoxyCodeLine{00080 \textcolor{preprocessor}{\#  include <stddef.h>}}
\DoxyCodeLine{00081 \textcolor{preprocessor}{\#  include "{}job.h"{}}}
\DoxyCodeLine{00082 \textcolor{preprocessor}{\#  include "{}librsync.h"{}}}
\DoxyCodeLine{00083 }
\DoxyCodeLine{00084 rs\_result rs\_tube\_catchup(rs\_job\_t *job);}
\DoxyCodeLine{00085 \textcolor{keywordtype}{int} rs\_tube\_is\_idle(rs\_job\_t \textcolor{keyword}{const} *job);}
\DoxyCodeLine{00086 \textcolor{keywordtype}{void} rs\_tube\_write(rs\_job\_t *job, \textcolor{keywordtype}{void} \textcolor{keyword}{const} *buf, \textcolor{keywordtype}{size\_t} len);}
\DoxyCodeLine{00087 \textcolor{keywordtype}{void} rs\_tube\_copy(rs\_job\_t *job, \textcolor{keywordtype}{size\_t} len);}
\DoxyCodeLine{00088 }
\DoxyCodeLine{00089 \textcolor{keywordtype}{void} rs\_scoop\_advance(rs\_job\_t *job, \textcolor{keywordtype}{size\_t} len);}
\DoxyCodeLine{00090 rs\_result rs\_scoop\_readahead(rs\_job\_t *job, \textcolor{keywordtype}{size\_t} len, \textcolor{keywordtype}{void} **ptr);}
\DoxyCodeLine{00091 rs\_result rs\_scoop\_read(rs\_job\_t *job, \textcolor{keywordtype}{size\_t} len, \textcolor{keywordtype}{void} **ptr);}
\DoxyCodeLine{00092 rs\_result rs\_scoop\_read\_rest(rs\_job\_t *job, \textcolor{keywordtype}{size\_t} *len, \textcolor{keywordtype}{void} **ptr);}
\DoxyCodeLine{00093 }
\DoxyCodeLine{00094 \textcolor{keyword}{static} \textcolor{keyword}{inline} \textcolor{keywordtype}{size\_t} rs\_scoop\_avail(rs\_job\_t *job)}
\DoxyCodeLine{00095 \{}
\DoxyCodeLine{00096     \textcolor{keywordflow}{return} job-\/>scoop\_avail + job-\/>stream-\/>avail\_in;}
\DoxyCodeLine{00097 \}}
\DoxyCodeLine{00098 \textcolor{comment}{}}
\DoxyCodeLine{00099 \textcolor{comment}{/** Test if the scoop has reached eof. */}}
\DoxyCodeLine{00100 \textcolor{keyword}{static} \textcolor{keyword}{inline} \textcolor{keywordtype}{bool} rs\_scoop\_eof(rs\_job\_t *job)}
\DoxyCodeLine{00101 \{}
\DoxyCodeLine{00102     \textcolor{keywordflow}{return} !rs\_scoop\_avail(job) \&\& job-\/>stream-\/>eof\_in;}
\DoxyCodeLine{00103 \}}
\DoxyCodeLine{00104 \textcolor{comment}{}}
\DoxyCodeLine{00105 \textcolor{comment}{/** Get a pointer to the next input in the scoop. */}}
\DoxyCodeLine{00106 \textcolor{keyword}{static} \textcolor{keyword}{inline} \textcolor{keywordtype}{void} *rs\_scoop\_buf(rs\_job\_t *job)}
\DoxyCodeLine{00107 \{}
\DoxyCodeLine{00108     \textcolor{keywordflow}{return} job-\/>scoop\_avail ? (\textcolor{keywordtype}{void} *)job-\/>scoop\_next : (\textcolor{keywordtype}{void} *)job-\/>}
\DoxyCodeLine{00109         stream-\/>next\_in;}
\DoxyCodeLine{00110 \}}
\DoxyCodeLine{00111 \textcolor{comment}{}}
\DoxyCodeLine{00112 \textcolor{comment}{/** Get the contiguous length of the next input in the scoop. */}}
\DoxyCodeLine{00113 \textcolor{keyword}{static} \textcolor{keyword}{inline} \textcolor{keywordtype}{size\_t} rs\_scoop\_len(rs\_job\_t *job)}
\DoxyCodeLine{00114 \{}
\DoxyCodeLine{00115     \textcolor{keywordflow}{return} job-\/>scoop\_avail ? job-\/>scoop\_avail : job-\/>stream-\/>avail\_in;}
\DoxyCodeLine{00116 \}}
\DoxyCodeLine{00117 \textcolor{comment}{}}
\DoxyCodeLine{00118 \textcolor{comment}{/** Get the next contiguous buffer of data available in the scoop.}}
\DoxyCodeLine{00119 \textcolor{comment}{ *}}
\DoxyCodeLine{00120 \textcolor{comment}{ * This will return a pointer to the data and reduce len to the amount of}}
\DoxyCodeLine{00121 \textcolor{comment}{ * contiguous data available at that position.}}
\DoxyCodeLine{00122 \textcolor{comment}{ *}}
\DoxyCodeLine{00123 \textcolor{comment}{ * \(\backslash\)param *job -\/ the job instance to use.}}
\DoxyCodeLine{00124 \textcolor{comment}{ *}}
\DoxyCodeLine{00125 \textcolor{comment}{ * \(\backslash\)param *len -\/ the amount of data desired, updated to the amount available.}}
\DoxyCodeLine{00126 \textcolor{comment}{ *}}
\DoxyCodeLine{00127 \textcolor{comment}{ * \(\backslash\)return A pointer to the data. */}}
\DoxyCodeLine{00128 \textcolor{keyword}{static} \textcolor{keyword}{inline} \textcolor{keywordtype}{void} *rs\_scoop\_getbuf(rs\_job\_t *job, \textcolor{keywordtype}{size\_t} *len)}
\DoxyCodeLine{00129 \{}
\DoxyCodeLine{00130     \textcolor{keywordtype}{size\_t} max\_len = rs\_scoop\_len(job);}
\DoxyCodeLine{00131     \textcolor{keywordflow}{if} (*len > max\_len)}
\DoxyCodeLine{00132         *len = max\_len;}
\DoxyCodeLine{00133     \textcolor{keywordflow}{return} rs\_scoop\_buf(job);}
\DoxyCodeLine{00134 \}}
\DoxyCodeLine{00135 \textcolor{comment}{}}
\DoxyCodeLine{00136 \textcolor{comment}{/** Iterate through and consume contiguous data buffers in the scoop.}}
\DoxyCodeLine{00137 \textcolor{comment}{ *}}
\DoxyCodeLine{00138 \textcolor{comment}{ * Example: \(\backslash\)code}}
\DoxyCodeLine{00139 \textcolor{comment}{ *   size\_t len=rs\_scoop\_avail(job);}}
\DoxyCodeLine{00140 \textcolor{comment}{ *   size\_t ilen;}}
\DoxyCodeLine{00141 \textcolor{comment}{ *}}
\DoxyCodeLine{00142 \textcolor{comment}{ *   for (buf = rs\_scoop\_iterbuf(job, \&len, \&ilen); ilen > 0;}}
\DoxyCodeLine{00143 \textcolor{comment}{ *        buf = rs\_scoop\_nextbuf(job, \&len, \&ilen))}}
\DoxyCodeLine{00144 \textcolor{comment}{ *     ilen = fwrite(buf, ilen, 1, f);}}
\DoxyCodeLine{00145 \textcolor{comment}{ * \(\backslash\)endcode}}
\DoxyCodeLine{00146 \textcolor{comment}{ *}}
\DoxyCodeLine{00147 \textcolor{comment}{ * At each iteration buf and ilen are the data and its length for the current}}
\DoxyCodeLine{00148 \textcolor{comment}{ * iteration, and len is the remaining data to iterate through including the}}
\DoxyCodeLine{00149 \textcolor{comment}{ * current iteration. During an iteration you can change ilen to indicate only}}
\DoxyCodeLine{00150 \textcolor{comment}{ * part of the buffer was processed and the next iteration will take this into}}
\DoxyCodeLine{00151 \textcolor{comment}{ * account. Setting ilen = 0 to indicate blocking or errors will terminate}}
\DoxyCodeLine{00152 \textcolor{comment}{ * iteration.}}
\DoxyCodeLine{00153 \textcolor{comment}{ *}}
\DoxyCodeLine{00154 \textcolor{comment}{ * At the end of iteration buf will point at the next location in the scoop}}
\DoxyCodeLine{00155 \textcolor{comment}{ * after the iterated data, len and ilen will be zero, or the remaining data}}
\DoxyCodeLine{00156 \textcolor{comment}{ * and last ilen if iteration was terminated by setting ilen = 0.}}
\DoxyCodeLine{00157 \textcolor{comment}{ *}}
\DoxyCodeLine{00158 \textcolor{comment}{ * \(\backslash\)param *job -\/ the job instance to use.}}
\DoxyCodeLine{00159 \textcolor{comment}{ *}}
\DoxyCodeLine{00160 \textcolor{comment}{ * \(\backslash\)param *len -\/ the size\_t amount of data to iterate over.}}
\DoxyCodeLine{00161 \textcolor{comment}{ *}}
\DoxyCodeLine{00162 \textcolor{comment}{ * \(\backslash\)param *ilen -\/ the size\_t amount of data in the current iteration.}}
\DoxyCodeLine{00163 \textcolor{comment}{ *}}
\DoxyCodeLine{00164 \textcolor{comment}{ * \(\backslash\)return A pointer to data in the current iteration. */}}
\DoxyCodeLine{00165 \textcolor{keyword}{static} \textcolor{keyword}{inline} \textcolor{keywordtype}{void} *rs\_scoop\_iterbuf(rs\_job\_t *job, \textcolor{keywordtype}{size\_t} *len, \textcolor{keywordtype}{size\_t} *ilen)}
\DoxyCodeLine{00166 \{}
\DoxyCodeLine{00167     *ilen = *len;}
\DoxyCodeLine{00168     \textcolor{keywordflow}{return} rs\_scoop\_getbuf(job, ilen);}
\DoxyCodeLine{00169 \}}
\DoxyCodeLine{00170 \textcolor{comment}{}}
\DoxyCodeLine{00171 \textcolor{comment}{/** Get the next iteration of contiguous data buffers from the scoop.}}
\DoxyCodeLine{00172 \textcolor{comment}{ *}}
\DoxyCodeLine{00173 \textcolor{comment}{ * This advances the scoop for the previous iteration, and gets the next}}
\DoxyCodeLine{00174 \textcolor{comment}{ * iteration. \(\backslash\)sa rs\_scoop\_iterbuf */}}
\DoxyCodeLine{00175 \textcolor{keyword}{static} \textcolor{keyword}{inline} \textcolor{keywordtype}{void} *rs\_scoop\_nextbuf(rs\_job\_t *job, \textcolor{keywordtype}{size\_t} *len, \textcolor{keywordtype}{size\_t} *ilen)}
\DoxyCodeLine{00176 \{}
\DoxyCodeLine{00177     \textcolor{keywordflow}{if} (*ilen == 0)}
\DoxyCodeLine{00178         \textcolor{keywordflow}{return} rs\_scoop\_buf(job);}
\DoxyCodeLine{00179     rs\_scoop\_advance(job, *ilen);}
\DoxyCodeLine{00180     *len -\/= *ilen;}
\DoxyCodeLine{00181     \textcolor{keywordflow}{return} rs\_scoop\_iterbuf(job, len, ilen);}
\DoxyCodeLine{00182 \}}
\DoxyCodeLine{00183 }
\DoxyCodeLine{00184 \textcolor{preprocessor}{\#endif                          }\textcolor{comment}{/* !SCOOP\_H */}\textcolor{preprocessor}{}}

\end{DoxyCode}
