| 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 |
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 |
int nChangeset, |
| 1831 |
void *pChangeset, |
| 1832 |
</pre></p> |
| 1833 |
|
| 1834 |
<p>Is replaced by:</p> |
| 1835 |
|
| 1836 |
<p> <pre> |
| 1837 |
int (*xInput)(void *pIn, void *pData, int *pnData), |
| 1838 |
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 |
int *pnChangeset, |
| 1865 |
void **ppChangeset, |
| 1866 |
</pre></p> |
| 1867 |
|
| 1868 |
<p>Is replaced by:</p> |
| 1869 |
|
| 1870 |
<p> <pre> |
| 1871 |
int (*xOutput)(void *pOut, const void *pData, int nData), |
| 1872 |
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 |
|