Debian Codegraph @

ext/session/sqlite3session.h

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