1717 lines
87 KiB
HTML
1717 lines
87 KiB
HTML
|
<!DOCTYPE html>
|
||
|
|
<html><head>
|
||
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
|
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
|
||
|
|
<link href="sqlite.css" rel="stylesheet">
|
||
|
|
<title>SQLite Session Module C/C++ Interface</title>
|
||
|
|
<!-- path= -->
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div class=nosearch>
|
||
|
|
<a href="index.html">
|
||
|
|
<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite" border="0">
|
||
|
|
</a>
|
||
|
|
<div><!-- IE hack to prevent disappearing logo --></div>
|
||
|
|
<div class="tagline desktoponly">
|
||
|
|
Small. Fast. Reliable.<br>Choose any three.
|
||
|
|
</div>
|
||
|
|
<div class="menu mainmenu">
|
||
|
|
<ul>
|
||
|
|
<li><a href="index.html">Home</a>
|
||
|
|
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
|
||
|
|
<li class='wideonly'><a href='about.html'>About</a>
|
||
|
|
<li class='desktoponly'><a href="docs.html">Documentation</a>
|
||
|
|
<li class='desktoponly'><a href="download.html">Download</a>
|
||
|
|
<li class='wideonly'><a href='copyright.html'>License</a>
|
||
|
|
<li class='desktoponly'><a href="support.html">Support</a>
|
||
|
|
<li class='desktoponly'><a href="prosupport.html">Purchase</a>
|
||
|
|
<li class='search' id='search_menubutton'>
|
||
|
|
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<div class="menu submenu" id="submenu">
|
||
|
|
<ul>
|
||
|
|
<li><a href='about.html'>About</a>
|
||
|
|
<li><a href='docs.html'>Documentation</a>
|
||
|
|
<li><a href='download.html'>Download</a>
|
||
|
|
<li><a href='support.html'>Support</a>
|
||
|
|
<li><a href='prosupport.html'>Purchase</a>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<div class="searchmenu" id="searchmenu">
|
||
|
|
<form method="GET" action="search">
|
||
|
|
<select name="s" id="searchtype">
|
||
|
|
<option value="d">Search Documentation</option>
|
||
|
|
<option value="c">Search Changelog</option>
|
||
|
|
</select>
|
||
|
|
<input type="text" name="q" id="searchbox" value="">
|
||
|
|
<input type="submit" value="Go">
|
||
|
|
</form>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<script>
|
||
|
|
function toggle_div(nm) {
|
||
|
|
var w = document.getElementById(nm);
|
||
|
|
if( w.style.display=="block" ){
|
||
|
|
w.style.display = "none";
|
||
|
|
}else{
|
||
|
|
w.style.display = "block";
|
||
|
|
}
|
||
|
|
}
|
||
|
|
function toggle_search() {
|
||
|
|
var w = document.getElementById("searchmenu");
|
||
|
|
if( w.style.display=="block" ){
|
||
|
|
w.style.display = "none";
|
||
|
|
} else {
|
||
|
|
w.style.display = "block";
|
||
|
|
setTimeout(function(){
|
||
|
|
document.getElementById("searchbox").focus()
|
||
|
|
}, 30);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
function div_off(nm){document.getElementById(nm).style.display="none";}
|
||
|
|
window.onbeforeunload = function(e){div_off("submenu");}
|
||
|
|
/* Disable the Search feature if we are not operating from CGI, since */
|
||
|
|
/* Search is accomplished using CGI and will not work without it. */
|
||
|
|
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
|
||
|
|
document.getElementById("search_menubutton").style.display = "none";
|
||
|
|
}
|
||
|
|
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
|
||
|
|
function hideorshow(btn,obj){
|
||
|
|
var x = document.getElementById(obj);
|
||
|
|
var b = document.getElementById(btn);
|
||
|
|
if( x.style.display!='none' ){
|
||
|
|
x.style.display = 'none';
|
||
|
|
b.innerHTML='show';
|
||
|
|
}else{
|
||
|
|
x.style.display = '';
|
||
|
|
b.innerHTML='hide';
|
||
|
|
}
|
||
|
|
return false;
|
||
|
|
}
|
||
|
|
</script>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
<h2>SQLite Session Module C/C++ Interface</h2>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<p>This page defines the C-language interface to the SQLite
|
||
|
|
<a href="sessionintro.html">session extension</a>.
|
||
|
|
This is not a tutorial. These pages are designed to be precise, not easy
|
||
|
|
to read. A tutorial is <a href="sessionintro.html">available separately</a>.
|
||
|
|
|
||
|
|
<p>This page contains all C-language interface information
|
||
|
|
in a single HTML file. The same information is also
|
||
|
|
available broken out into <a href="session/intro.html">lots of small pages</a>
|
||
|
|
for easier viewing, if you prefer.</p>
|
||
|
|
|
||
|
|
<p>This document is created by a script which scans comments in the source
|
||
|
|
code file sqlite3session.h.</p>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
|
||
|
|
|
||
|
|
<h2>Objects:</h2>
|
||
|
|
<div class='columns' style='columns: 15em auto;'>
|
||
|
|
<ul style='padding-top:0;'>
|
||
|
|
<li><a href='#sqlite3_changegroup'>sqlite3_changegroup</a></li>
|
||
|
|
<li><a href='#sqlite3_changeset_iter'>sqlite3_changeset_iter</a></li>
|
||
|
|
<li><a href='#sqlite3_rebaser'>sqlite3_rebaser<small><i>(exp)</i></small></a></li>
|
||
|
|
<li><a href='#sqlite3_session'>sqlite3_session</a></li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
|
||
|
|
<h2>Constants:</h2>
|
||
|
|
<div class='columns' style='columns: 20em auto;'>
|
||
|
|
<ul style='padding-top:0;'>
|
||
|
|
<li><a href='#SQLITE_CHANGESETAPPLY_INVERT'>SQLITE_CHANGESETAPPLY_INVERT</a></li>
|
||
|
|
<li><a href='#SQLITE_CHANGESETAPPLY_INVERT'>SQLITE_CHANGESETAPPLY_NOSAVEPOINT</a></li>
|
||
|
|
<li><a href='#SQLITE_CHANGESETSTART_INVERT'>SQLITE_CHANGESETSTART_INVERT</a></li>
|
||
|
|
<li><a href='#SQLITE_CHANGESET_ABORT'>SQLITE_CHANGESET_ABORT</a></li>
|
||
|
|
<li><a href='#SQLITE_CHANGESET_CONFLICT'>SQLITE_CHANGESET_CONFLICT</a></li>
|
||
|
|
<li><a href='#SQLITE_CHANGESET_CONFLICT'>SQLITE_CHANGESET_CONSTRAINT</a></li>
|
||
|
|
<li><a href='#SQLITE_CHANGESET_CONFLICT'>SQLITE_CHANGESET_DATA</a></li>
|
||
|
|
<li><a href='#SQLITE_CHANGESET_CONFLICT'>SQLITE_CHANGESET_FOREIGN_KEY</a></li>
|
||
|
|
<li><a href='#SQLITE_CHANGESET_CONFLICT'>SQLITE_CHANGESET_NOTFOUND</a></li>
|
||
|
|
<li><a href='#SQLITE_CHANGESET_ABORT'>SQLITE_CHANGESET_OMIT</a></li>
|
||
|
|
<li><a href='#SQLITE_CHANGESET_ABORT'>SQLITE_CHANGESET_REPLACE</a></li>
|
||
|
|
<li><a href='#SQLITE_SESSION_CONFIG_STRMSIZE'>SQLITE_SESSION_CONFIG_STRMSIZE</a></li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
|
||
|
|
<h2>Functions:</h2>
|
||
|
|
<div class='columns' style='columns: 15em auto;'>
|
||
|
|
<ul style='padding-top:0;'>
|
||
|
|
<li><a href='#sqlite3changegroup_add'>sqlite3changegroup_add</a></li>
|
||
|
|
<li><a href='#sqlite3changegroup_add_strm'>sqlite3changegroup_add_strm</a></li>
|
||
|
|
<li><a href='#sqlite3changegroup_delete'>sqlite3changegroup_delete</a></li>
|
||
|
|
<li><a href='#sqlite3changegroup_new'>sqlite3changegroup_new</a></li>
|
||
|
|
<li><a href='#sqlite3changegroup_output'>sqlite3changegroup_output</a></li>
|
||
|
|
<li><a href='#sqlite3changegroup_add_strm'>sqlite3changegroup_output_strm</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_apply'>sqlite3changeset_apply</a></li>
|
||
|
|
<li><a href='#sqlite3changegroup_add_strm'>sqlite3changeset_apply_strm</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_apply'>sqlite3changeset_apply_v2</a></li>
|
||
|
|
<li><a href='#sqlite3changegroup_add_strm'>sqlite3changeset_apply_v2_strm</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_concat'>sqlite3changeset_concat</a></li>
|
||
|
|
<li><a href='#sqlite3changegroup_add_strm'>sqlite3changeset_concat_strm</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_conflict'>sqlite3changeset_conflict</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_finalize'>sqlite3changeset_finalize</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_fk_conflicts'>sqlite3changeset_fk_conflicts</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_invert'>sqlite3changeset_invert</a></li>
|
||
|
|
<li><a href='#sqlite3changegroup_add_strm'>sqlite3changeset_invert_strm</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_new'>sqlite3changeset_new</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_next'>sqlite3changeset_next</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_old'>sqlite3changeset_old</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_op'>sqlite3changeset_op</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_pk'>sqlite3changeset_pk</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_start'>sqlite3changeset_start</a></li>
|
||
|
|
<li><a href='#sqlite3changegroup_add_strm'>sqlite3changeset_start_strm</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_start'>sqlite3changeset_start_v2</a></li>
|
||
|
|
<li><a href='#sqlite3changegroup_add_strm'>sqlite3changeset_start_v2_strm</a></li>
|
||
|
|
<li><a href='#sqlite3rebaser_configure'>sqlite3rebaser_configure<small><i>(exp)</i></small></a></li>
|
||
|
|
<li><a href='#sqlite3rebaser_create'>sqlite3rebaser_create<small><i>(exp)</i></small></a></li>
|
||
|
|
<li><a href='#sqlite3rebaser_delete'>sqlite3rebaser_delete<small><i>(exp)</i></small></a></li>
|
||
|
|
<li><a href='#sqlite3rebaser_rebase'>sqlite3rebaser_rebase<small><i>(exp)</i></small></a></li>
|
||
|
|
<li><a href='#sqlite3changegroup_add_strm'>sqlite3rebaser_rebase_strm</a></li>
|
||
|
|
<li><a href='#sqlite3session_attach'>sqlite3session_attach</a></li>
|
||
|
|
<li><a href='#sqlite3session_changeset'>sqlite3session_changeset</a></li>
|
||
|
|
<li><a href='#sqlite3changegroup_add_strm'>sqlite3session_changeset_strm</a></li>
|
||
|
|
<li><a href='#sqlite3session_config'>sqlite3session_config</a></li>
|
||
|
|
<li><a href='#sqlite3session_create'>sqlite3session_create</a></li>
|
||
|
|
<li><a href='#sqlite3session_delete'>sqlite3session_delete</a></li>
|
||
|
|
<li><a href='#sqlite3session_diff'>sqlite3session_diff</a></li>
|
||
|
|
<li><a href='#sqlite3session_enable'>sqlite3session_enable</a></li>
|
||
|
|
<li><a href='#sqlite3session_indirect'>sqlite3session_indirect</a></li>
|
||
|
|
<li><a href='#sqlite3session_isempty'>sqlite3session_isempty</a></li>
|
||
|
|
<li><a href='#sqlite3session_patchset'>sqlite3session_patchset</a></li>
|
||
|
|
<li><a href='#sqlite3changegroup_add_strm'>sqlite3session_patchset_strm</a></li>
|
||
|
|
<li><a href='#sqlite3session_table_filter'>sqlite3session_table_filter</a></li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<a name="SQLITE_CHANGESETSTART_INVERT"></a>
|
||
|
|
<h2>Flags for sqlite3changeset_start_v2</h2><blockquote><pre>#define SQLITE_CHANGESETSTART_INVERT 0x0002
|
||
|
|
</pre></blockquote><p>
|
||
|
|
The following flags may passed via the 4th parameter to
|
||
|
|
<a href="#sqlite3changeset_start">sqlite3changeset_start_v2</a> and <a href="#sqlite3changegroup_add_strm">sqlite3changeset_start_v2_strm</a>:</p>
|
||
|
|
|
||
|
|
<p><dt>SQLITE_CHANGESETAPPLY_INVERT <dd>
|
||
|
|
Invert the changeset while iterating through it. This is equivalent to
|
||
|
|
inverting a changeset using sqlite3changeset_invert() before applying it.
|
||
|
|
It is an error to specify this flag with a patchset.
|
||
|
|
</p><hr><a name="SQLITE_SESSION_CONFIG_STRMSIZE"></a>
|
||
|
|
<h2>Values for sqlite3session_config().</h2><blockquote><pre>#define SQLITE_SESSION_CONFIG_STRMSIZE 1
|
||
|
|
</pre></blockquote><p></p><hr><a name="sqlite3_changegroup"></a>
|
||
|
|
<h2>Changegroup Handle</h2><blockquote><pre>typedef struct sqlite3_changegroup sqlite3_changegroup;
|
||
|
|
</pre></blockquote><p>
|
||
|
|
A changegroup is an object used to combine two or more
|
||
|
|
<a href="sessionintro.html#changeset">changesets</a> or <a href="sessionintro.html#changeset">patchsets</a>
|
||
|
|
</p><p>Constructor: <a href="#sqlite3changegroup_new">sqlite3changegroup_new()</a></p>
|
||
|
|
<p>Destructor: <a href="#sqlite3changegroup_delete">sqlite3changegroup_delete()</a></p>
|
||
|
|
<p>Methods:
|
||
|
|
<a href="#sqlite3changegroup_add">sqlite3changegroup_add()</a>,
|
||
|
|
<a href="#sqlite3changegroup_output">sqlite3changegroup_output()</a></p>
|
||
|
|
<hr><a name="sqlite3_changeset_iter"></a>
|
||
|
|
<h2>Changeset Iterator Handle</h2><blockquote><pre>typedef struct sqlite3_changeset_iter sqlite3_changeset_iter;
|
||
|
|
</pre></blockquote><p>
|
||
|
|
An instance of this object acts as a cursor for iterating
|
||
|
|
over the elements of a <a href="sessionintro.html#changeset">changeset</a> or <a href="sessionintro.html#changeset">patchset</a>.
|
||
|
|
</p><p>Constructors:
|
||
|
|
<a href="#sqlite3changeset_start">sqlite3changeset_start()</a>,
|
||
|
|
<a href="#sqlite3changeset_start">sqlite3changeset_start_v2()</a></p>
|
||
|
|
<div class='columns' style='columns: 17em auto;'>
|
||
|
|
<ul style='padding-top:0;'>
|
||
|
|
<li><a href='#sqlite3changeset_conflict'>sqlite3changeset_conflict</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_finalize'>sqlite3changeset_finalize</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_fk_conflicts'>sqlite3changeset_fk_conflicts</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_new'>sqlite3changeset_new</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_next'>sqlite3changeset_next</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_old'>sqlite3changeset_old</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_op'>sqlite3changeset_op</a></li>
|
||
|
|
<li><a href='#sqlite3changeset_pk'>sqlite3changeset_pk</a></li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</p>
|
||
|
|
<hr><a name="sqlite3_rebaser"></a>
|
||
|
|
<h2>Rebasing changesets</h2><blockquote><pre>typedef struct sqlite3_rebaser sqlite3_rebaser;
|
||
|
|
</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>
|
||
|
|
Suppose there is a site hosting a database in state S0. And that
|
||
|
|
modifications are made that move that database to state S1 and a
|
||
|
|
changeset recorded (the "local" changeset). Then, a changeset based
|
||
|
|
on S0 is received from another site (the "remote" changeset) and
|
||
|
|
applied to the database. The database is then in state
|
||
|
|
(S1+"remote"), where the exact state depends on any conflict
|
||
|
|
resolution decisions (OMIT or REPLACE) made while applying "remote".
|
||
|
|
Rebasing a changeset is to update it to take those conflict
|
||
|
|
resolution decisions into account, so that the same conflicts
|
||
|
|
do not have to be resolved elsewhere in the network. </p>
|
||
|
|
|
||
|
|
<p>For example, if both the local and remote changesets contain an
|
||
|
|
INSERT of the same key on "CREATE TABLE t1(a PRIMARY KEY, b)":</p>
|
||
|
|
|
||
|
|
<p> local: INSERT INTO t1 VALUES(1, 'v1');
|
||
|
|
remote: INSERT INTO t1 VALUES(1, 'v2');</p>
|
||
|
|
|
||
|
|
<p>and the conflict resolution is REPLACE, then the INSERT change is
|
||
|
|
removed from the local changeset (it was overridden). Or, if the
|
||
|
|
conflict resolution was "OMIT", then the local changeset is modified
|
||
|
|
to instead contain:</p>
|
||
|
|
|
||
|
|
<p> UPDATE t1 SET b = 'v2' WHERE a=1;</p>
|
||
|
|
|
||
|
|
<p>Changes within the local changeset are rebased as follows:</p>
|
||
|
|
|
||
|
|
<p><dl>
|
||
|
|
<dt>Local INSERT<dd>
|
||
|
|
This may only conflict with a remote INSERT. If the conflict
|
||
|
|
resolution was OMIT, then add an UPDATE change to the rebased
|
||
|
|
changeset. Or, if the conflict resolution was REPLACE, add
|
||
|
|
nothing to the rebased changeset.</p>
|
||
|
|
|
||
|
|
<p><dt>Local DELETE<dd>
|
||
|
|
This may conflict with a remote UPDATE or DELETE. In both cases the
|
||
|
|
only possible resolution is OMIT. If the remote operation was a
|
||
|
|
DELETE, then add no change to the rebased changeset. If the remote
|
||
|
|
operation was an UPDATE, then the old.* fields of change are updated
|
||
|
|
to reflect the new.* values in the UPDATE.</p>
|
||
|
|
|
||
|
|
<p><dt>Local UPDATE<dd>
|
||
|
|
This may conflict with a remote UPDATE or DELETE. If it conflicts
|
||
|
|
with a DELETE, and the conflict resolution was OMIT, then the update
|
||
|
|
is changed into an INSERT. Any undefined values in the new.* record
|
||
|
|
from the update change are filled in using the old.* values from
|
||
|
|
the conflicting DELETE. Or, if the conflict resolution was REPLACE,
|
||
|
|
the UPDATE change is simply omitted from the rebased changeset.</p>
|
||
|
|
|
||
|
|
<p> If conflict is with a remote UPDATE and the resolution is OMIT, then
|
||
|
|
the old.* values are rebased using the new.* values in the remote
|
||
|
|
change. Or, if the resolution is REPLACE, then the change is copied
|
||
|
|
into the rebased changeset with updates to columns also updated by
|
||
|
|
the conflicting remote UPDATE removed. If this means no columns would
|
||
|
|
be updated, the change is omitted.
|
||
|
|
</dl></p>
|
||
|
|
|
||
|
|
<p>A local change may be rebased against multiple remote changes
|
||
|
|
simultaneously. If a single key is modified by multiple remote
|
||
|
|
changesets, they are combined as follows before the local changeset
|
||
|
|
is rebased:</p>
|
||
|
|
|
||
|
|
<p><ul>
|
||
|
|
<li> If there has been one or more REPLACE resolutions on a
|
||
|
|
key, it is rebased according to a REPLACE.</p>
|
||
|
|
|
||
|
|
<p> <li> If there have been no REPLACE resolutions on a key, then
|
||
|
|
the local changeset is rebased according to the most recent
|
||
|
|
of the OMIT resolutions.
|
||
|
|
</ul></p>
|
||
|
|
|
||
|
|
<p>Note that conflict resolutions from multiple remote changesets are
|
||
|
|
combined on a per-field basis, not per-row. This means that in the
|
||
|
|
case of multiple remote UPDATE operations, some fields of a single
|
||
|
|
local change may be rebased for REPLACE while others are rebased for
|
||
|
|
OMIT.</p>
|
||
|
|
|
||
|
|
<p>In order to rebase a local changeset, the remote changeset must first
|
||
|
|
be applied to the local database using sqlite3changeset_apply_v2() and
|
||
|
|
the buffer of rebase information captured. Then:</p>
|
||
|
|
|
||
|
|
<p><ol>
|
||
|
|
<li> An sqlite3_rebaser object is created by calling
|
||
|
|
sqlite3rebaser_create().
|
||
|
|
<li> The new object is configured with the rebase buffer obtained from
|
||
|
|
sqlite3changeset_apply_v2() by calling sqlite3rebaser_configure().
|
||
|
|
If the local changeset is to be rebased against multiple remote
|
||
|
|
changesets, then sqlite3rebaser_configure() should be called
|
||
|
|
multiple times, in the same order that the multiple
|
||
|
|
sqlite3changeset_apply_v2() calls were made.
|
||
|
|
<li> Each local changeset is rebased by calling sqlite3rebaser_rebase().
|
||
|
|
<li> The sqlite3_rebaser object is deleted by calling
|
||
|
|
sqlite3rebaser_delete().
|
||
|
|
</ol>
|
||
|
|
</p><hr><a name="sqlite3_session"></a>
|
||
|
|
<h2>Session Object Handle</h2><blockquote><pre>typedef struct sqlite3_session sqlite3_session;
|
||
|
|
</pre></blockquote><p>
|
||
|
|
An instance of this object is a <a href="sessionintro.html">session</a> that can be used to
|
||
|
|
record changes to a database.
|
||
|
|
</p><p>Constructor: <a href="#sqlite3session_create">sqlite3session_create()</a></p>
|
||
|
|
<p>Destructor: <a href="#sqlite3session_delete">sqlite3session_delete()</a></p>
|
||
|
|
<div class='columns' style='columns: 17em auto;'>
|
||
|
|
<ul style='padding-top:0;'>
|
||
|
|
<li><a href='#sqlite3session_attach'>sqlite3session_attach</a></li>
|
||
|
|
<li><a href='#sqlite3session_changeset'>sqlite3session_changeset</a></li>
|
||
|
|
<li><a href='#sqlite3session_diff'>sqlite3session_diff</a></li>
|
||
|
|
<li><a href='#sqlite3session_enable'>sqlite3session_enable</a></li>
|
||
|
|
<li><a href='#sqlite3session_indirect'>sqlite3session_indirect</a></li>
|
||
|
|
<li><a href='#sqlite3session_patchset'>sqlite3session_patchset</a></li>
|
||
|
|
<li><a href='#sqlite3session_table_filter'>sqlite3session_table_filter</a></li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</p>
|
||
|
|
<hr><a name="sqlite3changegroup_add"></a>
|
||
|
|
<h2>Add A Changeset To A Changegroup</h2><blockquote><pre>int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pData);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
Add all changes within the changeset (or patchset) in buffer pData (size
|
||
|
|
nData bytes) to the changegroup. </p>
|
||
|
|
|
||
|
|
<p>If the buffer contains a patchset, then all prior calls to this function
|
||
|
|
on the same changegroup object must also have specified patchsets. Or, if
|
||
|
|
the buffer contains a changeset, so must have the earlier calls to this
|
||
|
|
function. Otherwise, SQLITE_ERROR is returned and no changes are added
|
||
|
|
to the changegroup.</p>
|
||
|
|
|
||
|
|
<p>Rows within the changeset and changegroup are identified by the values in
|
||
|
|
their PRIMARY KEY columns. A change in the changeset is considered to
|
||
|
|
apply to the same row as a change already present in the changegroup if
|
||
|
|
the two rows have the same primary key.</p>
|
||
|
|
|
||
|
|
<p>Changes to rows that do not already appear in the changegroup are
|
||
|
|
simply copied into it. Or, if both the new changeset and the changegroup
|
||
|
|
contain changes that apply to a single row, the final contents of the
|
||
|
|
changegroup depends on the type of each change, as follows:</p>
|
||
|
|
|
||
|
|
<p><table border=1 style="margin-left:8ex;margin-right:8ex">
|
||
|
|
<tr><th style="white-space:pre">Existing Change </th>
|
||
|
|
<th style="white-space:pre">New Change </th>
|
||
|
|
<th>Output Change
|
||
|
|
<tr><td>INSERT <td>INSERT <td>
|
||
|
|
The new change is ignored. This case does not occur if the new
|
||
|
|
changeset was recorded immediately after the changesets already
|
||
|
|
added to the changegroup.
|
||
|
|
<tr><td>INSERT <td>UPDATE <td>
|
||
|
|
The INSERT change remains in the changegroup. The values in the
|
||
|
|
INSERT change are modified as if the row was inserted by the
|
||
|
|
existing change and then updated according to the new change.
|
||
|
|
<tr><td>INSERT <td>DELETE <td>
|
||
|
|
The existing INSERT is removed from the changegroup. The DELETE is
|
||
|
|
not added.
|
||
|
|
<tr><td>UPDATE <td>INSERT <td>
|
||
|
|
The new change is ignored. This case does not occur if the new
|
||
|
|
changeset was recorded immediately after the changesets already
|
||
|
|
added to the changegroup.
|
||
|
|
<tr><td>UPDATE <td>UPDATE <td>
|
||
|
|
The existing UPDATE remains within the changegroup. It is amended
|
||
|
|
so that the accompanying values are as if the row was updated once
|
||
|
|
by the existing change and then again by the new change.
|
||
|
|
<tr><td>UPDATE <td>DELETE <td>
|
||
|
|
The existing UPDATE is replaced by the new DELETE within the
|
||
|
|
changegroup.
|
||
|
|
<tr><td>DELETE <td>INSERT <td>
|
||
|
|
If one or more of the column values in the row inserted by the
|
||
|
|
new change differ from those in the row deleted by the existing
|
||
|
|
change, the existing DELETE is replaced by an UPDATE within the
|
||
|
|
changegroup. Otherwise, if the inserted row is exactly the same
|
||
|
|
as the deleted row, the existing DELETE is simply discarded.
|
||
|
|
<tr><td>DELETE <td>UPDATE <td>
|
||
|
|
The new change is ignored. This case does not occur if the new
|
||
|
|
changeset was recorded immediately after the changesets already
|
||
|
|
added to the changegroup.
|
||
|
|
<tr><td>DELETE <td>DELETE <td>
|
||
|
|
The new change is ignored. This case does not occur if the new
|
||
|
|
changeset was recorded immediately after the changesets already
|
||
|
|
added to the changegroup.
|
||
|
|
</table></p>
|
||
|
|
|
||
|
|
<p>If the new changeset contains changes to a table that is already present
|
||
|
|
in the changegroup, then the number of columns and the position of the
|
||
|
|
primary key columns for the table must be consistent. If this is not the
|
||
|
|
case, this function fails with SQLITE_SCHEMA. If the input changeset
|
||
|
|
appears to be corrupt and the corruption is detected, SQLITE_CORRUPT is
|
||
|
|
returned. Or, if an out-of-memory condition occurs during processing, this
|
||
|
|
function returns SQLITE_NOMEM. In all cases, if an error occurs the state
|
||
|
|
of the final contents of the changegroup is undefined.</p>
|
||
|
|
|
||
|
|
<p>If no error occurs, SQLITE_OK is returned.
|
||
|
|
</p><hr><a name="sqlite3changegroup_delete"></a>
|
||
|
|
<h2>Delete A Changegroup Object</h2><blockquote><pre>void sqlite3changegroup_delete(sqlite3_changegroup*);
|
||
|
|
</pre></blockquote><p></p><hr><a name="sqlite3changegroup_new"></a>
|
||
|
|
<h2>Create A New Changegroup Object</h2><blockquote><pre>int sqlite3changegroup_new(sqlite3_changegroup **pp);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
An sqlite3_changegroup object is used to combine two or more changesets
|
||
|
|
(or patchsets) into a single changeset (or patchset). A single changegroup
|
||
|
|
object may combine changesets or patchsets, but not both. The output is
|
||
|
|
always in the same format as the input.</p>
|
||
|
|
|
||
|
|
<p>If successful, this function returns SQLITE_OK and populates (*pp) with
|
||
|
|
a pointer to a new sqlite3_changegroup object before returning. The caller
|
||
|
|
should eventually free the returned object using a call to
|
||
|
|
sqlite3changegroup_delete(). If an error occurs, an SQLite error code
|
||
|
|
(i.e. SQLITE_NOMEM) is returned and *pp is set to NULL.</p>
|
||
|
|
|
||
|
|
<p>The usual usage pattern for an sqlite3_changegroup object is as follows:</p>
|
||
|
|
|
||
|
|
<p><ul>
|
||
|
|
<li> It is created using a call to sqlite3changegroup_new().</p>
|
||
|
|
|
||
|
|
<p> <li> Zero or more changesets (or patchsets) are added to the object
|
||
|
|
by calling sqlite3changegroup_add().</p>
|
||
|
|
|
||
|
|
<p> <li> The result of combining all input changesets together is obtained
|
||
|
|
by the application via a call to sqlite3changegroup_output().</p>
|
||
|
|
|
||
|
|
<p> <li> The object is deleted using a call to sqlite3changegroup_delete().
|
||
|
|
</ul></p>
|
||
|
|
|
||
|
|
<p>Any number of calls to add() and output() may be made between the calls to
|
||
|
|
new() and delete(), and in any order.</p>
|
||
|
|
|
||
|
|
<p>As well as the regular sqlite3changegroup_add() and
|
||
|
|
sqlite3changegroup_output() functions, also available are the streaming
|
||
|
|
versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm().
|
||
|
|
</p><hr><a name="sqlite3changegroup_output"></a>
|
||
|
|
<h2>Obtain A Composite Changeset From A Changegroup</h2><blockquote><pre>int sqlite3changegroup_output(
|
||
|
|
sqlite3_changegroup*,
|
||
|
|
int *pnData, /* OUT: Size of output buffer in bytes */
|
||
|
|
void **ppData /* OUT: Pointer to output buffer */
|
||
|
|
);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
Obtain a buffer containing a changeset (or patchset) representing the
|
||
|
|
current contents of the changegroup. If the inputs to the changegroup
|
||
|
|
were themselves changesets, the output is a changeset. Or, if the
|
||
|
|
inputs were patchsets, the output is also a patchset.</p>
|
||
|
|
|
||
|
|
<p>As with the output of the sqlite3session_changeset() and
|
||
|
|
sqlite3session_patchset() functions, all changes related to a single
|
||
|
|
table are grouped together in the output of this function. Tables appear
|
||
|
|
in the same order as for the very first changeset added to the changegroup.
|
||
|
|
If the second or subsequent changesets added to the changegroup contain
|
||
|
|
changes for tables that do not appear in the first changeset, they are
|
||
|
|
appended onto the end of the output changeset, again in the order in
|
||
|
|
which they are first encountered.</p>
|
||
|
|
|
||
|
|
<p>If an error occurs, an SQLite error code is returned and the output
|
||
|
|
variables (*pnData) and (*ppData) are set to 0. Otherwise, SQLITE_OK
|
||
|
|
is returned and the output variables are set to the size of and a
|
||
|
|
pointer to the output buffer, respectively. In this case it is the
|
||
|
|
responsibility of the caller to eventually free the buffer using a
|
||
|
|
call to sqlite3_free().
|
||
|
|
</p><hr><a name="sqlite3changeset_concat"></a>
|
||
|
|
<h2>Concatenate Two Changeset Objects</h2><blockquote><pre>int sqlite3changeset_concat(
|
||
|
|
int nA, /* Number of bytes in buffer pA */
|
||
|
|
void *pA, /* Pointer to buffer containing changeset A */
|
||
|
|
int nB, /* Number of bytes in buffer pB */
|
||
|
|
void *pB, /* Pointer to buffer containing changeset B */
|
||
|
|
int *pnOut, /* OUT: Number of bytes in output changeset */
|
||
|
|
void **ppOut /* OUT: Buffer containing output changeset */
|
||
|
|
);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
This function is used to concatenate two changesets, A and B, into a
|
||
|
|
single changeset. The result is a changeset equivalent to applying
|
||
|
|
changeset A followed by changeset B. </p>
|
||
|
|
|
||
|
|
<p>This function combines the two input changesets using an
|
||
|
|
sqlite3_changegroup object. Calling it produces similar results as the
|
||
|
|
following code fragment:</p>
|
||
|
|
|
||
|
|
<p><pre>
|
||
|
|
sqlite3_changegroup *pGrp;
|
||
|
|
rc = sqlite3_changegroup_new(&pGrp);
|
||
|
|
if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nA, pA);
|
||
|
|
if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nB, pB);
|
||
|
|
if( rc==SQLITE_OK ){
|
||
|
|
rc = sqlite3changegroup_output(pGrp, pnOut, ppOut);
|
||
|
|
}else{
|
||
|
|
*ppOut = 0;
|
||
|
|
*pnOut = 0;
|
||
|
|
}
|
||
|
|
</pre></p>
|
||
|
|
|
||
|
|
<p>Refer to the sqlite3_changegroup documentation below for details.
|
||
|
|
</p><hr><a name="sqlite3changeset_conflict"></a>
|
||
|
|
<h2>Obtain Conflicting Row Values From A Changeset Iterator</h2><blockquote><pre>int sqlite3changeset_conflict(
|
||
|
|
sqlite3_changeset_iter *pIter, /* Changeset iterator */
|
||
|
|
int iVal, /* Column number */
|
||
|
|
sqlite3_value **ppValue /* OUT: Value from conflicting row */
|
||
|
|
);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
This function should only be used with iterator objects passed to a
|
||
|
|
conflict-handler callback by <a href="#sqlite3changeset_apply">sqlite3changeset_apply()</a> with either
|
||
|
|
<a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_DATA</a> or <a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_CONFLICT</a>. If this function
|
||
|
|
is called on any other iterator, <a href="rescode.html#misuse">SQLITE_MISUSE</a> is returned and *ppValue
|
||
|
|
is set to NULL.</p>
|
||
|
|
|
||
|
|
<p>Argument iVal must be greater than or equal to 0, and less than the number
|
||
|
|
of columns in the table affected by the current change. Otherwise,
|
||
|
|
<a href="rescode.html#range">SQLITE_RANGE</a> is returned and *ppValue is set to NULL.</p>
|
||
|
|
|
||
|
|
<p>If successful, this function sets *ppValue to point to a protected
|
||
|
|
sqlite3_value object containing the iVal'th value from the
|
||
|
|
"conflicting row" associated with the current conflict-handler callback
|
||
|
|
and returns SQLITE_OK.</p>
|
||
|
|
|
||
|
|
<p>If some other error occurs (e.g. an OOM condition), an SQLite error code
|
||
|
|
is returned and *ppValue is set to NULL.
|
||
|
|
</p><hr><a name="sqlite3changeset_finalize"></a>
|
||
|
|
<h2>Finalize A Changeset Iterator</h2><blockquote><pre>int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
This function is used to finalize an iterator allocated with
|
||
|
|
<a href="#sqlite3changeset_start">sqlite3changeset_start()</a>.</p>
|
||
|
|
|
||
|
|
<p>This function should only be called on iterators created using the
|
||
|
|
<a href="#sqlite3changeset_start">sqlite3changeset_start()</a> function. If an application calls this
|
||
|
|
function with an iterator passed to a conflict-handler by
|
||
|
|
<a href="#sqlite3changeset_apply">sqlite3changeset_apply()</a>, <a href="rescode.html#misuse">SQLITE_MISUSE</a> is immediately returned and the
|
||
|
|
call has no effect.</p>
|
||
|
|
|
||
|
|
<p>If an error was encountered within a call to an sqlite3changeset_xxx()
|
||
|
|
function (for example an <a href="rescode.html#corrupt">SQLITE_CORRUPT</a> in <a href="#sqlite3changeset_next">sqlite3changeset_next()</a> or an
|
||
|
|
<a href="rescode.html#nomem">SQLITE_NOMEM</a> in <a href="#sqlite3changeset_new">sqlite3changeset_new()</a>) then an error code corresponding
|
||
|
|
to that error is returned by this function. Otherwise, SQLITE_OK is
|
||
|
|
returned. This is to allow the following pattern (pseudo-code):</p>
|
||
|
|
|
||
|
|
<p><pre>
|
||
|
|
sqlite3changeset_start();
|
||
|
|
while( SQLITE_ROW==sqlite3changeset_next() ){
|
||
|
|
// Do something with change.
|
||
|
|
}
|
||
|
|
rc = sqlite3changeset_finalize();
|
||
|
|
if( rc!=SQLITE_OK ){
|
||
|
|
// An error has occurred
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
</p><hr><a name="sqlite3changeset_fk_conflicts"></a>
|
||
|
|
<h2>Determine The Number Of Foreign Key Constraint Violations</h2><blockquote><pre>int sqlite3changeset_fk_conflicts(
|
||
|
|
sqlite3_changeset_iter *pIter, /* Changeset iterator */
|
||
|
|
int *pnOut /* OUT: Number of FK violations */
|
||
|
|
);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
This function may only be called with an iterator passed to an
|
||
|
|
SQLITE_CHANGESET_FOREIGN_KEY conflict handler callback. In this case
|
||
|
|
it sets the output variable to the total number of known foreign key
|
||
|
|
violations in the destination database and returns SQLITE_OK.</p>
|
||
|
|
|
||
|
|
<p>In all other cases this function returns SQLITE_MISUSE.
|
||
|
|
</p><hr><a name="sqlite3changeset_invert"></a>
|
||
|
|
<h2>Invert A Changeset</h2><blockquote><pre>int sqlite3changeset_invert(
|
||
|
|
int nIn, const void *pIn, /* Input changeset */
|
||
|
|
int *pnOut, void **ppOut /* OUT: Inverse of input */
|
||
|
|
);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
This function is used to "invert" a changeset object. Applying an inverted
|
||
|
|
changeset to a database reverses the effects of applying the uninverted
|
||
|
|
changeset. Specifically:</p>
|
||
|
|
|
||
|
|
<p><ul>
|
||
|
|
<li> Each DELETE change is changed to an INSERT, and
|
||
|
|
<li> Each INSERT change is changed to a DELETE, and
|
||
|
|
<li> For each UPDATE change, the old.* and new.* values are exchanged.
|
||
|
|
</ul></p>
|
||
|
|
|
||
|
|
<p>This function does not change the order in which changes appear within
|
||
|
|
the changeset. It merely reverses the sense of each individual change.</p>
|
||
|
|
|
||
|
|
<p>If successful, a pointer to a buffer containing the inverted changeset
|
||
|
|
is stored in *ppOut, the size of the same buffer is stored in *pnOut, and
|
||
|
|
SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are
|
||
|
|
zeroed and an SQLite error code returned.</p>
|
||
|
|
|
||
|
|
<p>It is the responsibility of the caller to eventually call sqlite3_free()
|
||
|
|
on the *ppOut pointer to free the buffer allocation following a successful
|
||
|
|
call to this function.</p>
|
||
|
|
|
||
|
|
<p>WARNING/TODO: This function currently assumes that the input is a valid
|
||
|
|
changeset. If it is not, the results are undefined.
|
||
|
|
</p><hr><a name="sqlite3changeset_new"></a>
|
||
|
|
<h2>Obtain new.* Values From A Changeset Iterator</h2><blockquote><pre>int sqlite3changeset_new(
|
||
|
|
sqlite3_changeset_iter *pIter, /* Changeset iterator */
|
||
|
|
int iVal, /* Column number */
|
||
|
|
sqlite3_value **ppValue /* OUT: New value (or NULL pointer) */
|
||
|
|
);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
The pIter argument passed to this function may either be an iterator
|
||
|
|
passed to a conflict-handler by <a href="#sqlite3changeset_apply">sqlite3changeset_apply()</a>, or an iterator
|
||
|
|
created by <a href="#sqlite3changeset_start">sqlite3changeset_start()</a>. In the latter case, the most recent
|
||
|
|
call to <a href="#sqlite3changeset_next">sqlite3changeset_next()</a> must have returned SQLITE_ROW.
|
||
|
|
Furthermore, it may only be called if the type of change that the iterator
|
||
|
|
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,
|
||
|
|
this function returns <a href="rescode.html#misuse">SQLITE_MISUSE</a> and sets *ppValue to NULL.</p>
|
||
|
|
|
||
|
|
<p>Argument iVal must be greater than or equal to 0, and less than the number
|
||
|
|
of columns in the table affected by the current change. Otherwise,
|
||
|
|
<a href="rescode.html#range">SQLITE_RANGE</a> is returned and *ppValue is set to NULL.</p>
|
||
|
|
|
||
|
|
<p>If successful, this function sets *ppValue to point to a protected
|
||
|
|
sqlite3_value object containing the iVal'th value from the vector of
|
||
|
|
new row values stored as part of the UPDATE or INSERT change and
|
||
|
|
returns SQLITE_OK. If the change is an UPDATE and does not include
|
||
|
|
a new value for the requested column, *ppValue is set to NULL and
|
||
|
|
SQLITE_OK returned. The name of the function comes from the fact that
|
||
|
|
this is similar to the "new.*" columns available to update or delete
|
||
|
|
triggers.</p>
|
||
|
|
|
||
|
|
<p>If some other error occurs (e.g. an OOM condition), an SQLite error code
|
||
|
|
is returned and *ppValue is set to NULL.
|
||
|
|
</p><hr><a name="sqlite3changeset_next"></a>
|
||
|
|
<h2>Advance A Changeset Iterator</h2><blockquote><pre>int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
This function may only be used with iterators created by the function
|
||
|
|
<a href="#sqlite3changeset_start">sqlite3changeset_start()</a>. If it is called on an iterator passed to
|
||
|
|
a conflict-handler callback by <a href="#sqlite3changeset_apply">sqlite3changeset_apply()</a>, SQLITE_MISUSE
|
||
|
|
is returned and the call has no effect.</p>
|
||
|
|
|
||
|
|
<p>Immediately after an iterator is created by sqlite3changeset_start(), it
|
||
|
|
does not point to any change in the changeset. Assuming the changeset
|
||
|
|
is not empty, the first call to this function advances the iterator to
|
||
|
|
point to the first change in the changeset. Each subsequent call advances
|
||
|
|
the iterator to point to the next change in the changeset (if any). If
|
||
|
|
no error occurs and the iterator points to a valid change after a call
|
||
|
|
to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned.
|
||
|
|
Otherwise, if all changes in the changeset have already been visited,
|
||
|
|
SQLITE_DONE is returned.</p>
|
||
|
|
|
||
|
|
<p>If an error occurs, an SQLite error code is returned. Possible error
|
||
|
|
codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or
|
||
|
|
SQLITE_NOMEM.
|
||
|
|
</p><hr><a name="sqlite3changeset_old"></a>
|
||
|
|
<h2>Obtain old.* Values From A Changeset Iterator</h2><blockquote><pre>int sqlite3changeset_old(
|
||
|
|
sqlite3_changeset_iter *pIter, /* Changeset iterator */
|
||
|
|
int iVal, /* Column number */
|
||
|
|
sqlite3_value **ppValue /* OUT: Old value (or NULL pointer) */
|
||
|
|
);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
The pIter argument passed to this function may either be an iterator
|
||
|
|
passed to a conflict-handler by <a href="#sqlite3changeset_apply">sqlite3changeset_apply()</a>, or an iterator
|
||
|
|
created by <a href="#sqlite3changeset_start">sqlite3changeset_start()</a>. In the latter case, the most recent
|
||
|
|
call to <a href="#sqlite3changeset_next">sqlite3changeset_next()</a> must have returned SQLITE_ROW.
|
||
|
|
Furthermore, it may only be called if the type of change that the iterator
|
||
|
|
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,
|
||
|
|
this function returns <a href="rescode.html#misuse">SQLITE_MISUSE</a> and sets *ppValue to NULL.</p>
|
||
|
|
|
||
|
|
<p>Argument iVal must be greater than or equal to 0, and less than the number
|
||
|
|
of columns in the table affected by the current change. Otherwise,
|
||
|
|
<a href="rescode.html#range">SQLITE_RANGE</a> is returned and *ppValue is set to NULL.</p>
|
||
|
|
|
||
|
|
<p>If successful, this function sets *ppValue to point to a protected
|
||
|
|
sqlite3_value object containing the iVal'th value from the vector of
|
||
|
|
original row values stored as part of the UPDATE or DELETE change and
|
||
|
|
returns SQLITE_OK. The name of the function comes from the fact that this
|
||
|
|
is similar to the "old.*" columns available to update or delete triggers.</p>
|
||
|
|
|
||
|
|
<p>If some other error occurs (e.g. an OOM condition), an SQLite error code
|
||
|
|
is returned and *ppValue is set to NULL.
|
||
|
|
</p><hr><a name="sqlite3changeset_op"></a>
|
||
|
|
<h2>Obtain The Current Operation From A Changeset Iterator</h2><blockquote><pre>int sqlite3changeset_op(
|
||
|
|
sqlite3_changeset_iter *pIter, /* Iterator object */
|
||
|
|
const char **pzTab, /* OUT: Pointer to table name */
|
||
|
|
int *pnCol, /* OUT: Number of columns in table */
|
||
|
|
int *pOp, /* OUT: SQLITE_INSERT, DELETE or UPDATE */
|
||
|
|
int *pbIndirect /* OUT: True for an 'indirect' change */
|
||
|
|
);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
The pIter argument passed to this function may either be an iterator
|
||
|
|
passed to a conflict-handler by <a href="#sqlite3changeset_apply">sqlite3changeset_apply()</a>, or an iterator
|
||
|
|
created by <a href="#sqlite3changeset_start">sqlite3changeset_start()</a>. In the latter case, the most recent
|
||
|
|
call to <a href="#sqlite3changeset_next">sqlite3changeset_next()</a> must have returned <a href="rescode.html#row">SQLITE_ROW</a>. If this
|
||
|
|
is not the case, this function returns <a href="rescode.html#misuse">SQLITE_MISUSE</a>.</p>
|
||
|
|
|
||
|
|
<p>If argument pzTab is not NULL, then *pzTab is set to point to a
|
||
|
|
nul-terminated utf-8 encoded string containing the name of the table
|
||
|
|
affected by the current change. The buffer remains valid until either
|
||
|
|
sqlite3changeset_next() is called on the iterator or until the
|
||
|
|
conflict-handler function returns. If pnCol is not NULL, then *pnCol is
|
||
|
|
set to the number of columns in the table affected by the change. If
|
||
|
|
pbIndirect is not NULL, then *pbIndirect is set to true (1) if the change
|
||
|
|
is an indirect change, or false (0) otherwise. See the documentation for
|
||
|
|
<a href="#sqlite3session_indirect">sqlite3session_indirect()</a> for a description of direct and indirect
|
||
|
|
changes. Finally, if pOp is not NULL, then *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>, depending on the
|
||
|
|
type of change that the iterator currently points to.</p>
|
||
|
|
|
||
|
|
<p>If no error occurs, SQLITE_OK is returned. If an error does occur, an
|
||
|
|
SQLite error code is returned. The values of the output variables may not
|
||
|
|
be trusted in this case.
|
||
|
|
</p><hr><a name="sqlite3changeset_pk"></a>
|
||
|
|
<h2>Obtain The Primary Key Definition Of A Table</h2><blockquote><pre>int sqlite3changeset_pk(
|
||
|
|
sqlite3_changeset_iter *pIter, /* Iterator object */
|
||
|
|
unsigned char **pabPK, /* OUT: Array of boolean - true for PK cols */
|
||
|
|
int *pnCol /* OUT: Number of entries in output array */
|
||
|
|
);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
For each modified table, a changeset includes the following:</p>
|
||
|
|
|
||
|
|
<p><ul>
|
||
|
|
<li> The number of columns in the table, and
|
||
|
|
<li> Which of those columns make up the tables PRIMARY KEY.
|
||
|
|
</ul></p>
|
||
|
|
|
||
|
|
<p>This function is used to find which columns comprise the PRIMARY KEY of
|
||
|
|
the table modified by the change that iterator pIter currently points to.
|
||
|
|
If successful, *pabPK is set to point to an array of nCol entries, where
|
||
|
|
nCol is the number of columns in the table. Elements of *pabPK are set to
|
||
|
|
0x01 if the corresponding column is part of the tables primary key, or
|
||
|
|
0x00 if it is not.</p>
|
||
|
|
|
||
|
|
<p>If argument pnCol is not NULL, then *pnCol is set to the number of columns
|
||
|
|
in the table.</p>
|
||
|
|
|
||
|
|
<p>If this function is called when the iterator does not point to a valid
|
||
|
|
entry, SQLITE_MISUSE is returned and the output variables zeroed. Otherwise,
|
||
|
|
SQLITE_OK is returned and the output variables populated as described
|
||
|
|
above.
|
||
|
|
</p><hr><a name="sqlite3rebaser_configure"></a>
|
||
|
|
<h2>Configure a changeset rebaser object.</h2><blockquote><pre>int sqlite3rebaser_configure(
|
||
|
|
sqlite3_rebaser*,
|
||
|
|
int nRebase, const void *pRebase
|
||
|
|
);
|
||
|
|
</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>
|
||
|
|
Configure the changeset rebaser object to rebase changesets according
|
||
|
|
to the conflict resolutions described by buffer pRebase (size nRebase
|
||
|
|
bytes), which must have been obtained from a previous call to
|
||
|
|
sqlite3changeset_apply_v2().
|
||
|
|
</p><hr><a name="sqlite3rebaser_create"></a>
|
||
|
|
<h2>Create a changeset rebaser object.</h2><blockquote><pre>int sqlite3rebaser_create(sqlite3_rebaser **ppNew);
|
||
|
|
</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>
|
||
|
|
Allocate a new changeset rebaser object. If successful, set (*ppNew) to
|
||
|
|
point to the new object and return SQLITE_OK. Otherwise, if an error
|
||
|
|
occurs, return an SQLite error code (e.g. SQLITE_NOMEM) and set (*ppNew)
|
||
|
|
to NULL.
|
||
|
|
</p><hr><a name="sqlite3rebaser_delete"></a>
|
||
|
|
<h2>Delete a changeset rebaser object.</h2><blockquote><pre>void sqlite3rebaser_delete(sqlite3_rebaser *p);
|
||
|
|
</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>
|
||
|
|
Delete the changeset rebaser object and all associated resources. There
|
||
|
|
should be one call to this function for each successful invocation
|
||
|
|
of sqlite3rebaser_create().
|
||
|
|
</p><hr><a name="sqlite3rebaser_rebase"></a>
|
||
|
|
<h2>Rebase a changeset</h2><blockquote><pre>int sqlite3rebaser_rebase(
|
||
|
|
sqlite3_rebaser*,
|
||
|
|
int nIn, const void *pIn,
|
||
|
|
int *pnOut, void **ppOut
|
||
|
|
);
|
||
|
|
</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>
|
||
|
|
Argument pIn must point to a buffer containing a changeset nIn bytes
|
||
|
|
in size. This function allocates and populates a buffer with a copy
|
||
|
|
of the changeset rebased according to the configuration of the
|
||
|
|
rebaser object passed as the first argument. If successful, (*ppOut)
|
||
|
|
is set to point to the new buffer containing the rebased changeset and
|
||
|
|
(*pnOut) to its size in bytes and SQLITE_OK returned. It is the
|
||
|
|
responsibility of the caller to eventually free the new buffer using
|
||
|
|
sqlite3_free(). Otherwise, if an error occurs, (*ppOut) and (*pnOut)
|
||
|
|
are set to zero and an SQLite error code returned.
|
||
|
|
</p><hr><a name="sqlite3session_attach"></a>
|
||
|
|
<h2>Attach A Table To A Session Object</h2><blockquote><pre>int sqlite3session_attach(
|
||
|
|
sqlite3_session *pSession, /* Session object */
|
||
|
|
const char *zTab /* Table name */
|
||
|
|
);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
If argument zTab is not NULL, then it is the name of a table to attach
|
||
|
|
to the session object passed as the first argument. All subsequent changes
|
||
|
|
made to the table while the session object is enabled will be recorded. See
|
||
|
|
documentation for <a href="#sqlite3session_changeset">sqlite3session_changeset()</a> for further details.</p>
|
||
|
|
|
||
|
|
<p>Or, if argument zTab is NULL, then changes are recorded for all tables
|
||
|
|
in the database. If additional tables are added to the database (by
|
||
|
|
executing "CREATE TABLE" statements) after this call is made, changes for
|
||
|
|
the new tables are also recorded.</p>
|
||
|
|
|
||
|
|
<p>Changes can only be recorded for tables that have a PRIMARY KEY explicitly
|
||
|
|
defined as part of their CREATE TABLE statement. It does not matter if the
|
||
|
|
PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY
|
||
|
|
KEY may consist of a single column, or may be a composite key.</p>
|
||
|
|
|
||
|
|
<p>It is not an error if the named table does not exist in the database. Nor
|
||
|
|
is it an error if the named table does not have a PRIMARY KEY. However,
|
||
|
|
no changes will be recorded in either of these scenarios.</p>
|
||
|
|
|
||
|
|
<p>Changes are not recorded for individual rows that have NULL values stored
|
||
|
|
in one or more of their PRIMARY KEY columns.</p>
|
||
|
|
|
||
|
|
<p>SQLITE_OK is returned if the call completes without error. Or, if an error
|
||
|
|
occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.</p>
|
||
|
|
|
||
|
|
<p><h3>Special sqlite_stat1 Handling</h3></p>
|
||
|
|
|
||
|
|
<p>As of SQLite version 3.22.0, the "sqlite_stat1" table is an exception to
|
||
|
|
some of the rules above. In SQLite, the schema of sqlite_stat1 is:
|
||
|
|
<pre>
|
||
|
|
CREATE TABLE sqlite_stat1(tbl,idx,stat)
|
||
|
|
</pre></p>
|
||
|
|
|
||
|
|
<p>Even though sqlite_stat1 does not have a PRIMARY KEY, changes are
|
||
|
|
recorded for it as if the PRIMARY KEY is (tbl,idx). Additionally, changes
|
||
|
|
are recorded for rows for which (idx IS NULL) is true. However, for such
|
||
|
|
rows a zero-length blob (SQL value X'') is stored in the changeset or
|
||
|
|
patchset instead of a NULL value. This allows such changesets to be
|
||
|
|
manipulated by legacy implementations of sqlite3changeset_invert(),
|
||
|
|
concat() and similar.</p>
|
||
|
|
|
||
|
|
<p>The sqlite3changeset_apply() function automatically converts the
|
||
|
|
zero-length blob back to a NULL value when updating the sqlite_stat1
|
||
|
|
table. However, if the application calls sqlite3changeset_new(),
|
||
|
|
sqlite3changeset_old() or sqlite3changeset_conflict on a changeset
|
||
|
|
iterator directly (including on a changeset iterator passed to a
|
||
|
|
conflict-handler callback) then the X'' value is returned. The application
|
||
|
|
must translate X'' to NULL itself if required.</p>
|
||
|
|
|
||
|
|
<p>Legacy (older than 3.22.0) versions of the sessions module cannot capture
|
||
|
|
changes made to the sqlite_stat1 table. Legacy versions of the
|
||
|
|
sqlite3changeset_apply() function silently ignore any modifications to the
|
||
|
|
sqlite_stat1 table that are part of a changeset or patchset.
|
||
|
|
</p><hr><a name="sqlite3session_changeset"></a>
|
||
|
|
<h2>Generate A Changeset From A Session Object</h2><blockquote><pre>int sqlite3session_changeset(
|
||
|
|
sqlite3_session *pSession, /* Session object */
|
||
|
|
int *pnChangeset, /* OUT: Size of buffer at *ppChangeset */
|
||
|
|
void **ppChangeset /* OUT: Buffer containing changeset */
|
||
|
|
);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
Obtain a changeset containing changes to the tables attached to the
|
||
|
|
session object passed as the first argument. If successful,
|
||
|
|
set *ppChangeset to point to a buffer containing the changeset
|
||
|
|
and *pnChangeset to the size of the changeset in bytes before returning
|
||
|
|
SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to
|
||
|
|
zero and return an SQLite error code.</p>
|
||
|
|
|
||
|
|
<p>A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes,
|
||
|
|
each representing a change to a single row of an attached table. An INSERT
|
||
|
|
change contains the values of each field of a new database row. A DELETE
|
||
|
|
contains the original values of each field of a deleted database row. An
|
||
|
|
UPDATE change contains the original values of each field of an updated
|
||
|
|
database row along with the updated values for each updated non-primary-key
|
||
|
|
column. It is not possible for an UPDATE change to represent a change that
|
||
|
|
modifies the values of primary key columns. If such a change is made, it
|
||
|
|
is represented in a changeset as a DELETE followed by an INSERT.</p>
|
||
|
|
|
||
|
|
<p>Changes are not recorded for rows that have NULL values stored in one or
|
||
|
|
more of their PRIMARY KEY columns. If such a row is inserted or deleted,
|
||
|
|
no corresponding change is present in the changesets returned by this
|
||
|
|
function. If an existing row with one or more NULL values stored in
|
||
|
|
PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL,
|
||
|
|
only an INSERT is appears in the changeset. Similarly, if an existing row
|
||
|
|
with non-NULL PRIMARY KEY values is updated so that one or more of its
|
||
|
|
PRIMARY KEY columns are set to NULL, the resulting changeset contains a
|
||
|
|
DELETE change only.</p>
|
||
|
|
|
||
|
|
<p>The contents of a changeset may be traversed using an iterator created
|
||
|
|
using the <a href="#sqlite3changeset_start">sqlite3changeset_start()</a> API. A changeset may be applied to
|
||
|
|
a database with a compatible schema using the <a href="#sqlite3changeset_apply">sqlite3changeset_apply()</a>
|
||
|
|
API.</p>
|
||
|
|
|
||
|
|
<p>Within a changeset generated by this function, all changes related to a
|
||
|
|
single table are grouped together. In other words, when iterating through
|
||
|
|
a changeset or when applying a changeset to a database, all changes related
|
||
|
|
to a single table are processed before moving on to the next table. Tables
|
||
|
|
are sorted in the same order in which they were attached (or auto-attached)
|
||
|
|
to the sqlite3_session object. The order in which the changes related to
|
||
|
|
a single table are stored is undefined.</p>
|
||
|
|
|
||
|
|
<p>Following a successful call to this function, it is the responsibility of
|
||
|
|
the caller to eventually free the buffer that *ppChangeset points to using
|
||
|
|
<a href="c3ref/free.html">sqlite3_free()</a>.</p>
|
||
|
|
|
||
|
|
<p><h3>Changeset Generation</h3></p>
|
||
|
|
|
||
|
|
<p>Once a table has been attached to a session object, the session object
|
||
|
|
records the primary key values of all new rows inserted into the table.
|
||
|
|
It also records the original primary key and other column values of any
|
||
|
|
deleted or updated rows. For each unique primary key value, data is only
|
||
|
|
recorded once - the first time a row with said primary key is inserted,
|
||
|
|
updated or deleted in the lifetime of the session.</p>
|
||
|
|
|
||
|
|
<p>There is one exception to the previous paragraph: when a row is inserted,
|
||
|
|
updated or deleted, if one or more of its primary key columns contain a
|
||
|
|
NULL value, no record of the change is made.</p>
|
||
|
|
|
||
|
|
<p>The session object therefore accumulates two types of records - those
|
||
|
|
that consist of primary key values only (created when the user inserts
|
||
|
|
a new record) and those that consist of the primary key values and the
|
||
|
|
original values of other table columns (created when the users deletes
|
||
|
|
or updates a record).</p>
|
||
|
|
|
||
|
|
<p>When this function is called, the requested changeset is created using
|
||
|
|
both the accumulated records and the current contents of the database
|
||
|
|
file. Specifically:</p>
|
||
|
|
|
||
|
|
<p><ul>
|
||
|
|
<li> For each record generated by an insert, the database is queried
|
||
|
|
for a row with a matching primary key. If one is found, an INSERT
|
||
|
|
change is added to the changeset. If no such row is found, no change
|
||
|
|
is added to the changeset.</p>
|
||
|
|
|
||
|
|
<p> <li> For each record generated by an update or delete, the database is
|
||
|
|
queried for a row with a matching primary key. If such a row is
|
||
|
|
found and one or more of the non-primary key fields have been
|
||
|
|
modified from their original values, an UPDATE change is added to
|
||
|
|
the changeset. Or, if no such row is found in the table, a DELETE
|
||
|
|
change is added to the changeset. If there is a row with a matching
|
||
|
|
primary key in the database, but all fields contain their original
|
||
|
|
values, no change is added to the changeset.
|
||
|
|
</ul></p>
|
||
|
|
|
||
|
|
<p>This means, amongst other things, that if a row is inserted and then later
|
||
|
|
deleted while a session object is active, neither the insert nor the delete
|
||
|
|
will be present in the changeset. Or if a row is deleted and then later a
|
||
|
|
row with the same primary key values inserted while a session object is
|
||
|
|
active, the resulting changeset will contain an UPDATE change instead of
|
||
|
|
a DELETE and an INSERT.</p>
|
||
|
|
|
||
|
|
<p>When a session object is disabled (see the <a href="#sqlite3session_enable">sqlite3session_enable()</a> API),
|
||
|
|
it does not accumulate records when rows are inserted, updated or deleted.
|
||
|
|
This may appear to have some counter-intuitive effects if a single row
|
||
|
|
is written to more than once during a session. For example, if a row
|
||
|
|
is inserted while a session object is enabled, then later deleted while
|
||
|
|
the same session object is disabled, no INSERT record will appear in the
|
||
|
|
changeset, even though the delete took place while the session was disabled.
|
||
|
|
Or, if one field of a row is updated while a session is disabled, and
|
||
|
|
another field of the same row is updated while the session is enabled, the
|
||
|
|
resulting changeset will contain an UPDATE change that updates both fields.
|
||
|
|
</p><hr><a name="sqlite3session_config"></a>
|
||
|
|
<h2>Configure global parameters</h2><blockquote><pre>int sqlite3session_config(int op, void *pArg);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
The sqlite3session_config() interface is used to make global configuration
|
||
|
|
changes to the sessions module in order to tune it to the specific needs
|
||
|
|
of the application.</p>
|
||
|
|
|
||
|
|
<p>The sqlite3session_config() interface is not threadsafe. If it is invoked
|
||
|
|
while any other thread is inside any other sessions method then the
|
||
|
|
results are undefined. Furthermore, if it is invoked after any sessions
|
||
|
|
related objects have been created, the results are also undefined. </p>
|
||
|
|
|
||
|
|
<p>The first argument to the sqlite3session_config() function must be one
|
||
|
|
of the SQLITE_SESSION_CONFIG_XXX constants defined below. The
|
||
|
|
interpretation of the (void*) value passed as the second parameter and
|
||
|
|
the effect of calling this function depends on the value of the first
|
||
|
|
parameter.</p>
|
||
|
|
|
||
|
|
<p><dl>
|
||
|
|
<dt>SQLITE_SESSION_CONFIG_STRMSIZE<dd>
|
||
|
|
By default, the sessions module streaming interfaces attempt to input
|
||
|
|
and output data in approximately 1 KiB chunks. This operand may be used
|
||
|
|
to set and query the value of this configuration setting. The pointer
|
||
|
|
passed as the second argument must point to a value of type (int).
|
||
|
|
If this value is greater than 0, it is used as the new streaming data
|
||
|
|
chunk size for both input and output. Before returning, the (int) value
|
||
|
|
pointed to by pArg is set to the final value of the streaming interface
|
||
|
|
chunk size.
|
||
|
|
</dl></p>
|
||
|
|
|
||
|
|
<p>This function returns SQLITE_OK if successful, or an SQLite error code
|
||
|
|
otherwise.
|
||
|
|
</p><hr><a name="sqlite3session_create"></a>
|
||
|
|
<h2>Create A New Session Object</h2><blockquote><pre>int sqlite3session_create(
|
||
|
|
sqlite3 *db, /* Database handle */
|
||
|
|
const char *zDb, /* Name of db (e.g. "main") */
|
||
|
|
sqlite3_session **ppSession /* OUT: New session object */
|
||
|
|
);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
Create a new session object attached to database handle db. If successful,
|
||
|
|
a pointer to the new object is written to *ppSession and SQLITE_OK is
|
||
|
|
returned. If an error occurs, *ppSession is set to NULL and an SQLite
|
||
|
|
error code (e.g. SQLITE_NOMEM) is returned.</p>
|
||
|
|
|
||
|
|
<p>It is possible to create multiple session objects attached to a single
|
||
|
|
database handle.</p>
|
||
|
|
|
||
|
|
<p>Session objects created using this function should be deleted using the
|
||
|
|
<a href="#sqlite3session_delete">sqlite3session_delete()</a> function before the database handle that they
|
||
|
|
are attached to is itself closed. If the database handle is closed before
|
||
|
|
the session object is deleted, then the results of calling any session
|
||
|
|
module function, including <a href="#sqlite3session_delete">sqlite3session_delete()</a> on the session object
|
||
|
|
are undefined.</p>
|
||
|
|
|
||
|
|
<p>Because the session module uses the <a href="c3ref/preupdate_count.html">sqlite3_preupdate_hook()</a> API, it
|
||
|
|
is not possible for an application to register a pre-update hook on a
|
||
|
|
database handle that has one or more session objects attached. Nor is
|
||
|
|
it possible to create a session object attached to a database handle for
|
||
|
|
which a pre-update hook is already defined. The results of attempting
|
||
|
|
either of these things are undefined.</p>
|
||
|
|
|
||
|
|
<p>The session object will be used to create changesets for tables in
|
||
|
|
database zDb, where zDb is either "main", or "temp", or the name of an
|
||
|
|
attached database. It is not an error if database zDb is not attached
|
||
|
|
to the database when the session object is created.
|
||
|
|
</p><hr><a name="sqlite3session_delete"></a>
|
||
|
|
<h2>Delete A Session Object</h2><blockquote><pre>void sqlite3session_delete(sqlite3_session *pSession);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
Delete a session object previously allocated using
|
||
|
|
<a href="#sqlite3session_create">sqlite3session_create()</a>. Once a session object has been deleted, the
|
||
|
|
results of attempting to use pSession with any other session module
|
||
|
|
function are undefined.</p>
|
||
|
|
|
||
|
|
<p>Session objects must be deleted before the database handle to which they
|
||
|
|
are attached is closed. Refer to the documentation for
|
||
|
|
<a href="#sqlite3session_create">sqlite3session_create()</a> for details.
|
||
|
|
</p><hr><a name="sqlite3session_diff"></a>
|
||
|
|
<h2>Load The Difference Between Tables Into A Session</h2><blockquote><pre>int sqlite3session_diff(
|
||
|
|
sqlite3_session *pSession,
|
||
|
|
const char *zFromDb,
|
||
|
|
const char *zTbl,
|
||
|
|
char **pzErrMsg
|
||
|
|
);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
If it is not already attached to the session object passed as the first
|
||
|
|
argument, this function attaches table zTbl in the same manner as the
|
||
|
|
<a href="#sqlite3session_attach">sqlite3session_attach()</a> function. If zTbl does not exist, or if it
|
||
|
|
does not have a primary key, this function is a no-op (but does not return
|
||
|
|
an error).</p>
|
||
|
|
|
||
|
|
<p>Argument zFromDb must be the name of a database ("main", "temp" etc.)
|
||
|
|
attached to the same database handle as the session object that contains
|
||
|
|
a table compatible with the table attached to the session by this function.
|
||
|
|
A table is considered compatible if it:</p>
|
||
|
|
|
||
|
|
<p><ul>
|
||
|
|
<li> Has the same name,
|
||
|
|
<li> Has the same set of columns declared in the same order, and
|
||
|
|
<li> Has the same PRIMARY KEY definition.
|
||
|
|
</ul></p>
|
||
|
|
|
||
|
|
<p>If the tables are not compatible, SQLITE_SCHEMA is returned. If the tables
|
||
|
|
are compatible but do not have any PRIMARY KEY columns, it is not an error
|
||
|
|
but no changes are added to the session object. As with other session
|
||
|
|
APIs, tables without PRIMARY KEYs are simply ignored.</p>
|
||
|
|
|
||
|
|
<p>This function adds a set of changes to the session object that could be
|
||
|
|
used to update the table in database zFrom (call this the "from-table")
|
||
|
|
so that its content is the same as the table attached to the session
|
||
|
|
object (call this the "to-table"). Specifically:</p>
|
||
|
|
|
||
|
|
<p><ul>
|
||
|
|
<li> For each row (primary key) that exists in the to-table but not in
|
||
|
|
the from-table, an INSERT record is added to the session object.</p>
|
||
|
|
|
||
|
|
<p> <li> For each row (primary key) that exists in the to-table but not in
|
||
|
|
the from-table, a DELETE record is added to the session object.</p>
|
||
|
|
|
||
|
|
<p> <li> For each row (primary key) that exists in both tables, but features
|
||
|
|
different non-PK values in each, an UPDATE record is added to the
|
||
|
|
session.
|
||
|
|
</ul></p>
|
||
|
|
|
||
|
|
<p>To clarify, if this function is called and then a changeset constructed
|
||
|
|
using <a href="#sqlite3session_changeset">sqlite3session_changeset()</a>, then after applying that changeset to
|
||
|
|
database zFrom the contents of the two compatible tables would be
|
||
|
|
identical.</p>
|
||
|
|
|
||
|
|
<p>It an error if database zFrom does not exist or does not contain the
|
||
|
|
required compatible table.</p>
|
||
|
|
|
||
|
|
<p>If the operation is successful, SQLITE_OK is returned. Otherwise, an SQLite
|
||
|
|
error code. In this case, if argument pzErrMsg is not NULL, *pzErrMsg
|
||
|
|
may be set to point to a buffer containing an English language error
|
||
|
|
message. It is the responsibility of the caller to free this buffer using
|
||
|
|
sqlite3_free().
|
||
|
|
</p><hr><a name="sqlite3session_enable"></a>
|
||
|
|
<h2>Enable Or Disable A Session Object</h2><blockquote><pre>int sqlite3session_enable(sqlite3_session *pSession, int bEnable);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
Enable or disable the recording of changes by a session object. When
|
||
|
|
enabled, a session object records changes made to the database. When
|
||
|
|
disabled - it does not. A newly created session object is enabled.
|
||
|
|
Refer to the documentation for <a href="#sqlite3session_changeset">sqlite3session_changeset()</a> for further
|
||
|
|
details regarding how enabling and disabling a session object affects
|
||
|
|
the eventual changesets.</p>
|
||
|
|
|
||
|
|
<p>Passing zero to this function disables the session. Passing a value
|
||
|
|
greater than zero enables it. Passing a value less than zero is a
|
||
|
|
no-op, and may be used to query the current state of the session.</p>
|
||
|
|
|
||
|
|
<p>The return value indicates the final state of the session object: 0 if
|
||
|
|
the session is disabled, or 1 if it is enabled.
|
||
|
|
</p><hr><a name="sqlite3session_indirect"></a>
|
||
|
|
<h2>Set Or Clear the Indirect Change Flag</h2><blockquote><pre>int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
Each change recorded by a session object is marked as either direct or
|
||
|
|
indirect. A change is marked as indirect if either:</p>
|
||
|
|
|
||
|
|
<p><ul>
|
||
|
|
<li> The session object "indirect" flag is set when the change is
|
||
|
|
made, or
|
||
|
|
<li> The change is made by an SQL trigger or foreign key action
|
||
|
|
instead of directly as a result of a users SQL statement.
|
||
|
|
</ul></p>
|
||
|
|
|
||
|
|
<p>If a single row is affected by more than one operation within a session,
|
||
|
|
then the change is considered indirect if all operations meet the criteria
|
||
|
|
for an indirect change above, or direct otherwise.</p>
|
||
|
|
|
||
|
|
<p>This function is used to set, clear or query the session object indirect
|
||
|
|
flag. If the second argument passed to this function is zero, then the
|
||
|
|
indirect flag is cleared. If it is greater than zero, the indirect flag
|
||
|
|
is set. Passing a value less than zero does not modify the current value
|
||
|
|
of the indirect flag, and may be used to query the current state of the
|
||
|
|
indirect flag for the specified session object.</p>
|
||
|
|
|
||
|
|
<p>The return value indicates the final state of the indirect flag: 0 if
|
||
|
|
it is clear, or 1 if it is set.
|
||
|
|
</p><hr><a name="sqlite3session_isempty"></a>
|
||
|
|
<h2>Test if a changeset has recorded any changes.</h2><blockquote><pre>int sqlite3session_isempty(sqlite3_session *pSession);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
Return non-zero if no changes to attached tables have been recorded by
|
||
|
|
the session object passed as the first argument. Otherwise, if one or
|
||
|
|
more changes have been recorded, return zero.</p>
|
||
|
|
|
||
|
|
<p>Even if this function returns zero, it is possible that calling
|
||
|
|
<a href="#sqlite3session_changeset">sqlite3session_changeset()</a> on the session handle may still return a
|
||
|
|
changeset that contains no changes. This can happen when a row in
|
||
|
|
an attached table is modified and then later on the original values
|
||
|
|
are restored. However, if this function returns non-zero, then it is
|
||
|
|
guaranteed that a call to sqlite3session_changeset() will return a
|
||
|
|
changeset containing zero changes.
|
||
|
|
</p><hr><a name="sqlite3session_patchset"></a>
|
||
|
|
<h2>Generate A Patchset From A Session Object</h2><blockquote><pre>int sqlite3session_patchset(
|
||
|
|
sqlite3_session *pSession, /* Session object */
|
||
|
|
int *pnPatchset, /* OUT: Size of buffer at *ppPatchset */
|
||
|
|
void **ppPatchset /* OUT: Buffer containing patchset */
|
||
|
|
);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
The differences between a patchset and a changeset are that:</p>
|
||
|
|
|
||
|
|
<p><ul>
|
||
|
|
<li> DELETE records consist of the primary key fields only. The
|
||
|
|
original values of other fields are omitted.
|
||
|
|
<li> The original values of any modified fields are omitted from
|
||
|
|
UPDATE records.
|
||
|
|
</ul></p>
|
||
|
|
|
||
|
|
<p>A patchset blob may be used with up to date versions of all
|
||
|
|
sqlite3changeset_xxx API functions except for sqlite3changeset_invert(),
|
||
|
|
which returns SQLITE_CORRUPT if it is passed a patchset. Similarly,
|
||
|
|
attempting to use a patchset blob with old versions of the
|
||
|
|
sqlite3changeset_xxx APIs also provokes an SQLITE_CORRUPT error. </p>
|
||
|
|
|
||
|
|
<p>Because the non-primary key "old.*" fields are omitted, no
|
||
|
|
SQLITE_CHANGESET_DATA conflicts can be detected or reported if a patchset
|
||
|
|
is passed to the sqlite3changeset_apply() API. Other conflict types work
|
||
|
|
in the same way as for changesets.</p>
|
||
|
|
|
||
|
|
<p>Changes within a patchset are ordered in the same way as for changesets
|
||
|
|
generated by the sqlite3session_changeset() function (i.e. all changes for
|
||
|
|
a single table are grouped together, tables appear in the order in which
|
||
|
|
they were attached to the session object).
|
||
|
|
</p><hr><a name="sqlite3session_table_filter"></a>
|
||
|
|
<h2>Set a table filter on a Session Object.</h2><blockquote><pre>void sqlite3session_table_filter(
|
||
|
|
sqlite3_session *pSession, /* Session object */
|
||
|
|
int(*xFilter)(
|
||
|
|
void *pCtx, /* Copy of third arg to _filter_table() */
|
||
|
|
const char *zTab /* Table name */
|
||
|
|
),
|
||
|
|
void *pCtx /* First argument passed to xFilter */
|
||
|
|
);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
The second argument (xFilter) is the "filter callback". For changes to rows
|
||
|
|
in tables that are not attached to the Session object, the filter is called
|
||
|
|
to determine whether changes to the table's rows should be tracked or not.
|
||
|
|
If xFilter returns 0, changes are not tracked. Note that once a table is
|
||
|
|
attached, xFilter will not be called again.
|
||
|
|
</p><hr><a name="SQLITE_CHANGESETAPPLY_INVERT"></a>
|
||
|
|
<h2>Flags for sqlite3changeset_apply_v2</h2><blockquote><pre>#define SQLITE_CHANGESETAPPLY_NOSAVEPOINT 0x0001
|
||
|
|
#define SQLITE_CHANGESETAPPLY_INVERT 0x0002
|
||
|
|
</pre></blockquote><p>
|
||
|
|
The following flags may passed via the 9th parameter to
|
||
|
|
<a href="#sqlite3changeset_apply">sqlite3changeset_apply_v2</a> and <a href="#sqlite3changegroup_add_strm">sqlite3changeset_apply_v2_strm</a>:</p>
|
||
|
|
|
||
|
|
<p><dl>
|
||
|
|
<dt>SQLITE_CHANGESETAPPLY_NOSAVEPOINT <dd>
|
||
|
|
Usually, the sessions module encloses all operations performed by
|
||
|
|
a single call to apply_v2() or apply_v2_strm() in a <a href="lang_savepoint.html">SAVEPOINT</a>. The
|
||
|
|
SAVEPOINT is committed if the changeset or patchset is successfully
|
||
|
|
applied, or rolled back if an error occurs. Specifying this flag
|
||
|
|
causes the sessions module to omit this savepoint. In this case, if the
|
||
|
|
caller has an open transaction or savepoint when apply_v2() is called,
|
||
|
|
it may revert the partially applied changeset by rolling it back.</p>
|
||
|
|
|
||
|
|
<p><dt>SQLITE_CHANGESETAPPLY_INVERT <dd>
|
||
|
|
Invert the changeset before applying it. This is equivalent to inverting
|
||
|
|
a changeset using sqlite3changeset_invert() before applying it. It is
|
||
|
|
an error to specify this flag with a patchset.
|
||
|
|
</p><hr><a name="SQLITE_CHANGESET_ABORT"></a>
|
||
|
|
<h2>Constants Returned By The Conflict Handler</h2><blockquote><pre>#define SQLITE_CHANGESET_OMIT 0
|
||
|
|
#define SQLITE_CHANGESET_REPLACE 1
|
||
|
|
#define SQLITE_CHANGESET_ABORT 2
|
||
|
|
</pre></blockquote><p>
|
||
|
|
A conflict handler callback must return one of the following three values.</p>
|
||
|
|
|
||
|
|
<p><dl>
|
||
|
|
<dt>SQLITE_CHANGESET_OMIT<dd>
|
||
|
|
If a conflict handler returns this value no special action is taken. The
|
||
|
|
change that caused the conflict is not applied. The session module
|
||
|
|
continues to the next change in the changeset.</p>
|
||
|
|
|
||
|
|
<p><dt>SQLITE_CHANGESET_REPLACE<dd>
|
||
|
|
This value may only be returned if the second argument to the conflict
|
||
|
|
handler was SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this
|
||
|
|
is not the case, any changes applied so far are rolled back and the
|
||
|
|
call to sqlite3changeset_apply() returns SQLITE_MISUSE.</p>
|
||
|
|
|
||
|
|
<p> If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_DATA conflict
|
||
|
|
handler, then the conflicting row is either updated or deleted, depending
|
||
|
|
on the type of change.</p>
|
||
|
|
|
||
|
|
<p> If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_CONFLICT conflict
|
||
|
|
handler, then the conflicting row is removed from the database and a
|
||
|
|
second attempt to apply the change is made. If this second attempt fails,
|
||
|
|
the original row is restored to the database before continuing.</p>
|
||
|
|
|
||
|
|
<p><dt>SQLITE_CHANGESET_ABORT<dd>
|
||
|
|
If this value is returned, any changes applied so far are rolled back
|
||
|
|
and the call to sqlite3changeset_apply() returns SQLITE_ABORT.
|
||
|
|
</dl>
|
||
|
|
</p><hr><a name="SQLITE_CHANGESET_CONFLICT"></a>
|
||
|
|
<h2>Constants Passed To The Conflict Handler</h2><blockquote><pre>#define SQLITE_CHANGESET_DATA 1
|
||
|
|
#define SQLITE_CHANGESET_NOTFOUND 2
|
||
|
|
#define SQLITE_CHANGESET_CONFLICT 3
|
||
|
|
#define SQLITE_CHANGESET_CONSTRAINT 4
|
||
|
|
#define SQLITE_CHANGESET_FOREIGN_KEY 5
|
||
|
|
</pre></blockquote><p>
|
||
|
|
Values that may be passed as the second argument to a conflict-handler.</p>
|
||
|
|
|
||
|
|
<p><dl>
|
||
|
|
<dt>SQLITE_CHANGESET_DATA<dd>
|
||
|
|
The conflict handler is invoked with CHANGESET_DATA as the second argument
|
||
|
|
when processing a DELETE or UPDATE change if a row with the required
|
||
|
|
PRIMARY KEY fields is present in the database, but one or more other
|
||
|
|
(non primary-key) fields modified by the update do not contain the
|
||
|
|
expected "before" values.</p>
|
||
|
|
|
||
|
|
<p> The conflicting row, in this case, is the database row with the matching
|
||
|
|
primary key.</p>
|
||
|
|
|
||
|
|
<p><dt>SQLITE_CHANGESET_NOTFOUND<dd>
|
||
|
|
The conflict handler is invoked with CHANGESET_NOTFOUND as the second
|
||
|
|
argument when processing a DELETE or UPDATE change if a row with the
|
||
|
|
required PRIMARY KEY fields is not present in the database.</p>
|
||
|
|
|
||
|
|
<p> There is no conflicting row in this case. The results of invoking the
|
||
|
|
sqlite3changeset_conflict() API are undefined.</p>
|
||
|
|
|
||
|
|
<p><dt>SQLITE_CHANGESET_CONFLICT<dd>
|
||
|
|
CHANGESET_CONFLICT is passed as the second argument to the conflict
|
||
|
|
handler while processing an INSERT change if the operation would result
|
||
|
|
in duplicate primary key values.</p>
|
||
|
|
|
||
|
|
<p> The conflicting row in this case is the database row with the matching
|
||
|
|
primary key.</p>
|
||
|
|
|
||
|
|
<p><dt>SQLITE_CHANGESET_FOREIGN_KEY<dd>
|
||
|
|
If foreign key handling is enabled, and applying a changeset leaves the
|
||
|
|
database in a state containing foreign key violations, the conflict
|
||
|
|
handler is invoked with CHANGESET_FOREIGN_KEY as the second argument
|
||
|
|
exactly once before the changeset is committed. If the conflict handler
|
||
|
|
returns CHANGESET_OMIT, the changes, including those that caused the
|
||
|
|
foreign key constraint violation, are committed. Or, if it returns
|
||
|
|
CHANGESET_ABORT, the changeset is rolled back.</p>
|
||
|
|
|
||
|
|
<p> No current or conflicting row information is provided. The only function
|
||
|
|
it is possible to call on the supplied sqlite3_changeset_iter handle
|
||
|
|
is sqlite3changeset_fk_conflicts().</p>
|
||
|
|
|
||
|
|
<p><dt>SQLITE_CHANGESET_CONSTRAINT<dd>
|
||
|
|
If any other constraint violation occurs while applying a change (i.e.
|
||
|
|
a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is
|
||
|
|
invoked with CHANGESET_CONSTRAINT as the second argument.</p>
|
||
|
|
|
||
|
|
<p> There is no conflicting row in this case. The results of invoking the
|
||
|
|
sqlite3changeset_conflict() API are undefined.</p>
|
||
|
|
|
||
|
|
<p></dl>
|
||
|
|
</p><hr><a name="sqlite3changegroup_add_strm"></a>
|
||
|
|
<h2>Streaming Versions of API functions.</h2><blockquote><pre>int sqlite3changeset_apply_strm(
|
||
|
|
sqlite3 *db, /* Apply change to "main" db of this handle */
|
||
|
|
int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
|
||
|
|
void *pIn, /* First arg for xInput */
|
||
|
|
int(*xFilter)(
|
||
|
|
void *pCtx, /* Copy of sixth arg to _apply() */
|
||
|
|
const char *zTab /* Table name */
|
||
|
|
),
|
||
|
|
int(*xConflict)(
|
||
|
|
void *pCtx, /* Copy of sixth arg to _apply() */
|
||
|
|
int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
|
||
|
|
sqlite3_changeset_iter *p /* Handle describing change and conflict */
|
||
|
|
),
|
||
|
|
void *pCtx /* First argument passed to xConflict */
|
||
|
|
);
|
||
|
|
int sqlite3changeset_apply_v2_strm(
|
||
|
|
sqlite3 *db, /* Apply change to "main" db of this handle */
|
||
|
|
int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
|
||
|
|
void *pIn, /* First arg for xInput */
|
||
|
|
int(*xFilter)(
|
||
|
|
void *pCtx, /* Copy of sixth arg to _apply() */
|
||
|
|
const char *zTab /* Table name */
|
||
|
|
),
|
||
|
|
int(*xConflict)(
|
||
|
|
void *pCtx, /* Copy of sixth arg to _apply() */
|
||
|
|
int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
|
||
|
|
sqlite3_changeset_iter *p /* Handle describing change and conflict */
|
||
|
|
),
|
||
|
|
void *pCtx, /* First argument passed to xConflict */
|
||
|
|
void **ppRebase, int *pnRebase,
|
||
|
|
int flags
|
||
|
|
);
|
||
|
|
int sqlite3changeset_concat_strm(
|
||
|
|
int (*xInputA)(void *pIn, void *pData, int *pnData),
|
||
|
|
void *pInA,
|
||
|
|
int (*xInputB)(void *pIn, void *pData, int *pnData),
|
||
|
|
void *pInB,
|
||
|
|
int (*xOutput)(void *pOut, const void *pData, int nData),
|
||
|
|
void *pOut
|
||
|
|
);
|
||
|
|
int sqlite3changeset_invert_strm(
|
||
|
|
int (*xInput)(void *pIn, void *pData, int *pnData),
|
||
|
|
void *pIn,
|
||
|
|
int (*xOutput)(void *pOut, const void *pData, int nData),
|
||
|
|
void *pOut
|
||
|
|
);
|
||
|
|
int sqlite3changeset_start_strm(
|
||
|
|
sqlite3_changeset_iter **pp,
|
||
|
|
int (*xInput)(void *pIn, void *pData, int *pnData),
|
||
|
|
void *pIn
|
||
|
|
);
|
||
|
|
int sqlite3changeset_start_v2_strm(
|
||
|
|
sqlite3_changeset_iter **pp,
|
||
|
|
int (*xInput)(void *pIn, void *pData, int *pnData),
|
||
|
|
void *pIn,
|
||
|
|
int flags
|
||
|
|
);
|
||
|
|
int sqlite3session_changeset_strm(
|
||
|
|
sqlite3_session *pSession,
|
||
|
|
int (*xOutput)(void *pOut, const void *pData, int nData),
|
||
|
|
void *pOut
|
||
|
|
);
|
||
|
|
int sqlite3session_patchset_strm(
|
||
|
|
sqlite3_session *pSession,
|
||
|
|
int (*xOutput)(void *pOut, const void *pData, int nData),
|
||
|
|
void *pOut
|
||
|
|
);
|
||
|
|
int sqlite3changegroup_add_strm(sqlite3_changegroup*,
|
||
|
|
int (*xInput)(void *pIn, void *pData, int *pnData),
|
||
|
|
void *pIn
|
||
|
|
);
|
||
|
|
int sqlite3changegroup_output_strm(sqlite3_changegroup*,
|
||
|
|
int (*xOutput)(void *pOut, const void *pData, int nData),
|
||
|
|
void *pOut
|
||
|
|
);
|
||
|
|
int sqlite3rebaser_rebase_strm(
|
||
|
|
sqlite3_rebaser *pRebaser,
|
||
|
|
int (*xInput)(void *pIn, void *pData, int *pnData),
|
||
|
|
void *pIn,
|
||
|
|
int (*xOutput)(void *pOut, const void *pData, int nData),
|
||
|
|
void *pOut
|
||
|
|
);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
The six streaming API xxx_strm() functions serve similar purposes to the
|
||
|
|
corresponding non-streaming API functions:</p>
|
||
|
|
|
||
|
|
<p><table border=1 style="margin-left:8ex;margin-right:8ex">
|
||
|
|
<tr><th>Streaming function<th>Non-streaming equivalent</th>
|
||
|
|
<tr><td>sqlite3changeset_apply_strm<td><a href="#sqlite3changeset_apply">sqlite3changeset_apply</a>
|
||
|
|
<tr><td>sqlite3changeset_apply_strm_v2<td><a href="#sqlite3changeset_apply">sqlite3changeset_apply_v2</a>
|
||
|
|
<tr><td>sqlite3changeset_concat_strm<td><a href="#sqlite3changeset_concat">sqlite3changeset_concat</a>
|
||
|
|
<tr><td>sqlite3changeset_invert_strm<td><a href="#sqlite3changeset_invert">sqlite3changeset_invert</a>
|
||
|
|
<tr><td>sqlite3changeset_start_strm<td><a href="#sqlite3changeset_start">sqlite3changeset_start</a>
|
||
|
|
<tr><td>sqlite3session_changeset_strm<td><a href="#sqlite3session_changeset">sqlite3session_changeset</a>
|
||
|
|
<tr><td>sqlite3session_patchset_strm<td><a href="#sqlite3session_patchset">sqlite3session_patchset</a>
|
||
|
|
</table></p>
|
||
|
|
|
||
|
|
<p>Non-streaming functions that accept changesets (or patchsets) as input
|
||
|
|
require that the entire changeset be stored in a single buffer in memory.
|
||
|
|
Similarly, those that return a changeset or patchset do so by returning
|
||
|
|
a pointer to a single large buffer allocated using sqlite3_malloc().
|
||
|
|
Normally this is convenient. However, if an application running in a
|
||
|
|
low-memory environment is required to handle very large changesets, the
|
||
|
|
large contiguous memory allocations required can become onerous.</p>
|
||
|
|
|
||
|
|
<p>In order to avoid this problem, instead of a single large buffer, input
|
||
|
|
is passed to a streaming API functions by way of a callback function that
|
||
|
|
the sessions module invokes to incrementally request input data as it is
|
||
|
|
required. In all cases, a pair of API function parameters such as</p>
|
||
|
|
|
||
|
|
<p> <pre>
|
||
|
|
int nChangeset,
|
||
|
|
void *pChangeset,
|
||
|
|
</pre></p>
|
||
|
|
|
||
|
|
<p>Is replaced by:</p>
|
||
|
|
|
||
|
|
<p> <pre>
|
||
|
|
int (*xInput)(void *pIn, void *pData, int *pnData),
|
||
|
|
void *pIn,
|
||
|
|
</pre></p>
|
||
|
|
|
||
|
|
<p>Each time the xInput callback is invoked by the sessions module, the first
|
||
|
|
argument passed is a copy of the supplied pIn context pointer. The second
|
||
|
|
argument, pData, points to a buffer (*pnData) bytes in size. Assuming no
|
||
|
|
error occurs the xInput method should copy up to (*pnData) bytes of data
|
||
|
|
into the buffer and set (*pnData) to the actual number of bytes copied
|
||
|
|
before returning SQLITE_OK. If the input is completely exhausted, (*pnData)
|
||
|
|
should be set to zero to indicate this. Or, if an error occurs, an SQLite
|
||
|
|
error code should be returned. In all cases, if an xInput callback returns
|
||
|
|
an error, all processing is abandoned and the streaming API function
|
||
|
|
returns a copy of the error code to the caller.</p>
|
||
|
|
|
||
|
|
<p>In the case of sqlite3changeset_start_strm(), the xInput callback may be
|
||
|
|
invoked by the sessions module at any point during the lifetime of the
|
||
|
|
iterator. If such an xInput callback returns an error, the iterator enters
|
||
|
|
an error state, whereby all subsequent calls to iterator functions
|
||
|
|
immediately fail with the same error code as returned by xInput.</p>
|
||
|
|
|
||
|
|
<p>Similarly, streaming API functions that return changesets (or patchsets)
|
||
|
|
return them in chunks by way of a callback function instead of via a
|
||
|
|
pointer to a single large buffer. In this case, a pair of parameters such
|
||
|
|
as:</p>
|
||
|
|
|
||
|
|
<p> <pre>
|
||
|
|
int *pnChangeset,
|
||
|
|
void **ppChangeset,
|
||
|
|
</pre></p>
|
||
|
|
|
||
|
|
<p>Is replaced by:</p>
|
||
|
|
|
||
|
|
<p> <pre>
|
||
|
|
int (*xOutput)(void *pOut, const void *pData, int nData),
|
||
|
|
void *pOut
|
||
|
|
</pre></p>
|
||
|
|
|
||
|
|
<p>The xOutput callback is invoked zero or more times to return data to
|
||
|
|
the application. The first parameter passed to each call is a copy of the
|
||
|
|
pOut pointer supplied by the application. The second parameter, pData,
|
||
|
|
points to a buffer nData bytes in size containing the chunk of output
|
||
|
|
data being returned. If the xOutput callback successfully processes the
|
||
|
|
supplied data, it should return SQLITE_OK to indicate success. Otherwise,
|
||
|
|
it should return some other SQLite error code. In this case processing
|
||
|
|
is immediately abandoned and the streaming API function returns a copy
|
||
|
|
of the xOutput error code to the application.</p>
|
||
|
|
|
||
|
|
<p>The sessions module never invokes an xOutput callback with the third
|
||
|
|
parameter set to a value less than or equal to zero. Other than this,
|
||
|
|
no guarantees are made as to the size of the chunks of data returned.
|
||
|
|
</p><hr><a name="sqlite3changeset_apply"></a>
|
||
|
|
<h2>Apply A Changeset To A Database</h2><blockquote><pre>int sqlite3changeset_apply(
|
||
|
|
sqlite3 *db, /* Apply change to "main" db of this handle */
|
||
|
|
int nChangeset, /* Size of changeset in bytes */
|
||
|
|
void *pChangeset, /* Changeset blob */
|
||
|
|
int(*xFilter)(
|
||
|
|
void *pCtx, /* Copy of sixth arg to _apply() */
|
||
|
|
const char *zTab /* Table name */
|
||
|
|
),
|
||
|
|
int(*xConflict)(
|
||
|
|
void *pCtx, /* Copy of sixth arg to _apply() */
|
||
|
|
int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
|
||
|
|
sqlite3_changeset_iter *p /* Handle describing change and conflict */
|
||
|
|
),
|
||
|
|
void *pCtx /* First argument passed to xConflict */
|
||
|
|
);
|
||
|
|
int sqlite3changeset_apply_v2(
|
||
|
|
sqlite3 *db, /* Apply change to "main" db of this handle */
|
||
|
|
int nChangeset, /* Size of changeset in bytes */
|
||
|
|
void *pChangeset, /* Changeset blob */
|
||
|
|
int(*xFilter)(
|
||
|
|
void *pCtx, /* Copy of sixth arg to _apply() */
|
||
|
|
const char *zTab /* Table name */
|
||
|
|
),
|
||
|
|
int(*xConflict)(
|
||
|
|
void *pCtx, /* Copy of sixth arg to _apply() */
|
||
|
|
int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
|
||
|
|
sqlite3_changeset_iter *p /* Handle describing change and conflict */
|
||
|
|
),
|
||
|
|
void *pCtx, /* First argument passed to xConflict */
|
||
|
|
void **ppRebase, int *pnRebase, /* OUT: Rebase data */
|
||
|
|
int flags /* SESSION_CHANGESETAPPLY_* flags */
|
||
|
|
);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
Apply a changeset or patchset to a database. These functions attempt to
|
||
|
|
update the "main" database attached to handle db with the changes found in
|
||
|
|
the changeset passed via the second and third arguments. </p>
|
||
|
|
|
||
|
|
<p>The fourth argument (xFilter) passed to these functions is the "filter
|
||
|
|
callback". If it is not NULL, then for each table affected by at least one
|
||
|
|
change in the changeset, the filter callback is invoked with
|
||
|
|
the table name as the second argument, and a copy of the context pointer
|
||
|
|
passed as the sixth argument as the first. If the "filter callback"
|
||
|
|
returns zero, then no attempt is made to apply any changes to the table.
|
||
|
|
Otherwise, if the return value is non-zero or the xFilter argument to
|
||
|
|
is NULL, all changes related to the table are attempted.</p>
|
||
|
|
|
||
|
|
<p>For each table that is not excluded by the filter callback, this function
|
||
|
|
tests that the target database contains a compatible table. A table is
|
||
|
|
considered compatible if all of the following are true:</p>
|
||
|
|
|
||
|
|
<p><ul>
|
||
|
|
<li> The table has the same name as the name recorded in the
|
||
|
|
changeset, and
|
||
|
|
<li> The table has at least as many columns as recorded in the
|
||
|
|
changeset, and
|
||
|
|
<li> The table has primary key columns in the same position as
|
||
|
|
recorded in the changeset.
|
||
|
|
</ul></p>
|
||
|
|
|
||
|
|
<p>If there is no compatible table, it is not an error, but none of the
|
||
|
|
changes associated with the table are applied. A warning message is issued
|
||
|
|
via the sqlite3_log() mechanism with the error code SQLITE_SCHEMA. At most
|
||
|
|
one such warning is issued for each table in the changeset.</p>
|
||
|
|
|
||
|
|
<p>For each change for which there is a compatible table, an attempt is made
|
||
|
|
to modify the table contents according to the UPDATE, INSERT or DELETE
|
||
|
|
change. If a change cannot be applied cleanly, the conflict handler
|
||
|
|
function passed as the fifth argument to sqlite3changeset_apply() may be
|
||
|
|
invoked. A description of exactly when the conflict handler is invoked for
|
||
|
|
each type of change is below.</p>
|
||
|
|
|
||
|
|
<p>Unlike the xFilter argument, xConflict may not be passed NULL. The results
|
||
|
|
of passing anything other than a valid function pointer as the xConflict
|
||
|
|
argument are undefined.</p>
|
||
|
|
|
||
|
|
<p>Each time the conflict handler function is invoked, it must return one
|
||
|
|
of <a href="#SQLITE_CHANGESET_ABORT">SQLITE_CHANGESET_OMIT</a>, <a href="#SQLITE_CHANGESET_ABORT">SQLITE_CHANGESET_ABORT</a> or
|
||
|
|
<a href="#SQLITE_CHANGESET_ABORT">SQLITE_CHANGESET_REPLACE</a>. SQLITE_CHANGESET_REPLACE may only be returned
|
||
|
|
if the second argument passed to the conflict handler is either
|
||
|
|
SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler
|
||
|
|
returns an illegal value, any changes already made are rolled back and
|
||
|
|
the call to sqlite3changeset_apply() returns SQLITE_MISUSE. Different
|
||
|
|
actions are taken by sqlite3changeset_apply() depending on the value
|
||
|
|
returned by each invocation of the conflict-handler function. Refer to
|
||
|
|
the documentation for the three
|
||
|
|
<a href="#SQLITE_CHANGESET_ABORT">available return values</a> for details.</p>
|
||
|
|
|
||
|
|
<p><dl>
|
||
|
|
<dt>DELETE Changes<dd>
|
||
|
|
For each DELETE change, the function checks if the target database
|
||
|
|
contains a row with the same primary key value (or values) as the
|
||
|
|
original row values stored in the changeset. If it does, and the values
|
||
|
|
stored in all non-primary key columns also match the values stored in
|
||
|
|
the changeset the row is deleted from the target database.</p>
|
||
|
|
|
||
|
|
<p> If a row with matching primary key values is found, but one or more of
|
||
|
|
the non-primary key fields contains a value different from the original
|
||
|
|
row value stored in the changeset, the conflict-handler function is
|
||
|
|
invoked with <a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_DATA</a> as the second argument. If the
|
||
|
|
database table has more columns than are recorded in the changeset,
|
||
|
|
only the values of those non-primary key fields are compared against
|
||
|
|
the current database contents - any trailing database table columns
|
||
|
|
are ignored.</p>
|
||
|
|
|
||
|
|
<p> If no row with matching primary key values is found in the database,
|
||
|
|
the conflict-handler function is invoked with <a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_NOTFOUND</a>
|
||
|
|
passed as the second argument.</p>
|
||
|
|
|
||
|
|
<p> If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT
|
||
|
|
(which can only happen if a foreign key constraint is violated), the
|
||
|
|
conflict-handler function is invoked with <a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_CONSTRAINT</a>
|
||
|
|
passed as the second argument. This includes the case where the DELETE
|
||
|
|
operation is attempted because an earlier call to the conflict handler
|
||
|
|
function returned <a href="#SQLITE_CHANGESET_ABORT">SQLITE_CHANGESET_REPLACE</a>.</p>
|
||
|
|
|
||
|
|
<p><dt>INSERT Changes<dd>
|
||
|
|
For each INSERT change, an attempt is made to insert the new row into
|
||
|
|
the database. If the changeset row contains fewer fields than the
|
||
|
|
database table, the trailing fields are populated with their default
|
||
|
|
values.</p>
|
||
|
|
|
||
|
|
<p> If the attempt to insert the row fails because the database already
|
||
|
|
contains a row with the same primary key values, the conflict handler
|
||
|
|
function is invoked with the second argument set to
|
||
|
|
<a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_CONFLICT</a>.</p>
|
||
|
|
|
||
|
|
<p> If the attempt to insert the row fails because of some other constraint
|
||
|
|
violation (e.g. NOT NULL or UNIQUE), the conflict handler function is
|
||
|
|
invoked with the second argument set to <a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_CONSTRAINT</a>.
|
||
|
|
This includes the case where the INSERT operation is re-attempted because
|
||
|
|
an earlier call to the conflict handler function returned
|
||
|
|
<a href="#SQLITE_CHANGESET_ABORT">SQLITE_CHANGESET_REPLACE</a>.</p>
|
||
|
|
|
||
|
|
<p><dt>UPDATE Changes<dd>
|
||
|
|
For each UPDATE change, the function checks if the target database
|
||
|
|
contains a row with the same primary key value (or values) as the
|
||
|
|
original row values stored in the changeset. If it does, and the values
|
||
|
|
stored in all modified non-primary key columns also match the values
|
||
|
|
stored in the changeset the row is updated within the target database.</p>
|
||
|
|
|
||
|
|
<p> If a row with matching primary key values is found, but one or more of
|
||
|
|
the modified non-primary key fields contains a value different from an
|
||
|
|
original row value stored in the changeset, the conflict-handler function
|
||
|
|
is invoked with <a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_DATA</a> as the second argument. Since
|
||
|
|
UPDATE changes only contain values for non-primary key fields that are
|
||
|
|
to be modified, only those fields need to match the original values to
|
||
|
|
avoid the SQLITE_CHANGESET_DATA conflict-handler callback.</p>
|
||
|
|
|
||
|
|
<p> If no row with matching primary key values is found in the database,
|
||
|
|
the conflict-handler function is invoked with <a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_NOTFOUND</a>
|
||
|
|
passed as the second argument.</p>
|
||
|
|
|
||
|
|
<p> If the UPDATE operation is attempted, but SQLite returns
|
||
|
|
SQLITE_CONSTRAINT, the conflict-handler function is invoked with
|
||
|
|
<a href="#SQLITE_CHANGESET_CONFLICT">SQLITE_CHANGESET_CONSTRAINT</a> passed as the second argument.
|
||
|
|
This includes the case where the UPDATE operation is attempted after
|
||
|
|
an earlier call to the conflict handler function returned
|
||
|
|
<a href="#SQLITE_CHANGESET_ABORT">SQLITE_CHANGESET_REPLACE</a>.
|
||
|
|
</dl></p>
|
||
|
|
|
||
|
|
<p>It is safe to execute SQL statements, including those that write to the
|
||
|
|
table that the callback related to, from within the xConflict callback.
|
||
|
|
This can be used to further customize the application's conflict
|
||
|
|
resolution strategy.</p>
|
||
|
|
|
||
|
|
<p>All changes made by these functions are enclosed in a savepoint transaction.
|
||
|
|
If any other error (aside from a constraint failure when attempting to
|
||
|
|
write to the target database) occurs, then the savepoint transaction is
|
||
|
|
rolled back, restoring the target database to its original state, and an
|
||
|
|
SQLite error code returned.</p>
|
||
|
|
|
||
|
|
<p>If the output parameters (ppRebase) and (pnRebase) are non-NULL and
|
||
|
|
the input is a changeset (not a patchset), then sqlite3changeset_apply_v2()
|
||
|
|
may set (*ppRebase) to point to a "rebase" that may be used with the
|
||
|
|
sqlite3_rebaser APIs buffer before returning. In this case (*pnRebase)
|
||
|
|
is set to the size of the buffer in bytes. It is the responsibility of the
|
||
|
|
caller to eventually free any such buffer using sqlite3_free(). The buffer
|
||
|
|
is only allocated and populated if one or more conflicts were encountered
|
||
|
|
while applying the patchset. See comments surrounding the sqlite3_rebaser
|
||
|
|
APIs for further details.</p>
|
||
|
|
|
||
|
|
<p>The behavior of sqlite3changeset_apply_v2() and its streaming equivalent
|
||
|
|
may be modified by passing a combination of
|
||
|
|
<a href="#SQLITE_CHANGESETAPPLY_INVERT">supported flags</a> as the 9th parameter.</p>
|
||
|
|
|
||
|
|
<p>Note that the sqlite3changeset_apply_v2() API is still <b>experimental</b>
|
||
|
|
and therefore subject to change.
|
||
|
|
</p><hr><a name="sqlite3changeset_start"></a>
|
||
|
|
<h2>Create An Iterator To Traverse A Changeset </h2><blockquote><pre>int sqlite3changeset_start(
|
||
|
|
sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */
|
||
|
|
int nChangeset, /* Size of changeset blob in bytes */
|
||
|
|
void *pChangeset /* Pointer to blob containing changeset */
|
||
|
|
);
|
||
|
|
int sqlite3changeset_start_v2(
|
||
|
|
sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */
|
||
|
|
int nChangeset, /* Size of changeset blob in bytes */
|
||
|
|
void *pChangeset, /* Pointer to blob containing changeset */
|
||
|
|
int flags /* SESSION_CHANGESETSTART_* flags */
|
||
|
|
);
|
||
|
|
</pre></blockquote><p>
|
||
|
|
Create an iterator used to iterate through the contents of a changeset.
|
||
|
|
If successful, *pp is set to point to the iterator handle and SQLITE_OK
|
||
|
|
is returned. Otherwise, if an error occurs, *pp is set to zero and an
|
||
|
|
SQLite error code is returned.</p>
|
||
|
|
|
||
|
|
<p>The following functions can be used to advance and query a changeset
|
||
|
|
iterator created by this function:</p>
|
||
|
|
|
||
|
|
<p><ul>
|
||
|
|
<li> <a href="#sqlite3changeset_next">sqlite3changeset_next()</a>
|
||
|
|
<li> <a href="#sqlite3changeset_op">sqlite3changeset_op()</a>
|
||
|
|
<li> <a href="#sqlite3changeset_new">sqlite3changeset_new()</a>
|
||
|
|
<li> <a href="#sqlite3changeset_old">sqlite3changeset_old()</a>
|
||
|
|
</ul></p>
|
||
|
|
|
||
|
|
<p>It is the responsibility of the caller to eventually destroy the iterator
|
||
|
|
by passing it to <a href="#sqlite3changeset_finalize">sqlite3changeset_finalize()</a>. The buffer containing the
|
||
|
|
changeset (pChangeset) must remain valid until after the iterator is
|
||
|
|
destroyed.</p>
|
||
|
|
|
||
|
|
<p>Assuming the changeset blob was created by one of the
|
||
|
|
<a href="#sqlite3session_changeset">sqlite3session_changeset()</a>, <a href="#sqlite3changeset_concat">sqlite3changeset_concat()</a> or
|
||
|
|
<a href="#sqlite3changeset_invert">sqlite3changeset_invert()</a> functions, all changes within the changeset
|
||
|
|
that apply to a single table are grouped together. This means that when
|
||
|
|
an application iterates through a changeset using an iterator created by
|
||
|
|
this function, all changes that relate to a single table are visited
|
||
|
|
consecutively. There is no chance that the iterator will visit a change
|
||
|
|
the applies to table X, then one for table Y, and then later on visit
|
||
|
|
another change for table X.</p>
|
||
|
|
|
||
|
|
<p>The behavior of sqlite3changeset_start_v2() and its streaming equivalent
|
||
|
|
may be modified by passing a combination of
|
||
|
|
<a href="#SQLITE_CHANGESETSTART_INVERT">supported flags</a> as the 4th parameter.</p>
|
||
|
|
|
||
|
|
<p>Note that the sqlite3changeset_start_v2() API is still <b>experimental</b>
|
||
|
|
and therefore subject to change.
|
||
|
|
</p><hr>
|
||
|
|
|