| blob | a3def5f1df1bf1359ef9d3d2407cadbf5c32a3b1 |
2 #if !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION)
3 #define __SQLITESESSION_H_ 1
5 /*
6 ** Make sure we can call this stuff from C++.
7 */
8 #ifdef __cplusplus
10 #endif
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 */
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 */
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 */
65 );
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 */
83 /*
84 ** CAPI3REF: Enable Or Disable A Session Object
85 ** METHOD: sqlite3_session
86 **
87 ** Enable or disable the recording of changes by a session object. When
88 ** enabled, a session object records changes made to the database. When
89 ** disabled - it does not. A newly created session object is enabled.
90 ** Refer to the documentation for [sqlite3session_changeset()] for further
91 ** details regarding how enabling and disabling a session object affects
92 ** the eventual changesets.
93 **
94 ** Passing zero to this function disables the session. Passing a value
95 ** greater than zero enables it. Passing a value less than zero is a
96 ** no-op, and may be used to query the current state of the session.
97 **
98 ** The return value indicates the final state of the session object: 0 if
99 ** the session is disabled, or 1 if it is enabled.
100 */
103 /*
104 ** CAPI3REF: Set Or Clear the Indirect Change Flag
105 ** METHOD: sqlite3_session
106 **
107 ** Each change recorded by a session object is marked as either direct or
108 ** indirect. A change is marked as indirect if either:
109 **
110 ** <ul>
111 ** <li> The session object "indirect" flag is set when the change is
112 ** made, or
113 ** <li> The change is made by an SQL trigger or foreign key action
114 ** instead of directly as a result of a users SQL statement.
115 ** </ul>
116 **
117 ** If a single row is affected by more than one operation within a session,
118 ** then the change is considered indirect if all operations meet the criteria
119 ** for an indirect change above, or direct otherwise.
120 **
121 ** This function is used to set, clear or query the session object indirect
122 ** flag. If the second argument passed to this function is zero, then the
123 ** indirect flag is cleared. If it is greater than zero, the indirect flag
124 ** is set. Passing a value less than zero does not modify the current value
125 ** of the indirect flag, and may be used to query the current state of the
126 ** indirect flag for the specified session object.
127 **
128 ** The return value indicates the final state of the indirect flag: 0 if
129 ** it is clear, or 1 if it is set.
130 */
133 /*
134 ** CAPI3REF: Attach A Table To A Session Object
135 ** METHOD: sqlite3_session
136 **
137 ** If argument zTab is not NULL, then it is the name of a table to attach
138 ** to the session object passed as the first argument. All subsequent changes
139 ** made to the table while the session object is enabled will be recorded. See
140 ** documentation for [sqlite3session_changeset()] for further details.
141 **
142 ** Or, if argument zTab is NULL, then changes are recorded for all tables
143 ** in the database. If additional tables are added to the database (by
144 ** executing "CREATE TABLE" statements) after this call is made, changes for
145 ** the new tables are also recorded.
146 **
147 ** Changes can only be recorded for tables that have a PRIMARY KEY explicitly
148 ** defined as part of their CREATE TABLE statement. It does not matter if the
149 ** PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY
150 ** KEY may consist of a single column, or may be a composite key.
151 **
152 ** It is not an error if the named table does not exist in the database. Nor
153 ** is it an error if the named table does not have a PRIMARY KEY. However,
154 ** no changes will be recorded in either of these scenarios.
155 **
156 ** Changes are not recorded for individual rows that have NULL values stored
157 ** in one or more of their PRIMARY KEY columns.
158 **
159 ** SQLITE_OK is returned if the call completes without error. Or, if an error
160 ** occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.
161 **
162 ** <h3>Special sqlite_stat1 Handling</h3>
163 **
164 ** As of SQLite version 3.22.0, the "sqlite_stat1" table is an exception to
165 ** some of the rules above. In SQLite, the schema of sqlite_stat1 is:
166 ** <pre>
167 ** CREATE TABLE sqlite_stat1(tbl,idx,stat)
168 ** </pre>
169 **
170 ** Even though sqlite_stat1 does not have a PRIMARY KEY, changes are
171 ** recorded for it as if the PRIMARY KEY is (tbl,idx). Additionally, changes
172 ** are recorded for rows for which (idx IS NULL) is true. However, for such
173 ** rows a zero-length blob (SQL value X'') is stored in the changeset or
174 ** patchset instead of a NULL value. This allows such changesets to be
175 ** manipulated by legacy implementations of sqlite3changeset_invert(),
176 ** concat() and similar.
177 **
178 ** The sqlite3changeset_apply() function automatically converts the
179 ** zero-length blob back to a NULL value when updating the sqlite_stat1
180 ** table. However, if the application calls sqlite3changeset_new(),
181 ** sqlite3changeset_old() or sqlite3changeset_conflict on a changeset
182 ** iterator directly (including on a changeset iterator passed to a
183 ** conflict-handler callback) then the X'' value is returned. The application
184 ** must translate X'' to NULL itself if required.
185 **
186 ** Legacy (older than 3.22.0) versions of the sessions module cannot capture
187 ** changes made to the sqlite_stat1 table. Legacy versions of the
188 ** sqlite3changeset_apply() function silently ignore any modifications to the
189 ** sqlite_stat1 table that are part of a changeset or patchset.
190 */
194 );
196 /*
197 ** CAPI3REF: Set a table filter on a Session Object.
198 ** METHOD: sqlite3_session
199 **
200 ** The second argument (xFilter) is the "filter callback". For changes to rows
201 ** in tables that are not attached to the Session object, the filter is called
202 ** to determine whether changes to the table's rows should be tracked or not.
203 ** If xFilter returns 0, changes is not tracked. Note that once a table is
204 ** attached, xFilter will not be called again.
205 */
211 ),
213 );
215 /*
216 ** CAPI3REF: Generate A Changeset From A Session Object
217 ** METHOD: sqlite3_session
218 **
219 ** Obtain a changeset containing changes to the tables attached to the
220 ** session object passed as the first argument. If successful,
221 ** set *ppChangeset to point to a buffer containing the changeset
222 ** and *pnChangeset to the size of the changeset in bytes before returning
223 ** SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to
224 ** zero and return an SQLite error code.
225 **
226 ** A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes,
227 ** each representing a change to a single row of an attached table. An INSERT
228 ** change contains the values of each field of a new database row. A DELETE
229 ** contains the original values of each field of a deleted database row. An
230 ** UPDATE change contains the original values of each field of an updated
231 ** database row along with the updated values for each updated non-primary-key
232 ** column. It is not possible for an UPDATE change to represent a change that
233 ** modifies the values of primary key columns. If such a change is made, it
234 ** is represented in a changeset as a DELETE followed by an INSERT.
235 **
236 ** Changes are not recorded for rows that have NULL values stored in one or
237 ** more of their PRIMARY KEY columns. If such a row is inserted or deleted,
238 ** no corresponding change is present in the changesets returned by this
239 ** function. If an existing row with one or more NULL values stored in
240 ** PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL,
241 ** only an INSERT is appears in the changeset. Similarly, if an existing row
242 ** with non-NULL PRIMARY KEY values is updated so that one or more of its
243 ** PRIMARY KEY columns are set to NULL, the resulting changeset contains a
244 ** DELETE change only.
245 **
246 ** The contents of a changeset may be traversed using an iterator created
247 ** using the [sqlite3changeset_start()] API. A changeset may be applied to
248 ** a database with a compatible schema using the [sqlite3changeset_apply()]
249 ** API.
250 **
251 ** Within a changeset generated by this function, all changes related to a
252 ** single table are grouped together. In other words, when iterating through
253 ** a changeset or when applying a changeset to a database, all changes related
254 ** to a single table are processed before moving on to the next table. Tables
255 ** are sorted in the same order in which they were attached (or auto-attached)
256 ** to the sqlite3_session object. The order in which the changes related to
257 ** a single table are stored is undefined.
258 **
259 ** Following a successful call to this function, it is the responsibility of
260 ** the caller to eventually free the buffer that *ppChangeset points to using
261 ** [sqlite3_free()].
262 **
263 ** <h3>Changeset Generation</h3>
264 **
265 ** Once a table has been attached to a session object, the session object
266 ** records the primary key values of all new rows inserted into the table.
267 ** It also records the original primary key and other column values of any
268 ** deleted or updated rows. For each unique primary key value, data is only
269 ** recorded once - the first time a row with said primary key is inserted,
270 ** updated or deleted in the lifetime of the session.
271 **
272 ** There is one exception to the previous paragraph: when a row is inserted,
273 ** updated or deleted, if one or more of its primary key columns contain a
274 ** NULL value, no record of the change is made.
275 **
276 ** The session object therefore accumulates two types of records - those
277 ** that consist of primary key values only (created when the user inserts
278 ** a new record) and those that consist of the primary key values and the
279 ** original values of other table columns (created when the users deletes
280 ** or updates a record).
281 **
282 ** When this function is called, the requested changeset is created using
283 ** both the accumulated records and the current contents of the database
284 ** file. Specifically:
285 **
286 ** <ul>
287 ** <li> For each record generated by an insert, the database is queried
288 ** for a row with a matching primary key. If one is found, an INSERT
289 ** change is added to the changeset. If no such row is found, no change
290 ** is added to the changeset.
291 **
292 ** <li> For each record generated by an update or delete, the database is
293 ** queried for a row with a matching primary key. If such a row is
294 ** found and one or more of the non-primary key fields have been
295 ** modified from their original values, an UPDATE change is added to
296 ** the changeset. Or, if no such row is found in the table, a DELETE
297 ** change is added to the changeset. If there is a row with a matching
298 ** primary key in the database, but all fields contain their original
299 ** values, no change is added to the changeset.
300 ** </ul>
301 **
302 ** This means, amongst other things, that if a row is inserted and then later
303 ** deleted while a session object is active, neither the insert nor the delete
304 ** will be present in the changeset. Or if a row is deleted and then later a
305 ** row with the same primary key values inserted while a session object is
306 ** active, the resulting changeset will contain an UPDATE change instead of
307 ** a DELETE and an INSERT.
308 **
309 ** When a session object is disabled (see the [sqlite3session_enable()] API),
310 ** it does not accumulate records when rows are inserted, updated or deleted.
311 ** This may appear to have some counter-intuitive effects if a single row
312 ** is written to more than once during a session. For example, if a row
313 ** is inserted while a session object is enabled, then later deleted while
314 ** the same session object is disabled, no INSERT record will appear in the
315 ** changeset, even though the delete took place while the session was disabled.
316 ** Or, if one field of a row is updated while a session is disabled, and
317 ** another field of the same row is updated while the session is enabled, the
318 ** resulting changeset will contain an UPDATE change that updates both fields.
319 */
324 );
326 /*
327 ** CAPI3REF: Load The Difference Between Tables Into A Session
328 ** METHOD: sqlite3_session
329 **
330 ** If it is not already attached to the session object passed as the first
331 ** argument, this function attaches table zTbl in the same manner as the
332 ** [sqlite3session_attach()] function. If zTbl does not exist, or if it
333 ** does not have a primary key, this function is a no-op (but does not return
334 ** an error).
335 **
336 ** Argument zFromDb must be the name of a database ("main", "temp" etc.)
337 ** attached to the same database handle as the session object that contains
338 ** a table compatible with the table attached to the session by this function.
339 ** A table is considered compatible if it:
340 **
341 ** <ul>
342 ** <li> Has the same name,
343 ** <li> Has the same set of columns declared in the same order, and
344 ** <li> Has the same PRIMARY KEY definition.
345 ** </ul>
346 **
347 ** If the tables are not compatible, SQLITE_SCHEMA is returned. If the tables
348 ** are compatible but do not have any PRIMARY KEY columns, it is not an error
349 ** but no changes are added to the session object. As with other session
350 ** APIs, tables without PRIMARY KEYs are simply ignored.
351 **
352 ** This function adds a set of changes to the session object that could be
353 ** used to update the table in database zFrom (call this the "from-table")
354 ** so that its content is the same as the table attached to the session
355 ** object (call this the "to-table"). Specifically:
356 **
357 ** <ul>
358 ** <li> For each row (primary key) that exists in the to-table but not in
359 ** the from-table, an INSERT record is added to the session object.
360 **
361 ** <li> For each row (primary key) that exists in the to-table but not in
362 ** the from-table, a DELETE record is added to the session object.
363 **
364 ** <li> For each row (primary key) that exists in both tables, but features
365 ** different non-PK values in each, an UPDATE record is added to the
366 ** session.
367 ** </ul>
368 **
369 ** To clarify, if this function is called and then a changeset constructed
370 ** using [sqlite3session_changeset()], then after applying that changeset to
371 ** database zFrom the contents of the two compatible tables would be
372 ** identical.
373 **
374 ** It an error if database zFrom does not exist or does not contain the
375 ** required compatible table.
376 **
377 ** If the operation successful, SQLITE_OK is returned. Otherwise, an SQLite
378 ** error code. In this case, if argument pzErrMsg is not NULL, *pzErrMsg
379 ** may be set to point to a buffer containing an English language error
380 ** message. It is the responsibility of the caller to free this buffer using
381 ** sqlite3_free().
382 */
388 );
391 /*
392 ** CAPI3REF: Generate A Patchset From A Session Object
393 ** METHOD: sqlite3_session
394 **
395 ** The differences between a patchset and a changeset are that:
396 **
397 ** <ul>
398 ** <li> DELETE records consist of the primary key fields only. The
399 ** original values of other fields are omitted.
400 ** <li> The original values of any modified fields are omitted from
401 ** UPDATE records.
402 ** </ul>
403 **
404 ** A patchset blob may be used with up to date versions of all
405 ** sqlite3changeset_xxx API functions except for sqlite3changeset_invert(),
406 ** which returns SQLITE_CORRUPT if it is passed a patchset. Similarly,
407 ** attempting to use a patchset blob with old versions of the
408 ** sqlite3changeset_xxx APIs also provokes an SQLITE_CORRUPT error.
409 **
410 ** Because the non-primary key "old.*" fields are omitted, no
411 ** SQLITE_CHANGESET_DATA conflicts can be detected or reported if a patchset
412 ** is passed to the sqlite3changeset_apply() API. Other conflict types work
413 ** in the same way as for changesets.
414 **
415 ** Changes within a patchset are ordered in the same way as for changesets
416 ** generated by the sqlite3session_changeset() function (i.e. all changes for
417 ** a single table are grouped together, tables appear in the order in which
418 ** they were attached to the session object).
419 */
424 );
426 /*
427 ** CAPI3REF: Test if a changeset has recorded any changes.
428 **
429 ** Return non-zero if no changes to attached tables have been recorded by
430 ** the session object passed as the first argument. Otherwise, if one or
431 ** more changes have been recorded, return zero.
432 **
433 ** Even if this function returns zero, it is possible that calling
434 ** [sqlite3session_changeset()] on the session handle may still return a
435 ** changeset that contains no changes. This can happen when a row in
436 ** an attached table is modified and then later on the original values
437 ** are restored. However, if this function returns non-zero, then it is
438 ** guaranteed that a call to sqlite3session_changeset() will return a
439 ** changeset containing zero changes.
440 */
443 /*
444 ** CAPI3REF: Create An Iterator To Traverse A Changeset
445 ** CONSTRUCTOR: sqlite3_changeset_iter
446 **
447 ** Create an iterator used to iterate through the contents of a changeset.
448 ** If successful, *pp is set to point to the iterator handle and SQLITE_OK
449 ** is returned. Otherwise, if an error occurs, *pp is set to zero and an
450 ** SQLite error code is returned.
451 **
452 ** The following functions can be used to advance and query a changeset
453 ** iterator created by this function:
454 **
455 ** <ul>
456 ** <li> [sqlite3changeset_next()]
457 ** <li> [sqlite3changeset_op()]
458 ** <li> [sqlite3changeset_new()]
459 ** <li> [sqlite3changeset_old()]
460 ** </ul>
461 **
462 ** It is the responsibility of the caller to eventually destroy the iterator
463 ** by passing it to [sqlite3changeset_finalize()]. The buffer containing the
464 ** changeset (pChangeset) must remain valid until after the iterator is
465 ** destroyed.
466 **
467 ** Assuming the changeset blob was created by one of the
468 ** [sqlite3session_changeset()], [sqlite3changeset_concat()] or
469 ** [sqlite3changeset_invert()] functions, all changes within the changeset
470 ** that apply to a single table are grouped together. This means that when
471 ** an application iterates through a changeset using an iterator created by
472 ** this function, all changes that relate to a single table are visited
473 ** consecutively. There is no chance that the iterator will visit a change
474 ** the applies to table X, then one for table Y, and then later on visit
475 ** another change for table X.
476 */
481 );
484 /*
485 ** CAPI3REF: Advance A Changeset Iterator
486 ** METHOD: sqlite3_changeset_iter
487 **
488 ** This function may only be used with iterators created by function
489 ** [sqlite3changeset_start()]. If it is called on an iterator passed to
490 ** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE
491 ** is returned and the call has no effect.
492 **
493 ** Immediately after an iterator is created by sqlite3changeset_start(), it
494 ** does not point to any change in the changeset. Assuming the changeset
495 ** is not empty, the first call to this function advances the iterator to
496 ** point to the first change in the changeset. Each subsequent call advances
497 ** the iterator to point to the next change in the changeset (if any). If
498 ** no error occurs and the iterator points to a valid change after a call
499 ** to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned.
500 ** Otherwise, if all changes in the changeset have already been visited,
501 ** SQLITE_DONE is returned.
502 **
503 ** If an error occurs, an SQLite error code is returned. Possible error
504 ** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or
505 ** SQLITE_NOMEM.
506 */
509 /*
510 ** CAPI3REF: Obtain The Current Operation From A Changeset Iterator
511 ** METHOD: sqlite3_changeset_iter
512 **
513 ** The pIter argument passed to this function may either be an iterator
514 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
515 ** created by [sqlite3changeset_start()]. In the latter case, the most recent
516 ** call to [sqlite3changeset_next()] must have returned [SQLITE_ROW]. If this
517 ** is not the case, this function returns [SQLITE_MISUSE].
518 **
519 ** If argument pzTab is not NULL, then *pzTab is set to point to a
520 ** nul-terminated utf-8 encoded string containing the name of the table
521 ** affected by the current change. The buffer remains valid until either
522 ** sqlite3changeset_next() is called on the iterator or until the
523 ** conflict-handler function returns. If pnCol is not NULL, then *pnCol is
524 ** set to the number of columns in the table affected by the change. If
525 ** pbIncorrect is not NULL, then *pbIndirect is set to true (1) if the change
526 ** is an indirect change, or false (0) otherwise. See the documentation for
527 ** [sqlite3session_indirect()] for a description of direct and indirect
528 ** changes. Finally, if pOp is not NULL, then *pOp is set to one of
529 ** [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], depending on the
530 ** type of change that the iterator currently points to.
531 **
532 ** If no error occurs, SQLITE_OK is returned. If an error does occur, an
533 ** SQLite error code is returned. The values of the output variables may not
534 ** be trusted in this case.
535 */
542 );
544 /*
545 ** CAPI3REF: Obtain The Primary Key Definition Of A Table
546 ** METHOD: sqlite3_changeset_iter
547 **
548 ** For each modified table, a changeset includes the following:
549 **
550 ** <ul>
551 ** <li> The number of columns in the table, and
552 ** <li> Which of those columns make up the tables PRIMARY KEY.
553 ** </ul>
554 **
555 ** This function is used to find which columns comprise the PRIMARY KEY of
556 ** the table modified by the change that iterator pIter currently points to.
557 ** If successful, *pabPK is set to point to an array of nCol entries, where
558 ** nCol is the number of columns in the table. Elements of *pabPK are set to
559 ** 0x01 if the corresponding column is part of the tables primary key, or
560 ** 0x00 if it is not.
561 **
562 ** If argument pnCol is not NULL, then *pnCol is set to the number of columns
563 ** in the table.
564 **
565 ** If this function is called when the iterator does not point to a valid
566 ** entry, SQLITE_MISUSE is returned and the output variables zeroed. Otherwise,
567 ** SQLITE_OK is returned and the output variables populated as described
568 ** above.
569 */
574 );
576 /*
577 ** CAPI3REF: Obtain old.* Values From A Changeset Iterator
578 ** METHOD: sqlite3_changeset_iter
579 **
580 ** The pIter argument passed to this function may either be an iterator
581 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
582 ** created by [sqlite3changeset_start()]. In the latter case, the most recent
583 ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.
584 ** Furthermore, it may only be called if the type of change that the iterator
585 ** currently points to is either [SQLITE_DELETE] or [SQLITE_UPDATE]. Otherwise,
586 ** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.
587 **
588 ** Argument iVal must be greater than or equal to 0, and less than the number
589 ** of columns in the table affected by the current change. Otherwise,
590 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
591 **
592 ** If successful, this function sets *ppValue to point to a protected
593 ** sqlite3_value object containing the iVal'th value from the vector of
594 ** original row values stored as part of the UPDATE or DELETE change and
595 ** returns SQLITE_OK. The name of the function comes from the fact that this
596 ** is similar to the "old.*" columns available to update or delete triggers.
597 **
598 ** If some other error occurs (e.g. an OOM condition), an SQLite error code
599 ** is returned and *ppValue is set to NULL.
600 */
605 );
607 /*
608 ** CAPI3REF: Obtain new.* Values From A Changeset Iterator
609 ** METHOD: sqlite3_changeset_iter
610 **
611 ** The pIter argument passed to this function may either be an iterator
612 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
613 ** created by [sqlite3changeset_start()]. In the latter case, the most recent
614 ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.
615 ** Furthermore, it may only be called if the type of change that the iterator
616 ** currently points to is either [SQLITE_UPDATE] or [SQLITE_INSERT]. Otherwise,
617 ** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.
618 **
619 ** Argument iVal must be greater than or equal to 0, and less than the number
620 ** of columns in the table affected by the current change. Otherwise,
621 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
622 **
623 ** If successful, this function sets *ppValue to point to a protected
624 ** sqlite3_value object containing the iVal'th value from the vector of
625 ** new row values stored as part of the UPDATE or INSERT change and
626 ** returns SQLITE_OK. If the change is an UPDATE and does not include
627 ** a new value for the requested column, *ppValue is set to NULL and
628 ** SQLITE_OK returned. The name of the function comes from the fact that
629 ** this is similar to the "new.*" columns available to update or delete
630 ** triggers.
631 **
632 ** If some other error occurs (e.g. an OOM condition), an SQLite error code
633 ** is returned and *ppValue is set to NULL.
634 */
639 );
641 /*
642 ** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator
643 ** METHOD: sqlite3_changeset_iter
644 **
645 ** This function should only be used with iterator objects passed to a
646 ** conflict-handler callback by [sqlite3changeset_apply()] with either
647 ** [SQLITE_CHANGESET_DATA] or [SQLITE_CHANGESET_CONFLICT]. If this function
648 ** is called on any other iterator, [SQLITE_MISUSE] is returned and *ppValue
649 ** is set to NULL.
650 **
651 ** Argument iVal must be greater than or equal to 0, and less than the number
652 ** of columns in the table affected by the current change. Otherwise,
653 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
654 **
655 ** If successful, this function sets *ppValue to point to a protected
656 ** sqlite3_value object containing the iVal'th value from the
657 ** "conflicting row" associated with the current conflict-handler callback
658 ** and returns SQLITE_OK.
659 **
660 ** If some other error occurs (e.g. an OOM condition), an SQLite error code
661 ** is returned and *ppValue is set to NULL.
662 */
667 );
669 /*
670 ** CAPI3REF: Determine The Number Of Foreign Key Constraint Violations
671 ** METHOD: sqlite3_changeset_iter
672 **
673 ** This function may only be called with an iterator passed to an
674 ** SQLITE_CHANGESET_FOREIGN_KEY conflict handler callback. In this case
675 ** it sets the output variable to the total number of known foreign key
676 ** violations in the destination database and returns SQLITE_OK.
677 **
678 ** In all other cases this function returns SQLITE_MISUSE.
679 */
683 );
686 /*
687 ** CAPI3REF: Finalize A Changeset Iterator
688 ** METHOD: sqlite3_changeset_iter
689 **
690 ** This function is used to finalize an iterator allocated with
691 ** [sqlite3changeset_start()].
692 **
693 ** This function should only be called on iterators created using the
694 ** [sqlite3changeset_start()] function. If an application calls this
695 ** function with an iterator passed to a conflict-handler by
696 ** [sqlite3changeset_apply()], [SQLITE_MISUSE] is immediately returned and the
697 ** call has no effect.
698 **
699 ** If an error was encountered within a call to an sqlite3changeset_xxx()
700 ** function (for example an [SQLITE_CORRUPT] in [sqlite3changeset_next()] or an
701 ** [SQLITE_NOMEM] in [sqlite3changeset_new()]) then an error code corresponding
702 ** to that error is returned by this function. Otherwise, SQLITE_OK is
703 ** returned. This is to allow the following pattern (pseudo-code):
704 **
705 ** <pre>
706 ** sqlite3changeset_start();
707 ** while( SQLITE_ROW==sqlite3changeset_next() ){
708 ** // Do something with change.
709 ** }
710 ** rc = sqlite3changeset_finalize();
711 ** if( rc!=SQLITE_OK ){
712 ** // An error has occurred
713 ** }
714 ** </pre>
715 */
718 /*
719 ** CAPI3REF: Invert A Changeset
720 **
721 ** This function is used to "invert" a changeset object. Applying an inverted
722 ** changeset to a database reverses the effects of applying the uninverted
723 ** changeset. Specifically:
724 **
725 ** <ul>
726 ** <li> Each DELETE change is changed to an INSERT, and
727 ** <li> Each INSERT change is changed to a DELETE, and
728 ** <li> For each UPDATE change, the old.* and new.* values are exchanged.
729 ** </ul>
730 **
731 ** This function does not change the order in which changes appear within
732 ** the changeset. It merely reverses the sense of each individual change.
733 **
734 ** If successful, a pointer to a buffer containing the inverted changeset
735 ** is stored in *ppOut, the size of the same buffer is stored in *pnOut, and
736 ** SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are
737 ** zeroed and an SQLite error code returned.
738 **
739 ** It is the responsibility of the caller to eventually call sqlite3_free()
740 ** on the *ppOut pointer to free the buffer allocation following a successful
741 ** call to this function.
742 **
743 ** WARNING/TODO: This function currently assumes that the input is a valid
744 ** changeset. If it is not, the results are undefined.
745 */
749 );
751 /*
752 ** CAPI3REF: Concatenate Two Changeset Objects
753 **
754 ** This function is used to concatenate two changesets, A and B, into a
755 ** single changeset. The result is a changeset equivalent to applying
756 ** changeset A followed by changeset B.
757 **
758 ** This function combines the two input changesets using an
759 ** sqlite3_changegroup object. Calling it produces similar results as the
760 ** following code fragment:
761 **
762 ** <pre>
763 ** sqlite3_changegroup *pGrp;
764 ** rc = sqlite3_changegroup_new(&pGrp);
765 ** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nA, pA);
766 ** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nB, pB);
767 ** if( rc==SQLITE_OK ){
768 ** rc = sqlite3changegroup_output(pGrp, pnOut, ppOut);
769 ** }else{
770 ** *ppOut = 0;
771 ** *pnOut = 0;
772 ** }
773 ** </pre>
774 **
775 ** Refer to the sqlite3_changegroup documentation below for details.
776 */
784 );
787 /*
788 ** CAPI3REF: Changegroup Handle
789 **
790 ** A changegroup is an object used to combine two or more
791 ** [changesets] or [patchsets]
792 */
795 /*
796 ** CAPI3REF: Create A New Changegroup Object
797 ** CONSTRUCTOR: sqlite3_changegroup
798 **
799 ** An sqlite3_changegroup object is used to combine two or more changesets
800 ** (or patchsets) into a single changeset (or patchset). A single changegroup
801 ** object may combine changesets or patchsets, but not both. The output is
802 ** always in the same format as the input.
803 **
804 ** If successful, this function returns SQLITE_OK and populates (*pp) with
805 ** a pointer to a new sqlite3_changegroup object before returning. The caller
806 ** should eventually free the returned object using a call to
807 ** sqlite3changegroup_delete(). If an error occurs, an SQLite error code
808 ** (i.e. SQLITE_NOMEM) is returned and *pp is set to NULL.
809 **
810 ** The usual usage pattern for an sqlite3_changegroup object is as follows:
811 **
812 ** <ul>
813 ** <li> It is created using a call to sqlite3changegroup_new().
814 **
815 ** <li> Zero or more changesets (or patchsets) are added to the object
816 ** by calling sqlite3changegroup_add().
817 **
818 ** <li> The result of combining all input changesets together is obtained
819 ** by the application via a call to sqlite3changegroup_output().
820 **
821 ** <li> The object is deleted using a call to sqlite3changegroup_delete().
822 ** </ul>
823 **
824 ** Any number of calls to add() and output() may be made between the calls to
825 ** new() and delete(), and in any order.
826 **
827 ** As well as the regular sqlite3changegroup_add() and
828 ** sqlite3changegroup_output() functions, also available are the streaming
829 ** versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm().
830 */
833 /*
834 ** CAPI3REF: Add A Changeset To A Changegroup
835 ** METHOD: sqlite3_changegroup
836 **
837 ** Add all changes within the changeset (or patchset) in buffer pData (size
838 ** nData bytes) to the changegroup.
839 **
840 ** If the buffer contains a patchset, then all prior calls to this function
841 ** on the same changegroup object must also have specified patchsets. Or, if
842 ** the buffer contains a changeset, so must have the earlier calls to this
843 ** function. Otherwise, SQLITE_ERROR is returned and no changes are added
844 ** to the changegroup.
845 **
846 ** Rows within the changeset and changegroup are identified by the values in
847 ** their PRIMARY KEY columns. A change in the changeset is considered to
848 ** apply to the same row as a change already present in the changegroup if
849 ** the two rows have the same primary key.
850 **
851 ** Changes to rows that do not already appear in the changegroup are
852 ** simply copied into it. Or, if both the new changeset and the changegroup
853 ** contain changes that apply to a single row, the final contents of the
854 ** changegroup depends on the type of each change, as follows:
855 **
856 ** <table border=1 style="margin-left:8ex;margin-right:8ex">
857 ** <tr><th style="white-space:pre">Existing Change </th>
858 ** <th style="white-space:pre">New Change </th>
859 ** <th>Output Change
860 ** <tr><td>INSERT <td>INSERT <td>
861 ** The new change is ignored. This case does not occur if the new
862 ** changeset was recorded immediately after the changesets already
863 ** added to the changegroup.
864 ** <tr><td>INSERT <td>UPDATE <td>
865 ** The INSERT change remains in the changegroup. The values in the
866 ** INSERT change are modified as if the row was inserted by the
867 ** existing change and then updated according to the new change.
868 ** <tr><td>INSERT <td>DELETE <td>
869 ** The existing INSERT is removed from the changegroup. The DELETE is
870 ** not added.
871 ** <tr><td>UPDATE <td>INSERT <td>
872 ** The new change is ignored. This case does not occur if the new
873 ** changeset was recorded immediately after the changesets already
874 ** added to the changegroup.
875 ** <tr><td>UPDATE <td>UPDATE <td>
876 ** The existing UPDATE remains within the changegroup. It is amended
877 ** so that the accompanying values are as if the row was updated once
878 ** by the existing change and then again by the new change.
879 ** <tr><td>UPDATE <td>DELETE <td>
880 ** The existing UPDATE is replaced by the new DELETE within the
881 ** changegroup.
882 ** <tr><td>DELETE <td>INSERT <td>
883 ** If one or more of the column values in the row inserted by the
884 ** new change differ from those in the row deleted by the existing
885 ** change, the existing DELETE is replaced by an UPDATE within the
886 ** changegroup. Otherwise, if the inserted row is exactly the same
887 ** as the deleted row, the existing DELETE is simply discarded.
888 ** <tr><td>DELETE <td>UPDATE <td>
889 ** The new change is ignored. This case does not occur if the new
890 ** changeset was recorded immediately after the changesets already
891 ** added to the changegroup.
892 ** <tr><td>DELETE <td>DELETE <td>
893 ** The new change is ignored. This case does not occur if the new
894 ** changeset was recorded immediately after the changesets already
895 ** added to the changegroup.
896 ** </table>
897 **
898 ** If the new changeset contains changes to a table that is already present
899 ** in the changegroup, then the number of columns and the position of the
900 ** primary key columns for the table must be consistent. If this is not the
901 ** case, this function fails with SQLITE_SCHEMA. If the input changeset
902 ** appears to be corrupt and the corruption is detected, SQLITE_CORRUPT is
903 ** returned. Or, if an out-of-memory condition occurs during processing, this
904 ** function returns SQLITE_NOMEM. In all cases, if an error occurs the
905 ** final contents of the changegroup is undefined.
906 **
907 ** If no error occurs, SQLITE_OK is returned.
908 */
911 /*
912 ** CAPI3REF: Obtain A Composite Changeset From A Changegroup
913 ** METHOD: sqlite3_changegroup
914 **
915 ** Obtain a buffer containing a changeset (or patchset) representing the
916 ** current contents of the changegroup. If the inputs to the changegroup
917 ** were themselves changesets, the output is a changeset. Or, if the
918 ** inputs were patchsets, the output is also a patchset.
919 **
920 ** As with the output of the sqlite3session_changeset() and
921 ** sqlite3session_patchset() functions, all changes related to a single
922 ** table are grouped together in the output of this function. Tables appear
923 ** in the same order as for the very first changeset added to the changegroup.
924 ** If the second or subsequent changesets added to the changegroup contain
925 ** changes for tables that do not appear in the first changeset, they are
926 ** appended onto the end of the output changeset, again in the order in
927 ** which they are first encountered.
928 **
929 ** If an error occurs, an SQLite error code is returned and the output
930 ** variables (*pnData) and (*ppData) are set to 0. Otherwise, SQLITE_OK
931 ** is returned and the output variables are set to the size of and a
932 ** pointer to the output buffer, respectively. In this case it is the
933 ** responsibility of the caller to eventually free the buffer using a
934 ** call to sqlite3_free().
935 */
937 sqlite3_changegroup*,
940 );
942 /*
943 ** CAPI3REF: Delete A Changegroup Object
944 ** DESTRUCTOR: sqlite3_changegroup
945 */
948 /*
949 ** CAPI3REF: Apply A Changeset To A Database
950 **
951 ** Apply a changeset or patchset to a database. These functions attempt to
952 ** update the "main" database attached to handle db with the changes found in
953 ** the changeset passed via the second and third arguments.
954 **
955 ** The fourth argument (xFilter) passed to these functions is the "filter
956 ** callback". If it is not NULL, then for each table affected by at least one
957 ** change in the changeset, the filter callback is invoked with
958 ** the table name as the second argument, and a copy of the context pointer
959 ** passed as the sixth argument as the first. If the "filter callback"
960 ** returns zero, then no attempt is made to apply any changes to the table.
961 ** Otherwise, if the return value is non-zero or the xFilter argument to
962 ** is NULL, all changes related to the table are attempted.
963 **
964 ** For each table that is not excluded by the filter callback, this function
965 ** tests that the target database contains a compatible table. A table is
966 ** considered compatible if all of the following are true:
967 **
968 ** <ul>
969 ** <li> The table has the same name as the name recorded in the
970 ** changeset, and
971 ** <li> The table has at least as many columns as recorded in the
972 ** changeset, and
973 ** <li> The table has primary key columns in the same position as
974 ** recorded in the changeset.
975 ** </ul>
976 **
977 ** If there is no compatible table, it is not an error, but none of the
978 ** changes associated with the table are applied. A warning message is issued
979 ** via the sqlite3_log() mechanism with the error code SQLITE_SCHEMA. At most
980 ** one such warning is issued for each table in the changeset.
981 **
982 ** For each change for which there is a compatible table, an attempt is made
983 ** to modify the table contents according to the UPDATE, INSERT or DELETE
984 ** change. If a change cannot be applied cleanly, the conflict handler
985 ** function passed as the fifth argument to sqlite3changeset_apply() may be
986 ** invoked. A description of exactly when the conflict handler is invoked for
987 ** each type of change is below.
988 **
989 ** Unlike the xFilter argument, xConflict may not be passed NULL. The results
990 ** of passing anything other than a valid function pointer as the xConflict
991 ** argument are undefined.
992 **
993 ** Each time the conflict handler function is invoked, it must return one
994 ** of [SQLITE_CHANGESET_OMIT], [SQLITE_CHANGESET_ABORT] or
995 ** [SQLITE_CHANGESET_REPLACE]. SQLITE_CHANGESET_REPLACE may only be returned
996 ** if the second argument passed to the conflict handler is either
997 ** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler
998 ** returns an illegal value, any changes already made are rolled back and
999 ** the call to sqlite3changeset_apply() returns SQLITE_MISUSE. Different
1000 ** actions are taken by sqlite3changeset_apply() depending on the value
1001 ** returned by each invocation of the conflict-handler function. Refer to
1002 ** the documentation for the three
1003 ** [SQLITE_CHANGESET_OMIT|available return values] for details.
1004 **
1005 ** <dl>
1006 ** <dt>DELETE Changes<dd>
1007 ** For each DELETE change, the function checks if the target database
1008 ** contains a row with the same primary key value (or values) as the
1009 ** original row values stored in the changeset. If it does, and the values
1010 ** stored in all non-primary key columns also match the values stored in
1011 ** the changeset the row is deleted from the target database.
1012 **
1013 ** If a row with matching primary key values is found, but one or more of
1014 ** the non-primary key fields contains a value different from the original
1015 ** row value stored in the changeset, the conflict-handler function is
1016 ** invoked with [SQLITE_CHANGESET_DATA] as the second argument. If the
1017 ** database table has more columns than are recorded in the changeset,
1018 ** only the values of those non-primary key fields are compared against
1019 ** the current database contents - any trailing database table columns
1020 ** are ignored.
1021 **
1022 ** If no row with matching primary key values is found in the database,
1023 ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
1024 ** passed as the second argument.
1025 **
1026 ** If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT
1027 ** (which can only happen if a foreign key constraint is violated), the
1028 ** conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT]
1029 ** passed as the second argument. This includes the case where the DELETE
1030 ** operation is attempted because an earlier call to the conflict handler
1031 ** function returned [SQLITE_CHANGESET_REPLACE].
1032 **
1033 ** <dt>INSERT Changes<dd>
1034 ** For each INSERT change, an attempt is made to insert the new row into
1035 ** the database. If the changeset row contains fewer fields than the
1036 ** database table, the trailing fields are populated with their default
1037 ** values.
1038 **
1039 ** If the attempt to insert the row fails because the database already
1040 ** contains a row with the same primary key values, the conflict handler
1041 ** function is invoked with the second argument set to
1042 ** [SQLITE_CHANGESET_CONFLICT].
1043 **
1044 ** If the attempt to insert the row fails because of some other constraint
1045 ** violation (e.g. NOT NULL or UNIQUE), the conflict handler function is
1046 ** invoked with the second argument set to [SQLITE_CHANGESET_CONSTRAINT].
1047 ** This includes the case where the INSERT operation is re-attempted because
1048 ** an earlier call to the conflict handler function returned
1049 ** [SQLITE_CHANGESET_REPLACE].
1050 **
1051 ** <dt>UPDATE Changes<dd>
1052 ** For each UPDATE change, the function checks if the target database
1053 ** contains a row with the same primary key value (or values) as the
1054 ** original row values stored in the changeset. If it does, and the values
1055 ** stored in all modified non-primary key columns also match the values
1056 ** stored in the changeset the row is updated within the target database.
1057 **
1058 ** If a row with matching primary key values is found, but one or more of
1059 ** the modified non-primary key fields contains a value different from an
1060 ** original row value stored in the changeset, the conflict-handler function
1061 ** is invoked with [SQLITE_CHANGESET_DATA] as the second argument. Since
1062 ** UPDATE changes only contain values for non-primary key fields that are
1063 ** to be modified, only those fields need to match the original values to
1064 ** avoid the SQLITE_CHANGESET_DATA conflict-handler callback.
1065 **
1066 ** If no row with matching primary key values is found in the database,
1067 ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
1068 ** passed as the second argument.
1069 **
1070 ** If the UPDATE operation is attempted, but SQLite returns
1071 ** SQLITE_CONSTRAINT, the conflict-handler function is invoked with
1072 ** [SQLITE_CHANGESET_CONSTRAINT] passed as the second argument.
1073 ** This includes the case where the UPDATE operation is attempted after
1074 ** an earlier call to the conflict handler function returned
1075 ** [SQLITE_CHANGESET_REPLACE].
1076 ** </dl>
1077 **
1078 ** It is safe to execute SQL statements, including those that write to the
1079 ** table that the callback related to, from within the xConflict callback.
1080 ** This can be used to further customize the applications conflict
1081 ** resolution strategy.
1082 **
1083 ** All changes made by these functions are enclosed in a savepoint transaction.
1084 ** If any other error (aside from a constraint failure when attempting to
1085 ** write to the target database) occurs, then the savepoint transaction is
1086 ** rolled back, restoring the target database to its original state, and an
1087 ** SQLite error code returned.
1088 **
1089 ** If the output parameters (ppRebase) and (pnRebase) are non-NULL and
1090 ** the input is a changeset (not a patchset), then sqlite3changeset_apply_v2()
1091 ** may set (*ppRebase) to point to a "rebase" that may be used with the
1092 ** sqlite3_rebaser APIs buffer before returning. In this case (*pnRebase)
1093 ** is set to the size of the buffer in bytes. It is the responsibility of the
1094 ** caller to eventually free any such buffer using sqlite3_free(). The buffer
1095 ** is only allocated and populated if one or more conflicts were encountered
1096 ** while applying the patchset. See comments surrounding the sqlite3_rebaser
1097 ** APIs for further details.
1098 **
1099 ** The behavior of sqlite3changeset_apply_v2() and its streaming equivalent
1100 ** may be modified by passing a combination of
1101 ** [SQLITE_CHANGESETAPPLY_NOSAVEPOINT | supported flags] as the 9th parameter.
1102 **
1103 ** Note that the sqlite3changeset_apply_v2() API is still <b>experimental</b>
1104 ** and therefore subject to change.
1105 */
1113 ),
1118 ),
1120 );
1128 ),
1133 ),
1137 );
1139 /*
1140 ** CAPI3REF: Flags for sqlite3changeset_apply_v2
1141 **
1142 ** The following flags may passed via the 9th parameter to
1143 ** [sqlite3changeset_apply_v2] and [sqlite3changeset_apply_v2_strm]:
1144 **
1145 ** <dl>
1146 ** <dt>SQLITE_CHANGESETAPPLY_NOSAVEPOINT <dd>
1147 ** Usually, the sessions module encloses all operations performed by
1148 ** a single call to apply_v2() or apply_v2_strm() in a [SAVEPOINT]. The
1149 ** SAVEPOINT is committed if the changeset or patchset is successfully
1150 ** applied, or rolled back if an error occurs. Specifying this flag
1151 ** causes the sessions module to omit this savepoint. In this case, if the
1152 ** caller has an open transaction or savepoint when apply_v2() is called,
1153 ** it may revert the partially applied changeset by rolling it back.
1154 */
1155 #define SQLITE_CHANGESETAPPLY_NOSAVEPOINT 0x0001
1157 /*
1158 ** CAPI3REF: Constants Passed To The Conflict Handler
1159 **
1160 ** Values that may be passed as the second argument to a conflict-handler.
1161 **
1162 ** <dl>
1163 ** <dt>SQLITE_CHANGESET_DATA<dd>
1164 ** The conflict handler is invoked with CHANGESET_DATA as the second argument
1165 ** when processing a DELETE or UPDATE change if a row with the required
1166 ** PRIMARY KEY fields is present in the database, but one or more other
1167 ** (non primary-key) fields modified by the update do not contain the
1168 ** expected "before" values.
1169 **
1170 ** The conflicting row, in this case, is the database row with the matching
1171 ** primary key.
1172 **
1173 ** <dt>SQLITE_CHANGESET_NOTFOUND<dd>
1174 ** The conflict handler is invoked with CHANGESET_NOTFOUND as the second
1175 ** argument when processing a DELETE or UPDATE change if a row with the
1176 ** required PRIMARY KEY fields is not present in the database.
1177 **
1178 ** There is no conflicting row in this case. The results of invoking the
1179 ** sqlite3changeset_conflict() API are undefined.
1180 **
1181 ** <dt>SQLITE_CHANGESET_CONFLICT<dd>
1182 ** CHANGESET_CONFLICT is passed as the second argument to the conflict
1183 ** handler while processing an INSERT change if the operation would result
1184 ** in duplicate primary key values.
1185 **
1186 ** The conflicting row in this case is the database row with the matching
1187 ** primary key.
1188 **
1189 ** <dt>SQLITE_CHANGESET_FOREIGN_KEY<dd>
1190 ** If foreign key handling is enabled, and applying a changeset leaves the
1191 ** database in a state containing foreign key violations, the conflict
1192 ** handler is invoked with CHANGESET_FOREIGN_KEY as the second argument
1193 ** exactly once before the changeset is committed. If the conflict handler
1194 ** returns CHANGESET_OMIT, the changes, including those that caused the
1195 ** foreign key constraint violation, are committed. Or, if it returns
1196 ** CHANGESET_ABORT, the changeset is rolled back.
1197 **
1198 ** No current or conflicting row information is provided. The only function
1199 ** it is possible to call on the supplied sqlite3_changeset_iter handle
1200 ** is sqlite3changeset_fk_conflicts().
1201 **
1202 ** <dt>SQLITE_CHANGESET_CONSTRAINT<dd>
1203 ** If any other constraint violation occurs while applying a change (i.e.
1204 ** a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is
1205 ** invoked with CHANGESET_CONSTRAINT as the second argument.
1206 **
1207 ** There is no conflicting row in this case. The results of invoking the
1208 ** sqlite3changeset_conflict() API are undefined.
1209 **
1210 ** </dl>
1211 */
1212 #define SQLITE_CHANGESET_DATA 1
1213 #define SQLITE_CHANGESET_NOTFOUND 2
1214 #define SQLITE_CHANGESET_CONFLICT 3
1215 #define SQLITE_CHANGESET_CONSTRAINT 4
1216 #define SQLITE_CHANGESET_FOREIGN_KEY 5
1218 /*
1219 ** CAPI3REF: Constants Returned By The Conflict Handler
1220 **
1221 ** A conflict handler callback must return one of the following three values.
1222 **
1223 ** <dl>
1224 ** <dt>SQLITE_CHANGESET_OMIT<dd>
1225 ** If a conflict handler returns this value no special action is taken. The
1226 ** change that caused the conflict is not applied. The session module
1227 ** continues to the next change in the changeset.
1228 **
1229 ** <dt>SQLITE_CHANGESET_REPLACE<dd>
1230 ** This value may only be returned if the second argument to the conflict
1231 ** handler was SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this
1232 ** is not the case, any changes applied so far are rolled back and the
1233 ** call to sqlite3changeset_apply() returns SQLITE_MISUSE.
1234 **
1235 ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_DATA conflict
1236 ** handler, then the conflicting row is either updated or deleted, depending
1237 ** on the type of change.
1238 **
1239 ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_CONFLICT conflict
1240 ** handler, then the conflicting row is removed from the database and a
1241 ** second attempt to apply the change is made. If this second attempt fails,
1242 ** the original row is restored to the database before continuing.
1243 **
1244 ** <dt>SQLITE_CHANGESET_ABORT<dd>
1245 ** If this value is returned, any changes applied so far are rolled back
1246 ** and the call to sqlite3changeset_apply() returns SQLITE_ABORT.
1247 ** </dl>
1248 */
1249 #define SQLITE_CHANGESET_OMIT 0
1250 #define SQLITE_CHANGESET_REPLACE 1
1251 #define SQLITE_CHANGESET_ABORT 2
1253 /*
1254 ** CAPI3REF: Rebasing changesets
1255 ** EXPERIMENTAL
1256 **
1257 ** Suppose there is a site hosting a database in state S0. And that
1258 ** modifications are made that move that database to state S1 and a
1259 ** changeset recorded (the "local" changeset). Then, a changeset based
1260 ** on S0 is received from another site (the "remote" changeset) and
1261 ** applied to the database. The database is then in state
1262 ** (S1+"remote"), where the exact state depends on any conflict
1263 ** resolution decisions (OMIT or REPLACE) made while applying "remote".
1264 ** Rebasing a changeset is to update it to take those conflict
1265 ** resolution decisions into account, so that the same conflicts
1266 ** do not have to be resolved elsewhere in the network.
1267 **
1268 ** For example, if both the local and remote changesets contain an
1269 ** INSERT of the same key on "CREATE TABLE t1(a PRIMARY KEY, b)":
1270 **
1271 ** local: INSERT INTO t1 VALUES(1, 'v1');
1272 ** remote: INSERT INTO t1 VALUES(1, 'v2');
1273 **
1274 ** and the conflict resolution is REPLACE, then the INSERT change is
1275 ** removed from the local changeset (it was overridden). Or, if the
1276 ** conflict resolution was "OMIT", then the local changeset is modified
1277 ** to instead contain:
1278 **
1279 ** UPDATE t1 SET b = 'v2' WHERE a=1;
1280 **
1281 ** Changes within the local changeset are rebased as follows:
1282 **
1283 ** <dl>
1284 ** <dt>Local INSERT<dd>
1285 ** This may only conflict with a remote INSERT. If the conflict
1286 ** resolution was OMIT, then add an UPDATE change to the rebased
1287 ** changeset. Or, if the conflict resolution was REPLACE, add
1288 ** nothing to the rebased changeset.
1289 **
1290 ** <dt>Local DELETE<dd>
1291 ** This may conflict with a remote UPDATE or DELETE. In both cases the
1292 ** only possible resolution is OMIT. If the remote operation was a
1293 ** DELETE, then add no change to the rebased changeset. If the remote
1294 ** operation was an UPDATE, then the old.* fields of change are updated
1295 ** to reflect the new.* values in the UPDATE.
1296 **
1297 ** <dt>Local UPDATE<dd>
1298 ** This may conflict with a remote UPDATE or DELETE. If it conflicts
1299 ** with a DELETE, and the conflict resolution was OMIT, then the update
1300 ** is changed into an INSERT. Any undefined values in the new.* record
1301 ** from the update change are filled in using the old.* values from
1302 ** the conflicting DELETE. Or, if the conflict resolution was REPLACE,
1303 ** the UPDATE change is simply omitted from the rebased changeset.
1304 **
1305 ** If conflict is with a remote UPDATE and the resolution is OMIT, then
1306 ** the old.* values are rebased using the new.* values in the remote
1307 ** change. Or, if the resolution is REPLACE, then the change is copied
1308 ** into the rebased changeset with updates to columns also updated by
1309 ** the conflicting remote UPDATE removed. If this means no columns would
1310 ** be updated, the change is omitted.
1311 ** </dl>
1312 **
1313 ** A local change may be rebased against multiple remote changes
1314 ** simultaneously. If a single key is modified by multiple remote
1315 ** changesets, they are combined as follows before the local changeset
1316 ** is rebased:
1317 **
1318 ** <ul>
1319 ** <li> If there has been one or more REPLACE resolutions on a
1320 ** key, it is rebased according to a REPLACE.
1321 **
1322 ** <li> If there have been no REPLACE resolutions on a key, then
1323 ** the local changeset is rebased according to the most recent
1324 ** of the OMIT resolutions.
1325 ** </ul>
1326 **
1327 ** Note that conflict resolutions from multiple remote changesets are
1328 ** combined on a per-field basis, not per-row. This means that in the
1329 ** case of multiple remote UPDATE operations, some fields of a single
1330 ** local change may be rebased for REPLACE while others are rebased for
1331 ** OMIT.
1332 **
1333 ** In order to rebase a local changeset, the remote changeset must first
1334 ** be applied to the local database using sqlite3changeset_apply_v2() and
1335 ** the buffer of rebase information captured. Then:
1336 **
1337 ** <ol>
1338 ** <li> An sqlite3_rebaser object is created by calling
1339 ** sqlite3rebaser_create().
1340 ** <li> The new object is configured with the rebase buffer obtained from
1341 ** sqlite3changeset_apply_v2() by calling sqlite3rebaser_configure().
1342 ** If the local changeset is to be rebased against multiple remote
1343 ** changesets, then sqlite3rebaser_configure() should be called
1344 ** multiple times, in the same order that the multiple
1345 ** sqlite3changeset_apply_v2() calls were made.
1346 ** <li> Each local changeset is rebased by calling sqlite3rebaser_rebase().
1347 ** <li> The sqlite3_rebaser object is deleted by calling
1348 ** sqlite3rebaser_delete().
1349 ** </ol>
1350 */
1353 /*
1354 ** CAPI3REF: Create a changeset rebaser object.
1355 ** EXPERIMENTAL
1356 **
1357 ** Allocate a new changeset rebaser object. If successful, set (*ppNew) to
1358 ** point to the new object and return SQLITE_OK. Otherwise, if an error
1359 ** occurs, return an SQLite error code (e.g. SQLITE_NOMEM) and set (*ppNew)
1360 ** to NULL.
1361 */
1364 /*
1365 ** CAPI3REF: Configure a changeset rebaser object.
1366 ** EXPERIMENTAL
1367 **
1368 ** Configure the changeset rebaser object to rebase changesets according
1369 ** to the conflict resolutions described by buffer pRebase (size nRebase
1370 ** bytes), which must have been obtained from a previous call to
1371 ** sqlite3changeset_apply_v2().
1372 */
1374 sqlite3_rebaser*,
1376 );
1378 /*
1379 ** CAPI3REF: Rebase a changeset
1380 ** EXPERIMENTAL
1381 **
1382 ** Argument pIn must point to a buffer containing a changeset nIn bytes
1383 ** in size. This function allocates and populates a buffer with a copy
1384 ** of the changeset rebased rebased according to the configuration of the
1385 ** rebaser object passed as the first argument. If successful, (*ppOut)
1386 ** is set to point to the new buffer containing the rebased changset and
1387 ** (*pnOut) to its size in bytes and SQLITE_OK returned. It is the
1388 ** responsibility of the caller to eventually free the new buffer using
1389 ** sqlite3_free(). Otherwise, if an error occurs, (*ppOut) and (*pnOut)
1390 ** are set to zero and an SQLite error code returned.
1391 */
1393 sqlite3_rebaser*,
1396 );
1398 /*
1399 ** CAPI3REF: Delete a changeset rebaser object.
1400 ** EXPERIMENTAL
1401 **
1402 ** Delete the changeset rebaser object and all associated resources. There
1403 ** should be one call to this function for each successful invocation
1404 ** of sqlite3rebaser_create().
1405 */
1408 /*
1409 ** CAPI3REF: Streaming Versions of API functions.
1410 **
1411 ** The six streaming API xxx_strm() functions serve similar purposes to the
1412 ** corresponding non-streaming API functions:
1413 **
1414 ** <table border=1 style="margin-left:8ex;margin-right:8ex">
1415 ** <tr><th>Streaming function<th>Non-streaming equivalent</th>
1416 ** <tr><td>sqlite3changeset_apply_strm<td>[sqlite3changeset_apply]
1417 ** <tr><td>sqlite3changeset_apply_strm_v2<td>[sqlite3changeset_apply_v2]
1418 ** <tr><td>sqlite3changeset_concat_strm<td>[sqlite3changeset_concat]
1419 ** <tr><td>sqlite3changeset_invert_strm<td>[sqlite3changeset_invert]
1420 ** <tr><td>sqlite3changeset_start_strm<td>[sqlite3changeset_start]
1421 ** <tr><td>sqlite3session_changeset_strm<td>[sqlite3session_changeset]
1422 ** <tr><td>sqlite3session_patchset_strm<td>[sqlite3session_patchset]
1423 ** </table>
1424 **
1425 ** Non-streaming functions that accept changesets (or patchsets) as input
1426 ** require that the entire changeset be stored in a single buffer in memory.
1427 ** Similarly, those that return a changeset or patchset do so by returning
1428 ** a pointer to a single large buffer allocated using sqlite3_malloc().
1429 ** Normally this is convenient. However, if an application running in a
1430 ** low-memory environment is required to handle very large changesets, the
1431 ** large contiguous memory allocations required can become onerous.
1432 **
1433 ** In order to avoid this problem, instead of a single large buffer, input
1434 ** is passed to a streaming API functions by way of a callback function that
1435 ** the sessions module invokes to incrementally request input data as it is
1436 ** required. In all cases, a pair of API function parameters such as
1437 **
1438 ** <pre>
1439 ** int nChangeset,
1440 ** void *pChangeset,
1441 ** </pre>
1442 **
1443 ** Is replaced by:
1444 **
1445 ** <pre>
1446 ** int (*xInput)(void *pIn, void *pData, int *pnData),
1447 ** void *pIn,
1448 ** </pre>
1449 **
1450 ** Each time the xInput callback is invoked by the sessions module, the first
1451 ** argument passed is a copy of the supplied pIn context pointer. The second
1452 ** argument, pData, points to a buffer (*pnData) bytes in size. Assuming no
1453 ** error occurs the xInput method should copy up to (*pnData) bytes of data
1454 ** into the buffer and set (*pnData) to the actual number of bytes copied
1455 ** before returning SQLITE_OK. If the input is completely exhausted, (*pnData)
1456 ** should be set to zero to indicate this. Or, if an error occurs, an SQLite
1457 ** error code should be returned. In all cases, if an xInput callback returns
1458 ** an error, all processing is abandoned and the streaming API function
1459 ** returns a copy of the error code to the caller.
1460 **
1461 ** In the case of sqlite3changeset_start_strm(), the xInput callback may be
1462 ** invoked by the sessions module at any point during the lifetime of the
1463 ** iterator. If such an xInput callback returns an error, the iterator enters
1464 ** an error state, whereby all subsequent calls to iterator functions
1465 ** immediately fail with the same error code as returned by xInput.
1466 **
1467 ** Similarly, streaming API functions that return changesets (or patchsets)
1468 ** return them in chunks by way of a callback function instead of via a
1469 ** pointer to a single large buffer. In this case, a pair of parameters such
1470 ** as:
1471 **
1472 ** <pre>
1473 ** int *pnChangeset,
1474 ** void **ppChangeset,
1475 ** </pre>
1476 **
1477 ** Is replaced by:
1478 **
1479 ** <pre>
1480 ** int (*xOutput)(void *pOut, const void *pData, int nData),
1481 ** void *pOut
1482 ** </pre>
1483 **
1484 ** The xOutput callback is invoked zero or more times to return data to
1485 ** the application. The first parameter passed to each call is a copy of the
1486 ** pOut pointer supplied by the application. The second parameter, pData,
1487 ** points to a buffer nData bytes in size containing the chunk of output
1488 ** data being returned. If the xOutput callback successfully processes the
1489 ** supplied data, it should return SQLITE_OK to indicate success. Otherwise,
1490 ** it should return some other SQLite error code. In this case processing
1491 ** is immediately abandoned and the streaming API function returns a copy
1492 ** of the xOutput error code to the application.
1493 **
1494 ** The sessions module never invokes an xOutput callback with the third
1495 ** parameter set to a value less than or equal to zero. Other than this,
1496 ** no guarantees are made as to the size of the chunks of data returned.
1497 */
1505 ),
1510 ),
1512 );
1520 ),
1525 ),
1528 int flags
1529 );
1537 );
1543 );
1548 );
1553 );
1558 );
1562 );
1566 );
1573 );
1576 /*
1577 ** Make sure we can call this stuff from C++.
1578 */
1579 #ifdef __cplusplus
1580 }
1581 #endif