From 18657a960e125336f704ea058e25c27bd3900dcb Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 5 May 2024 19:28:19 +0200 Subject: Adding upstream version 3.40.1. Signed-off-by: Daniel Baumann --- www/session/c_changeset_abort.html | 153 ++++++++++++ www/session/c_changeset_conflict.html | 179 ++++++++++++++ www/session/c_changesetapply_invert.html | 142 ++++++++++++ www/session/c_changesetstart_invert.html | 131 +++++++++++ www/session/c_session_config_strmsize.html | 123 ++++++++++ www/session/changegroup.html | 131 +++++++++++ www/session/changeset_iter.html | 142 ++++++++++++ www/session/constlist.html | 141 +++++++++++ www/session/funclist.html | 175 ++++++++++++++ www/session/intro.html | 155 +++++++++++++ www/session/objlist.html | 133 +++++++++++ www/session/rebaser.html | 217 +++++++++++++++++ www/session/session.html | 141 +++++++++++ www/session/sqlite3changegroup_add.html | 195 ++++++++++++++++ www/session/sqlite3changegroup_add_strm.html | 291 +++++++++++++++++++++++ www/session/sqlite3changegroup_delete.html | 123 ++++++++++ www/session/sqlite3changegroup_new.html | 155 +++++++++++++ www/session/sqlite3changegroup_output.html | 148 ++++++++++++ www/session/sqlite3changeset_apply.html | 309 +++++++++++++++++++++++++ www/session/sqlite3changeset_concat.html | 153 ++++++++++++ www/session/sqlite3changeset_conflict.html | 145 ++++++++++++ www/session/sqlite3changeset_finalize.html | 149 ++++++++++++ www/session/sqlite3changeset_fk_conflicts.html | 133 +++++++++++ www/session/sqlite3changeset_invert.html | 151 ++++++++++++ www/session/sqlite3changeset_new.html | 151 ++++++++++++ www/session/sqlite3changeset_next.html | 142 ++++++++++++ www/session/sqlite3changeset_old.html | 148 ++++++++++++ www/session/sqlite3changeset_op.html | 157 +++++++++++++ www/session/sqlite3changeset_pk.html | 149 ++++++++++++ www/session/sqlite3changeset_start.html | 170 ++++++++++++++ www/session/sqlite3rebaser_configure.html | 131 +++++++++++ www/session/sqlite3rebaser_create.html | 128 ++++++++++ www/session/sqlite3rebaser_delete.html | 127 ++++++++++ www/session/sqlite3rebaser_rebase.html | 137 +++++++++++ www/session/sqlite3session_attach.html | 180 ++++++++++++++ www/session/sqlite3session_changeset.html | 228 ++++++++++++++++++ www/session/sqlite3session_changeset_size.html | 133 +++++++++++ www/session/sqlite3session_config.html | 153 ++++++++++++ www/session/sqlite3session_create.html | 154 ++++++++++++ www/session/sqlite3session_delete.html | 132 +++++++++++ www/session/sqlite3session_diff.html | 181 +++++++++++++++ www/session/sqlite3session_enable.html | 137 +++++++++++ www/session/sqlite3session_indirect.html | 147 ++++++++++++ www/session/sqlite3session_isempty.html | 135 +++++++++++ www/session/sqlite3session_memory_used.html | 126 ++++++++++ www/session/sqlite3session_patchset.html | 152 ++++++++++++ www/session/sqlite3session_table_filter.html | 136 +++++++++++ 47 files changed, 7349 insertions(+) create mode 100644 www/session/c_changeset_abort.html create mode 100644 www/session/c_changeset_conflict.html create mode 100644 www/session/c_changesetapply_invert.html create mode 100644 www/session/c_changesetstart_invert.html create mode 100644 www/session/c_session_config_strmsize.html create mode 100644 www/session/changegroup.html create mode 100644 www/session/changeset_iter.html create mode 100644 www/session/constlist.html create mode 100644 www/session/funclist.html create mode 100644 www/session/intro.html create mode 100644 www/session/objlist.html create mode 100644 www/session/rebaser.html create mode 100644 www/session/session.html create mode 100644 www/session/sqlite3changegroup_add.html create mode 100644 www/session/sqlite3changegroup_add_strm.html create mode 100644 www/session/sqlite3changegroup_delete.html create mode 100644 www/session/sqlite3changegroup_new.html create mode 100644 www/session/sqlite3changegroup_output.html create mode 100644 www/session/sqlite3changeset_apply.html create mode 100644 www/session/sqlite3changeset_concat.html create mode 100644 www/session/sqlite3changeset_conflict.html create mode 100644 www/session/sqlite3changeset_finalize.html create mode 100644 www/session/sqlite3changeset_fk_conflicts.html create mode 100644 www/session/sqlite3changeset_invert.html create mode 100644 www/session/sqlite3changeset_new.html create mode 100644 www/session/sqlite3changeset_next.html create mode 100644 www/session/sqlite3changeset_old.html create mode 100644 www/session/sqlite3changeset_op.html create mode 100644 www/session/sqlite3changeset_pk.html create mode 100644 www/session/sqlite3changeset_start.html create mode 100644 www/session/sqlite3rebaser_configure.html create mode 100644 www/session/sqlite3rebaser_create.html create mode 100644 www/session/sqlite3rebaser_delete.html create mode 100644 www/session/sqlite3rebaser_rebase.html create mode 100644 www/session/sqlite3session_attach.html create mode 100644 www/session/sqlite3session_changeset.html create mode 100644 www/session/sqlite3session_changeset_size.html create mode 100644 www/session/sqlite3session_config.html create mode 100644 www/session/sqlite3session_create.html create mode 100644 www/session/sqlite3session_delete.html create mode 100644 www/session/sqlite3session_diff.html create mode 100644 www/session/sqlite3session_enable.html create mode 100644 www/session/sqlite3session_indirect.html create mode 100644 www/session/sqlite3session_isempty.html create mode 100644 www/session/sqlite3session_memory_used.html create mode 100644 www/session/sqlite3session_patchset.html create mode 100644 www/session/sqlite3session_table_filter.html (limited to 'www/session') diff --git a/www/session/c_changeset_abort.html b/www/session/c_changeset_abort.html new file mode 100644 index 0000000..457aa2e --- /dev/null +++ b/www/session/c_changeset_abort.html @@ -0,0 +1,153 @@ + + + + + +Constants Returned By The Conflict Handler + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Constants Returned By The Conflict Handler

#define SQLITE_CHANGESET_OMIT       0
+#define SQLITE_CHANGESET_REPLACE    1
+#define SQLITE_CHANGESET_ABORT      2
+

+A conflict handler callback must return one of the following three values.

+ +

+
SQLITE_CHANGESET_OMIT
+ 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.

+ +

SQLITE_CHANGESET_REPLACE
+ 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.

+ +

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.

+ +

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.

+ +

SQLITE_CHANGESET_ABORT
+ If this value is returned, any changes applied so far are rolled back + and the call to sqlite3changeset_apply() returns SQLITE_ABORT. +
+

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/c_changeset_conflict.html b/www/session/c_changeset_conflict.html new file mode 100644 index 0000000..063f212 --- /dev/null +++ b/www/session/c_changeset_conflict.html @@ -0,0 +1,179 @@ + + + + + +Constants Passed To The Conflict Handler + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Constants Passed To The Conflict Handler

#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
+

+Values that may be passed as the second argument to a conflict-handler.

+ +

+
SQLITE_CHANGESET_DATA
+ 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.

+ +

The conflicting row, in this case, is the database row with the matching + primary key.

+ +

SQLITE_CHANGESET_NOTFOUND
+ 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.

+ +

There is no conflicting row in this case. The results of invoking the + sqlite3changeset_conflict() API are undefined.

+ +

SQLITE_CHANGESET_CONFLICT
+ 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.

+ +

The conflicting row in this case is the database row with the matching + primary key.

+ +

SQLITE_CHANGESET_FOREIGN_KEY
+ 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.

+ +

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().

+ +

SQLITE_CHANGESET_CONSTRAINT
+ 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.

+ +

There is no conflicting row in this case. The results of invoking the + sqlite3changeset_conflict() API are undefined.

+ +

+

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/c_changesetapply_invert.html b/www/session/c_changesetapply_invert.html new file mode 100644 index 0000000..62e93be --- /dev/null +++ b/www/session/c_changesetapply_invert.html @@ -0,0 +1,142 @@ + + + + + +Flags for sqlite3changeset_apply_v2 + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Flags for sqlite3changeset_apply_v2

#define SQLITE_CHANGESETAPPLY_NOSAVEPOINT   0x0001
+#define SQLITE_CHANGESETAPPLY_INVERT        0x0002
+

+The following flags may passed via the 9th parameter to +sqlite3changeset_apply_v2 and sqlite3changeset_apply_v2_strm:

+ +

+
SQLITE_CHANGESETAPPLY_NOSAVEPOINT
+ Usually, the sessions module encloses all operations performed by + a single call to apply_v2() or apply_v2_strm() in a SAVEPOINT. 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.

+ +

SQLITE_CHANGESETAPPLY_INVERT
+ 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. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/c_changesetstart_invert.html b/www/session/c_changesetstart_invert.html new file mode 100644 index 0000000..53a41db --- /dev/null +++ b/www/session/c_changesetstart_invert.html @@ -0,0 +1,131 @@ + + + + + +Flags for sqlite3changeset_start_v2 + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Flags for sqlite3changeset_start_v2

#define SQLITE_CHANGESETSTART_INVERT        0x0002
+

+The following flags may passed via the 4th parameter to +sqlite3changeset_start_v2 and sqlite3changeset_start_v2_strm:

+ +

SQLITE_CHANGESETAPPLY_INVERT
+ 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. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/c_session_config_strmsize.html b/www/session/c_session_config_strmsize.html new file mode 100644 index 0000000..45b17df --- /dev/null +++ b/www/session/c_session_config_strmsize.html @@ -0,0 +1,123 @@ + + + + + +Values for sqlite3session_config(). + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Values for sqlite3session_config().

#define SQLITE_SESSION_CONFIG_STRMSIZE 1
+

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/changegroup.html b/www/session/changegroup.html new file mode 100644 index 0000000..4bd98fe --- /dev/null +++ b/www/session/changegroup.html @@ -0,0 +1,131 @@ + + + + + +Changegroup Handle + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Changegroup Handle

typedef struct sqlite3_changegroup sqlite3_changegroup;
+

+A changegroup is an object used to combine two or more +changesets or patchsets +

Constructor: sqlite3changegroup_new()

+

Destructor: sqlite3changegroup_delete()

+

Methods: + sqlite3changegroup_add(), +sqlite3changegroup_output()

+

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/changeset_iter.html b/www/session/changeset_iter.html new file mode 100644 index 0000000..fe88325 --- /dev/null +++ b/www/session/changeset_iter.html @@ -0,0 +1,142 @@ + + + + + +Changeset Iterator Handle + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Changeset Iterator Handle

typedef struct sqlite3_changeset_iter sqlite3_changeset_iter;
+

+An instance of this object acts as a cursor for iterating +over the elements of a changeset or patchset. +

Constructors: + sqlite3changeset_start(), +sqlite3changeset_start_v2()

+
+ +
+

+

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/constlist.html b/www/session/constlist.html new file mode 100644 index 0000000..7370652 --- /dev/null +++ b/www/session/constlist.html @@ -0,0 +1,141 @@ + + + + + +List Of SQLite Constants + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

 + +

Constants:

+
+ +
+

Other lists: +Objects and +Functions.

+ + diff --git a/www/session/funclist.html b/www/session/funclist.html new file mode 100644 index 0000000..2311e74 --- /dev/null +++ b/www/session/funclist.html @@ -0,0 +1,175 @@ + + + + + +List Of SQLite Functions + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

 + +

Functions:

+
+ +
+

Other lists: +Constants and +Objects.

+ + diff --git a/www/session/intro.html b/www/session/intro.html new file mode 100644 index 0000000..5871778 --- /dev/null +++ b/www/session/intro.html @@ -0,0 +1,155 @@ + + + + + +Introduction + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ + + +

These pages define the C-language interface for the SQLite +session extension. +This is not a tutorial. These pages are designed to be precise, not +easy to read. A tutorial is available separately. + +

This version of the C-language interface reference is +broken down into small pages for easy viewing. The +same content is also available as a +single large HTML file +for those who prefer that format.

+ +

The content on these pages is extracted from comments +in the source code.

+ +

The interface is broken down into three categories:

+ +
    +

  1. List Of Objects. + This is a list of the three abstract objects used by the SQLite session + module. + + +

  2. List Of Constants. + This is a list of numeric constants used by the SQLite session module + and represented by #defines in the sqlite3session.h header file. There + are constants passed to conflict handler callbacks to indicate the type + of conflict, and constants returned by the conflict handler to indicate + how the conflict should be resolved. + +

  3. List Of Functions. + This is a list of all SQLite session module functions. + +

+ + + diff --git a/www/session/objlist.html b/www/session/objlist.html new file mode 100644 index 0000000..3f43837 --- /dev/null +++ b/www/session/objlist.html @@ -0,0 +1,133 @@ + + + + + +List Of SQLite Objects + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

 + +

Objects:

+
+ +
+

Other lists: +Constants and +Functions. + + diff --git a/www/session/rebaser.html b/www/session/rebaser.html new file mode 100644 index 0000000..7788f3d --- /dev/null +++ b/www/session/rebaser.html @@ -0,0 +1,217 @@ + + + + + +Rebasing changesets + + + +

+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Rebasing changesets

typedef struct sqlite3_rebaser sqlite3_rebaser;
+

Important: This interface is experimental and is subject to change without notice.

+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.

+ +

For example, if both the local and remote changesets contain an +INSERT of the same key on "CREATE TABLE t1(a PRIMARY KEY, b)":

+ +

local: INSERT INTO t1 VALUES(1, 'v1'); + remote: INSERT INTO t1 VALUES(1, 'v2');

+ +

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:

+ +

UPDATE t1 SET b = 'v2' WHERE a=1;

+ +

Changes within the local changeset are rebased as follows:

+ +

+
Local INSERT
+ 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.

+ +

Local DELETE
+ 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.

+ +

Local UPDATE
+ 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.

+ +

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. +

+ +

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:

+ +

    +
  • If there has been one or more REPLACE resolutions on a + key, it is rebased according to a REPLACE.

    + +

  • 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. +

+ +

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.

+ +

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:

+ +

    +
  1. An sqlite3_rebaser object is created by calling + sqlite3rebaser_create(). +
  2. 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. +
  3. Each local changeset is rebased by calling sqlite3rebaser_rebase(). +
  4. The sqlite3_rebaser object is deleted by calling + sqlite3rebaser_delete(). +
+

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/session.html b/www/session/session.html new file mode 100644 index 0000000..664719d --- /dev/null +++ b/www/session/session.html @@ -0,0 +1,141 @@ + + + + + +Session Object Handle + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Session Object Handle

typedef struct sqlite3_session sqlite3_session;
+

+An instance of this object is a session that can be used to +record changes to a database. +

Constructor: sqlite3session_create()

+

Destructor: sqlite3session_delete()

+
+ +
+

+

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3changegroup_add.html b/www/session/sqlite3changegroup_add.html new file mode 100644 index 0000000..cb6f018 --- /dev/null +++ b/www/session/sqlite3changegroup_add.html @@ -0,0 +1,195 @@ + + + + + +Add A Changeset To A Changegroup + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Add A Changeset To A Changegroup

int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pData);
+

+Add all changes within the changeset (or patchset) in buffer pData (size +nData bytes) to the changegroup.

+ +

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.

+ +

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.

+ +

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:

+ +

+ + +
Existing Change New Change Output Change +
INSERT INSERT + 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. +
INSERT UPDATE + 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. +
INSERT DELETE + The existing INSERT is removed from the changegroup. The DELETE is + not added. +
UPDATE INSERT + 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. +
UPDATE UPDATE + 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. +
UPDATE DELETE + The existing UPDATE is replaced by the new DELETE within the + changegroup. +
DELETE INSERT + 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. +
DELETE UPDATE + 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. +
DELETE DELETE + 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. +

+ +

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.

+ +

If no error occurs, SQLITE_OK is returned. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3changegroup_add_strm.html b/www/session/sqlite3changegroup_add_strm.html new file mode 100644 index 0000000..0d04941 --- /dev/null +++ b/www/session/sqlite3changegroup_add_strm.html @@ -0,0 +1,291 @@ + + + + + +Streaming Versions of API functions. + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Streaming Versions of API functions.

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
+);
+

+The six streaming API xxx_strm() functions serve similar purposes to the +corresponding non-streaming API functions:

+ +

+ +
Streaming functionNon-streaming equivalent
sqlite3changeset_apply_strmsqlite3changeset_apply +
sqlite3changeset_apply_strm_v2sqlite3changeset_apply_v2 +
sqlite3changeset_concat_strmsqlite3changeset_concat +
sqlite3changeset_invert_strmsqlite3changeset_invert +
sqlite3changeset_start_strmsqlite3changeset_start +
sqlite3session_changeset_strmsqlite3session_changeset +
sqlite3session_patchset_strmsqlite3session_patchset +

+ +

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.

+ +

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

+ +

+       int nChangeset,
+       void *pChangeset,
+

+ +

Is replaced by:

+ +

+       int (*xInput)(void *pIn, void *pData, int *pnData),
+       void *pIn,
+

+ +

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.

+ +

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.

+ +

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:

+ +

+       int *pnChangeset,
+       void **ppChangeset,
+

+ +

Is replaced by:

+ +

+       int (*xOutput)(void *pOut, const void *pData, int nData),
+       void *pOut
+

+ +

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.

+ +

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. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3changegroup_delete.html b/www/session/sqlite3changegroup_delete.html new file mode 100644 index 0000000..1134e7a --- /dev/null +++ b/www/session/sqlite3changegroup_delete.html @@ -0,0 +1,123 @@ + + + + + +Delete A Changegroup Object + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Delete A Changegroup Object

void sqlite3changegroup_delete(sqlite3_changegroup*);
+

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3changegroup_new.html b/www/session/sqlite3changegroup_new.html new file mode 100644 index 0000000..2b2c724 --- /dev/null +++ b/www/session/sqlite3changegroup_new.html @@ -0,0 +1,155 @@ + + + + + +Create A New Changegroup Object + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Create A New Changegroup Object

int sqlite3changegroup_new(sqlite3_changegroup **pp);
+

+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.

+ +

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.

+ +

The usual usage pattern for an sqlite3_changegroup object is as follows:

+ +

    +
  • It is created using a call to sqlite3changegroup_new().

    + +

  • Zero or more changesets (or patchsets) are added to the object + by calling sqlite3changegroup_add().

    + +

  • The result of combining all input changesets together is obtained + by the application via a call to sqlite3changegroup_output().

    + +

  • The object is deleted using a call to sqlite3changegroup_delete(). +

+ +

Any number of calls to add() and output() may be made between the calls to +new() and delete(), and in any order.

+ +

As well as the regular sqlite3changegroup_add() and +sqlite3changegroup_output() functions, also available are the streaming +versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm(). +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3changegroup_output.html b/www/session/sqlite3changegroup_output.html new file mode 100644 index 0000000..5cea844 --- /dev/null +++ b/www/session/sqlite3changegroup_output.html @@ -0,0 +1,148 @@ + + + + + +Obtain A Composite Changeset From A Changegroup + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Obtain A Composite Changeset From A Changegroup

int sqlite3changegroup_output(
+  sqlite3_changegroup*,
+  int *pnData,                    /* OUT: Size of output buffer in bytes */
+  void **ppData                   /* OUT: Pointer to output buffer */
+);
+

+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.

+ +

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.

+ +

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(). +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3changeset_apply.html b/www/session/sqlite3changeset_apply.html new file mode 100644 index 0000000..ca95e9d --- /dev/null +++ b/www/session/sqlite3changeset_apply.html @@ -0,0 +1,309 @@ + + + + + +Apply A Changeset To A Database + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Apply A Changeset To A Database

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 */
+);
+

+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.

+ +

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.

+ +

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:

+ +

    +
  • The table has the same name as the name recorded in the + changeset, and +
  • The table has at least as many columns as recorded in the + changeset, and +
  • The table has primary key columns in the same position as + recorded in the changeset. +

+ +

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.

+ +

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.

+ +

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.

+ +

Each time the conflict handler function is invoked, it must return one +of SQLITE_CHANGESET_OMIT, SQLITE_CHANGESET_ABORT or +SQLITE_CHANGESET_REPLACE. 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 +available return values for details.

+ +

+
DELETE Changes
+ 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.

+ +

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 SQLITE_CHANGESET_DATA 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.

+ +

If no row with matching primary key values is found in the database, + the conflict-handler function is invoked with SQLITE_CHANGESET_NOTFOUND + passed as the second argument.

+ +

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 SQLITE_CHANGESET_CONSTRAINT + 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 SQLITE_CHANGESET_REPLACE.

+ +

INSERT Changes
+ 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.

+ +

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 + SQLITE_CHANGESET_CONFLICT.

+ +

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 SQLITE_CHANGESET_CONSTRAINT. + This includes the case where the INSERT operation is re-attempted because + an earlier call to the conflict handler function returned + SQLITE_CHANGESET_REPLACE.

+ +

UPDATE Changes
+ 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.

+ +

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 SQLITE_CHANGESET_DATA 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.

+ +

If no row with matching primary key values is found in the database, + the conflict-handler function is invoked with SQLITE_CHANGESET_NOTFOUND + passed as the second argument.

+ +

If the UPDATE operation is attempted, but SQLite returns + SQLITE_CONSTRAINT, the conflict-handler function is invoked with + SQLITE_CHANGESET_CONSTRAINT 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 + SQLITE_CHANGESET_REPLACE. +

+ +

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.

+ +

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.

+ +

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.

+ +

The behavior of sqlite3changeset_apply_v2() and its streaming equivalent +may be modified by passing a combination of +supported flags as the 9th parameter.

+ +

Note that the sqlite3changeset_apply_v2() API is still experimental +and therefore subject to change. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3changeset_concat.html b/www/session/sqlite3changeset_concat.html new file mode 100644 index 0000000..569b136 --- /dev/null +++ b/www/session/sqlite3changeset_concat.html @@ -0,0 +1,153 @@ + + + + + +Concatenate Two Changeset Objects + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Concatenate Two Changeset Objects

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 */
+);
+

+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.

+ +

This function combines the two input changesets using an +sqlite3_changegroup object. Calling it produces similar results as the +following code fragment:

+ +

+  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;
+  }
+

+ +

Refer to the sqlite3_changegroup documentation below for details. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3changeset_conflict.html b/www/session/sqlite3changeset_conflict.html new file mode 100644 index 0000000..080ca8a --- /dev/null +++ b/www/session/sqlite3changeset_conflict.html @@ -0,0 +1,145 @@ + + + + + +Obtain Conflicting Row Values From A Changeset Iterator + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Obtain Conflicting Row Values From A Changeset Iterator

int sqlite3changeset_conflict(
+  sqlite3_changeset_iter *pIter,  /* Changeset iterator */
+  int iVal,                       /* Column number */
+  sqlite3_value **ppValue         /* OUT: Value from conflicting row */
+);
+

+This function should only be used with iterator objects passed to a +conflict-handler callback by sqlite3changeset_apply() with either +SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this function +is called on any other iterator, SQLITE_MISUSE is returned and *ppValue +is set to NULL.

+ +

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, +SQLITE_RANGE is returned and *ppValue is set to NULL.

+ +

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.

+ +

If some other error occurs (e.g. an OOM condition), an SQLite error code +is returned and *ppValue is set to NULL. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3changeset_finalize.html b/www/session/sqlite3changeset_finalize.html new file mode 100644 index 0000000..6a08745 --- /dev/null +++ b/www/session/sqlite3changeset_finalize.html @@ -0,0 +1,149 @@ + + + + + +Finalize A Changeset Iterator + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Finalize A Changeset Iterator

int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);
+

+This function is used to finalize an iterator allocated with +sqlite3changeset_start().

+ +

This function should only be called on iterators created using the +sqlite3changeset_start() function. If an application calls this +function with an iterator passed to a conflict-handler by +sqlite3changeset_apply(), SQLITE_MISUSE is immediately returned and the +call has no effect.

+ +

If an error was encountered within a call to an sqlite3changeset_xxx() +function (for example an SQLITE_CORRUPT in sqlite3changeset_next() or an +SQLITE_NOMEM in sqlite3changeset_new()) 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):

+ +

+  sqlite3changeset_start();
+  while( SQLITE_ROW==sqlite3changeset_next() ){
+    // Do something with change.
+  }
+  rc = sqlite3changeset_finalize();
+  if( rc!=SQLITE_OK ){
+    // An error has occurred 
+  }
+
+

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3changeset_fk_conflicts.html b/www/session/sqlite3changeset_fk_conflicts.html new file mode 100644 index 0000000..e61d9f1 --- /dev/null +++ b/www/session/sqlite3changeset_fk_conflicts.html @@ -0,0 +1,133 @@ + + + + + +Determine The Number Of Foreign Key Constraint Violations + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Determine The Number Of Foreign Key Constraint Violations

int sqlite3changeset_fk_conflicts(
+  sqlite3_changeset_iter *pIter,  /* Changeset iterator */
+  int *pnOut                      /* OUT: Number of FK violations */
+);
+

+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.

+ +

In all other cases this function returns SQLITE_MISUSE. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3changeset_invert.html b/www/session/sqlite3changeset_invert.html new file mode 100644 index 0000000..8efb2f5 --- /dev/null +++ b/www/session/sqlite3changeset_invert.html @@ -0,0 +1,151 @@ + + + + + +Invert A Changeset + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Invert A Changeset

int sqlite3changeset_invert(
+  int nIn, const void *pIn,       /* Input changeset */
+  int *pnOut, void **ppOut        /* OUT: Inverse of input */
+);
+

+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:

+ +

    +
  • Each DELETE change is changed to an INSERT, and +
  • Each INSERT change is changed to a DELETE, and +
  • For each UPDATE change, the old.* and new.* values are exchanged. +

+ +

This function does not change the order in which changes appear within +the changeset. It merely reverses the sense of each individual change.

+ +

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.

+ +

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.

+ +

WARNING/TODO: This function currently assumes that the input is a valid +changeset. If it is not, the results are undefined. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3changeset_new.html b/www/session/sqlite3changeset_new.html new file mode 100644 index 0000000..4514b69 --- /dev/null +++ b/www/session/sqlite3changeset_new.html @@ -0,0 +1,151 @@ + + + + + +Obtain new.* Values From A Changeset Iterator + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Obtain new.* Values From A Changeset Iterator

int sqlite3changeset_new(
+  sqlite3_changeset_iter *pIter,  /* Changeset iterator */
+  int iVal,                       /* Column number */
+  sqlite3_value **ppValue         /* OUT: New value (or NULL pointer) */
+);
+

+The pIter argument passed to this function may either be an iterator +passed to a conflict-handler by sqlite3changeset_apply(), or an iterator +created by sqlite3changeset_start(). In the latter case, the most recent +call to sqlite3changeset_next() must have returned SQLITE_ROW. +Furthermore, it may only be called if the type of change that the iterator +currently points to is either SQLITE_UPDATE or SQLITE_INSERT. Otherwise, +this function returns SQLITE_MISUSE and sets *ppValue to NULL.

+ +

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, +SQLITE_RANGE is returned and *ppValue is set to NULL.

+ +

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.

+ +

If some other error occurs (e.g. an OOM condition), an SQLite error code +is returned and *ppValue is set to NULL. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3changeset_next.html b/www/session/sqlite3changeset_next.html new file mode 100644 index 0000000..18dd351 --- /dev/null +++ b/www/session/sqlite3changeset_next.html @@ -0,0 +1,142 @@ + + + + + +Advance A Changeset Iterator + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Advance A Changeset Iterator

int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
+

+This function may only be used with iterators created by the function +sqlite3changeset_start(). If it is called on an iterator passed to +a conflict-handler callback by sqlite3changeset_apply(), SQLITE_MISUSE +is returned and the call has no effect.

+ +

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.

+ +

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. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3changeset_old.html b/www/session/sqlite3changeset_old.html new file mode 100644 index 0000000..83c7d4b --- /dev/null +++ b/www/session/sqlite3changeset_old.html @@ -0,0 +1,148 @@ + + + + + +Obtain old.* Values From A Changeset Iterator + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Obtain old.* Values From A Changeset Iterator

int sqlite3changeset_old(
+  sqlite3_changeset_iter *pIter,  /* Changeset iterator */
+  int iVal,                       /* Column number */
+  sqlite3_value **ppValue         /* OUT: Old value (or NULL pointer) */
+);
+

+The pIter argument passed to this function may either be an iterator +passed to a conflict-handler by sqlite3changeset_apply(), or an iterator +created by sqlite3changeset_start(). In the latter case, the most recent +call to sqlite3changeset_next() must have returned SQLITE_ROW. +Furthermore, it may only be called if the type of change that the iterator +currently points to is either SQLITE_DELETE or SQLITE_UPDATE. Otherwise, +this function returns SQLITE_MISUSE and sets *ppValue to NULL.

+ +

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, +SQLITE_RANGE is returned and *ppValue is set to NULL.

+ +

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.

+ +

If some other error occurs (e.g. an OOM condition), an SQLite error code +is returned and *ppValue is set to NULL. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3changeset_op.html b/www/session/sqlite3changeset_op.html new file mode 100644 index 0000000..ee12396 --- /dev/null +++ b/www/session/sqlite3changeset_op.html @@ -0,0 +1,157 @@ + + + + + +Obtain The Current Operation From A Changeset Iterator + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Obtain The Current Operation From A Changeset Iterator

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 */
+);
+

+The pIter argument passed to this function may either be an iterator +passed to a conflict-handler by sqlite3changeset_apply(), or an iterator +created by sqlite3changeset_start(). In the latter case, the most recent +call to sqlite3changeset_next() must have returned SQLITE_ROW. If this +is not the case, this function returns SQLITE_MISUSE.

+ +

Arguments pOp, pnCol and pzTab may not be NULL. Upon return, three +outputs are set through these pointers:

+ +

*pOp is set to one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, +depending on the type of change that the iterator currently points to;

+ +

*pnCol is set to the number of columns in the table affected by the change; and

+ +

*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 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 +sqlite3session_indirect() for a description of direct and indirect +changes.

+ +

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. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3changeset_pk.html b/www/session/sqlite3changeset_pk.html new file mode 100644 index 0000000..bc7162b --- /dev/null +++ b/www/session/sqlite3changeset_pk.html @@ -0,0 +1,149 @@ + + + + + +Obtain The Primary Key Definition Of A Table + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Obtain The Primary Key Definition Of A Table

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 */
+);
+

+For each modified table, a changeset includes the following:

+ +

    +
  • The number of columns in the table, and +
  • Which of those columns make up the tables PRIMARY KEY. +

+ +

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.

+ +

If argument pnCol is not NULL, then *pnCol is set to the number of columns +in the table.

+ +

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. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3changeset_start.html b/www/session/sqlite3changeset_start.html new file mode 100644 index 0000000..2a0fc4e --- /dev/null +++ b/www/session/sqlite3changeset_start.html @@ -0,0 +1,170 @@ + + + + + +Create An Iterator To Traverse A Changeset + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Create An Iterator To Traverse A Changeset 

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 */
+);
+

+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.

+ +

The following functions can be used to advance and query a changeset +iterator created by this function:

+ +

+ +

It is the responsibility of the caller to eventually destroy the iterator +by passing it to sqlite3changeset_finalize(). The buffer containing the +changeset (pChangeset) must remain valid until after the iterator is +destroyed.

+ +

Assuming the changeset blob was created by one of the +sqlite3session_changeset(), sqlite3changeset_concat() or +sqlite3changeset_invert() 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.

+ +

The behavior of sqlite3changeset_start_v2() and its streaming equivalent +may be modified by passing a combination of +supported flags as the 4th parameter.

+ +

Note that the sqlite3changeset_start_v2() API is still experimental +and therefore subject to change. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3rebaser_configure.html b/www/session/sqlite3rebaser_configure.html new file mode 100644 index 0000000..09212d2 --- /dev/null +++ b/www/session/sqlite3rebaser_configure.html @@ -0,0 +1,131 @@ + + + + + +Configure a changeset rebaser object. + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Configure a changeset rebaser object.

int sqlite3rebaser_configure(
+  sqlite3_rebaser*, 
+  int nRebase, const void *pRebase
+); 
+

Important: This interface is experimental and is subject to change without notice.

+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(). +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3rebaser_create.html b/www/session/sqlite3rebaser_create.html new file mode 100644 index 0000000..4944f47 --- /dev/null +++ b/www/session/sqlite3rebaser_create.html @@ -0,0 +1,128 @@ + + + + + +Create a changeset rebaser object. + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Create a changeset rebaser object.

int sqlite3rebaser_create(sqlite3_rebaser **ppNew);
+

Important: This interface is experimental and is subject to change without notice.

+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. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3rebaser_delete.html b/www/session/sqlite3rebaser_delete.html new file mode 100644 index 0000000..7bbe064 --- /dev/null +++ b/www/session/sqlite3rebaser_delete.html @@ -0,0 +1,127 @@ + + + + + +Delete a changeset rebaser object. + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Delete a changeset rebaser object.

void sqlite3rebaser_delete(sqlite3_rebaser *p); 
+

Important: This interface is experimental and is subject to change without notice.

+Delete the changeset rebaser object and all associated resources. There +should be one call to this function for each successful invocation +of sqlite3rebaser_create(). +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3rebaser_rebase.html b/www/session/sqlite3rebaser_rebase.html new file mode 100644 index 0000000..ad2bdb3 --- /dev/null +++ b/www/session/sqlite3rebaser_rebase.html @@ -0,0 +1,137 @@ + + + + + +Rebase a changeset + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Rebase a changeset

int sqlite3rebaser_rebase(
+  sqlite3_rebaser*,
+  int nIn, const void *pIn, 
+  int *pnOut, void **ppOut 
+);
+

Important: This interface is experimental and is subject to change without notice.

+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. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3session_attach.html b/www/session/sqlite3session_attach.html new file mode 100644 index 0000000..25a2303 --- /dev/null +++ b/www/session/sqlite3session_attach.html @@ -0,0 +1,180 @@ + + + + + +Attach A Table To A Session Object + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Attach A Table To A Session Object

int sqlite3session_attach(
+  sqlite3_session *pSession,      /* Session object */
+  const char *zTab                /* Table name */
+);
+

+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 sqlite3session_changeset() for further details.

+ +

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.

+ +

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.

+ +

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.

+ +

Changes are not recorded for individual rows that have NULL values stored +in one or more of their PRIMARY KEY columns.

+ +

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.

+ +

Special sqlite_stat1 Handling

+ +

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: + 

+       CREATE TABLE sqlite_stat1(tbl,idx,stat)  
+

+ +

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.

+ +

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.

+ +

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. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3session_changeset.html b/www/session/sqlite3session_changeset.html new file mode 100644 index 0000000..729ca8e --- /dev/null +++ b/www/session/sqlite3session_changeset.html @@ -0,0 +1,228 @@ + + + + + +Generate A Changeset From A Session Object + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Generate A Changeset From A Session Object

int sqlite3session_changeset(
+  sqlite3_session *pSession,      /* Session object */
+  int *pnChangeset,               /* OUT: Size of buffer at *ppChangeset */
+  void **ppChangeset              /* OUT: Buffer containing changeset */
+);
+

+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.

+ +

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.

+ +

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.

+ +

The contents of a changeset may be traversed using an iterator created +using the sqlite3changeset_start() API. A changeset may be applied to +a database with a compatible schema using the sqlite3changeset_apply() +API.

+ +

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.

+ +

Following a successful call to this function, it is the responsibility of +the caller to eventually free the buffer that *ppChangeset points to using +sqlite3_free().

+ +

Changeset Generation

+ +

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.

+ +

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.

+ +

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).

+ +

When this function is called, the requested changeset is created using +both the accumulated records and the current contents of the database +file. Specifically:

+ +

    +
  • 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.

    + +

  • 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. +

+ +

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.

+ +

When a session object is disabled (see the sqlite3session_enable() 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. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3session_changeset_size.html b/www/session/sqlite3session_changeset_size.html new file mode 100644 index 0000000..719df80 --- /dev/null +++ b/www/session/sqlite3session_changeset_size.html @@ -0,0 +1,133 @@ + + + + + +Return An Upper-limit For The Size Of The Changeset + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Return An Upper-limit For The Size Of The Changeset

sqlite3_int64 sqlite3session_changeset_size(sqlite3_session *pSession);
+

+By default, this function always returns 0. For it to return +a useful result, the sqlite3_session object must have been configured +to enable this API using sqlite3session_object_config() with the +SQLITE_SESSION_OBJCONFIG_SIZE verb.

+ +

When enabled, this function returns an upper limit, in bytes, for the size +of the changeset that might be produced if sqlite3session_changeset() were +called. The final changeset size might be equal to or smaller than the +size in bytes returned by this function. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3session_config.html b/www/session/sqlite3session_config.html new file mode 100644 index 0000000..3f9a9bb --- /dev/null +++ b/www/session/sqlite3session_config.html @@ -0,0 +1,153 @@ + + + + + +Configure global parameters + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Configure global parameters

int sqlite3session_config(int op, void *pArg);
+

+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.

+ +

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.

+ +

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.

+ +

+
SQLITE_SESSION_CONFIG_STRMSIZE
+ 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. +

+ +

This function returns SQLITE_OK if successful, or an SQLite error code +otherwise. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3session_create.html b/www/session/sqlite3session_create.html new file mode 100644 index 0000000..8755501 --- /dev/null +++ b/www/session/sqlite3session_create.html @@ -0,0 +1,154 @@ + + + + + +Create A New Session Object + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Create A New Session Object

int sqlite3session_create(
+  sqlite3 *db,                    /* Database handle */
+  const char *zDb,                /* Name of db (e.g. "main") */
+  sqlite3_session **ppSession     /* OUT: New session object */
+);
+

+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.

+ +

It is possible to create multiple session objects attached to a single +database handle.

+ +

Session objects created using this function should be deleted using the +sqlite3session_delete() 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 sqlite3session_delete() on the session object +are undefined.

+ +

Because the session module uses the sqlite3_preupdate_hook() 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.

+ +

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. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3session_delete.html b/www/session/sqlite3session_delete.html new file mode 100644 index 0000000..4fece3e --- /dev/null +++ b/www/session/sqlite3session_delete.html @@ -0,0 +1,132 @@ + + + + + +Delete A Session Object + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Delete A Session Object

void sqlite3session_delete(sqlite3_session *pSession);
+

+Delete a session object previously allocated using +sqlite3session_create(). Once a session object has been deleted, the +results of attempting to use pSession with any other session module +function are undefined.

+ +

Session objects must be deleted before the database handle to which they +are attached is closed. Refer to the documentation for +sqlite3session_create() for details. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3session_diff.html b/www/session/sqlite3session_diff.html new file mode 100644 index 0000000..cb4e478 --- /dev/null +++ b/www/session/sqlite3session_diff.html @@ -0,0 +1,181 @@ + + + + + +Load The Difference Between Tables Into A Session + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Load The Difference Between Tables Into A Session

int sqlite3session_diff(
+  sqlite3_session *pSession,
+  const char *zFromDb,
+  const char *zTbl,
+  char **pzErrMsg
+);
+

+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 +sqlite3session_attach() 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).

+ +

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:

+ +

    +
  • Has the same name, +
  • Has the same set of columns declared in the same order, and +
  • Has the same PRIMARY KEY definition. +

+ +

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.

+ +

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:

+ +

    +
  • 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.

    + +

  • 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.

    + +

  • 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. +

+ +

To clarify, if this function is called and then a changeset constructed +using sqlite3session_changeset(), then after applying that changeset to +database zFrom the contents of the two compatible tables would be +identical.

+ +

It an error if database zFrom does not exist or does not contain the +required compatible table.

+ +

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(). +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3session_enable.html b/www/session/sqlite3session_enable.html new file mode 100644 index 0000000..2454a35 --- /dev/null +++ b/www/session/sqlite3session_enable.html @@ -0,0 +1,137 @@ + + + + + +Enable Or Disable A Session Object + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Enable Or Disable A Session Object

int sqlite3session_enable(sqlite3_session *pSession, int bEnable);
+

+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 sqlite3session_changeset() for further +details regarding how enabling and disabling a session object affects +the eventual changesets.

+ +

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.

+ +

The return value indicates the final state of the session object: 0 if +the session is disabled, or 1 if it is enabled. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3session_indirect.html b/www/session/sqlite3session_indirect.html new file mode 100644 index 0000000..0d4022b --- /dev/null +++ b/www/session/sqlite3session_indirect.html @@ -0,0 +1,147 @@ + + + + + +Set Or Clear the Indirect Change Flag + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Set Or Clear the Indirect Change Flag

int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect);
+

+Each change recorded by a session object is marked as either direct or +indirect. A change is marked as indirect if either:

+ +

    +
  • The session object "indirect" flag is set when the change is + made, or +
  • The change is made by an SQL trigger or foreign key action + instead of directly as a result of a users SQL statement. +

+ +

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.

+ +

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.

+ +

The return value indicates the final state of the indirect flag: 0 if +it is clear, or 1 if it is set. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3session_isempty.html b/www/session/sqlite3session_isempty.html new file mode 100644 index 0000000..2762f9c --- /dev/null +++ b/www/session/sqlite3session_isempty.html @@ -0,0 +1,135 @@ + + + + + +Test if a changeset has recorded any changes. + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Test if a changeset has recorded any changes.

int sqlite3session_isempty(sqlite3_session *pSession);
+

+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.

+ +

Even if this function returns zero, it is possible that calling +sqlite3session_changeset() 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. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3session_memory_used.html b/www/session/sqlite3session_memory_used.html new file mode 100644 index 0000000..04c1f53 --- /dev/null +++ b/www/session/sqlite3session_memory_used.html @@ -0,0 +1,126 @@ + + + + + +Query for the amount of heap memory used by a session object. + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Query for the amount of heap memory used by a session object.

sqlite3_int64 sqlite3session_memory_used(sqlite3_session *pSession);
+

+This API returns the total amount of heap memory in bytes currently +used by the session object passed as the only argument. +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3session_patchset.html b/www/session/sqlite3session_patchset.html new file mode 100644 index 0000000..a7acd25 --- /dev/null +++ b/www/session/sqlite3session_patchset.html @@ -0,0 +1,152 @@ + + + + + +Generate A Patchset From A Session Object + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Generate A Patchset From A Session Object

int sqlite3session_patchset(
+  sqlite3_session *pSession,      /* Session object */
+  int *pnPatchset,                /* OUT: Size of buffer at *ppPatchset */
+  void **ppPatchset               /* OUT: Buffer containing patchset */
+);
+

+The differences between a patchset and a changeset are that:

+ +

    +
  • DELETE records consist of the primary key fields only. The + original values of other fields are omitted. +
  • The original values of any modified fields are omitted from + UPDATE records. +

+ +

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.

+ +

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.

+ +

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). +

See also lists of + Objects, + Constants, and + Functions.

+ diff --git a/www/session/sqlite3session_table_filter.html b/www/session/sqlite3session_table_filter.html new file mode 100644 index 0000000..331b9c2 --- /dev/null +++ b/www/session/sqlite3session_table_filter.html @@ -0,0 +1,136 @@ + + + + + +Set a table filter on a Session Object. + + + +
+ + + +
+
+Small. Fast. Reliable.
Choose any three. +
+
+ +
+ +
+
+ + + +
+
+
+ +

Session Module C Interface

Set a table filter on a Session Object.

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 */
+);
+

+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. +

See also lists of + Objects, + Constants, and + Functions.

+ -- cgit v1.2.3