Debian Codegraph @

www/session.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>SQLite Session Module C/C++ Interface</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
119
120 <h2>SQLite Session Module C/C++ Interface</h2>
121
122
123
124 <p>This page defines the C-language interface to the SQLite
125 <a href="sessionintro.html">session extension</a>.
126 This is not a tutorial. These pages are designed to be precise, not easy
127 to read. A tutorial is <a href="sessionintro.html">available separately</a>.
128
129 <p>This page contains all C-language interface information
130 in a single HTML file. The same information is also available
131 broken out into <a href="../session/intro.html">some smaller pages</a>
132 for easier viewing, if you prefer.</p>
133
134 <p>This document is created by a script which scans comments in the source
135 code file sqlite3session.h.</p>
136
137 <hr>
138
139
140 <h2>Objects:</h2>
141 <div class='columns' style='columns: 15em auto;'>
142 <ul style='padding-top:0;'>
143 <li><a href='#sqlite3_changegroup'>sqlite3_changegroup</a></li>
144 <li><a href='#sqlite3_changeset_iter'>sqlite3_changeset_iter</a></li>
145 <li><a href='#sqlite3_rebaser'>sqlite3_rebaser<small><i>(exp)</i></small></a></li>
146 <li><a href='#sqlite3_session'>sqlite3_session</a></li>
147 </ul>
148 </div>
149 <hr>
150
151 <h2>Constants:</h2>
152 <div class='columns' style='columns: 20em auto;'>
153 <ul style='padding-top:0;'>
154 <li><a href='#SQLITE_CHANGEGROUP_CONFIG_PATCHSET'>SQLITE_CHANGEGROUP_CONFIG_PATCHSET</a></li>
155 <li><a href='#SQLITE_CHANGESETAPPLY_FKNOACTION'>SQLITE_CHANGESETAPPLY_FKNOACTION</a></li>
156 <li><a href='#SQLITE_CHANGESETAPPLY_FKNOACTION'>SQLITE_CHANGESETAPPLY_IGNORENOOP</a></li>
157 <li><a href='#SQLITE_CHANGESETAPPLY_FKNOACTION'>SQLITE_CHANGESETAPPLY_INVERT</a></li>
158 <li><a href='#SQLITE_CHANGESETAPPLY_FKNOACTION'>SQLITE_CHANGESETAPPLY_NOSAVEPOINT</a></li>
159 <li><a href='#SQLITE_CHANGESETAPPLY_FKNOACTION'>SQLITE_CHANGESETAPPLY_NOUPDATELOOP</a></li>
160 <li><a href='#SQLITE_CHANGESETSTART_INVERT'>SQLITE_CHANGESETSTART_INVERT</a></li>
161 <li><a href='#SQLITE_CHANGESET_ABORT'>SQLITE_CHANGESET_ABORT</a></li>
162 <li><a href='#SQLITE_CHANGESET_CONFLICT'>SQLITE_CHANGESET_CONFLICT</a></li>
163 <li><a href='#SQLITE_CHANGESET_CONFLICT'>SQLITE_CHANGESET_CONSTRAINT</a></li>
164 <li><a href='#SQLITE_CHANGESET_CONFLICT'>SQLITE_CHANGESET_DATA</a></li>
165 <li><a href='#SQLITE_CHANGESET_CONFLICT'>SQLITE_CHANGESET_FOREIGN_KEY</a></li>
166 <li><a href='#SQLITE_CHANGESET_CONFLICT'>SQLITE_CHANGESET_NOTFOUND</a></li>
167 <li><a href='#SQLITE_CHANGESET_ABORT'>SQLITE_CHANGESET_OMIT</a></li>
168 <li><a href='#SQLITE_CHANGESET_ABORT'>SQLITE_CHANGESET_REPLACE</a></li>
169 <li><a href='#SQLITE_SESSION_CONFIG_STRMSIZE'>SQLITE_SESSION_CONFIG_STRMSIZE</a></li>
170 <li><a href='#SQLITE_SESSION_OBJCONFIG_ROWID'>SQLITE_SESSION_OBJCONFIG_ROWID</a></li>
171 <li><a href='#SQLITE_SESSION_OBJCONFIG_ROWID'>SQLITE_SESSION_OBJCONFIG_SIZE</a></li>
172 </ul>
173 </div>
174 <hr>
175
176 <h2>Functions:</h2>
177 <div class='columns' style='columns: 17em auto;'>
178 <ul style='padding-top:0;'>
179 <li><a href='#sqlite3changegroup_add'>sqlite3changegroup_add</a></li>
180 <li><a href='#sqlite3changegroup_add_change'>sqlite3changegroup_add_change</a></li>
181 <li><a href='#sqlite3changegroup_add_strm'>sqlite3changegroup_add_strm</a></li>
182 <li><a href='#sqlite3changegroup_change_begin'>sqlite3changegroup_change_begin</a></li>
183 <li><a href='#sqlite3changegroup_change_blob'>sqlite3changegroup_change_blob</a></li>
184 <li><a href='#sqlite3changegroup_change_double'>sqlite3changegroup_change_double</a></li>
185 <li><a href='#sqlite3changegroup_change_finish'>sqlite3changegroup_change_finish</a></li>
186 <li><a href='#sqlite3changegroup_change_int64'>sqlite3changegroup_change_int64</a></li>
187 <li><a href='#sqlite3changegroup_change_null'>sqlite3changegroup_change_null</a></li>
188 <li><a href='#sqlite3changegroup_change_text'>sqlite3changegroup_change_text</a></li>
189 <li><a href='#sqlite3changegroup_config'>sqlite3changegroup_config</a></li>
190 <li><a href='#sqlite3changegroup_delete'>sqlite3changegroup_delete</a></li>
191 <li><a href='#sqlite3changegroup_new'>sqlite3changegroup_new</a></li>
192 <li><a href='#sqlite3changegroup_output'>sqlite3changegroup_output</a></li>
193 <li><a href='#sqlite3changegroup_add_strm'>sqlite3changegroup_output_strm</a></li>
194 <li><a href='#sqlite3changegroup_schema'>sqlite3changegroup_schema</a></li>
195 <li><a href='#sqlite3changeset_apply'>sqlite3changeset_apply</a></li>
196 <li><a href='#sqlite3changegroup_add_strm'>sqlite3changeset_apply_strm</a></li>
197 <li><a href='#sqlite3changeset_apply'>sqlite3changeset_apply_v2</a></li>
198 <li><a href='#sqlite3changegroup_add_strm'>sqlite3changeset_apply_v2_strm</a></li>
199 <li><a href='#sqlite3changeset_apply'>sqlite3changeset_apply_v3</a></li>
200 <li><a href='#sqlite3changegroup_add_strm'>sqlite3changeset_apply_v3_strm</a></li>
201 <li><a href='#sqlite3changeset_concat'>sqlite3changeset_concat</a></li>
202 <li><a href='#sqlite3changegroup_add_strm'>sqlite3changeset_concat_strm</a></li>
203 <li><a href='#sqlite3changeset_conflict'>sqlite3changeset_conflict</a></li>
204 <li><a href='#sqlite3changeset_finalize'>sqlite3changeset_finalize</a></li>
205 <li><a href='#sqlite3changeset_fk_conflicts'>sqlite3changeset_fk_conflicts</a></li>
206 <li><a href='#sqlite3changeset_invert'>sqlite3changeset_invert</a></li>
207 <li><a href='#sqlite3changegroup_add_strm'>sqlite3changeset_invert_strm</a></li>
208 <li><a href='#sqlite3changeset_new'>sqlite3changeset_new</a></li>
209 <li><a href='#sqlite3changeset_next'>sqlite3changeset_next</a></li>
210 <li><a href='#sqlite3changeset_old'>sqlite3changeset_old</a></li>
211 <li><a href='#sqlite3changeset_op'>sqlite3changeset_op</a></li>
212 <li><a href='#sqlite3changeset_pk'>sqlite3changeset_pk</a></li>
213 <li><a href='#sqlite3changeset_start'>sqlite3changeset_start</a></li>
214 <li><a href='#sqlite3changegroup_add_strm'>sqlite3changeset_start_strm</a></li>
215 <li><a href='#sqlite3changeset_start'>sqlite3changeset_start_v2</a></li>
216 <li><a href='#sqlite3changegroup_add_strm'>sqlite3changeset_start_v2_strm</a></li>
217 <li><a href='#sqlite3rebaser_configure'>sqlite3rebaser_configure<small><i>(exp)</i></small></a></li>
218 <li><a href='#sqlite3rebaser_create'>sqlite3rebaser_create<small><i>(exp)</i></small></a></li>
219 <li><a href='#sqlite3rebaser_delete'>sqlite3rebaser_delete<small><i>(exp)</i></small></a></li>
220 <li><a href='#sqlite3rebaser_rebase'>sqlite3rebaser_rebase<small><i>(exp)</i></small></a></li>
221 <li><a href='#sqlite3changegroup_add_strm'>sqlite3rebaser_rebase_strm</a></li>
222 <li><a href='#sqlite3session_attach'>sqlite3session_attach</a></li>
223 <li><a href='#sqlite3session_changeset'>sqlite3session_changeset</a></li>
224 <li><a href='#sqlite3session_changeset_size'>sqlite3session_changeset_size</a></li>
225 <li><a href='#sqlite3changegroup_add_strm'>sqlite3session_changeset_strm</a></li>
226 <li><a href='#sqlite3session_config'>sqlite3session_config</a></li>
227 <li><a href='#sqlite3session_create'>sqlite3session_create</a></li>
228 <li><a href='#sqlite3session_delete'>sqlite3session_delete</a></li>
229 <li><a href='#sqlite3session_diff'>sqlite3session_diff</a></li>
230 <li><a href='#sqlite3session_enable'>sqlite3session_enable</a></li>
231 <li><a href='#sqlite3session_indirect'>sqlite3session_indirect</a></li>
232 <li><a href='#sqlite3session_isempty'>sqlite3session_isempty</a></li>
233 <li><a href='#sqlite3session_memory_used'>sqlite3session_memory_used</a></li>
234 <li><a href='#sqlite3session_object_config'>sqlite3session_object_config</a></li>
235 <li><a href='#sqlite3session_patchset'>sqlite3session_patchset</a></li>
236 <li><a href='#sqlite3changegroup_add_strm'>sqlite3session_patchset_strm</a></li>
237 <li><a href='#sqlite3session_table_filter'>sqlite3session_table_filter</a></li>
238 </ul>
239 </div>
240 <hr>
241 <a name="SQLITE_CHANGEGROUP_CONFIG_PATCHSET"></a>
242 <h2>Options for sqlite3changegroup_config().</h2><blockquote><pre>#define SQLITE_CHANGEGROUP_CONFIG_PATCHSET 1
243 </pre></blockquote><p>
244 The following values may be passed as the 2nd parameter to
245 sqlite3changegroup_config().</p>
246
247 <p><dt>SQLITE_CHANGEGROUP_CONFIG_PATCHSET <dd>
248 A changegroup object generates either a changeset or patchset. Usually,
249 this is determined by whether the first call to sqlite3changegroup_add()
250 is passed a changeset or a patchset. Or, if the first changes are added
251 to the changegroup object using the sqlite3changegroup_change_xxx()
252 APIs, then this option may be used to configure whether the changegroup
253 object generates a changeset or patchset. </p>
254
255 <p> When this option is invoked, parameter pArg must point to a value of
256 type int. If the changegroup currently contains zero changes, and the
257 value of the int variable is zero or greater than zero, then the
258 changegroup is configured to generate a changeset or patchset,
259 respectively. It is a no-op, not an error, if the changegroup is not
260 configured because it has already started accumulating changes.</p>
261
262 <p> Before returning, the int variable is set to 0 if the changegroup is
263 configured to generate a changeset, or 1 if it is configured to generate
264 a patchset.
265 </p><hr><a name="SQLITE_CHANGESETSTART_INVERT"></a>
266 <h2>Flags for sqlite3changeset_start_v2</h2><blockquote><pre>#define SQLITE_CHANGESETSTART_INVERT 0x0002
267 </pre></blockquote><p>
268 The following flags may passed via the 4th parameter to
269 <a href="#sqlite3changeset_start">sqlite3changeset_start_v2</a> and <a href="#sqlite3changegroup_add_strm">sqlite3changeset_start_v2_strm</a>:</p>
270
271 <p><dt>SQLITE_CHANGESETSTART_INVERT <dd>
272 Invert the changeset while iterating through it. This is equivalent to
273 inverting a changeset using sqlite3changeset_invert() before applying it.
274 It is an error to specify this flag with a patchset.
275 </p><hr><a name="SQLITE_SESSION_CONFIG_STRMSIZE"></a>
276 <h2>Values for sqlite3session_config().</h2><blockquote><pre>#define SQLITE_SESSION_CONFIG_STRMSIZE 1
277 </pre></blockquote><p></p><hr><a name="sqlite3_changegroup"></a>
278 <h2>Changegroup Handle</h2><blockquote><pre>typedef struct sqlite3_changegroup sqlite3_changegroup;
279 </pre></blockquote><p>
280 A changegroup is an object used to combine two or more
281 <a href="sessionintro.html#changeset">changesets</a> or <a href="sessionintro.html#changeset">patchsets</a>
282 </p><p>Constructor: <a href="#sqlite3changegroup_new">sqlite3changegroup_new()</a></p>
283 <p>Destructor: <a href="#sqlite3changegroup_delete">sqlite3changegroup_delete()</a></p>
284 <p>Methods:
285 <a href="#sqlite3changegroup_add">sqlite3changegroup_add()</a>,
286 <a href="#sqlite3changegroup_add_change">sqlite3changegroup_add_change()</a>,
287 <a href="#sqlite3changegroup_output">sqlite3changegroup_output()</a></p>
288 <hr><a name="sqlite3_changeset_iter"></a>
289 <h2>Changeset Iterator Handle</h2><blockquote><pre>typedef struct sqlite3_changeset_iter sqlite3_changeset_iter;
290 </pre></blockquote><p>
291 An instance of this object acts as a cursor for iterating
292 over the elements of a <a href="sessionintro.html#changeset">changeset</a> or <a href="sessionintro.html#changeset">patchset</a>.
293 </p><p>Constructors:
294 <a href="#sqlite3changeset_start">sqlite3changeset_start()</a>,
295 <a href="#sqlite3changeset_start">sqlite3changeset_start_v2()</a></p>
296 <div class='columns' style='columns: 17em auto;'>
297 <ul style='padding-top:0;'>
298 <li><a href='#sqlite3changeset_conflict'>sqlite3changeset_conflict</a></li>
299 <li><a href='#sqlite3changeset_finalize'>sqlite3changeset_finalize</a></li>
300 <li><a href='#sqlite3changeset_fk_conflicts'>sqlite3changeset_fk_conflicts</a></li>
301 <li><a href='#sqlite3changeset_new'>sqlite3changeset_new</a></li>
302 <li><a href='#sqlite3changeset_next'>sqlite3changeset_next</a></li>
303 <li><a href='#sqlite3changeset_old'>sqlite3changeset_old</a></li>
304 <li><a href='#sqlite3changeset_op'>sqlite3changeset_op</a></li>
305 <li><a href='#sqlite3changeset_pk'>sqlite3changeset_pk</a></li>
306 </ul>
307 </div>
308 </p>
309 <hr><a name="sqlite3_rebaser"></a>
310 <h2>Rebasing changesets</h2><blockquote><pre>typedef struct sqlite3_rebaser sqlite3_rebaser;
311 </pre></blockquote><p><b>Important:</b> This interface is <a href="c3ref/experimental.html">experimental</a> and is subject to change without notice.</p><p>
312 Suppose there is a site hosting a database in state S0. And that
313 modifications are made that move that database to state S1 and a
314 changeset recorded (the "local" changeset). Then, a changeset based
315 on S0 is received from another site (the "remote" changeset) and
316 applied to the database. The database is then in state
317 (S1+"remote"), where the exact state depends on any conflict
318 resolution decisions (OMIT or REPLACE) made while applying "remote".
319 Rebasing a changeset is to update it to take those conflict
320 resolution decisions into account, so that the same conflicts
321 do not have to be resolved elsewhere in the network. </p>
322
323 <p>For example, if both the local and remote changesets contain an
324 INSERT of the same key on "CREATE TABLE t1(a PRIMARY KEY, b)":</p>
325
326 <p> local: INSERT INTO t1 VALUES(1, 'v1');
327 remote: INSERT INTO t1 VALUES(1, 'v2');</p>
328
329 <p>and the conflict resolution is REPLACE, then the INSERT change is
330 removed from the local changeset (it was overridden). Or, if the
331 conflict resolution was "OMIT", then the local changeset is modified
332 to instead contain:</p>
333
334 <p> UPDATE t1 SET b = 'v2' WHERE a=1;</p>
335
336 <p>Changes within the local changeset are rebased as follows:</p>
337
338 <p><dl>
339 <dt>Local INSERT<dd>
340 This may only conflict with a remote INSERT. If the conflict
341 resolution was OMIT, then add an UPDATE change to the rebased
342 changeset. Or, if the conflict resolution was REPLACE, add
343 nothing to the rebased changeset.</p>
344
345 <p><dt>Local DELETE<dd>
346 This may conflict with a remote UPDATE or DELETE. In both cases the
347 only possible resolution is OMIT. If the remote operation was a
348 DELETE, then add no change to the rebased changeset. If the remote
349 operation was an UPDATE, then the old.* fields of change are updated
350 to reflect the new.* values in the UPDATE.</p>
351
352 <p><dt>Local UPDATE<dd>
353 This may conflict with a remote UPDATE or DELETE. If it conflicts
354 with a DELETE, and the conflict resolution was OMIT, then the update
355 is changed into an INSERT. Any undefined values in the new.* record
356 from the update change are filled in using the old.* values from
357 the conflicting DELETE. Or, if the conflict resolution was REPLACE,
358 the UPDATE change is simply omitted from the rebased changeset.</p>
359
360 <p> If conflict is with a remote UPDATE and the resolution is OMIT, then
361 the old.* values are rebased using the new.* values in the remote
362 change. Or, if the resolution is REPLACE, then the change is copied
363 into the rebased changeset with updates to columns also updated by
364 the conflicting remote UPDATE removed. If this means no columns would
365 be updated, the change is omitted.
366 </dl></p>
367
368 <p>A local change may be rebased against multiple remote changes
369 simultaneously. If a single key is modified by multiple remote
370 changesets, they are combined as follows before the local changeset
371 is rebased:</p>
372
373 <p><ul>
374 <li> If there has been one or more REPLACE resolutions on a
375 key, it is rebased according to a REPLACE.</p>
376
377 <p> <li> If there have been no REPLACE resolutions on a key, then
378 the local changeset is rebased according to the most recent
379 of the OMIT resolutions.
380 </ul></p>
381
382 <p>Note that conflict resolutions from multiple remote changesets are
383 combined on a per-field basis, not per-row. This means that in the
384 case of multiple remote UPDATE operations, some fields of a single
385 local change may be rebased for REPLACE while others are rebased for
386 OMIT.</p>
387
388 <p>In order to rebase a local changeset, the remote changeset must first
389 be applied to the local database using sqlite3changeset_apply_v2() and
390 the buffer of rebase information captured. Then:</p>
391
392 <p><ol>
393 <li> An sqlite3_rebaser object is created by calling
394 sqlite3rebaser_create().
395 <li> The new object is configured with the rebase buffer obtained from
396 sqlite3changeset_apply_v2() by calling sqlite3rebaser_configure().
397 If the local changeset is to be rebased against multiple remote
398 changesets, then sqlite3rebaser_configure() should be called
399 multiple times, in the same order that the multiple
400 sqlite3changeset_apply_v2() calls were made.
401 <li> Each local changeset is rebased by calling sqlite3rebaser_rebase().
402 <li> The sqlite3_rebaser object is deleted by calling
403 sqlite3rebaser_delete().
404 </ol>
405 </p><hr><a name="sqlite3_session"></a>
406 <h2>Session Object Handle</h2><blockquote><pre>typedef struct sqlite3_session sqlite3_session;
407 </pre></blockquote><p>
408 An instance of this object is a <a href="sessionintro.html">session</a> that can be used to
409 record changes to a database.
410 </p><p>Constructor: <a href="#sqlite3session_create">sqlite3session_create()</a></p>
411 <p>Destructor: <a href="#sqlite3session_delete">sqlite3session_delete()</a></p>
412 <div class='columns' style='columns: 17em auto;'>
413 <ul style='padding-top:0;'>
414 <li><a href='#sqlite3session_attach'>sqlite3session_attach</a></li>
415 <li><a href='#sqlite3session_changeset'>sqlite3session_changeset</a></li>
416 <li><a href='#sqlite3session_changeset_size'>sqlite3session_changeset_size</a></li>
417 <li><a href='#sqlite3session_diff'>sqlite3session_diff</a></li>
418 <li><a href='#sqlite3session_enable'>sqlite3session_enable</a></li>
419 <li><a href='#sqlite3session_indirect'>sqlite3session_indirect</a></li>
420 <li><a href='#sqlite3session_object_config'>sqlite3session_object_config</a></li>
421 <li><a href='#sqlite3session_patchset'>sqlite3session_patchset</a></li>
422 <li><a href='#sqlite3session_table_filter'>sqlite3session_table_filter</a></li>
423 </ul>
424 </div>
425 </p>
426 <hr><a name="sqlite3changegroup_add"></a>
427 <h2>Add A Changeset To A Changegroup</h2><blockquote><pre>int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pData);
428 </pre></blockquote><p>
429 Add all changes within the changeset (or patchset) in buffer pData (size
430 nData bytes) to the changegroup. </p>
431
432 <p>If the buffer contains a patchset, then all prior calls to this function
433 on the same changegroup object must also have specified patchsets. Or, if
434 the buffer contains a changeset, so must have the earlier calls to this
435 function. Otherwise, SQLITE_ERROR is returned and no changes are added
436 to the changegroup.</p>
437
438 <p>Rows within the changeset and changegroup are identified by the values in
439 their PRIMARY KEY columns. A change in the changeset is considered to
440 apply to the same row as a change already present in the changegroup if
441 the two rows have the same primary key.</p>
442
443 <p>Changes to rows that do not already appear in the changegroup are
444 simply copied into it. Or, if both the new changeset and the changegroup
445 contain changes that apply to a single row, the final contents of the
446 changegroup depends on the type of each change, as follows:</p>
447
448 <p><table border=1 style="margin-left:8ex;margin-right:8ex">
449 <tr><th style="white-space:pre">Existing Change </th>
450 <th style="white-space:pre">New Change </th>
451 <th>Output Change
452 <tr><td>INSERT <td>INSERT <td>
453 The new change is ignored. This case does not occur if the new
454 changeset was recorded immediately after the changesets already
455 added to the changegroup.
456 <tr><td>INSERT <td>UPDATE <td>
457 The INSERT change remains in the changegroup. The values in the
458 INSERT change are modified as if the row was inserted by the
459 existing change and then updated according to the new change.
460 <tr><td>INSERT <td>DELETE <td>
461 The existing INSERT is removed from the changegroup. The DELETE is
462 not added.
463 <tr><td>UPDATE <td>INSERT <td>
464 The new change is ignored. This case does not occur if the new
465 changeset was recorded immediately after the changesets already
466 added to the changegroup.
467 <tr><td>UPDATE <td>UPDATE <td>
468 The existing UPDATE remains within the changegroup. It is amended
469 so that the accompanying values are as if the row was updated once
470 by the existing change and then again by the new change.
471 <tr><td>UPDATE <td>DELETE <td>
472 The existing UPDATE is replaced by the new DELETE within the
473 changegroup.
474 <tr><td>DELETE <td>INSERT <td>
475 If one or more of the column values in the row inserted by the
476 new change differ from those in the row deleted by the existing
477 change, the existing DELETE is replaced by an UPDATE within the
478 changegroup. Otherwise, if the inserted row is exactly the same
479 as the deleted row, the existing DELETE is simply discarded.
480 <tr><td>DELETE <td>UPDATE <td>
481 The new change is ignored. This case does not occur if the new
482 changeset was recorded immediately after the changesets already
483 added to the changegroup.
484 <tr><td>DELETE <td>DELETE <td>
485 The new change is ignored. This case does not occur if the new
486 changeset was recorded immediately after the changesets already
487 added to the changegroup.
488 </table></p>
489
490 <p>If the new changeset contains changes to a table that is already present
491 in the changegroup, then the number of columns and the position of the
492 primary key columns for the table must be consistent. If this is not the
493 case, this function fails with SQLITE_SCHEMA. Except, if the changegroup
494 object has been configured with a database schema using the
495 sqlite3changegroup_schema() API, then it is possible to combine changesets
496 with different numbers of columns for a single table, provided that
497 they are otherwise compatible.</p>
498
499 <p>If the input changeset appears to be corrupt and the corruption is
500 detected, SQLITE_CORRUPT is returned. Or, if an out-of-memory condition
501 occurs during processing, this function returns SQLITE_NOMEM. </p>
502
503 <p>In all cases, if an error occurs the state of the final contents of the
504 changegroup is undefined. If no error occurs, SQLITE_OK is returned.
505 </p><hr><a name="sqlite3changegroup_add_change"></a>
506 <h2>Add A Single Change To A Changegroup</h2><blockquote><pre>int sqlite3changegroup_add_change(
507 sqlite3_changegroup*,
508 sqlite3_changeset_iter*
509 );
510 </pre></blockquote><p>
511 This function adds the single change currently indicated by the iterator
512 passed as the second argument to the changegroup object. The rules for
513 adding the change are just as described for <a href="#sqlite3changegroup_add">sqlite3changegroup_add()</a>.</p>
514
515 <p>If the change is successfully added to the changegroup, SQLITE_OK is
516 returned. Otherwise, an SQLite error code is returned.</p>
517
518 <p>The iterator must point to a valid entry when this function is called.
519 If it does not, SQLITE_ERROR is returned and no change is added to the
520 changegroup. Additionally, the iterator must not have been opened with
521 the SQLITE_CHANGESETAPPLY_INVERT flag. In this case SQLITE_ERROR is also
522 returned.
523 </p><hr><a name="sqlite3changegroup_change_begin"></a>
524 <h2>Begin adding a change to a changegroup</h2><blockquote><pre>int sqlite3changegroup_change_begin(
525 sqlite3_changegroup*,
526 int eOp,
527 const char *zTab,
528 int bIndirect,
529 char **pzErr
530 );
531 </pre></blockquote><p>
532 This API is used, in concert with other sqlite3changegroup_change_xxx()
533 APIs, to add changes to a changegroup object one at a time. To add a
534 single change, the caller must:</p>
535
536 <p> 1. Invoke sqlite3changegroup_change_begin() to indicate the type of
537 change (INSERT, UPDATE or DELETE), the affected table and whether
538 or not the change should be marked as indirect.</p>
539
540 <p> 2. Invoke sqlite3changegroup_change_int64() or one of the other four
541 value functions - _null(), _double(), _text() or _blob() - one or
542 more times to specify old.* and new.* values for the change being
543 constructed.</p>
544
545 <p> 3. Invoke sqlite3changegroup_change_finish() to either finish adding
546 the change to the group, or to discard the change altogether.</p>
547
548 <p>The first argument to this function must be a pointer to the existing
549 changegroup object that the change will be added to. The second argument
550 must be SQLITE_INSERT, SQLITE_UPDATE or SQLITE_DELETE. The third is the
551 name of the table that the change affects, and the fourth is a boolean
552 flag specifying whether the change should be marked as "indirect" (if
553 bIndirect is non-zero) or not indirect (if bIndirect is zero).</p>
554
555 <p>Following a successful call to this function, this function may not be
556 called again on the same changegroup object until after
557 sqlite3changegroup_change_finish() has been called. Doing so is an
558 SQLITE_MISUSE error.</p>
559
560 <p>The changegroup object passed as the first argument must be already
561 configured with schema data for the specified table. It may be configured
562 either by calling sqlite3changegroup_schema() with a database that contains
563 the table, or sqlite3changegroup_add() with a changeset that contains the
564 table. If the changegroup object has not been configured with a schema for
565 the specified table when this function is called, SQLITE_ERROR is returned.</p>
566
567 <p>If successful, SQLITE_OK is returned. Otherwise, if an error occurs, an
568 SQLite error code is returned. In this case, if argument pzErr is non-NULL,
569 then (*pzErr) may be set to point to a buffer containing a utf-8 formated,
570 nul-terminated, English language error message. It is the responsibility
571 of the caller to eventually free this buffer using sqlite3_free().
572 </p><hr><a name="sqlite3changegroup_change_blob"></a>
573 <h2>Add a blob to a changegroup</h2><blockquote><pre>int sqlite3changegroup_change_blob(
574 sqlite3_changegroup*, int, int, const void *pVal, int nVal
575 );
576 </pre></blockquote><p>
577 This function is similar to sqlite3changegroup_change_int64(). It configures
578 the currently accumulated change with a blob value instead of a 64-bit
579 integer. Parameter pVal points to a buffer containing the blob. Parameter
580 nVal is the size of the blob in bytes.
581 </p><hr><a name="sqlite3changegroup_change_double"></a>
582 <h2>Add an double to a changegroup</h2><blockquote><pre>int sqlite3changegroup_change_double(sqlite3_changegroup*, int, int, double);
583 </pre></blockquote><p>
584 This function is similar to sqlite3changegroup_change_int64(). Except that
585 it configures the change currently being constructed with a real value
586 instead of a 64-bit integer.
587 </p><hr><a name="sqlite3changegroup_change_finish"></a>
588 <h2>Finish adding one-at-at-time changes to a changegroup</h2><blockquote><pre>int sqlite3changegroup_change_finish(
589 sqlite3_changegroup*,
590 int bDiscard,
591 char **pzErr
592 );
593 </pre></blockquote><p>
594 This function may only be called following a successful call to
595 sqlite3changegroup_change_begin(). Otherwise, it is an SQLITE_MISUSE error.</p>
596
597 <p>If parameter bDiscard is non-zero, then the current change is simply
598 discarded. In this case this function is always successful and SQLITE_OK
599 returned.</p>
600
601 <p>If parameter bDiscard is zero, then an attempt is made to add the current
602 change to the changegroup. Assuming the changegroup is configured to
603 produce a changeset (not a patchset), this requires that:</p>
604
605 <p> * If the change is an INSERT or DELETE, then a value must be specified
606 for all columns of the new.* or old.* record, respectively.</p>
607
608 <p> * If the change is an UPDATE record, then values must be provided for
609 the PRIMARY KEY columns of the old.* record, but must not be provided
610 for PRIMARY KEY columns of the new.* record.</p>
611
612 <p> * If the change is an UPDATE record, then for each non-PRIMARY KEY
613 column in the old.* record for which a value has been provided, a
614 value must also be provided for the same column in the new.* record.
615 Similarly, for each non-PK column in the old.* record for which
616 a value is not provided, a value must not be provided for the same
617 column in the new.* record.</p>
618
619 <p> * All values specified for PRIMARY KEY columns must be non-NULL.</p>
620
621 <p>Otherwise, it is an error. </p>
622
623 <p>If the changegroup already contains a change for the same row (identified
624 by PRIMARY KEY columns), then the current change is combined with the
625 existing change in the same way as for sqlite3changegroup_add().</p>
626
627 <p>For a patchset, all of the above rules apply except that it doesn't matter
628 whether or not values are provided for the non-PK old.* record columns
629 for an UPDATE or DELETE change. This means that code used to produce
630 a changeset using the sqlite3changegroup_change_xxx() APIs may also
631 be used to produce patchsets.</p>
632
633 <p>If the call is successful, SQLITE_OK is returned. Otherwise, if an error
634 occurs, an SQLite error code is returned. If an error is returned and
635 parameter pzErr is not NULL, then (*pzErr) may be set to point to a buffer
636 containing a nul-terminated, utf-8 encoded, English language error message.
637 It is the responsibility of the caller to eventually free any such error
638 message buffer using sqlite3_free().
639 </p><hr><a name="sqlite3changegroup_change_int64"></a>
640 <h2>Add a 64-bit integer to a changegroup</h2><blockquote><pre>int sqlite3changegroup_change_int64(
641 sqlite3_changegroup*,
642 int bNew,
643 int iCol,
644 sqlite3_int64 iVal
645 );
646 </pre></blockquote><p>
647 This function may only be called between a successful call to
648 sqlite3changegroup_change_begin() and its matching
649 sqlite3changegroup_change_finish() call. If it is called at any
650 other time, it is an SQLITE_MISUSE error. Calling this function
651 specifies a 64-bit integer value to be used in the change currently being
652 added to the changegroup object passed as the first argument.</p>
653
654 <p>The second parameter, bNew, specifies whether the value is to be part of
655 the new.* (if bNew is non-zero) or old.* (if bNew is zero) record of
656 the change under construction. If this does not match the type of change
657 specified by the preceding call to sqlite3changegroup_change_begin() (i.e.
658 an old.* value for an SQLITE_INSERT change, or a new.* value for an
659 SQLITE_DELETE), then SQLITE_ERROR is returned.</p>
660
661 <p>The third parameter specifies the column of the old.* or new.* record that
662 the value will be a part of. If the specified table has an explicit primary
663 key, then this is the index of the table column, numbered from 0 in the order
664 specified within the CREATE TABLE statement. Or, if the table uses an
665 implicit rowid key, then the column 0 is the rowid and the explicit columns
666 are numbered starting from 1. If the iCol parameter is less than 0 or greater
667 than the index of the last column in the table, SQLITE_RANGE is returned.</p>
668
669 <p>The fourth parameter is the integer value to use as part of the old.* or
670 new.* record.</p>
671
672 <p>If this call is successful, SQLITE_OK is returned. Otherwise, if an
673 error occurs, an SQLite error code is returned.
674 </p><hr><a name="sqlite3changegroup_change_null"></a>
675 <h2>Add a NULL to a changegroup</h2><blockquote><pre>int sqlite3changegroup_change_null(sqlite3_changegroup*, int, int);
676 </pre></blockquote><p>
677 This function is similar to sqlite3changegroup_change_int64(). Except that
678 it configures the change currently under construction with a NULL value
679 instead of a 64-bit integer.
680 </p><hr><a name="sqlite3changegroup_change_text"></a>
681 <h2>Add a text value to a changegroup</h2><blockquote><pre>int sqlite3changegroup_change_text(
682 sqlite3_changegroup*, int, int, const char *pVal, int nVal
683 );
684 </pre></blockquote><p>
685 This function is similar to sqlite3changegroup_change_int64(). It configures
686 the currently accumulated change with a text value instead of a 64-bit
687 integer. Parameter pVal points to a buffer containing the text encoded using
688 utf-8. Parameter nVal may either be the size of the text value in bytes, or
689 else a negative value, in which case the buffer pVal points to is assumed to
690 be nul-terminated.
691 </p><hr><a name="sqlite3changegroup_config"></a>
692 <h2>Configure a changegroup object</h2><blockquote><pre>int sqlite3changegroup_config(sqlite3_changegroup*, int, void *pArg);
693 </pre></blockquote><p>
694 Configure the changegroup object passed as the first argument.
695 At present the only valid value for the second parameter is
696 <a href="#SQLITE_CHANGEGROUP_CONFIG_PATCHSET">SQLITE_CHANGEGROUP_CONFIG_PATCHSET</a>.
697 </p><hr><a name="sqlite3changegroup_delete"></a>
698 <h2>Delete A Changegroup Object</h2><blockquote><pre>void sqlite3changegroup_delete(sqlite3_changegroup*);
699 </pre></blockquote><p></p><hr><a name="sqlite3changegroup_new"></a>
700 <h2>Create A New Changegroup Object</h2><blockquote><pre>int sqlite3changegroup_new(sqlite3_changegroup **pp);
701 </pre></blockquote><p>
702 An sqlite3_changegroup object is used to combine two or more changesets
703 (or patchsets) into a single changeset (or patchset). A single changegroup
704 object may combine changesets or patchsets, but not both. The output is
705 always in the same format as the input.</p>
706
707 <p>If successful, this function returns SQLITE_OK and populates (*pp) with
708 a pointer to a new sqlite3_changegroup object before returning. The caller
709 should eventually free the returned object using a call to
710 sqlite3changegroup_delete(). If an error occurs, an SQLite error code
711 (i.e. SQLITE_NOMEM) is returned and *pp is set to NULL.</p>
712
713 <p>The usual usage pattern for an sqlite3_changegroup object is as follows:</p>
714
715 <p><ul>
716 <li> It is created using a call to sqlite3changegroup_new().</p>
717
718 <p> <li> Zero or more changesets (or patchsets) are added to the object
719 by calling sqlite3changegroup_add().</p>
720
721 <p> <li> The result of combining all input changesets together is obtained
722 by the application via a call to sqlite3changegroup_output().</p>
723
724 <p> <li> The object is deleted using a call to sqlite3changegroup_delete().
725 </ul></p>
726
727 <p>Any number of calls to add() and output() may be made between the calls to
728 new() and delete(), and in any order.</p>
729
730 <p>As well as the regular sqlite3changegroup_add() and
731 sqlite3changegroup_output() functions, also available are the streaming
732 versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm().
733 </p><hr><a name="sqlite3changegroup_output"></a>
734 <h2>Obtain A Composite Changeset From A Changegroup</h2><blockquote><pre>int sqlite3changegroup_output(
735 sqlite3_changegroup*,
736 int *pnData, /* OUT: Size of output buffer in bytes */
737 void **ppData /* OUT: Pointer to output buffer */
738 );
739 </pre></blockquote><p>
740 Obtain a buffer containing a changeset (or patchset) representing the
741 current contents of the changegroup. If the inputs to the changegroup
742 were themselves changesets, the output is a changeset. Or, if the
743 inputs were patchsets, the output is also a patchset.</p>
744
745 <p>As with the output of the sqlite3session_changeset() and
746 sqlite3session_patchset() functions, all changes related to a single
747 table are grouped together in the output of this function. Tables appear
748 in the same order as for the very first changeset added to the changegroup.
749 If the second or subsequent changesets added to the changegroup contain
750 changes for tables that do not appear in the first changeset, they are
751 appended onto the end of the output changeset, again in the order in
752 which they are first encountered.</p>
753
754 <p>If an error occurs, an SQLite error code is returned and the output
755 variables (*pnData) and (*ppData) are set to 0. Otherwise, SQLITE_OK
756 is returned and the output variables are set to the size of and a
757 pointer to the output buffer, respectively. In this case it is the
758 responsibility of the caller to eventually free the buffer using a
759 call to sqlite3_free().
760 </p><hr><a name="sqlite3changegroup_schema"></a>
761 <h2>Add a Schema to a Changegroup</h2><blockquote><pre>int sqlite3changegroup_schema(sqlite3_changegroup*, sqlite3*, const char *zDb);
762 </pre></blockquote><p>
763 This method may be used to optionally enforce the rule that the changesets
764 added to the changegroup handle must match the schema of database zDb
765 ("main", "temp", or the name of an attached database). If
766 sqlite3changegroup_add() is called to add a changeset that is not compatible
767 with the configured schema, SQLITE_SCHEMA is returned and the changegroup
768 object is left in an undefined state.</p>
769
770 <p>A changeset schema is considered compatible with the database schema in
771 the same way as for sqlite3changeset_apply(). Specifically, for each
772 table in the changeset, there exists a database table with:</p>
773
774 <p><ul>
775 <li> The name identified by the changeset, and
776 <li> at least as many columns as recorded in the changeset, and
777 <li> the primary key columns in the same position as recorded in
778 the changeset.
779 </ul></p>
780
781 <p>The output of the changegroup object always has the same schema as the
782 database nominated using this function. In cases where changesets passed
783 to sqlite3changegroup_add() have fewer columns than the corresponding table
784 in the database schema, these are filled in using the default column
785 values from the database schema. This makes it possible to combined
786 changesets that have different numbers of columns for a single table
787 within a changegroup, provided that they are otherwise compatible.
788 </p><hr><a name="sqlite3changeset_concat"></a>
789 <h2>Concatenate Two Changeset Objects</h2><blockquote><pre>int sqlite3changeset_concat(
790 int nA, /* Number of bytes in buffer pA */
791 void *pA, /* Pointer to buffer containing changeset A */
792 int nB, /* Number of bytes in buffer pB */
793 void *pB, /* Pointer to buffer containing changeset B */
794 int *pnOut, /* OUT: Number of bytes in output changeset */
795 void **ppOut /* OUT: Buffer containing output changeset */
796 );
797 </pre></blockquote><p>
798 This function is used to concatenate two changesets, A and B, into a
799 single changeset. The result is a changeset equivalent to applying
800 changeset A followed by changeset B. </p>
801
802 <p>This function combines the two input changesets using an
803 sqlite3_changegroup object. Calling it produces similar results as the
804 following code fragment:</p>
805
806 <p><pre>
807 sqlite3_changegroup *pGrp;
808 rc = sqlite3_changegroup_new(&pGrp);
809 if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nA, pA);
810 if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nB, pB);
811 if( rc==SQLITE_OK ){
812 rc = sqlite3changegroup_output(pGrp, pnOut, ppOut);
813 }else{
814 *ppOut = 0;
815 *pnOut = 0;
816 }
817 </pre></p>
818
819 <p>Refer to the sqlite3_changegroup documentation below for details.
820 </p><hr><a name="sqlite3changeset_conflict"></a>
821 <h2>Obtain Conflicting Row Values From A Changeset Iterator</h2><blockquote><pre>int sqlite3changeset_conflict(
822 sqlite3_changeset_iter *pIter, /* Changeset iterator */
823 int iVal, /* Column number */
824 sqlite3_value **ppValue /* OUT: Value from conflicting row */
825 );
826 </pre></blockquote><p>
827 This function should only be used with iterator objects passed to a
828 conflict-handler callback by <a href="#sqlite3changeset_apply">sqlite3changeset_apply()</a> with either
829 <a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_DATA</a> or <a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_CONFLICT</a>. If this function
830 is called on any other iterator, <a href="rescode.html#misuse">SQLITE_MISUSE</a> is returned and *ppValue
831 is set to NULL.</p>
832
833 <p>Argument iVal must be greater than or equal to 0, and less than the number
834 of columns in the table affected by the current change. Otherwise,
835 <a href="rescode.html#range">SQLITE_RANGE</a> is returned and *ppValue is set to NULL.</p>
836
837 <p>If successful, this function sets *ppValue to point to a protected
838 sqlite3_value object containing the iVal'th value from the
839 "conflicting row" associated with the current conflict-handler callback
840 and returns SQLITE_OK.</p>
841
842 <p>If some other error occurs (e.g. an OOM condition), an SQLite error code
843 is returned and *ppValue is set to NULL.
844 </p><hr><a name="sqlite3changeset_finalize"></a>
845 <h2>Finalize A Changeset Iterator</h2><blockquote><pre>int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);
846 </pre></blockquote><p>
847 This function is used to finalize an iterator allocated with
848 <a href="#sqlite3changeset_start">sqlite3changeset_start()</a>.</p>
849
850 <p>This function should only be called on iterators created using the
851 <a href="#sqlite3changeset_start">sqlite3changeset_start()</a> function. If an application calls this
852 function with an iterator passed to a conflict-handler by
853 <a href="#sqlite3changeset_apply">sqlite3changeset_apply()</a>, <a href="rescode.html#misuse">SQLITE_MISUSE</a> is immediately returned and the
854 call has no effect.</p>
855
856 <p>If an error was encountered within a call to an sqlite3changeset_xxx()
857 function (for example an <a href="rescode.html#corrupt">SQLITE_CORRUPT</a> in <a href="#sqlite3changeset_next">sqlite3changeset_next()</a> or an
858 <a href="rescode.html#nomem">SQLITE_NOMEM</a> in <a href="#sqlite3changeset_new">sqlite3changeset_new()</a>) then an error code corresponding
859 to that error is returned by this function. Otherwise, SQLITE_OK is
860 returned. This is to allow the following pattern (pseudo-code):</p>
861
862 <p><pre>
863 sqlite3changeset_start();
864 while( SQLITE_ROW==sqlite3changeset_next() ){
865 // Do something with change.
866 }
867 rc = sqlite3changeset_finalize();
868 if( rc!=SQLITE_OK ){
869 // An error has occurred
870 }
871 </pre>
872 </p><hr><a name="sqlite3changeset_fk_conflicts"></a>
873 <h2>Determine The Number Of Foreign Key Constraint Violations</h2><blockquote><pre>int sqlite3changeset_fk_conflicts(
874 sqlite3_changeset_iter *pIter, /* Changeset iterator */
875 int *pnOut /* OUT: Number of FK violations */
876 );
877 </pre></blockquote><p>
878 This function may only be called with an iterator passed to an
879 SQLITE_CHANGESET_FOREIGN_KEY conflict handler callback. In this case
880 it sets the output variable to the total number of known foreign key
881 violations in the destination database and returns SQLITE_OK.</p>
882
883 <p>In all other cases this function returns SQLITE_MISUSE.
884 </p><hr><a name="sqlite3changeset_invert"></a>
885 <h2>Invert A Changeset</h2><blockquote><pre>int sqlite3changeset_invert(
886 int nIn, const void *pIn, /* Input changeset */
887 int *pnOut, void **ppOut /* OUT: Inverse of input */
888 );
889 </pre></blockquote><p>
890 This function is used to "invert" a changeset object. Applying an inverted
891 changeset to a database reverses the effects of applying the uninverted
892 changeset. Specifically:</p>
893
894 <p><ul>
895 <li> Each DELETE change is changed to an INSERT, and
896 <li> Each INSERT change is changed to a DELETE, and
897 <li> For each UPDATE change, the old.* and new.* values are exchanged.
898 </ul></p>
899
900 <p>This function does not change the order in which changes appear within
901 the changeset. It merely reverses the sense of each individual change.</p>
902
903 <p>If successful, a pointer to a buffer containing the inverted changeset
904 is stored in *ppOut, the size of the same buffer is stored in *pnOut, and
905 SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are
906 zeroed and an SQLite error code returned.</p>
907
908 <p>It is the responsibility of the caller to eventually call sqlite3_free()
909 on the *ppOut pointer to free the buffer allocation following a successful
910 call to this function.</p>
911
912 <p>WARNING/TODO: This function currently assumes that the input is a valid
913 changeset. If it is not, the results are undefined.
914 </p><hr><a name="sqlite3changeset_new"></a>
915 <h2>Obtain new.* Values From A Changeset Iterator</h2><blockquote><pre>int sqlite3changeset_new(
916 sqlite3_changeset_iter *pIter, /* Changeset iterator */
917 int iVal, /* Column number */
918 sqlite3_value **ppValue /* OUT: New value (or NULL pointer) */
919 );
920 </pre></blockquote><p>
921 The pIter argument passed to this function may either be an iterator
922 passed to a conflict-handler by <a href="#sqlite3changeset_apply">sqlite3changeset_apply()</a>, or an iterator
923 created by <a href="#sqlite3changeset_start">sqlite3changeset_start()</a>. In the latter case, the most recent
924 call to <a href="#sqlite3changeset_next">sqlite3changeset_next()</a> must have returned SQLITE_ROW.
925 Furthermore, it may only be called if the type of change that the iterator
926 currently points to is either <a href="c3ref/c_alter_table.html">SQLITE_UPDATE</a> or <a href="c3ref/c_alter_table.html">SQLITE_INSERT</a>. Otherwise,
927 this function returns <a href="rescode.html#misuse">SQLITE_MISUSE</a> and sets *ppValue to NULL.</p>
928
929 <p>Argument iVal must be greater than or equal to 0, and less than the number
930 of columns in the table affected by the current change. Otherwise,
931 <a href="rescode.html#range">SQLITE_RANGE</a> is returned and *ppValue is set to NULL.</p>
932
933 <p>If successful, this function sets *ppValue to point to a protected
934 sqlite3_value object containing the iVal'th value from the vector of
935 new row values stored as part of the UPDATE or INSERT change and
936 returns SQLITE_OK. If the change is an UPDATE and does not include
937 a new value for the requested column, *ppValue is set to NULL and
938 SQLITE_OK returned. The name of the function comes from the fact that
939 this is similar to the "new.*" columns available to update or delete
940 triggers.</p>
941
942 <p>If some other error occurs (e.g. an OOM condition), an SQLite error code
943 is returned and *ppValue is set to NULL.
944 </p><hr><a name="sqlite3changeset_next"></a>
945 <h2>Advance A Changeset Iterator</h2><blockquote><pre>int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
946 </pre></blockquote><p>
947 This function may only be used with iterators created by the function
948 <a href="#sqlite3changeset_start">sqlite3changeset_start()</a>. If it is called on an iterator passed to
949 a conflict-handler callback by <a href="#sqlite3changeset_apply">sqlite3changeset_apply()</a>, SQLITE_MISUSE
950 is returned and the call has no effect.</p>
951
952 <p>Immediately after an iterator is created by sqlite3changeset_start(), it
953 does not point to any change in the changeset. Assuming the changeset
954 is not empty, the first call to this function advances the iterator to
955 point to the first change in the changeset. Each subsequent call advances
956 the iterator to point to the next change in the changeset (if any). If
957 no error occurs and the iterator points to a valid change after a call
958 to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned.
959 Otherwise, if all changes in the changeset have already been visited,
960 SQLITE_DONE is returned.</p>
961
962 <p>If an error occurs, an SQLite error code is returned. Possible error
963 codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or
964 SQLITE_NOMEM.
965 </p><hr><a name="sqlite3changeset_old"></a>
966 <h2>Obtain old.* Values From A Changeset Iterator</h2><blockquote><pre>int sqlite3changeset_old(
967 sqlite3_changeset_iter *pIter, /* Changeset iterator */
968 int iVal, /* Column number */
969 sqlite3_value **ppValue /* OUT: Old value (or NULL pointer) */
970 );
971 </pre></blockquote><p>
972 The pIter argument passed to this function may either be an iterator
973 passed to a conflict-handler by <a href="#sqlite3changeset_apply">sqlite3changeset_apply()</a>, or an iterator
974 created by <a href="#sqlite3changeset_start">sqlite3changeset_start()</a>. In the latter case, the most recent
975 call to <a href="#sqlite3changeset_next">sqlite3changeset_next()</a> must have returned SQLITE_ROW.
976 Furthermore, it may only be called if the type of change that the iterator
977 currently points to is either <a href="c3ref/c_alter_table.html">SQLITE_DELETE</a> or <a href="c3ref/c_alter_table.html">SQLITE_UPDATE</a>. Otherwise,
978 this function returns <a href="rescode.html#misuse">SQLITE_MISUSE</a> and sets *ppValue to NULL.</p>
979
980 <p>Argument iVal must be greater than or equal to 0, and less than the number
981 of columns in the table affected by the current change. Otherwise,
982 <a href="rescode.html#range">SQLITE_RANGE</a> is returned and *ppValue is set to NULL.</p>
983
984 <p>If successful, this function sets *ppValue to point to a protected
985 sqlite3_value object containing the iVal'th value from the vector of
986 original row values stored as part of the UPDATE or DELETE change and
987 returns SQLITE_OK. The name of the function comes from the fact that this
988 is similar to the "old.*" columns available to update or delete triggers.</p>
989
990 <p>If some other error occurs (e.g. an OOM condition), an SQLite error code
991 is returned and *ppValue is set to NULL.
992 </p><hr><a name="sqlite3changeset_op"></a>
993 <h2>Obtain The Current Operation From A Changeset Iterator</h2><blockquote><pre>int sqlite3changeset_op(
994 sqlite3_changeset_iter *pIter, /* Iterator object */
995 const char **pzTab, /* OUT: Pointer to table name */
996 int *pnCol, /* OUT: Number of columns in table */
997 int *pOp, /* OUT: SQLITE_INSERT, DELETE or UPDATE */
998 int *pbIndirect /* OUT: True for an 'indirect' change */
999 );
1000 </pre></blockquote><p>
1001 The pIter argument passed to this function may either be an iterator
1002 passed to a conflict-handler by <a href="#sqlite3changeset_apply">sqlite3changeset_apply()</a>, or an iterator
1003 created by <a href="#sqlite3changeset_start">sqlite3changeset_start()</a>. In the latter case, the most recent
1004 call to <a href="#sqlite3changeset_next">sqlite3changeset_next()</a> must have returned <a href="rescode.html#row">SQLITE_ROW</a>. If this
1005 is not the case, this function returns <a href="rescode.html#misuse">SQLITE_MISUSE</a>.</p>
1006
1007 <p>Arguments pOp, pnCol and pzTab may not be NULL. Upon return, three
1008 outputs are set through these pointers: </p>
1009
1010 <p>*pOp is set to one of <a href="c3ref/c_alter_table.html">SQLITE_INSERT</a>, <a href="c3ref/c_alter_table.html">SQLITE_DELETE</a> or <a href="c3ref/c_alter_table.html">SQLITE_UPDATE</a>,
1011 depending on the type of change that the iterator currently points to;</p>
1012
1013 <p>*pnCol is set to the number of columns in the table affected by the change; and</p>
1014
1015 <p>*pzTab is set to point to a nul-terminated utf-8 encoded string containing
1016 the name of the table affected by the current change. The buffer remains
1017 valid until either sqlite3changeset_next() is called on the iterator
1018 or until the conflict-handler function returns.</p>
1019
1020 <p>If pbIndirect is not NULL, then *pbIndirect is set to true (1) if the change
1021 is an indirect change, or false (0) otherwise. See the documentation for
1022 <a href="#sqlite3session_indirect">sqlite3session_indirect()</a> for a description of direct and indirect
1023 changes.</p>
1024
1025 <p>If no error occurs, SQLITE_OK is returned. If an error does occur, an
1026 SQLite error code is returned. The values of the output variables may not
1027 be trusted in this case.
1028 </p><hr><a name="sqlite3changeset_pk"></a>
1029 <h2>Obtain The Primary Key Definition Of A Table</h2><blockquote><pre>int sqlite3changeset_pk(
1030 sqlite3_changeset_iter *pIter, /* Iterator object */
1031 unsigned char **pabPK, /* OUT: Array of boolean - true for PK cols */
1032 int *pnCol /* OUT: Number of entries in output array */
1033 );
1034 </pre></blockquote><p>
1035 For each modified table, a changeset includes the following:</p>
1036
1037 <p><ul>
1038 <li> The number of columns in the table, and
1039 <li> Which of those columns make up the tables PRIMARY KEY.
1040 </ul></p>
1041
1042 <p>This function is used to find which columns comprise the PRIMARY KEY of
1043 the table modified by the change that iterator pIter currently points to.
1044 If successful, *pabPK is set to point to an array of nCol entries, where
1045 nCol is the number of columns in the table. Elements of *pabPK are set to
1046 0x01 if the corresponding column is part of the tables primary key, or
1047 0x00 if it is not.</p>
1048
1049 <p>If argument pnCol is not NULL, then *pnCol is set to the number of columns
1050 in the table.</p>
1051
1052 <p>If this function is called when the iterator does not point to a valid
1053 entry, SQLITE_MISUSE is returned and the output variables zeroed. Otherwise,
1054 SQLITE_OK is returned and the output variables populated as described
1055 above.
1056 </p><hr><a name="sqlite3rebaser_configure"></a>
1057 <h2>Configure a changeset rebaser object.</h2><blockquote><pre>int sqlite3rebaser_configure(
1058 sqlite3_rebaser*,
1059 int nRebase, const void *pRebase
1060 );
1061 </pre></blockquote><p><b>Important:</b> This interface is <a href="c3ref/experimental.html">experimental</a> and is subject to change without notice.</p><p>
1062 Configure the changeset rebaser object to rebase changesets according
1063 to the conflict resolutions described by buffer pRebase (size nRebase
1064 bytes), which must have been obtained from a previous call to
1065 sqlite3changeset_apply_v2().
1066 </p><hr><a name="sqlite3rebaser_create"></a>
1067 <h2>Create a changeset rebaser object.</h2><blockquote><pre>int sqlite3rebaser_create(sqlite3_rebaser **ppNew);
1068 </pre></blockquote><p><b>Important:</b> This interface is <a href="c3ref/experimental.html">experimental</a> and is subject to change without notice.</p><p>
1069 Allocate a new changeset rebaser object. If successful, set (*ppNew) to
1070 point to the new object and return SQLITE_OK. Otherwise, if an error
1071 occurs, return an SQLite error code (e.g. SQLITE_NOMEM) and set (*ppNew)
1072 to NULL.
1073 </p><hr><a name="sqlite3rebaser_delete"></a>
1074 <h2>Delete a changeset rebaser object.</h2><blockquote><pre>void sqlite3rebaser_delete(sqlite3_rebaser *p);
1075 </pre></blockquote><p><b>Important:</b> This interface is <a href="c3ref/experimental.html">experimental</a> and is subject to change without notice.</p><p>
1076 Delete the changeset rebaser object and all associated resources. There
1077 should be one call to this function for each successful invocation
1078 of sqlite3rebaser_create().
1079 </p><hr><a name="sqlite3rebaser_rebase"></a>
1080 <h2>Rebase a changeset</h2><blockquote><pre>int sqlite3rebaser_rebase(
1081 sqlite3_rebaser*,
1082 int nIn, const void *pIn,
1083 int *pnOut, void **ppOut
1084 );
1085 </pre></blockquote><p><b>Important:</b> This interface is <a href="c3ref/experimental.html">experimental</a> and is subject to change without notice.</p><p>
1086 Argument pIn must point to a buffer containing a changeset nIn bytes
1087 in size. This function allocates and populates a buffer with a copy
1088 of the changeset rebased according to the configuration of the
1089 rebaser object passed as the first argument. If successful, (*ppOut)
1090 is set to point to the new buffer containing the rebased changeset and
1091 (*pnOut) to its size in bytes and SQLITE_OK returned. It is the
1092 responsibility of the caller to eventually free the new buffer using
1093 sqlite3_free(). Otherwise, if an error occurs, (*ppOut) and (*pnOut)
1094 are set to zero and an SQLite error code returned.
1095 </p><hr><a name="sqlite3session_attach"></a>
1096 <h2>Attach A Table To A Session Object</h2><blockquote><pre>int sqlite3session_attach(
1097 sqlite3_session *pSession, /* Session object */
1098 const char *zTab /* Table name */
1099 );
1100 </pre></blockquote><p>
1101 If argument zTab is not NULL, then it is the name of a table to attach
1102 to the session object passed as the first argument. All subsequent changes
1103 made to the table while the session object is enabled will be recorded. See
1104 documentation for <a href="#sqlite3session_changeset">sqlite3session_changeset()</a> for further details.</p>
1105
1106 <p>Or, if argument zTab is NULL, then changes are recorded for all tables
1107 in the database. If additional tables are added to the database (by
1108 executing "CREATE TABLE" statements) after this call is made, changes for
1109 the new tables are also recorded.</p>
1110
1111 <p>Changes can only be recorded for tables that have a PRIMARY KEY explicitly
1112 defined as part of their CREATE TABLE statement. It does not matter if the
1113 PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY
1114 KEY may consist of a single column, or may be a composite key.</p>
1115
1116 <p>It is not an error if the named table does not exist in the database. Nor
1117 is it an error if the named table does not have a PRIMARY KEY. However,
1118 no changes will be recorded in either of these scenarios.</p>
1119
1120 <p>Changes are not recorded for individual rows that have NULL values stored
1121 in one or more of their PRIMARY KEY columns.</p>
1122
1123 <p>SQLITE_OK is returned if the call completes without error. Or, if an error
1124 occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.</p>
1125
1126 <p><h3>Special sqlite_stat1 Handling</h3></p>
1127
1128 <p>As of SQLite version 3.22.0, the "sqlite_stat1" table is an exception to
1129 some of the rules above. In SQLite, the schema of sqlite_stat1 is:
1130 <pre>
1131 &nbsp; CREATE TABLE sqlite_stat1(tbl,idx,stat)
1132 </pre></p>
1133
1134 <p>Even though sqlite_stat1 does not have a PRIMARY KEY, changes are
1135 recorded for it as if the PRIMARY KEY is (tbl,idx). Additionally, changes
1136 are recorded for rows for which (idx IS NULL) is true. However, for such
1137 rows a zero-length blob (SQL value X'') is stored in the changeset or
1138 patchset instead of a NULL value. This allows such changesets to be
1139 manipulated by legacy implementations of sqlite3changeset_invert(),
1140 concat() and similar.</p>
1141
1142 <p>The sqlite3changeset_apply() function automatically converts the
1143 zero-length blob back to a NULL value when updating the sqlite_stat1
1144 table. However, if the application calls sqlite3changeset_new(),
1145 sqlite3changeset_old() or sqlite3changeset_conflict on a changeset
1146 iterator directly (including on a changeset iterator passed to a
1147 conflict-handler callback) then the X'' value is returned. The application
1148 must translate X'' to NULL itself if required.</p>
1149
1150 <p>Legacy (older than 3.22.0) versions of the sessions module cannot capture
1151 changes made to the sqlite_stat1 table. Legacy versions of the
1152 sqlite3changeset_apply() function silently ignore any modifications to the
1153 sqlite_stat1 table that are part of a changeset or patchset.
1154 </p><hr><a name="sqlite3session_changeset"></a>
1155 <h2>Generate A Changeset From A Session Object</h2><blockquote><pre>int sqlite3session_changeset(
1156 sqlite3_session *pSession, /* Session object */
1157 int *pnChangeset, /* OUT: Size of buffer at *ppChangeset */
1158 void **ppChangeset /* OUT: Buffer containing changeset */
1159 );
1160 </pre></blockquote><p>
1161 Obtain a changeset containing changes to the tables attached to the
1162 session object passed as the first argument. If successful,
1163 set *ppChangeset to point to a buffer containing the changeset
1164 and *pnChangeset to the size of the changeset in bytes before returning
1165 SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to
1166 zero and return an SQLite error code.</p>
1167
1168 <p>A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes,
1169 each representing a change to a single row of an attached table. An INSERT
1170 change contains the values of each field of a new database row. A DELETE
1171 contains the original values of each field of a deleted database row. An
1172 UPDATE change contains the original values of each field of an updated
1173 database row along with the updated values for each updated non-primary-key
1174 column. It is not possible for an UPDATE change to represent a change that
1175 modifies the values of primary key columns. If such a change is made, it
1176 is represented in a changeset as a DELETE followed by an INSERT.</p>
1177
1178 <p>Changes are not recorded for rows that have NULL values stored in one or
1179 more of their PRIMARY KEY columns. If such a row is inserted or deleted,
1180 no corresponding change is present in the changesets returned by this
1181 function. If an existing row with one or more NULL values stored in
1182 PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL,
1183 only an INSERT is appears in the changeset. Similarly, if an existing row
1184 with non-NULL PRIMARY KEY values is updated so that one or more of its
1185 PRIMARY KEY columns are set to NULL, the resulting changeset contains a
1186 DELETE change only.</p>
1187
1188 <p>The contents of a changeset may be traversed using an iterator created
1189 using the <a href="#sqlite3changeset_start">sqlite3changeset_start()</a> API. A changeset may be applied to
1190 a database with a compatible schema using the <a href="#sqlite3changeset_apply">sqlite3changeset_apply()</a>
1191 API.</p>
1192
1193 <p>Within a changeset generated by this function, all changes related to a
1194 single table are grouped together. In other words, when iterating through
1195 a changeset or when applying a changeset to a database, all changes related
1196 to a single table are processed before moving on to the next table. Tables
1197 are sorted in the same order in which they were attached (or auto-attached)
1198 to the sqlite3_session object. The order in which the changes related to
1199 a single table are stored is undefined.</p>
1200
1201 <p>Following a successful call to this function, it is the responsibility of
1202 the caller to eventually free the buffer that *ppChangeset points to using
1203 <a href="c3ref/free.html">sqlite3_free()</a>.</p>
1204
1205 <p><h3>Changeset Generation</h3></p>
1206
1207 <p>Once a table has been attached to a session object, the session object
1208 records the primary key values of all new rows inserted into the table.
1209 It also records the original primary key and other column values of any
1210 deleted or updated rows. For each unique primary key value, data is only
1211 recorded once - the first time a row with said primary key is inserted,
1212 updated or deleted in the lifetime of the session.</p>
1213
1214 <p>There is one exception to the previous paragraph: when a row is inserted,
1215 updated or deleted, if one or more of its primary key columns contain a
1216 NULL value, no record of the change is made.</p>
1217
1218 <p>The session object therefore accumulates two types of records - those
1219 that consist of primary key values only (created when the user inserts
1220 a new record) and those that consist of the primary key values and the
1221 original values of other table columns (created when the users deletes
1222 or updates a record).</p>
1223
1224 <p>When this function is called, the requested changeset is created using
1225 both the accumulated records and the current contents of the database
1226 file. Specifically:</p>
1227
1228 <p><ul>
1229 <li> For each record generated by an insert, the database is queried
1230 for a row with a matching primary key. If one is found, an INSERT
1231 change is added to the changeset. If no such row is found, no change
1232 is added to the changeset.</p>
1233
1234 <p> <li> For each record generated by an update or delete, the database is
1235 queried for a row with a matching primary key. If such a row is
1236 found and one or more of the non-primary key fields have been
1237 modified from their original values, an UPDATE change is added to
1238 the changeset. Or, if no such row is found in the table, a DELETE
1239 change is added to the changeset. If there is a row with a matching
1240 primary key in the database, but all fields contain their original
1241 values, no change is added to the changeset.
1242 </ul></p>
1243
1244 <p>This means, amongst other things, that if a row is inserted and then later
1245 deleted while a session object is active, neither the insert nor the delete
1246 will be present in the changeset. Or if a row is deleted and then later a
1247 row with the same primary key values inserted while a session object is
1248 active, the resulting changeset will contain an UPDATE change instead of
1249 a DELETE and an INSERT.</p>
1250
1251 <p>When a session object is disabled (see the <a href="#sqlite3session_enable">sqlite3session_enable()</a> API),
1252 it does not accumulate records when rows are inserted, updated or deleted.
1253 This may appear to have some counter-intuitive effects if a single row
1254 is written to more than once during a session. For example, if a row
1255 is inserted while a session object is enabled, then later deleted while
1256 the same session object is disabled, no INSERT record will appear in the
1257 changeset, even though the delete took place while the session was disabled.
1258 Or, if one field of a row is updated while a session is enabled, and
1259 then another field of the same row is updated while the session is disabled,
1260 the resulting changeset will contain an UPDATE change that updates both
1261 fields.
1262 </p><hr><a name="sqlite3session_changeset_size"></a>
1263 <h2>Return An Upper-limit For The Size Of The Changeset</h2><blockquote><pre>sqlite3_int64 sqlite3session_changeset_size(sqlite3_session *pSession);
1264 </pre></blockquote><p>
1265 By default, this function always returns 0. For it to return
1266 a useful result, the sqlite3_session object must have been configured
1267 to enable this API using sqlite3session_object_config() with the
1268 SQLITE_SESSION_OBJCONFIG_SIZE verb.</p>
1269
1270 <p>When enabled, this function returns an upper limit, in bytes, for the size
1271 of the changeset that might be produced if sqlite3session_changeset() were
1272 called. The final changeset size might be equal to or smaller than the
1273 size in bytes returned by this function.
1274 </p><hr><a name="sqlite3session_config"></a>
1275 <h2>Configure global parameters</h2><blockquote><pre>int sqlite3session_config(int op, void *pArg);
1276 </pre></blockquote><p>
1277 The sqlite3session_config() interface is used to make global configuration
1278 changes to the sessions module in order to tune it to the specific needs
1279 of the application.</p>
1280
1281 <p>The sqlite3session_config() interface is not threadsafe. If it is invoked
1282 while any other thread is inside any other sessions method then the
1283 results are undefined. Furthermore, if it is invoked after any sessions
1284 related objects have been created, the results are also undefined. </p>
1285
1286 <p>The first argument to the sqlite3session_config() function must be one
1287 of the SQLITE_SESSION_CONFIG_XXX constants defined below. The
1288 interpretation of the (void*) value passed as the second parameter and
1289 the effect of calling this function depends on the value of the first
1290 parameter.</p>
1291
1292 <p><dl>
1293 <dt>SQLITE_SESSION_CONFIG_STRMSIZE<dd>
1294 By default, the sessions module streaming interfaces attempt to input
1295 and output data in approximately 1 KiB chunks. This operand may be used
1296 to set and query the value of this configuration setting. The pointer
1297 passed as the second argument must point to a value of type (int).
1298 If this value is greater than 0, it is used as the new streaming data
1299 chunk size for both input and output. Before returning, the (int) value
1300 pointed to by pArg is set to the final value of the streaming interface
1301 chunk size.
1302 </dl></p>
1303
1304 <p>This function returns SQLITE_OK if successful, or an SQLite error code
1305 otherwise.
1306 </p><hr><a name="sqlite3session_create"></a>
1307 <h2>Create A New Session Object</h2><blockquote><pre>int sqlite3session_create(
1308 sqlite3 *db, /* Database handle */
1309 const char *zDb, /* Name of db (e.g. "main") */
1310 sqlite3_session **ppSession /* OUT: New session object */
1311 );
1312 </pre></blockquote><p>
1313 Create a new session object attached to database handle db. If successful,
1314 a pointer to the new object is written to *ppSession and SQLITE_OK is
1315 returned. If an error occurs, *ppSession is set to NULL and an SQLite
1316 error code (e.g. SQLITE_NOMEM) is returned.</p>
1317
1318 <p>It is possible to create multiple session objects attached to a single
1319 database handle.</p>
1320
1321 <p>Session objects created using this function should be deleted using the
1322 <a href="#sqlite3session_delete">sqlite3session_delete()</a> function before the database handle that they
1323 are attached to is itself closed. If the database handle is closed before
1324 the session object is deleted, then the results of calling any session
1325 module function, including <a href="#sqlite3session_delete">sqlite3session_delete()</a> on the session object
1326 are undefined.</p>
1327
1328 <p>Because the session module uses the <a href="c3ref/preupdate_blobwrite.html">sqlite3_preupdate_hook()</a> API, it
1329 is not possible for an application to register a pre-update hook on a
1330 database handle that has one or more session objects attached. Nor is
1331 it possible to create a session object attached to a database handle for
1332 which a pre-update hook is already defined. The results of attempting
1333 either of these things are undefined.</p>
1334
1335 <p>The session object will be used to create changesets for tables in
1336 database zDb, where zDb is either "main", or "temp", or the name of an
1337 attached database. It is not an error if database zDb is not attached
1338 to the database when the session object is created.
1339 </p><hr><a name="sqlite3session_delete"></a>
1340 <h2>Delete A Session Object</h2><blockquote><pre>void sqlite3session_delete(sqlite3_session *pSession);
1341 </pre></blockquote><p>
1342 Delete a session object previously allocated using
1343 <a href="#sqlite3session_create">sqlite3session_create()</a>. Once a session object has been deleted, the
1344 results of attempting to use pSession with any other session module
1345 function are undefined.</p>
1346
1347 <p>Session objects must be deleted before the database handle to which they
1348 are attached is closed. Refer to the documentation for
1349 <a href="#sqlite3session_create">sqlite3session_create()</a> for details.
1350 </p><hr><a name="sqlite3session_diff"></a>
1351 <h2>Load The Difference Between Tables Into A Session</h2><blockquote><pre>int sqlite3session_diff(
1352 sqlite3_session *pSession,
1353 const char *zFromDb,
1354 const char *zTbl,
1355 char **pzErrMsg
1356 );
1357 </pre></blockquote><p>
1358 If it is not already attached to the session object passed as the first
1359 argument, this function attaches table zTbl in the same manner as the
1360 <a href="#sqlite3session_attach">sqlite3session_attach()</a> function. If zTbl does not exist, or if it
1361 does not have a primary key, this function is a no-op (but does not return
1362 an error).</p>
1363
1364 <p>Argument zFromDb must be the name of a database ("main", "temp" etc.)
1365 attached to the same database handle as the session object that contains
1366 a table compatible with the table attached to the session by this function.
1367 A table is considered compatible if it:</p>
1368
1369 <p><ul>
1370 <li> Has the same name,
1371 <li> Has the same set of columns declared in the same order, and
1372 <li> Has the same PRIMARY KEY definition.
1373 </ul></p>
1374
1375 <p>If the tables are not compatible, SQLITE_SCHEMA is returned. If the tables
1376 are compatible but do not have any PRIMARY KEY columns, it is not an error
1377 but no changes are added to the session object. As with other session
1378 APIs, tables without PRIMARY KEYs are simply ignored.</p>
1379
1380 <p>This function adds a set of changes to the session object that could be
1381 used to update the table in database zFrom (call this the "from-table")
1382 so that its content is the same as the table attached to the session
1383 object (call this the "to-table"). Specifically:</p>
1384
1385 <p><ul>
1386 <li> For each row (primary key) that exists in the to-table but not in
1387 the from-table, an INSERT record is added to the session object.</p>
1388
1389 <p> <li> For each row (primary key) that exists in the to-table but not in
1390 the from-table, a DELETE record is added to the session object.</p>
1391
1392 <p> <li> For each row (primary key) that exists in both tables, but features
1393 different non-PK values in each, an UPDATE record is added to the
1394 session.
1395 </ul></p>
1396
1397 <p>To clarify, if this function is called and then a changeset constructed
1398 using <a href="#sqlite3session_changeset">sqlite3session_changeset()</a>, then after applying that changeset to
1399 database zFrom the contents of the two compatible tables would be
1400 identical.</p>
1401
1402 <p>Unless the call to this function is a no-op as described above, it is an
1403 error if database zFrom does not exist or does not contain the required
1404 compatible table.</p>
1405
1406 <p>If the operation is successful, SQLITE_OK is returned. Otherwise, an SQLite
1407 error code. In this case, if argument pzErrMsg is not NULL, *pzErrMsg
1408 may be set to point to a buffer containing an English language error
1409 message. It is the responsibility of the caller to free this buffer using
1410 sqlite3_free().
1411 </p><hr><a name="sqlite3session_enable"></a>
1412 <h2>Enable Or Disable A Session Object</h2><blockquote><pre>int sqlite3session_enable(sqlite3_session *pSession, int bEnable);
1413 </pre></blockquote><p>
1414 Enable or disable the recording of changes by a session object. When
1415 enabled, a session object records changes made to the database. When
1416 disabled - it does not. A newly created session object is enabled.
1417 Refer to the documentation for <a href="#sqlite3session_changeset">sqlite3session_changeset()</a> for further
1418 details regarding how enabling and disabling a session object affects
1419 the eventual changesets.</p>
1420
1421 <p>Passing zero to this function disables the session. Passing a value
1422 greater than zero enables it. Passing a value less than zero is a
1423 no-op, and may be used to query the current state of the session.</p>
1424
1425 <p>The return value indicates the final state of the session object: 0 if
1426 the session is disabled, or 1 if it is enabled.
1427 </p><hr><a name="sqlite3session_indirect"></a>
1428 <h2>Set Or Clear the Indirect Change Flag</h2><blockquote><pre>int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect);
1429 </pre></blockquote><p>
1430 Each change recorded by a session object is marked as either direct or
1431 indirect. A change is marked as indirect if either:</p>
1432
1433 <p><ul>
1434 <li> The session object "indirect" flag is set when the change is
1435 made, or
1436 <li> The change is made by an SQL trigger or foreign key action
1437 instead of directly as a result of a users SQL statement.
1438 </ul></p>
1439
1440 <p>If a single row is affected by more than one operation within a session,
1441 then the change is considered indirect if all operations meet the criteria
1442 for an indirect change above, or direct otherwise.</p>
1443
1444 <p>This function is used to set, clear or query the session object indirect
1445 flag. If the second argument passed to this function is zero, then the
1446 indirect flag is cleared. If it is greater than zero, the indirect flag
1447 is set. Passing a value less than zero does not modify the current value
1448 of the indirect flag, and may be used to query the current state of the
1449 indirect flag for the specified session object.</p>
1450
1451 <p>The return value indicates the final state of the indirect flag: 0 if
1452 it is clear, or 1 if it is set.
1453 </p><hr><a name="sqlite3session_isempty"></a>
1454 <h2>Test if a changeset has recorded any changes.</h2><blockquote><pre>int sqlite3session_isempty(sqlite3_session *pSession);
1455 </pre></blockquote><p>
1456 Return non-zero if no changes to attached tables have been recorded by
1457 the session object passed as the first argument. Otherwise, if one or
1458 more changes have been recorded, return zero.</p>
1459
1460 <p>Even if this function returns zero, it is possible that calling
1461 <a href="#sqlite3session_changeset">sqlite3session_changeset()</a> on the session handle may still return a
1462 changeset that contains no changes. This can happen when a row in
1463 an attached table is modified and then later on the original values
1464 are restored. However, if this function returns non-zero, then it is
1465 guaranteed that a call to sqlite3session_changeset() will return a
1466 changeset containing zero changes.
1467 </p><hr><a name="sqlite3session_memory_used"></a>
1468 <h2>Query for the amount of heap memory used by a session object.</h2><blockquote><pre>sqlite3_int64 sqlite3session_memory_used(sqlite3_session *pSession);
1469 </pre></blockquote><p>
1470 This API returns the total amount of heap memory in bytes currently
1471 used by the session object passed as the only argument.
1472 </p><hr><a name="sqlite3session_object_config"></a>
1473 <h2>Configure a Session Object</h2><blockquote><pre>int sqlite3session_object_config(sqlite3_session*, int op, void *pArg);
1474 </pre></blockquote><p>
1475 This method is used to configure a session object after it has been
1476 created. At present the only valid values for the second parameter are
1477 <a href="#SQLITE_SESSION_OBJCONFIG_ROWID">SQLITE_SESSION_OBJCONFIG_SIZE</a> and <a href="#SQLITE_SESSION_OBJCONFIG_ROWID">SQLITE_SESSION_OBJCONFIG_ROWID</a>.</p>
1478
1479 <p></p><hr><a name="sqlite3session_patchset"></a>
1480 <h2>Generate A Patchset From A Session Object</h2><blockquote><pre>int sqlite3session_patchset(
1481 sqlite3_session *pSession, /* Session object */
1482 int *pnPatchset, /* OUT: Size of buffer at *ppPatchset */
1483 void **ppPatchset /* OUT: Buffer containing patchset */
1484 );
1485 </pre></blockquote><p>
1486 The differences between a patchset and a changeset are that:</p>
1487
1488 <p><ul>
1489 <li> DELETE records consist of the primary key fields only. The
1490 original values of other fields are omitted.
1491 <li> The original values of any modified fields are omitted from
1492 UPDATE records.
1493 </ul></p>
1494
1495 <p>A patchset blob may be used with up to date versions of all
1496 sqlite3changeset_xxx API functions except for sqlite3changeset_invert(),
1497 which returns SQLITE_CORRUPT if it is passed a patchset. Similarly,
1498 attempting to use a patchset blob with old versions of the
1499 sqlite3changeset_xxx APIs also provokes an SQLITE_CORRUPT error. </p>
1500
1501 <p>Because the non-primary key "old.*" fields are omitted, no
1502 SQLITE_CHANGESET_DATA conflicts can be detected or reported if a patchset
1503 is passed to the sqlite3changeset_apply() API. Other conflict types work
1504 in the same way as for changesets.</p>
1505
1506 <p>Changes within a patchset are ordered in the same way as for changesets
1507 generated by the sqlite3session_changeset() function (i.e. all changes for
1508 a single table are grouped together, tables appear in the order in which
1509 they were attached to the session object).
1510 </p><hr><a name="sqlite3session_table_filter"></a>
1511 <h2>Set a table filter on a Session Object.</h2><blockquote><pre>void sqlite3session_table_filter(
1512 sqlite3_session *pSession, /* Session object */
1513 int(*xFilter)(
1514 void *pCtx, /* Copy of third arg to _filter_table() */
1515 const char *zTab /* Table name */
1516 ),
1517 void *pCtx /* First argument passed to xFilter */
1518 );
1519 </pre></blockquote><p>
1520 The second argument (xFilter) is the "filter callback". For changes to rows
1521 in tables that are not attached to the Session object, the filter is called
1522 to determine whether changes to the table's rows should be tracked or not.
1523 If xFilter returns 0, changes are not tracked. Note that once a table is
1524 attached, xFilter will not be called again.
1525 </p><hr><a name="SQLITE_CHANGESETAPPLY_FKNOACTION"></a>
1526 <h2>Flags for sqlite3changeset_apply_v2</h2><blockquote><pre>#define SQLITE_CHANGESETAPPLY_NOSAVEPOINT 0x0001
1527 #define SQLITE_CHANGESETAPPLY_INVERT 0x0002
1528 #define SQLITE_CHANGESETAPPLY_IGNORENOOP 0x0004
1529 #define SQLITE_CHANGESETAPPLY_FKNOACTION 0x0008
1530 #define SQLITE_CHANGESETAPPLY_NOUPDATELOOP 0x0010
1531 </pre></blockquote><p>
1532 The following flags may passed via the 9th parameter to
1533 <a href="#sqlite3changeset_apply">sqlite3changeset_apply_v2</a> and <a href="#sqlite3changegroup_add_strm">sqlite3changeset_apply_v2_strm</a>:</p>
1534
1535 <p><dl>
1536 <dt>SQLITE_CHANGESETAPPLY_NOSAVEPOINT <dd>
1537 Usually, the sessions module encloses all operations performed by
1538 a single call to apply_v2() or apply_v2_strm() in a <a href="lang_savepoint.html">SAVEPOINT</a>. The
1539 SAVEPOINT is committed if the changeset or patchset is successfully
1540 applied, or rolled back if an error occurs. Specifying this flag
1541 causes the sessions module to omit this savepoint. In this case, if the
1542 caller has an open transaction or savepoint when apply_v2() is called,
1543 it may revert the partially applied changeset by rolling it back.</p>
1544
1545 <p><dt>SQLITE_CHANGESETAPPLY_INVERT <dd>
1546 Invert the changeset before applying it. This is equivalent to inverting
1547 a changeset using sqlite3changeset_invert() before applying it. It is
1548 an error to specify this flag with a patchset.</p>
1549
1550 <p><dt>SQLITE_CHANGESETAPPLY_IGNORENOOP <dd>
1551 Do not invoke the conflict handler callback for any changes that
1552 would not actually modify the database even if they were applied.
1553 Specifically, this means that the conflict handler is not invoked
1554 for:
1555 <ul>
1556 <li>a delete change if the row being deleted cannot be found,
1557 <li>an update change if the modified fields are already set to
1558 their new values in the conflicting row, or
1559 <li>an insert change if all fields of the conflicting row match
1560 the row being inserted.
1561 </ul></p>
1562
1563 <p><dt>SQLITE_CHANGESETAPPLY_FKNOACTION <dd>
1564 If this flag it set, then all foreign key constraints in the target
1565 database behave as if they were declared with "ON UPDATE NO ACTION ON
1566 DELETE NO ACTION", even if they are actually CASCADE, RESTRICT, SET NULL
1567 or SET DEFAULT.</p>
1568
1569 <p><dt>SQLITE_CHANGESETAPPLY_NOUPDATELOOP <dd>
1570 Sometimes, a changeset contains two or more update statements such that
1571 although after applying all updates the database will contain no
1572 constraint violations, no single update can be applied before the others.
1573 The simplest example of this is a pair of UPDATEs that have "swapped"
1574 two column values with a UNIQUE constraint.
1575 <p>
1576 Usually, sqlite3changeset_apply() and similar functions work hard to try
1577 to find a way to apply such a changeset. However, if this flag is set,
1578 then all such updates are considered CONSTRAINT conflicts.
1579 </p><hr><a name="SQLITE_CHANGESET_ABORT"></a>
1580 <h2>Constants Returned By The Conflict Handler</h2><blockquote><pre>#define SQLITE_CHANGESET_OMIT 0
1581 #define SQLITE_CHANGESET_REPLACE 1
1582 #define SQLITE_CHANGESET_ABORT 2
1583 </pre></blockquote><p>
1584 A conflict handler callback must return one of the following three values.</p>
1585
1586 <p><dl>
1587 <dt>SQLITE_CHANGESET_OMIT<dd>
1588 If a conflict handler returns this value no special action is taken. The
1589 change that caused the conflict is not applied. The session module
1590 continues to the next change in the changeset.</p>
1591
1592 <p><dt>SQLITE_CHANGESET_REPLACE<dd>
1593 This value may only be returned if the second argument to the conflict
1594 handler was SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this
1595 is not the case, any changes applied so far are rolled back and the
1596 call to sqlite3changeset_apply() returns SQLITE_MISUSE.</p>
1597
1598 <p> If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_DATA conflict
1599 handler, then the conflicting row is either updated or deleted, depending
1600 on the type of change.</p>
1601
1602 <p> If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_CONFLICT conflict
1603 handler, then the conflicting row is removed from the database and a
1604 second attempt to apply the change is made. If this second attempt fails,
1605 the original row is restored to the database before continuing.</p>
1606
1607 <p><dt>SQLITE_CHANGESET_ABORT<dd>
1608 If this value is returned, any changes applied so far are rolled back
1609 and the call to sqlite3changeset_apply() returns SQLITE_ABORT.
1610 </dl>
1611 </p><hr><a name="SQLITE_CHANGESET_CONFLICT"></a>
1612 <h2>Constants Passed To The Conflict Handler</h2><blockquote><pre>#define SQLITE_CHANGESET_DATA 1
1613 #define SQLITE_CHANGESET_NOTFOUND 2
1614 #define SQLITE_CHANGESET_CONFLICT 3
1615 #define SQLITE_CHANGESET_CONSTRAINT 4
1616 #define SQLITE_CHANGESET_FOREIGN_KEY 5
1617 </pre></blockquote><p>
1618 Values that may be passed as the second argument to a conflict-handler.</p>
1619
1620 <p><dl>
1621 <dt>SQLITE_CHANGESET_DATA<dd>
1622 The conflict handler is invoked with CHANGESET_DATA as the second argument
1623 when processing a DELETE or UPDATE change if a row with the required
1624 PRIMARY KEY fields is present in the database, but one or more other
1625 (non primary-key) fields modified by the update do not contain the
1626 expected "before" values.</p>
1627
1628 <p> The conflicting row, in this case, is the database row with the matching
1629 primary key.</p>
1630
1631 <p><dt>SQLITE_CHANGESET_NOTFOUND<dd>
1632 The conflict handler is invoked with CHANGESET_NOTFOUND as the second
1633 argument when processing a DELETE or UPDATE change if a row with the
1634 required PRIMARY KEY fields is not present in the database.</p>
1635
1636 <p> There is no conflicting row in this case. The results of invoking the
1637 sqlite3changeset_conflict() API are undefined.</p>
1638
1639 <p><dt>SQLITE_CHANGESET_CONFLICT<dd>
1640 CHANGESET_CONFLICT is passed as the second argument to the conflict
1641 handler while processing an INSERT change if the operation would result
1642 in duplicate primary key values.</p>
1643
1644 <p> The conflicting row in this case is the database row with the matching
1645 primary key.</p>
1646
1647 <p><dt>SQLITE_CHANGESET_FOREIGN_KEY<dd>
1648 If foreign key handling is enabled, and applying a changeset leaves the
1649 database in a state containing foreign key violations, the conflict
1650 handler is invoked with CHANGESET_FOREIGN_KEY as the second argument
1651 exactly once before the changeset is committed. If the conflict handler
1652 returns CHANGESET_OMIT, the changes, including those that caused the
1653 foreign key constraint violation, are committed. Or, if it returns
1654 CHANGESET_ABORT, the changeset is rolled back.</p>
1655
1656 <p> No current or conflicting row information is provided. The only function
1657 it is possible to call on the supplied sqlite3_changeset_iter handle
1658 is sqlite3changeset_fk_conflicts().</p>
1659
1660 <p><dt>SQLITE_CHANGESET_CONSTRAINT<dd>
1661 If any other constraint violation occurs while applying a change (i.e.
1662 a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is
1663 invoked with CHANGESET_CONSTRAINT as the second argument.</p>
1664
1665 <p> There is no conflicting row in this case. The results of invoking the
1666 sqlite3changeset_conflict() API are undefined.</p>
1667
1668 <p></dl>
1669 </p><hr><a name="SQLITE_SESSION_OBJCONFIG_ROWID"></a>
1670 <h2>Options for sqlite3session_object_config</h2><blockquote><pre>#define SQLITE_SESSION_OBJCONFIG_SIZE 1
1671 #define SQLITE_SESSION_OBJCONFIG_ROWID 2
1672 </pre></blockquote><p>
1673 The following values may passed as the the 2nd parameter to
1674 sqlite3session_object_config().</p>
1675
1676 <p><dt>SQLITE_SESSION_OBJCONFIG_SIZE <dd>
1677 This option is used to set, clear or query the flag that enables
1678 the <a href="#sqlite3session_changeset_size">sqlite3session_changeset_size()</a> API. Because it imposes some
1679 computational overhead, this API is disabled by default. Argument
1680 pArg must point to a value of type (int). If the value is initially
1681 0, then the sqlite3session_changeset_size() API is disabled. If it
1682 is greater than 0, then the same API is enabled. Or, if the initial
1683 value is less than zero, no change is made. In all cases the (int)
1684 variable is set to 1 if the sqlite3session_changeset_size() API is
1685 enabled following the current call, or 0 otherwise.</p>
1686
1687 <p> It is an error (SQLITE_MISUSE) to attempt to modify this setting after
1688 the first table has been attached to the session object.</p>
1689
1690 <p><dt>SQLITE_SESSION_OBJCONFIG_ROWID <dd>
1691 This option is used to set, clear or query the flag that enables
1692 collection of data for tables with no explicit PRIMARY KEY.</p>
1693
1694 <p> Normally, tables with no explicit PRIMARY KEY are simply ignored
1695 by the sessions module. However, if this flag is set, it behaves
1696 as if such tables have a column "_rowid_ INTEGER PRIMARY KEY" inserted
1697 as their leftmost columns.</p>
1698
1699 <p> It is an error (SQLITE_MISUSE) to attempt to modify this setting after
1700 the first table has been attached to the session object.
1701 </p><hr><a name="sqlite3changegroup_add_strm"></a>
1702 <h2>Streaming Versions of API functions.</h2><blockquote><pre>int sqlite3changeset_apply_strm(
1703 sqlite3 *db, /* Apply change to "main" db of this handle */
1704 int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
1705 void *pIn, /* First arg for xInput */
1706 int(*xFilter)(
1707 void *pCtx, /* Copy of sixth arg to _apply() */
1708 const char *zTab /* Table name */
1709 ),
1710 int(*xConflict)(
1711 void *pCtx, /* Copy of sixth arg to _apply() */
1712 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
1713 sqlite3_changeset_iter *p /* Handle describing change and conflict */
1714 ),
1715 void *pCtx /* First argument passed to xConflict */
1716 );
1717 int sqlite3changeset_apply_v2_strm(
1718 sqlite3 *db, /* Apply change to "main" db of this handle */
1719 int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
1720 void *pIn, /* First arg for xInput */
1721 int(*xFilter)(
1722 void *pCtx, /* Copy of sixth arg to _apply() */
1723 const char *zTab /* Table name */
1724 ),
1725 int(*xConflict)(
1726 void *pCtx, /* Copy of sixth arg to _apply() */
1727 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
1728 sqlite3_changeset_iter *p /* Handle describing change and conflict */
1729 ),
1730 void *pCtx, /* First argument passed to xConflict */
1731 void **ppRebase, int *pnRebase,
1732 int flags
1733 );
1734 int sqlite3changeset_apply_v3_strm(
1735 sqlite3 *db, /* Apply change to "main" db of this handle */
1736 int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
1737 void *pIn, /* First arg for xInput */
1738 int(*xFilter)(
1739 void *pCtx, /* Copy of sixth arg to _apply() */
1740 sqlite3_changeset_iter *p
1741 ),
1742 int(*xConflict)(
1743 void *pCtx, /* Copy of sixth arg to _apply() */
1744 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
1745 sqlite3_changeset_iter *p /* Handle describing change and conflict */
1746 ),
1747 void *pCtx, /* First argument passed to xConflict */
1748 void **ppRebase, int *pnRebase,
1749 int flags
1750 );
1751 int sqlite3changeset_concat_strm(
1752 int (*xInputA)(void *pIn, void *pData, int *pnData),
1753 void *pInA,
1754 int (*xInputB)(void *pIn, void *pData, int *pnData),
1755 void *pInB,
1756 int (*xOutput)(void *pOut, const void *pData, int nData),
1757 void *pOut
1758 );
1759 int sqlite3changeset_invert_strm(
1760 int (*xInput)(void *pIn, void *pData, int *pnData),
1761 void *pIn,
1762 int (*xOutput)(void *pOut, const void *pData, int nData),
1763 void *pOut
1764 );
1765 int sqlite3changeset_start_strm(
1766 sqlite3_changeset_iter **pp,
1767 int (*xInput)(void *pIn, void *pData, int *pnData),
1768 void *pIn
1769 );
1770 int sqlite3changeset_start_v2_strm(
1771 sqlite3_changeset_iter **pp,
1772 int (*xInput)(void *pIn, void *pData, int *pnData),
1773 void *pIn,
1774 int flags
1775 );
1776 int sqlite3session_changeset_strm(
1777 sqlite3_session *pSession,
1778 int (*xOutput)(void *pOut, const void *pData, int nData),
1779 void *pOut
1780 );
1781 int sqlite3session_patchset_strm(
1782 sqlite3_session *pSession,
1783 int (*xOutput)(void *pOut, const void *pData, int nData),
1784 void *pOut
1785 );
1786 int sqlite3changegroup_add_strm(sqlite3_changegroup*,
1787 int (*xInput)(void *pIn, void *pData, int *pnData),
1788 void *pIn
1789 );
1790 int sqlite3changegroup_output_strm(sqlite3_changegroup*,
1791 int (*xOutput)(void *pOut, const void *pData, int nData),
1792 void *pOut
1793 );
1794 int sqlite3rebaser_rebase_strm(
1795 sqlite3_rebaser *pRebaser,
1796 int (*xInput)(void *pIn, void *pData, int *pnData),
1797 void *pIn,
1798 int (*xOutput)(void *pOut, const void *pData, int nData),
1799 void *pOut
1800 );
1801 </pre></blockquote><p>
1802 The six streaming API xxx_strm() functions serve similar purposes to the
1803 corresponding non-streaming API functions:</p>
1804
1805 <p><table border=1 style="margin-left:8ex;margin-right:8ex">
1806 <tr><th>Streaming function<th>Non-streaming equivalent</th>
1807 <tr><td>sqlite3changeset_apply_strm<td><a href="#sqlite3changeset_apply">sqlite3changeset_apply</a>
1808 <tr><td>sqlite3changeset_apply_strm_v2<td><a href="#sqlite3changeset_apply">sqlite3changeset_apply_v2</a>
1809 <tr><td>sqlite3changeset_concat_strm<td><a href="#sqlite3changeset_concat">sqlite3changeset_concat</a>
1810 <tr><td>sqlite3changeset_invert_strm<td><a href="#sqlite3changeset_invert">sqlite3changeset_invert</a>
1811 <tr><td>sqlite3changeset_start_strm<td><a href="#sqlite3changeset_start">sqlite3changeset_start</a>
1812 <tr><td>sqlite3session_changeset_strm<td><a href="#sqlite3session_changeset">sqlite3session_changeset</a>
1813 <tr><td>sqlite3session_patchset_strm<td><a href="#sqlite3session_patchset">sqlite3session_patchset</a>
1814 </table></p>
1815
1816 <p>Non-streaming functions that accept changesets (or patchsets) as input
1817 require that the entire changeset be stored in a single buffer in memory.
1818 Similarly, those that return a changeset or patchset do so by returning
1819 a pointer to a single large buffer allocated using sqlite3_malloc().
1820 Normally this is convenient. However, if an application running in a
1821 low-memory environment is required to handle very large changesets, the
1822 large contiguous memory allocations required can become onerous.</p>
1823
1824 <p>In order to avoid this problem, instead of a single large buffer, input
1825 is passed to a streaming API functions by way of a callback function that
1826 the sessions module invokes to incrementally request input data as it is
1827 required. In all cases, a pair of API function parameters such as</p>
1828
1829 <p> <pre>
1830 &nbsp; int nChangeset,
1831 &nbsp; void *pChangeset,
1832 </pre></p>
1833
1834 <p>Is replaced by:</p>
1835
1836 <p> <pre>
1837 &nbsp; int (*xInput)(void *pIn, void *pData, int *pnData),
1838 &nbsp; void *pIn,
1839 </pre></p>
1840
1841 <p>Each time the xInput callback is invoked by the sessions module, the first
1842 argument passed is a copy of the supplied pIn context pointer. The second
1843 argument, pData, points to a buffer (*pnData) bytes in size. Assuming no
1844 error occurs the xInput method should copy up to (*pnData) bytes of data
1845 into the buffer and set (*pnData) to the actual number of bytes copied
1846 before returning SQLITE_OK. If the input is completely exhausted, (*pnData)
1847 should be set to zero to indicate this. Or, if an error occurs, an SQLite
1848 error code should be returned. In all cases, if an xInput callback returns
1849 an error, all processing is abandoned and the streaming API function
1850 returns a copy of the error code to the caller.</p>
1851
1852 <p>In the case of sqlite3changeset_start_strm(), the xInput callback may be
1853 invoked by the sessions module at any point during the lifetime of the
1854 iterator. If such an xInput callback returns an error, the iterator enters
1855 an error state, whereby all subsequent calls to iterator functions
1856 immediately fail with the same error code as returned by xInput.</p>
1857
1858 <p>Similarly, streaming API functions that return changesets (or patchsets)
1859 return them in chunks by way of a callback function instead of via a
1860 pointer to a single large buffer. In this case, a pair of parameters such
1861 as:</p>
1862
1863 <p> <pre>
1864 &nbsp; int *pnChangeset,
1865 &nbsp; void **ppChangeset,
1866 </pre></p>
1867
1868 <p>Is replaced by:</p>
1869
1870 <p> <pre>
1871 &nbsp; int (*xOutput)(void *pOut, const void *pData, int nData),
1872 &nbsp; void *pOut
1873 </pre></p>
1874
1875 <p>The xOutput callback is invoked zero or more times to return data to
1876 the application. The first parameter passed to each call is a copy of the
1877 pOut pointer supplied by the application. The second parameter, pData,
1878 points to a buffer nData bytes in size containing the chunk of output
1879 data being returned. If the xOutput callback successfully processes the
1880 supplied data, it should return SQLITE_OK to indicate success. Otherwise,
1881 it should return some other SQLite error code. In this case processing
1882 is immediately abandoned and the streaming API function returns a copy
1883 of the xOutput error code to the application.</p>
1884
1885 <p>The sessions module never invokes an xOutput callback with the third
1886 parameter set to a value less than or equal to zero. Other than this,
1887 no guarantees are made as to the size of the chunks of data returned.
1888 </p><hr><a name="sqlite3changeset_apply"></a>
1889 <h2>Apply A Changeset To A Database</h2><blockquote><pre>int sqlite3changeset_apply(
1890 sqlite3 *db, /* Apply change to "main" db of this handle */
1891 int nChangeset, /* Size of changeset in bytes */
1892 void *pChangeset, /* Changeset blob */
1893 int(*xFilter)(
1894 void *pCtx, /* Copy of sixth arg to _apply() */
1895 const char *zTab /* Table name */
1896 ),
1897 int(*xConflict)(
1898 void *pCtx, /* Copy of sixth arg to _apply() */
1899 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
1900 sqlite3_changeset_iter *p /* Handle describing change and conflict */
1901 ),
1902 void *pCtx /* First argument passed to xConflict */
1903 );
1904 int sqlite3changeset_apply_v2(
1905 sqlite3 *db, /* Apply change to "main" db of this handle */
1906 int nChangeset, /* Size of changeset in bytes */
1907 void *pChangeset, /* Changeset blob */
1908 int(*xFilter)(
1909 void *pCtx, /* Copy of sixth arg to _apply() */
1910 const char *zTab /* Table name */
1911 ),
1912 int(*xConflict)(
1913 void *pCtx, /* Copy of sixth arg to _apply() */
1914 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
1915 sqlite3_changeset_iter *p /* Handle describing change and conflict */
1916 ),
1917 void *pCtx, /* First argument passed to xConflict */
1918 void **ppRebase, int *pnRebase, /* OUT: Rebase data */
1919 int flags /* SESSION_CHANGESETAPPLY_* flags */
1920 );
1921 int sqlite3changeset_apply_v3(
1922 sqlite3 *db, /* Apply change to "main" db of this handle */
1923 int nChangeset, /* Size of changeset in bytes */
1924 void *pChangeset, /* Changeset blob */
1925 int(*xFilter)(
1926 void *pCtx, /* Copy of sixth arg to _apply() */
1927 sqlite3_changeset_iter *p /* Handle describing change */
1928 ),
1929 int(*xConflict)(
1930 void *pCtx, /* Copy of sixth arg to _apply() */
1931 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
1932 sqlite3_changeset_iter *p /* Handle describing change and conflict */
1933 ),
1934 void *pCtx, /* First argument passed to xConflict */
1935 void **ppRebase, int *pnRebase, /* OUT: Rebase data */
1936 int flags /* SESSION_CHANGESETAPPLY_* flags */
1937 );
1938 </pre></blockquote><p>
1939 Apply a changeset or patchset to a database. These functions attempt to
1940 update the "main" database attached to handle db with the changes found in
1941 the changeset passed via the second and third arguments. </p>
1942
1943 <p>All changes made by these functions are enclosed in a savepoint transaction.
1944 If any other error (aside from a constraint failure when attempting to
1945 write to the target database) occurs, then the savepoint transaction is
1946 rolled back, restoring the target database to its original state, and an
1947 SQLite error code returned. Additionally, starting with version 3.51.0,
1948 an error code and error message that may be accessed using the
1949 <a href="c3ref/errcode.html">sqlite3_errcode()</a> and <a href="c3ref/errcode.html">sqlite3_errmsg()</a> APIs are left in the database
1950 handle.</p>
1951
1952 <p>The fourth argument (xFilter) passed to these functions is the "filter
1953 callback". This may be passed NULL, in which case all changes in the
1954 changeset are applied to the database. For sqlite3changeset_apply() and
1955 sqlite3_changeset_apply_v2(), if it is not NULL, then it is invoked once
1956 for each table affected by at least one change in the changeset. In this
1957 case the table name is passed as the second argument, and a copy of
1958 the context pointer passed as the sixth argument to apply() or apply_v2()
1959 as the first. If the "filter callback" returns zero, then no attempt is
1960 made to apply any changes to the table. Otherwise, if the return value is
1961 non-zero, all changes related to the table are attempted.</p>
1962
1963 <p>For sqlite3_changeset_apply_v3(), the xFilter callback is invoked once
1964 per change. The second argument in this case is an sqlite3_changeset_iter
1965 that may be queried using the usual APIs for the details of the current
1966 change. If the "filter callback" returns zero in this case, then no attempt
1967 is made to apply the current change. If it returns non-zero, the change
1968 is applied.</p>
1969
1970 <p>For each table that is not excluded by the filter callback, this function
1971 tests that the target database contains a compatible table. A table is
1972 considered compatible if all of the following are true:</p>
1973
1974 <p><ul>
1975 <li> The table has the same name as the name recorded in the
1976 changeset, and
1977 <li> The table has at least as many columns as recorded in the
1978 changeset, and
1979 <li> The table has primary key columns in the same position as
1980 recorded in the changeset.
1981 </ul></p>
1982
1983 <p>If there is no compatible table, it is not an error, but none of the
1984 changes associated with the table are applied. A warning message is issued
1985 via the sqlite3_log() mechanism with the error code SQLITE_SCHEMA. At most
1986 one such warning is issued for each table in the changeset.</p>
1987
1988 <p>For each change for which there is a compatible table, an attempt is made
1989 to modify the table contents according to each UPDATE, INSERT or DELETE
1990 change that is not excluded by a filter callback. If a change cannot be
1991 applied cleanly, the conflict handler function passed as the fifth argument
1992 to sqlite3changeset_apply() may be invoked. A description of exactly when
1993 the conflict handler is invoked for each type of change is below.</p>
1994
1995 <p>Unlike the xFilter argument, xConflict may not be passed NULL. The results
1996 of passing anything other than a valid function pointer as the xConflict
1997 argument are undefined.</p>
1998
1999 <p>Each time the conflict handler function is invoked, it must return one
2000 of <a href="#SQLITE_CHANGESET_ABORT">SQLITE_CHANGESET_OMIT</a>, <a href="#SQLITE_CHANGESET_ABORT">SQLITE_CHANGESET_ABORT</a> or
2001 <a href="#SQLITE_CHANGESET_ABORT">SQLITE_CHANGESET_REPLACE</a>. SQLITE_CHANGESET_REPLACE may only be returned
2002 if the second argument passed to the conflict handler is either
2003 SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler
2004 returns an illegal value, any changes already made are rolled back and
2005 the call to sqlite3changeset_apply() returns SQLITE_MISUSE. Different
2006 actions are taken by sqlite3changeset_apply() depending on the value
2007 returned by each invocation of the conflict-handler function. Refer to
2008 the documentation for the three
2009 <a href="#SQLITE_CHANGESET_ABORT">available return values</a> for details.</p>
2010
2011 <p><dl>
2012 <dt>DELETE Changes<dd>
2013 For each DELETE change, the function checks if the target database
2014 contains a row with the same primary key value (or values) as the
2015 original row values stored in the changeset. If it does, and the values
2016 stored in all non-primary key columns also match the values stored in
2017 the changeset the row is deleted from the target database.</p>
2018
2019 <p> If a row with matching primary key values is found, but one or more of
2020 the non-primary key fields contains a value different from the original
2021 row value stored in the changeset, the conflict-handler function is
2022 invoked with <a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_DATA</a> as the second argument. If the
2023 database table has more columns than are recorded in the changeset,
2024 only the values of those non-primary key fields are compared against
2025 the current database contents - any trailing database table columns
2026 are ignored.</p>
2027
2028 <p> If no row with matching primary key values is found in the database,
2029 the conflict-handler function is invoked with <a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_NOTFOUND</a>
2030 passed as the second argument.</p>
2031
2032 <p> If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT
2033 (which can only happen if a foreign key constraint is violated), the
2034 conflict-handler function is invoked with <a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_CONSTRAINT</a>
2035 passed as the second argument. This includes the case where the DELETE
2036 operation is attempted because an earlier call to the conflict handler
2037 function returned <a href="#SQLITE_CHANGESET_ABORT">SQLITE_CHANGESET_REPLACE</a>.</p>
2038
2039 <p><dt>INSERT Changes<dd>
2040 For each INSERT change, an attempt is made to insert the new row into
2041 the database. If the changeset row contains fewer fields than the
2042 database table, the trailing fields are populated with their default
2043 values.</p>
2044
2045 <p> If the attempt to insert the row fails because the database already
2046 contains a row with the same primary key values, the conflict handler
2047 function is invoked with the second argument set to
2048 <a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_CONFLICT</a>.</p>
2049
2050 <p> If the attempt to insert the row fails because of some other constraint
2051 violation (e.g. NOT NULL or UNIQUE), the conflict handler function is
2052 invoked with the second argument set to <a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_CONSTRAINT</a>.
2053 This includes the case where the INSERT operation is re-attempted because
2054 an earlier call to the conflict handler function returned
2055 <a href="#SQLITE_CHANGESET_ABORT">SQLITE_CHANGESET_REPLACE</a>.</p>
2056
2057 <p><dt>UPDATE Changes<dd>
2058 For each UPDATE change, the function checks if the target database
2059 contains a row with the same primary key value (or values) as the
2060 original row values stored in the changeset. If it does, and the values
2061 stored in all modified non-primary key columns also match the values
2062 stored in the changeset the row is updated within the target database.</p>
2063
2064 <p> If a row with matching primary key values is found, but one or more of
2065 the modified non-primary key fields contains a value different from an
2066 original row value stored in the changeset, the conflict-handler function
2067 is invoked with <a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_DATA</a> as the second argument. Since
2068 UPDATE changes only contain values for non-primary key fields that are
2069 to be modified, only those fields need to match the original values to
2070 avoid the SQLITE_CHANGESET_DATA conflict-handler callback.</p>
2071
2072 <p> If no row with matching primary key values is found in the database,
2073 the conflict-handler function is invoked with <a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_NOTFOUND</a>
2074 passed as the second argument.</p>
2075
2076 <p> If the UPDATE operation is attempted, but SQLite returns
2077 SQLITE_CONSTRAINT, the conflict-handler function is invoked with
2078 <a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_CONSTRAINT</a> passed as the second argument.
2079 This includes the case where the UPDATE operation is attempted after
2080 an earlier call to the conflict handler function returned
2081 <a href="#SQLITE_CHANGESET_ABORT">SQLITE_CHANGESET_REPLACE</a>.
2082 </dl></p>
2083
2084 <p>It is safe to execute SQL statements, including those that write to the
2085 table that the callback related to, from within the xConflict callback.
2086 This can be used to further customize the application's conflict
2087 resolution strategy.</p>
2088
2089 <p>If the output parameters (ppRebase) and (pnRebase) are non-NULL and
2090 the input is a changeset (not a patchset), then sqlite3changeset_apply_v2()
2091 may set (*ppRebase) to point to a "rebase" that may be used with the
2092 sqlite3_rebaser APIs buffer before returning. In this case (*pnRebase)
2093 is set to the size of the buffer in bytes. It is the responsibility of the
2094 caller to eventually free any such buffer using sqlite3_free(). The buffer
2095 is only allocated and populated if one or more conflicts were encountered
2096 while applying the patchset. See comments surrounding the sqlite3_rebaser
2097 APIs for further details.</p>
2098
2099 <p>The behavior of sqlite3changeset_apply_v2() and its streaming equivalent
2100 may be modified by passing a combination of
2101 <a href="#SQLITE_CHANGESETAPPLY_FKNOACTION">supported flags</a> as the 9th parameter.</p>
2102
2103 <p>Note that the sqlite3changeset_apply_v2() API is still <b>experimental</b>
2104 and therefore subject to change.
2105 </p><hr><a name="sqlite3changeset_start"></a>
2106 <h2>Create An Iterator To Traverse A Changeset </h2><blockquote><pre>int sqlite3changeset_start(
2107 sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */
2108 int nChangeset, /* Size of changeset blob in bytes */
2109 void *pChangeset /* Pointer to blob containing changeset */
2110 );
2111 int sqlite3changeset_start_v2(
2112 sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */
2113 int nChangeset, /* Size of changeset blob in bytes */
2114 void *pChangeset, /* Pointer to blob containing changeset */
2115 int flags /* SESSION_CHANGESETSTART_* flags */
2116 );
2117 </pre></blockquote><p>
2118 Create an iterator used to iterate through the contents of a changeset.
2119 If successful, *pp is set to point to the iterator handle and SQLITE_OK
2120 is returned. Otherwise, if an error occurs, *pp is set to zero and an
2121 SQLite error code is returned.</p>
2122
2123 <p>The following functions can be used to advance and query a changeset
2124 iterator created by this function:</p>
2125
2126 <p><ul>
2127 <li> <a href="#sqlite3changeset_next">sqlite3changeset_next()</a>
2128 <li> <a href="#sqlite3changeset_op">sqlite3changeset_op()</a>
2129 <li> <a href="#sqlite3changeset_new">sqlite3changeset_new()</a>
2130 <li> <a href="#sqlite3changeset_old">sqlite3changeset_old()</a>
2131 </ul></p>
2132
2133 <p>It is the responsibility of the caller to eventually destroy the iterator
2134 by passing it to <a href="#sqlite3changeset_finalize">sqlite3changeset_finalize()</a>. The buffer containing the
2135 changeset (pChangeset) must remain valid until after the iterator is
2136 destroyed.</p>
2137
2138 <p>Assuming the changeset blob was created by one of the
2139 <a href="#sqlite3session_changeset">sqlite3session_changeset()</a>, <a href="#sqlite3changeset_concat">sqlite3changeset_concat()</a> or
2140 <a href="#sqlite3changeset_invert">sqlite3changeset_invert()</a> functions, all changes within the changeset
2141 that apply to a single table are grouped together. This means that when
2142 an application iterates through a changeset using an iterator created by
2143 this function, all changes that relate to a single table are visited
2144 consecutively. There is no chance that the iterator will visit a change
2145 the applies to table X, then one for table Y, and then later on visit
2146 another change for table X.</p>
2147
2148 <p>The behavior of sqlite3changeset_start_v2() and its streaming equivalent
2149 may be modified by passing a combination of
2150 <a href="#SQLITE_CHANGESETSTART_INVERT">supported flags</a> as the 4th parameter.</p>
2151
2152 <p>Note that the sqlite3changeset_start_v2() API is still <b>experimental</b>
2153 and therefore subject to change.
2154 </p><hr>
2155
2156