| |
| #if !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION) |
| #define __SQLITESESSION_H_ 1 |
| |
| /* |
| ** Make sure we can call this stuff from C++. |
| */ |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| #include "sqlite3.h" |
| |
| /* |
| ** CAPI3REF: Session Object Handle |
| ** |
| ** An instance of this object is a [session] that can be used to |
| ** record changes to a database. |
| */ |
| typedef struct sqlite3_session sqlite3_session; |
| |
| /* |
| ** CAPI3REF: Changeset Iterator Handle |
| ** |
| ** An instance of this object acts as a cursor for iterating |
| ** over the elements of a [changeset] or [patchset]. |
| */ |
| typedef struct sqlite3_changeset_iter sqlite3_changeset_iter; |
| |
| /* |
| ** CAPI3REF: Create A New Session Object |
| ** CONSTRUCTOR: sqlite3_session |
| ** |
| ** 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. |
| */ |
| int sqlite3session_create( |
| sqlite3 *db, /* Database handle */ |
| const char *zDb, /* Name of db (e.g. "main") */ |
| sqlite3_session **ppSession /* OUT: New session object */ |
| ); |
| |
| /* |
| ** CAPI3REF: Delete A Session Object |
| ** DESTRUCTOR: sqlite3_session |
| ** |
| ** 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. |
| */ |
| void sqlite3session_delete(sqlite3_session *pSession); |
| |
| /* |
| ** CAPI3REF: Configure a Session Object |
| ** METHOD: sqlite3_session |
| ** |
| ** This method is used to configure a session object after it has been |
| ** created. At present the only valid values for the second parameter are |
| ** [SQLITE_SESSION_OBJCONFIG_SIZE] and [SQLITE_SESSION_OBJCONFIG_ROWID]. |
| ** |
| */ |
| int sqlite3session_object_config(sqlite3_session*, int op, void *pArg); |
| |
| /* |
| ** CAPI3REF: Options for sqlite3session_object_config |
| ** |
| ** The following values may passed as the the 2nd parameter to |
| ** sqlite3session_object_config(). |
| ** |
| ** <dt>SQLITE_SESSION_OBJCONFIG_SIZE <dd> |
| ** This option is used to set, clear or query the flag that enables |
| ** the [sqlite3session_changeset_size()] API. Because it imposes some |
| ** computational overhead, this API is disabled by default. Argument |
| ** pArg must point to a value of type (int). If the value is initially |
| ** 0, then the sqlite3session_changeset_size() API is disabled. If it |
| ** is greater than 0, then the same API is enabled. Or, if the initial |
| ** value is less than zero, no change is made. In all cases the (int) |
| ** variable is set to 1 if the sqlite3session_changeset_size() API is |
| ** enabled following the current call, or 0 otherwise. |
| ** |
| ** It is an error (SQLITE_MISUSE) to attempt to modify this setting after |
| ** the first table has been attached to the session object. |
| ** |
| ** <dt>SQLITE_SESSION_OBJCONFIG_ROWID <dd> |
| ** This option is used to set, clear or query the flag that enables |
| ** collection of data for tables with no explicit PRIMARY KEY. |
| ** |
| ** Normally, tables with no explicit PRIMARY KEY are simply ignored |
| ** by the sessions module. However, if this flag is set, it behaves |
| ** as if such tables have a column "_rowid_ INTEGER PRIMARY KEY" inserted |
| ** as their leftmost columns. |
| ** |
| ** It is an error (SQLITE_MISUSE) to attempt to modify this setting after |
| ** the first table has been attached to the session object. |
| */ |
| #define SQLITE_SESSION_OBJCONFIG_SIZE 1 |
| #define SQLITE_SESSION_OBJCONFIG_ROWID 2 |
| |
| /* |
| ** CAPI3REF: Enable Or Disable A Session Object |
| ** METHOD: sqlite3_session |
| ** |
| ** 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. |
| */ |
| int sqlite3session_enable(sqlite3_session *pSession, int bEnable); |
| |
| /* |
| ** CAPI3REF: Set Or Clear the Indirect Change Flag |
| ** METHOD: sqlite3_session |
| ** |
| ** Each change recorded by a session object is marked as either direct or |
| ** indirect. A change is marked as indirect if either: |
| ** |
| ** <ul> |
| ** <li> The session object "indirect" flag is set when the change is |
| ** made, or |
| ** <li> The change is made by an SQL trigger or foreign key action |
| ** instead of directly as a result of a users SQL statement. |
| ** </ul> |
| ** |
| ** 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. |
| */ |
| int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect); |
| |
| /* |
| ** CAPI3REF: Attach A Table To A Session Object |
| ** METHOD: sqlite3_session |
| ** |
| ** 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. |
| ** |
| ** <h3>Special sqlite_stat1 Handling</h3> |
| ** |
| ** As of SQLite version 3.22.0, the "sqlite_stat1" table is an exception to |
| ** some of the rules above. In SQLite, the schema of sqlite_stat1 is: |
| ** <pre> |
| ** CREATE TABLE sqlite_stat1(tbl,idx,stat) |
| ** </pre> |
| ** |
| ** 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. |
| */ |
| int sqlite3session_attach( |
| sqlite3_session *pSession, /* Session object */ |
| const char *zTab /* Table name */ |
| ); |
| |
| /* |
| ** CAPI3REF: Set a table filter on a Session Object. |
| ** METHOD: sqlite3_session |
| ** |
| ** 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. |
| */ |
| 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 */ |
| ); |
| |
| /* |
| ** CAPI3REF: Generate A Changeset From A Session Object |
| ** METHOD: sqlite3_session |
| ** |
| ** 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()]. |
| ** |
| ** <h3>Changeset Generation</h3> |
| ** |
| ** 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: |
| ** |
| ** <ul> |
| ** <li> For each record generated by an insert, the database is queried |
| ** for a row with a matching primary key. If one is found, an INSERT |
| ** change is added to the changeset. If no such row is found, no change |
| ** is added to the changeset. |
| ** |
| ** <li> For each record generated by an update or delete, the database is |
| ** queried for a row with a matching primary key. If such a row is |
| ** found and one or more of the non-primary key fields have been |
| ** modified from their original values, an UPDATE change is added to |
| ** the changeset. Or, if no such row is found in the table, a DELETE |
| ** change is added to the changeset. If there is a row with a matching |
| ** primary key in the database, but all fields contain their original |
| ** values, no change is added to the changeset. |
| ** </ul> |
| ** |
| ** 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. |
| */ |
| int sqlite3session_changeset( |
| sqlite3_session *pSession, /* Session object */ |
| int *pnChangeset, /* OUT: Size of buffer at *ppChangeset */ |
| void **ppChangeset /* OUT: Buffer containing changeset */ |
| ); |
| |
| /* |
| ** CAPI3REF: Return An Upper-limit For The Size Of The Changeset |
| ** METHOD: sqlite3_session |
| ** |
| ** 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. |
| */ |
| sqlite3_int64 sqlite3session_changeset_size(sqlite3_session *pSession); |
| |
| /* |
| ** CAPI3REF: Load The Difference Between Tables Into A Session |
| ** METHOD: sqlite3_session |
| ** |
| ** 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: |
| ** |
| ** <ul> |
| ** <li> Has the same name, |
| ** <li> Has the same set of columns declared in the same order, and |
| ** <li> Has the same PRIMARY KEY definition. |
| ** </ul> |
| ** |
| ** 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: |
| ** |
| ** <ul> |
| ** <li> For each row (primary key) that exists in the to-table but not in |
| ** the from-table, an INSERT record is added to the session object. |
| ** |
| ** <li> For each row (primary key) that exists in the to-table but not in |
| ** the from-table, a DELETE record is added to the session object. |
| ** |
| ** <li> For each row (primary key) that exists in both tables, but features |
| ** different non-PK values in each, an UPDATE record is added to the |
| ** session. |
| ** </ul> |
| ** |
| ** 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(). |
| */ |
| int sqlite3session_diff( |
| sqlite3_session *pSession, |
| const char *zFromDb, |
| const char *zTbl, |
| char **pzErrMsg |
| ); |
| |
| |
| /* |
| ** CAPI3REF: Generate A Patchset From A Session Object |
| ** METHOD: sqlite3_session |
| ** |
| ** The differences between a patchset and a changeset are that: |
| ** |
| ** <ul> |
| ** <li> DELETE records consist of the primary key fields only. The |
| ** original values of other fields are omitted. |
| ** <li> The original values of any modified fields are omitted from |
| ** UPDATE records. |
| ** </ul> |
| ** |
| ** 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). |
| */ |
| int sqlite3session_patchset( |
| sqlite3_session *pSession, /* Session object */ |
| int *pnPatchset, /* OUT: Size of buffer at *ppPatchset */ |
| void **ppPatchset /* OUT: Buffer containing patchset */ |
| ); |
| |
| /* |
| ** CAPI3REF: Test if a changeset has recorded any changes. |
| ** |
| ** 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. |
| */ |
| int sqlite3session_isempty(sqlite3_session *pSession); |
| |
| /* |
| ** CAPI3REF: Query for the amount of heap memory used by a session object. |
| ** |
| ** This API returns the total amount of heap memory in bytes currently |
| ** used by the session object passed as the only argument. |
| */ |
| sqlite3_int64 sqlite3session_memory_used(sqlite3_session *pSession); |
| |
| /* |
| ** CAPI3REF: Create An Iterator To Traverse A Changeset |
| ** CONSTRUCTOR: sqlite3_changeset_iter |
| ** |
| ** 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: |
| ** |
| ** <ul> |
| ** <li> [sqlite3changeset_next()] |
| ** <li> [sqlite3changeset_op()] |
| ** <li> [sqlite3changeset_new()] |
| ** <li> [sqlite3changeset_old()] |
| ** </ul> |
| ** |
| ** 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 |
| ** [SQLITE_CHANGESETSTART_INVERT | supported flags] as the 4th parameter. |
| ** |
| ** Note that the sqlite3changeset_start_v2() API is still <b>experimental</b> |
| ** and therefore subject to change. |
| */ |
| 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 */ |
| ); |
| |
| /* |
| ** CAPI3REF: Flags for sqlite3changeset_start_v2 |
| ** |
| ** The following flags may passed via the 4th parameter to |
| ** [sqlite3changeset_start_v2] and [sqlite3changeset_start_v2_strm]: |
| ** |
| ** <dt>SQLITE_CHANGESETAPPLY_INVERT <dd> |
| ** Invert the changeset while iterating through it. This is equivalent to |
| ** inverting a changeset using sqlite3changeset_invert() before applying it. |
| ** It is an error to specify this flag with a patchset. |
| */ |
| #define SQLITE_CHANGESETSTART_INVERT 0x0002 |
| |
| |
| /* |
| ** CAPI3REF: Advance A Changeset Iterator |
| ** METHOD: sqlite3_changeset_iter |
| ** |
| ** 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. |
| */ |
| int sqlite3changeset_next(sqlite3_changeset_iter *pIter); |
| |
| /* |
| ** CAPI3REF: Obtain The Current Operation From A Changeset Iterator |
| ** METHOD: sqlite3_changeset_iter |
| ** |
| ** 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. |
| */ |
| 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 */ |
| ); |
| |
| /* |
| ** CAPI3REF: Obtain The Primary Key Definition Of A Table |
| ** METHOD: sqlite3_changeset_iter |
| ** |
| ** For each modified table, a changeset includes the following: |
| ** |
| ** <ul> |
| ** <li> The number of columns in the table, and |
| ** <li> Which of those columns make up the tables PRIMARY KEY. |
| ** </ul> |
| ** |
| ** 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. |
| */ |
| 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 */ |
| ); |
| |
| /* |
| ** CAPI3REF: Obtain old.* Values From A Changeset Iterator |
| ** METHOD: sqlite3_changeset_iter |
| ** |
| ** 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. |
| */ |
| int sqlite3changeset_old( |
| sqlite3_changeset_iter *pIter, /* Changeset iterator */ |
| int iVal, /* Column number */ |
| sqlite3_value **ppValue /* OUT: Old value (or NULL pointer) */ |
| ); |
| |
| /* |
| ** CAPI3REF: Obtain new.* Values From A Changeset Iterator |
| ** METHOD: sqlite3_changeset_iter |
| ** |
| ** 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. |
| */ |
| int sqlite3changeset_new( |
| sqlite3_changeset_iter *pIter, /* Changeset iterator */ |
| int iVal, /* Column number */ |
| sqlite3_value **ppValue /* OUT: New value (or NULL pointer) */ |
| ); |
| |
| /* |
| ** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator |
| ** METHOD: sqlite3_changeset_iter |
| ** |
| ** 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. |
| */ |
| int sqlite3changeset_conflict( |
| sqlite3_changeset_iter *pIter, /* Changeset iterator */ |
| int iVal, /* Column number */ |
| sqlite3_value **ppValue /* OUT: Value from conflicting row */ |
| ); |
| |
| /* |
| ** CAPI3REF: Determine The Number Of Foreign Key Constraint Violations |
| ** METHOD: sqlite3_changeset_iter |
| ** |
| ** 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. |
| */ |
| int sqlite3changeset_fk_conflicts( |
| sqlite3_changeset_iter *pIter, /* Changeset iterator */ |
| int *pnOut /* OUT: Number of FK violations */ |
| ); |
| |
| |
| /* |
| ** CAPI3REF: Finalize A Changeset Iterator |
| ** METHOD: sqlite3_changeset_iter |
| ** |
| ** 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): |
| ** |
| ** <pre> |
| ** sqlite3changeset_start(); |
| ** while( SQLITE_ROW==sqlite3changeset_next() ){ |
| ** // Do something with change. |
| ** } |
| ** rc = sqlite3changeset_finalize(); |
| ** if( rc!=SQLITE_OK ){ |
| ** // An error has occurred |
| ** } |
| ** </pre> |
| */ |
| int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter); |
| |
| /* |
| ** CAPI3REF: Invert A Changeset |
| ** |
| ** 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: |
| ** |
| ** <ul> |
| ** <li> Each DELETE change is changed to an INSERT, and |
| ** <li> Each INSERT change is changed to a DELETE, and |
| ** <li> For each UPDATE change, the old.* and new.* values are exchanged. |
| ** </ul> |
| ** |
| ** 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. |
| */ |
| int sqlite3changeset_invert( |
| int nIn, const void *pIn, /* Input changeset */ |
| int *pnOut, void **ppOut /* OUT: Inverse of input */ |
| ); |
| |
| /* |
| ** CAPI3REF: Concatenate Two Changeset Objects |
| ** |
| ** 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: |
| ** |
| ** <pre> |
| ** sqlite3_changegroup *pGrp; |
| ** rc = sqlite3_changegroup_new(&pGrp); |
| ** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nA, pA); |
| ** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nB, pB); |
| ** if( rc==SQLITE_OK ){ |
| ** rc = sqlite3changegroup_output(pGrp, pnOut, ppOut); |
| ** }else{ |
| ** *ppOut = 0; |
| ** *pnOut = 0; |
| ** } |
| ** </pre> |
| ** |
| ** Refer to the sqlite3_changegroup documentation below for details. |
| */ |
| 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 */ |
| ); |
| |
| |
| /* |
| ** CAPI3REF: Upgrade the Schema of a Changeset/Patchset |
| */ |
| int sqlite3changeset_upgrade( |
| sqlite3 *db, |
| const char *zDb, |
| int nIn, const void *pIn, /* Input changeset */ |
| int *pnOut, void **ppOut /* OUT: Inverse of input */ |
| ); |
| |
| |
| |
| /* |
| ** CAPI3REF: Changegroup Handle |
| ** |
| ** A changegroup is an object used to combine two or more |
| ** [changesets] or [patchsets] |
| */ |
| typedef struct sqlite3_changegroup sqlite3_changegroup; |
| |
| /* |
| ** CAPI3REF: Create A New Changegroup Object |
| ** CONSTRUCTOR: sqlite3_changegroup |
| ** |
| ** 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: |
| ** |
| ** <ul> |
| ** <li> It is created using a call to sqlite3changegroup_new(). |
| ** |
| ** <li> Zero or more changesets (or patchsets) are added to the object |
| ** by calling sqlite3changegroup_add(). |
| ** |
| ** <li> The result of combining all input changesets together is obtained |
| ** by the application via a call to sqlite3changegroup_output(). |
| ** |
| ** <li> The object is deleted using a call to sqlite3changegroup_delete(). |
| ** </ul> |
| ** |
| ** 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(). |
| */ |
| int sqlite3changegroup_new(sqlite3_changegroup **pp); |
| |
| /* |
| ** CAPI3REF: Add a Schema to a Changegroup |
| ** METHOD: sqlite3_changegroup_schema |
| ** |
| ** This method may be used to optionally enforce the rule that the changesets |
| ** added to the changegroup handle must match the schema of database zDb |
| ** ("main", "temp", or the name of an attached database). If |
| ** sqlite3changegroup_add() is called to add a changeset that is not compatible |
| ** with the configured schema, SQLITE_SCHEMA is returned and the changegroup |
| ** object is left in an undefined state. |
| ** |
| ** A changeset schema is considered compatible with the database schema in |
| ** the same way as for sqlite3changeset_apply(). Specifically, for each |
| ** table in the changeset, there exists a database table with: |
| ** |
| ** <ul> |
| ** <li> The name identified by the changeset, and |
| ** <li> at least as many columns as recorded in the changeset, and |
| ** <li> the primary key columns in the same position as recorded in |
| ** the changeset. |
| ** </ul> |
| ** |
| ** The output of the changegroup object always has the same schema as the |
| ** database nominated using this function. In cases where changesets passed |
| ** to sqlite3changegroup_add() have fewer columns than the corresponding table |
| ** in the database schema, these are filled in using the default column |
| ** values from the database schema. This makes it possible to combined |
| ** changesets that have different numbers of columns for a single table |
| ** within a changegroup, provided that they are otherwise compatible. |
| */ |
| int sqlite3changegroup_schema(sqlite3_changegroup*, sqlite3*, const char *zDb); |
| |
| /* |
| ** CAPI3REF: Add A Changeset To A Changegroup |
| ** METHOD: sqlite3_changegroup |
| ** |
| ** 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: |
| ** |
| ** <table border=1 style="margin-left:8ex;margin-right:8ex"> |
| ** <tr><th style="white-space:pre">Existing Change </th> |
| ** <th style="white-space:pre">New Change </th> |
| ** <th>Output Change |
| ** <tr><td>INSERT <td>INSERT <td> |
| ** The new change is ignored. This case does not occur if the new |
| ** changeset was recorded immediately after the changesets already |
| ** added to the changegroup. |
| ** <tr><td>INSERT <td>UPDATE <td> |
| ** The INSERT change remains in the changegroup. The values in the |
| ** INSERT change are modified as if the row was inserted by the |
| ** existing change and then updated according to the new change. |
| ** <tr><td>INSERT <td>DELETE <td> |
| ** The existing INSERT is removed from the changegroup. The DELETE is |
| ** not added. |
| ** <tr><td>UPDATE <td>INSERT <td> |
| ** The new change is ignored. This case does not occur if the new |
| ** changeset was recorded immediately after the changesets already |
| ** added to the changegroup. |
| ** <tr><td>UPDATE <td>UPDATE <td> |
| ** The existing UPDATE remains within the changegroup. It is amended |
| ** so that the accompanying values are as if the row was updated once |
| ** by the existing change and then again by the new change. |
| ** <tr><td>UPDATE <td>DELETE <td> |
| ** The existing UPDATE is replaced by the new DELETE within the |
| ** changegroup. |
| ** <tr><td>DELETE <td>INSERT <td> |
| ** If one or more of the column values in the row inserted by the |
| ** new change differ from those in the row deleted by the existing |
| ** change, the existing DELETE is replaced by an UPDATE within the |
| ** changegroup. Otherwise, if the inserted row is exactly the same |
| ** as the deleted row, the existing DELETE is simply discarded. |
| ** <tr><td>DELETE <td>UPDATE <td> |
| ** The new change is ignored. This case does not occur if the new |
| ** changeset was recorded immediately after the changesets already |
| ** added to the changegroup. |
| ** <tr><td>DELETE <td>DELETE <td> |
| ** The new change is ignored. This case does not occur if the new |
| ** changeset was recorded immediately after the changesets already |
| ** added to the changegroup. |
| ** </table> |
| ** |
| ** 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. Except, if the changegroup |
| ** object has been configured with a database schema using the |
| ** sqlite3changegroup_schema() API, then it is possible to combine changesets |
| ** with different numbers of columns for a single table, provided that |
| ** they are otherwise compatible. |
| ** |
| ** 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. |
| */ |
| int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pData); |
| |
| /* |
| ** CAPI3REF: Add A Single Change To A Changegroup |
| ** METHOD: sqlite3_changegroup |
| ** |
| ** This function adds the single change currently indicated by the iterator |
| ** passed as the second argument to the changegroup object. The rules for |
| ** adding the change are just as described for [sqlite3changegroup_add()]. |
| ** |
| ** If the change is successfully added to the changegroup, SQLITE_OK is |
| ** returned. Otherwise, an SQLite error code is returned. |
| ** |
| ** The iterator must point to a valid entry when this function is called. |
| ** If it does not, SQLITE_ERROR is returned and no change is added to the |
| ** changegroup. Additionally, the iterator must not have been opened with |
| ** the SQLITE_CHANGESETAPPLY_INVERT flag. In this case SQLITE_ERROR is also |
| ** returned. |
| */ |
| int sqlite3changegroup_add_change( |
| sqlite3_changegroup*, |
| sqlite3_changeset_iter* |
| ); |
| |
| |
| |
| /* |
| ** CAPI3REF: Obtain A Composite Changeset From A Changegroup |
| ** METHOD: sqlite3_changegroup |
| ** |
| ** 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(). |
| */ |
| int sqlite3changegroup_output( |
| sqlite3_changegroup*, |
| int *pnData, /* OUT: Size of output buffer in bytes */ |
| void **ppData /* OUT: Pointer to output buffer */ |
| ); |
| |
| /* |
| ** CAPI3REF: Delete A Changegroup Object |
| ** DESTRUCTOR: sqlite3_changegroup |
| */ |
| void sqlite3changegroup_delete(sqlite3_changegroup*); |
| |
| /* |
| ** CAPI3REF: Apply A Changeset To A Database |
| ** |
| ** 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: |
| ** |
| ** <ul> |
| ** <li> The table has the same name as the name recorded in the |
| ** changeset, and |
| ** <li> The table has at least as many columns as recorded in the |
| ** changeset, and |
| ** <li> The table has primary key columns in the same position as |
| ** recorded in the changeset. |
| ** </ul> |
| ** |
| ** 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 |
| ** [SQLITE_CHANGESET_OMIT|available return values] for details. |
| ** |
| ** <dl> |
| ** <dt>DELETE Changes<dd> |
| ** For each DELETE change, the function checks if the target database |
| ** contains a row with the same primary key value (or values) as the |
| ** original row values stored in the changeset. If it does, and the values |
| ** stored in all non-primary key columns also match the values stored in |
| ** the changeset the row is deleted from the target database. |
| ** |
| ** 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]. |
| ** |
| ** <dt>INSERT Changes<dd> |
| ** For each INSERT change, an attempt is made to insert the new row into |
| ** the database. If the changeset row contains fewer fields than the |
| ** database table, the trailing fields are populated with their default |
| ** values. |
| ** |
| ** 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]. |
| ** |
| ** <dt>UPDATE Changes<dd> |
| ** For each UPDATE change, the function checks if the target database |
| ** contains a row with the same primary key value (or values) as the |
| ** original row values stored in the changeset. If it does, and the values |
| ** stored in all modified non-primary key columns also match the values |
| ** stored in the changeset the row is updated within the target database. |
| ** |
| ** 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]. |
| ** </dl> |
| ** |
| ** 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 |
| ** [SQLITE_CHANGESETAPPLY_NOSAVEPOINT | supported flags] as the 9th parameter. |
| ** |
| ** Note that the sqlite3changeset_apply_v2() API is still <b>experimental</b> |
| ** and therefore subject to change. |
| */ |
| 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 */ |
| ); |
| |
| /* |
| ** CAPI3REF: Flags for sqlite3changeset_apply_v2 |
| ** |
| ** The following flags may passed via the 9th parameter to |
| ** [sqlite3changeset_apply_v2] and [sqlite3changeset_apply_v2_strm]: |
| ** |
| ** <dl> |
| ** <dt>SQLITE_CHANGESETAPPLY_NOSAVEPOINT <dd> |
| ** Usually, the sessions module encloses all operations performed by |
| ** a single call to apply_v2() or apply_v2_strm() in a [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. |
| ** |
| ** <dt>SQLITE_CHANGESETAPPLY_INVERT <dd> |
| ** Invert the changeset before applying it. This is equivalent to inverting |
| ** a changeset using sqlite3changeset_invert() before applying it. It is |
| ** an error to specify this flag with a patchset. |
| ** |
| ** <dt>SQLITE_CHANGESETAPPLY_IGNORENOOP <dd> |
| ** Do not invoke the conflict handler callback for any changes that |
| ** would not actually modify the database even if they were applied. |
| ** Specifically, this means that the conflict handler is not invoked |
| ** for: |
| ** <ul> |
| ** <li>a delete change if the row being deleted cannot be found, |
| ** <li>an update change if the modified fields are already set to |
| ** their new values in the conflicting row, or |
| ** <li>an insert change if all fields of the conflicting row match |
| ** the row being inserted. |
| ** </ul> |
| ** |
| ** <dt>SQLITE_CHANGESETAPPLY_FKNOACTION <dd> |
| ** If this flag it set, then all foreign key constraints in the target |
| ** database behave as if they were declared with "ON UPDATE NO ACTION ON |
| ** DELETE NO ACTION", even if they are actually CASCADE, RESTRICT, SET NULL |
| ** or SET DEFAULT. |
| */ |
| #define SQLITE_CHANGESETAPPLY_NOSAVEPOINT 0x0001 |
| #define SQLITE_CHANGESETAPPLY_INVERT 0x0002 |
| #define SQLITE_CHANGESETAPPLY_IGNORENOOP 0x0004 |
| #define SQLITE_CHANGESETAPPLY_FKNOACTION 0x0008 |
| |
| /* |
| ** CAPI3REF: Constants Passed To The Conflict Handler |
| ** |
| ** Values that may be passed as the second argument to a conflict-handler. |
| ** |
| ** <dl> |
| ** <dt>SQLITE_CHANGESET_DATA<dd> |
| ** The conflict handler is invoked with CHANGESET_DATA as the second argument |
| ** when processing a DELETE or UPDATE change if a row with the required |
| ** PRIMARY KEY fields is present in the database, but one or more other |
| ** (non primary-key) fields modified by the update do not contain the |
| ** expected "before" values. |
| ** |
| ** The conflicting row, in this case, is the database row with the matching |
| ** primary key. |
| ** |
| ** <dt>SQLITE_CHANGESET_NOTFOUND<dd> |
| ** The conflict handler is invoked with CHANGESET_NOTFOUND as the second |
| ** argument when processing a DELETE or UPDATE change if a row with the |
| ** required PRIMARY KEY fields is not present in the database. |
| ** |
| ** There is no conflicting row in this case. The results of invoking the |
| ** sqlite3changeset_conflict() API are undefined. |
| ** |
| ** <dt>SQLITE_CHANGESET_CONFLICT<dd> |
| ** CHANGESET_CONFLICT is passed as the second argument to the conflict |
| ** handler while processing an INSERT change if the operation would result |
| ** in duplicate primary key values. |
| ** |
| ** The conflicting row in this case is the database row with the matching |
| ** primary key. |
| ** |
| ** <dt>SQLITE_CHANGESET_FOREIGN_KEY<dd> |
| ** If foreign key handling is enabled, and applying a changeset leaves the |
| ** database in a state containing foreign key violations, the conflict |
| ** handler is invoked with CHANGESET_FOREIGN_KEY as the second argument |
| ** exactly once before the changeset is committed. If the conflict handler |
| ** returns CHANGESET_OMIT, the changes, including those that caused the |
| ** foreign key constraint violation, are committed. Or, if it returns |
| ** CHANGESET_ABORT, the changeset is rolled back. |
| ** |
| ** 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(). |
| ** |
| ** <dt>SQLITE_CHANGESET_CONSTRAINT<dd> |
| ** If any other constraint violation occurs while applying a change (i.e. |
| ** a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is |
| ** invoked with CHANGESET_CONSTRAINT as the second argument. |
| ** |
| ** There is no conflicting row in this case. The results of invoking the |
| ** sqlite3changeset_conflict() API are undefined. |
| ** |
| ** </dl> |
| */ |
| #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 |
| |
| /* |
| ** CAPI3REF: Constants Returned By The Conflict Handler |
| ** |
| ** A conflict handler callback must return one of the following three values. |
| ** |
| ** <dl> |
| ** <dt>SQLITE_CHANGESET_OMIT<dd> |
| ** If a conflict handler returns this value no special action is taken. The |
| ** change that caused the conflict is not applied. The session module |
| ** continues to the next change in the changeset. |
| ** |
| ** <dt>SQLITE_CHANGESET_REPLACE<dd> |
| ** This value may only be returned if the second argument to the conflict |
| ** handler was SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this |
| ** is not the case, any changes applied so far are rolled back and the |
| ** call to sqlite3changeset_apply() returns SQLITE_MISUSE. |
| ** |
| ** 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. |
| ** |
| ** <dt>SQLITE_CHANGESET_ABORT<dd> |
| ** If this value is returned, any changes applied so far are rolled back |
| ** and the call to sqlite3changeset_apply() returns SQLITE_ABORT. |
| ** </dl> |
| */ |
| #define SQLITE_CHANGESET_OMIT 0 |
| #define SQLITE_CHANGESET_REPLACE 1 |
| #define SQLITE_CHANGESET_ABORT 2 |
| |
| /* |
| ** CAPI3REF: Rebasing changesets |
| ** EXPERIMENTAL |
| ** |
| ** 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: |
| ** |
| ** <dl> |
| ** <dt>Local INSERT<dd> |
| ** This may only conflict with a remote INSERT. If the conflict |
| ** resolution was OMIT, then add an UPDATE change to the rebased |
| ** changeset. Or, if the conflict resolution was REPLACE, add |
| ** nothing to the rebased changeset. |
| ** |
| ** <dt>Local DELETE<dd> |
| ** This may conflict with a remote UPDATE or DELETE. In both cases the |
| ** only possible resolution is OMIT. If the remote operation was a |
| ** DELETE, then add no change to the rebased changeset. If the remote |
| ** operation was an UPDATE, then the old.* fields of change are updated |
| ** to reflect the new.* values in the UPDATE. |
| ** |
| ** <dt>Local UPDATE<dd> |
| ** This may conflict with a remote UPDATE or DELETE. If it conflicts |
| ** with a DELETE, and the conflict resolution was OMIT, then the update |
| ** is changed into an INSERT. Any undefined values in the new.* record |
| ** from the update change are filled in using the old.* values from |
| ** the conflicting DELETE. Or, if the conflict resolution was REPLACE, |
| ** the UPDATE change is simply omitted from the rebased changeset. |
| ** |
| ** If conflict is with a remote UPDATE and the resolution is OMIT, then |
| ** the old.* values are rebased using the new.* values in the remote |
| ** change. Or, if the resolution is REPLACE, then the change is copied |
| ** into the rebased changeset with updates to columns also updated by |
| ** the conflicting remote UPDATE removed. If this means no columns would |
| ** be updated, the change is omitted. |
| ** </dl> |
| ** |
| ** 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: |
| ** |
| ** <ul> |
| ** <li> If there has been one or more REPLACE resolutions on a |
| ** key, it is rebased according to a REPLACE. |
| ** |
| ** <li> If there have been no REPLACE resolutions on a key, then |
| ** the local changeset is rebased according to the most recent |
| ** of the OMIT resolutions. |
| ** </ul> |
| ** |
| ** 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: |
| ** |
| ** <ol> |
| ** <li> An sqlite3_rebaser object is created by calling |
| ** sqlite3rebaser_create(). |
| ** <li> The new object is configured with the rebase buffer obtained from |
| ** sqlite3changeset_apply_v2() by calling sqlite3rebaser_configure(). |
| ** If the local changeset is to be rebased against multiple remote |
| ** changesets, then sqlite3rebaser_configure() should be called |
| ** multiple times, in the same order that the multiple |
| ** sqlite3changeset_apply_v2() calls were made. |
| ** <li> Each local changeset is rebased by calling sqlite3rebaser_rebase(). |
| ** <li> The sqlite3_rebaser object is deleted by calling |
| ** sqlite3rebaser_delete(). |
| ** </ol> |
| */ |
| typedef struct sqlite3_rebaser sqlite3_rebaser; |
| |
| /* |
| ** CAPI3REF: Create a changeset rebaser object. |
| ** EXPERIMENTAL |
| ** |
| ** 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. |
| */ |
| int sqlite3rebaser_create(sqlite3_rebaser **ppNew); |
| |
| /* |
| ** CAPI3REF: Configure a changeset rebaser object. |
| ** EXPERIMENTAL |
| ** |
| ** 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(). |
| */ |
| int sqlite3rebaser_configure( |
| sqlite3_rebaser*, |
| int nRebase, const void *pRebase |
| ); |
| |
| /* |
| ** CAPI3REF: Rebase a changeset |
| ** EXPERIMENTAL |
| ** |
| ** 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. |
| */ |
| int sqlite3rebaser_rebase( |
| sqlite3_rebaser*, |
| int nIn, const void *pIn, |
| int *pnOut, void **ppOut |
| ); |
| |
| /* |
| ** CAPI3REF: Delete a changeset rebaser object. |
| ** EXPERIMENTAL |
| ** |
| ** Delete the changeset rebaser object and all associated resources. There |
| ** should be one call to this function for each successful invocation |
| ** of sqlite3rebaser_create(). |
| */ |
| void sqlite3rebaser_delete(sqlite3_rebaser *p); |
| |
| /* |
| ** CAPI3REF: Streaming Versions of API functions. |
| ** |
| ** The six streaming API xxx_strm() functions serve similar purposes to the |
| ** corresponding non-streaming API functions: |
| ** |
| ** <table border=1 style="margin-left:8ex;margin-right:8ex"> |
| ** <tr><th>Streaming function<th>Non-streaming equivalent</th> |
| ** <tr><td>sqlite3changeset_apply_strm<td>[sqlite3changeset_apply] |
| ** <tr><td>sqlite3changeset_apply_strm_v2<td>[sqlite3changeset_apply_v2] |
| ** <tr><td>sqlite3changeset_concat_strm<td>[sqlite3changeset_concat] |
| ** <tr><td>sqlite3changeset_invert_strm<td>[sqlite3changeset_invert] |
| ** <tr><td>sqlite3changeset_start_strm<td>[sqlite3changeset_start] |
| ** <tr><td>sqlite3session_changeset_strm<td>[sqlite3session_changeset] |
| ** <tr><td>sqlite3session_patchset_strm<td>[sqlite3session_patchset] |
| ** </table> |
| ** |
| ** 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 |
| ** |
| ** <pre> |
| ** int nChangeset, |
| ** void *pChangeset, |
| ** </pre> |
| ** |
| ** Is replaced by: |
| ** |
| ** <pre> |
| ** int (*xInput)(void *pIn, void *pData, int *pnData), |
| ** void *pIn, |
| ** </pre> |
| ** |
| ** 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: |
| ** |
| ** <pre> |
| ** int *pnChangeset, |
| ** void **ppChangeset, |
| ** </pre> |
| ** |
| ** Is replaced by: |
| ** |
| ** <pre> |
| ** int (*xOutput)(void *pOut, const void *pData, int nData), |
| ** void *pOut |
| ** </pre> |
| ** |
| ** 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. |
| */ |
| 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 |
| ); |
| |
| /* |
| ** CAPI3REF: Configure global parameters |
| ** |
| ** 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. |
| ** |
| ** <dl> |
| ** <dt>SQLITE_SESSION_CONFIG_STRMSIZE<dd> |
| ** By default, the sessions module streaming interfaces attempt to input |
| ** and output data in approximately 1 KiB chunks. This operand may be used |
| ** to set and query the value of this configuration setting. The pointer |
| ** passed as the second argument must point to a value of type (int). |
| ** If this value is greater than 0, it is used as the new streaming data |
| ** chunk size for both input and output. Before returning, the (int) value |
| ** pointed to by pArg is set to the final value of the streaming interface |
| ** chunk size. |
| ** </dl> |
| ** |
| ** This function returns SQLITE_OK if successful, or an SQLite error code |
| ** otherwise. |
| */ |
| int sqlite3session_config(int op, void *pArg); |
| |
| /* |
| ** CAPI3REF: Values for sqlite3session_config(). |
| */ |
| #define SQLITE_SESSION_CONFIG_STRMSIZE 1 |
| |
| /* |
| ** Make sure we can call this stuff from C++. |
| */ |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION) */ |