Debian Codegraph @

www/session/sqlite3changegroup_add_strm.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="../sqlite.css" rel="stylesheet">
6 <title>Streaming Versions of API functions.</title>
7 <!-- path=../ -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="../index.html">
12 <img class="logo" src="../images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="../index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='../about.html'>About</a>
23 <li class='desktoponly'><a href="../docs.html">Documentation</a>
24 <li class='desktoponly'><a href="../download.html">Download</a>
25 <li class='wideonly'><a href='../copyright.html'>License</a>
26 <li class='desktoponly'><a href="../support.html">Support</a>
27 <li class='desktoponly'><a href="../prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='../about.html'>About</a>
35 <li><a href='../docs.html'>Documentation</a>
36 <li><a href='../download.html'>Download</a>
37 <li><a href='../support.html'>Support</a>
38 <li><a href='../prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="../search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118 <a href="../session/intro.html"><h2>Session Module C Interface</h2></a><h2>Streaming Versions of API functions.</h2><blockquote><pre>int sqlite3changeset_apply_strm(
119 sqlite3 *db, /* Apply change to "main" db of this handle */
120 int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
121 void *pIn, /* First arg for xInput */
122 int(*xFilter)(
123 void *pCtx, /* Copy of sixth arg to _apply() */
124 const char *zTab /* Table name */
125 ),
126 int(*xConflict)(
127 void *pCtx, /* Copy of sixth arg to _apply() */
128 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
129 sqlite3_changeset_iter *p /* Handle describing change and conflict */
130 ),
131 void *pCtx /* First argument passed to xConflict */
132 );
133 int sqlite3changeset_apply_v2_strm(
134 sqlite3 *db, /* Apply change to "main" db of this handle */
135 int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
136 void *pIn, /* First arg for xInput */
137 int(*xFilter)(
138 void *pCtx, /* Copy of sixth arg to _apply() */
139 const char *zTab /* Table name */
140 ),
141 int(*xConflict)(
142 void *pCtx, /* Copy of sixth arg to _apply() */
143 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
144 sqlite3_changeset_iter *p /* Handle describing change and conflict */
145 ),
146 void *pCtx, /* First argument passed to xConflict */
147 void **ppRebase, int *pnRebase,
148 int flags
149 );
150 int sqlite3changeset_apply_v3_strm(
151 sqlite3 *db, /* Apply change to "main" db of this handle */
152 int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
153 void *pIn, /* First arg for xInput */
154 int(*xFilter)(
155 void *pCtx, /* Copy of sixth arg to _apply() */
156 sqlite3_changeset_iter *p
157 ),
158 int(*xConflict)(
159 void *pCtx, /* Copy of sixth arg to _apply() */
160 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
161 sqlite3_changeset_iter *p /* Handle describing change and conflict */
162 ),
163 void *pCtx, /* First argument passed to xConflict */
164 void **ppRebase, int *pnRebase,
165 int flags
166 );
167 int sqlite3changeset_concat_strm(
168 int (*xInputA)(void *pIn, void *pData, int *pnData),
169 void *pInA,
170 int (*xInputB)(void *pIn, void *pData, int *pnData),
171 void *pInB,
172 int (*xOutput)(void *pOut, const void *pData, int nData),
173 void *pOut
174 );
175 int sqlite3changeset_invert_strm(
176 int (*xInput)(void *pIn, void *pData, int *pnData),
177 void *pIn,
178 int (*xOutput)(void *pOut, const void *pData, int nData),
179 void *pOut
180 );
181 int sqlite3changeset_start_strm(
182 sqlite3_changeset_iter **pp,
183 int (*xInput)(void *pIn, void *pData, int *pnData),
184 void *pIn
185 );
186 int sqlite3changeset_start_v2_strm(
187 sqlite3_changeset_iter **pp,
188 int (*xInput)(void *pIn, void *pData, int *pnData),
189 void *pIn,
190 int flags
191 );
192 int sqlite3session_changeset_strm(
193 sqlite3_session *pSession,
194 int (*xOutput)(void *pOut, const void *pData, int nData),
195 void *pOut
196 );
197 int sqlite3session_patchset_strm(
198 sqlite3_session *pSession,
199 int (*xOutput)(void *pOut, const void *pData, int nData),
200 void *pOut
201 );
202 int sqlite3changegroup_add_strm(sqlite3_changegroup*,
203 int (*xInput)(void *pIn, void *pData, int *pnData),
204 void *pIn
205 );
206 int sqlite3changegroup_output_strm(sqlite3_changegroup*,
207 int (*xOutput)(void *pOut, const void *pData, int nData),
208 void *pOut
209 );
210 int sqlite3rebaser_rebase_strm(
211 sqlite3_rebaser *pRebaser,
212 int (*xInput)(void *pIn, void *pData, int *pnData),
213 void *pIn,
214 int (*xOutput)(void *pOut, const void *pData, int nData),
215 void *pOut
216 );
217 </pre></blockquote><p>
218 The six streaming API xxx_strm() functions serve similar purposes to the
219 corresponding non-streaming API functions:</p>
220
221 <p><table border=1 style="margin-left:8ex;margin-right:8ex">
222 <tr><th>Streaming function<th>Non-streaming equivalent</th>
223 <tr><td>sqlite3changeset_apply_strm<td><a href="../session/sqlite3changeset_apply.html">sqlite3changeset_apply</a>
224 <tr><td>sqlite3changeset_apply_strm_v2<td><a href="../session/sqlite3changeset_apply.html">sqlite3changeset_apply_v2</a>
225 <tr><td>sqlite3changeset_concat_strm<td><a href="../session/sqlite3changeset_concat.html">sqlite3changeset_concat</a>
226 <tr><td>sqlite3changeset_invert_strm<td><a href="../session/sqlite3changeset_invert.html">sqlite3changeset_invert</a>
227 <tr><td>sqlite3changeset_start_strm<td><a href="../session/sqlite3changeset_start.html">sqlite3changeset_start</a>
228 <tr><td>sqlite3session_changeset_strm<td><a href="../session/sqlite3session_changeset.html">sqlite3session_changeset</a>
229 <tr><td>sqlite3session_patchset_strm<td><a href="../session/sqlite3session_patchset.html">sqlite3session_patchset</a>
230 </table></p>
231
232 <p>Non-streaming functions that accept changesets (or patchsets) as input
233 require that the entire changeset be stored in a single buffer in memory.
234 Similarly, those that return a changeset or patchset do so by returning
235 a pointer to a single large buffer allocated using sqlite3_malloc().
236 Normally this is convenient. However, if an application running in a
237 low-memory environment is required to handle very large changesets, the
238 large contiguous memory allocations required can become onerous.</p>
239
240 <p>In order to avoid this problem, instead of a single large buffer, input
241 is passed to a streaming API functions by way of a callback function that
242 the sessions module invokes to incrementally request input data as it is
243 required. In all cases, a pair of API function parameters such as</p>
244
245 <p> <pre>
246 &nbsp; int nChangeset,
247 &nbsp; void *pChangeset,
248 </pre></p>
249
250 <p>Is replaced by:</p>
251
252 <p> <pre>
253 &nbsp; int (*xInput)(void *pIn, void *pData, int *pnData),
254 &nbsp; void *pIn,
255 </pre></p>
256
257 <p>Each time the xInput callback is invoked by the sessions module, the first
258 argument passed is a copy of the supplied pIn context pointer. The second
259 argument, pData, points to a buffer (*pnData) bytes in size. Assuming no
260 error occurs the xInput method should copy up to (*pnData) bytes of data
261 into the buffer and set (*pnData) to the actual number of bytes copied
262 before returning SQLITE_OK. If the input is completely exhausted, (*pnData)
263 should be set to zero to indicate this. Or, if an error occurs, an SQLite
264 error code should be returned. In all cases, if an xInput callback returns
265 an error, all processing is abandoned and the streaming API function
266 returns a copy of the error code to the caller.</p>
267
268 <p>In the case of sqlite3changeset_start_strm(), the xInput callback may be
269 invoked by the sessions module at any point during the lifetime of the
270 iterator. If such an xInput callback returns an error, the iterator enters
271 an error state, whereby all subsequent calls to iterator functions
272 immediately fail with the same error code as returned by xInput.</p>
273
274 <p>Similarly, streaming API functions that return changesets (or patchsets)
275 return them in chunks by way of a callback function instead of via a
276 pointer to a single large buffer. In this case, a pair of parameters such
277 as:</p>
278
279 <p> <pre>
280 &nbsp; int *pnChangeset,
281 &nbsp; void **ppChangeset,
282 </pre></p>
283
284 <p>Is replaced by:</p>
285
286 <p> <pre>
287 &nbsp; int (*xOutput)(void *pOut, const void *pData, int nData),
288 &nbsp; void *pOut
289 </pre></p>
290
291 <p>The xOutput callback is invoked zero or more times to return data to
292 the application. The first parameter passed to each call is a copy of the
293 pOut pointer supplied by the application. The second parameter, pData,
294 points to a buffer nData bytes in size containing the chunk of output
295 data being returned. If the xOutput callback successfully processes the
296 supplied data, it should return SQLITE_OK to indicate success. Otherwise,
297 it should return some other SQLite error code. In this case processing
298 is immediately abandoned and the streaming API function returns a copy
299 of the xOutput error code to the application.</p>
300
301 <p>The sessions module never invokes an xOutput callback with the third
302 parameter set to a value less than or equal to zero. Other than this,
303 no guarantees are made as to the size of the chunks of data returned.
304 </p><p>See also lists of
305 <a href="../session/objlist.html">Objects</a>,
306 <a href="../session/constlist.html">Constants</a>, and
307 <a href="../session/funclist.html">Functions</a>.</p>
308