| blob | 9f33855df09ee07bddd35ca29d53e09e2b5cf5b1 |
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 */
19 /*
20 ** CAPI3REF: Changeset Iterator Handle
21 */
24 /*
25 ** CAPI3REF: Create A New Session Object
26 **
27 ** Create a new session object attached to database handle db. If successful,
28 ** a pointer to the new object is written to *ppSession and SQLITE_OK is
29 ** returned. If an error occurs, *ppSession is set to NULL and an SQLite
30 ** error code (e.g. SQLITE_NOMEM) is returned.
31 **
32 ** It is possible to create multiple session objects attached to a single
33 ** database handle.
34 **
35 ** Session objects created using this function should be deleted using the
36 ** [sqlite3session_delete()] function before the database handle that they
37 ** are attached to is itself closed. If the database handle is closed before
38 ** the session object is deleted, then the results of calling any session
39 ** module function, including [sqlite3session_delete()] on the session object
40 ** are undefined.
41 **
42 ** Because the session module uses the [sqlite3_preupdate_hook()] API, it
43 ** is not possible for an application to register a pre-update hook on a
44 ** database handle that has one or more session objects attached. Nor is
45 ** it possible to create a session object attached to a database handle for
46 ** which a pre-update hook is already defined. The results of attempting
47 ** either of these things are undefined.
48 **
49 ** The session object will be used to create changesets for tables in
50 ** database zDb, where zDb is either "main", or "temp", or the name of an
51 ** attached database. It is not an error if database zDb is not attached
52 ** to the database when the session object is created.
53 */
58 );
60 /*
61 ** CAPI3REF: Delete A Session Object
62 **
63 ** Delete a session object previously allocated using
64 ** [sqlite3session_create()]. Once a session object has been deleted, the
65 ** results of attempting to use pSession with any other session module
66 ** function are undefined.
67 **
68 ** Session objects must be deleted before the database handle to which they
69 ** are attached is closed. Refer to the documentation for
70 ** [sqlite3session_create()] for details.
71 */
75 /*
76 ** CAPI3REF: Enable Or Disable A Session Object
77 **
78 ** Enable or disable the recording of changes by a session object. When
79 ** enabled, a session object records changes made to the database. When
80 ** disabled - it does not. A newly created session object is enabled.
81 ** Refer to the documentation for [sqlite3session_changeset()] for further
82 ** details regarding how enabling and disabling a session object affects
83 ** the eventual changesets.
84 **
85 ** Passing zero to this function disables the session. Passing a value
86 ** greater than zero enables it. Passing a value less than zero is a
87 ** no-op, and may be used to query the current state of the session.
88 **
89 ** The return value indicates the final state of the session object: 0 if
90 ** the session is disabled, or 1 if it is enabled.
91 */
94 /*
95 ** CAPI3REF: Set Or Clear the Indirect Change Flag
96 **
97 ** Each change recorded by a session object is marked as either direct or
98 ** indirect. A change is marked as indirect if either:
99 **
100 ** <ul>
101 ** <li> The session object "indirect" flag is set when the change is
102 ** made, or
103 ** <li> The change is made by an SQL trigger or foreign key action
104 ** instead of directly as a result of a users SQL statement.
105 ** </ul>
106 **
107 ** If a single row is affected by more than one operation within a session,
108 ** then the change is considered indirect if all operations meet the criteria
109 ** for an indirect change above, or direct otherwise.
110 **
111 ** This function is used to set, clear or query the session object indirect
112 ** flag. If the second argument passed to this function is zero, then the
113 ** indirect flag is cleared. If it is greater than zero, the indirect flag
114 ** is set. Passing a value less than zero does not modify the current value
115 ** of the indirect flag, and may be used to query the current state of the
116 ** indirect flag for the specified session object.
117 **
118 ** The return value indicates the final state of the indirect flag: 0 if
119 ** it is clear, or 1 if it is set.
120 */
123 /*
124 ** CAPI3REF: Attach A Table To A Session Object
125 **
126 ** If argument zTab is not NULL, then it is the name of a table to attach
127 ** to the session object passed as the first argument. All subsequent changes
128 ** made to the table while the session object is enabled will be recorded. See
129 ** documentation for [sqlite3session_changeset()] for further details.
130 **
131 ** Or, if argument zTab is NULL, then changes are recorded for all tables
132 ** in the database. If additional tables are added to the database (by
133 ** executing "CREATE TABLE" statements) after this call is made, changes for
134 ** the new tables are also recorded.
135 **
136 ** Changes can only be recorded for tables that have a PRIMARY KEY explicitly
137 ** defined as part of their CREATE TABLE statement. It does not matter if the
138 ** PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY
139 ** KEY may consist of a single column, or may be a composite key.
140 **
141 ** It is not an error if the named table does not exist in the database. Nor
142 ** is it an error if the named table does not have a PRIMARY KEY. However,
143 ** no changes will be recorded in either of these scenarios.
144 **
145 ** Changes are not recorded for individual rows that have NULL values stored
146 ** in one or more of their PRIMARY KEY columns.
147 **
148 ** SQLITE_OK is returned if the call completes without error. Or, if an error
149 ** occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.
150 **
151 ** <h3>Special sqlite_stat1 Handling</h3>
152 **
153 ** As of SQLite version 3.22.0, the "sqlite_stat1" table is an exception to
154 ** some of the rules above. In SQLite, the schema of sqlite_stat1 is:
155 ** <pre>
156 ** CREATE TABLE sqlite_stat1(tbl,idx,stat)
157 ** </pre>
158 **
159 ** Even though sqlite_stat1 does not have a PRIMARY KEY, changes are
160 ** recorded for it as if the PRIMARY KEY is (tbl,idx). Additionally, changes
161 ** are recorded for rows for which (idx IS NULL) is true. However, for such
162 ** rows a zero-length blob (SQL value X'') is stored in the changeset or
163 ** patchset instead of a NULL value. This allows such changesets to be
164 ** manipulated by legacy implementations of sqlite3changeset_invert(),
165 ** concat() and similar.
166 **
167 ** The sqlite3changeset_apply() function automatically converts the
168 ** zero-length blob back to a NULL value when updating the sqlite_stat1
169 ** table. However, if the application calls sqlite3changeset_new(),
170 ** sqlite3changeset_old() or sqlite3changeset_conflict on a changeset
171 ** iterator directly (including on a changeset iterator passed to a
172 ** conflict-handler callback) then the X'' value is returned. The application
173 ** must translate X'' to NULL itself if required.
174 **
175 ** Legacy (older than 3.22.0) versions of the sessions module cannot capture
176 ** changes made to the sqlite_stat1 table. Legacy versions of the
177 ** sqlite3changeset_apply() function silently ignore any modifications to the
178 ** sqlite_stat1 table that are part of a changeset or patchset.
179 */
183 );
185 /*
186 ** CAPI3REF: Set a table filter on a Session Object.
187 **
188 ** The second argument (xFilter) is the "filter callback". For changes to rows
189 ** in tables that are not attached to the Session object, the filter is called
190 ** to determine whether changes to the table's rows should be tracked or not.
191 ** If xFilter returns 0, changes is not tracked. Note that once a table is
192 ** attached, xFilter will not be called again.
193 */
199 ),
201 );
203 /*
204 ** CAPI3REF: Generate A Changeset From A Session Object
205 **
206 ** Obtain a changeset containing changes to the tables attached to the
207 ** session object passed as the first argument. If successful,
208 ** set *ppChangeset to point to a buffer containing the changeset
209 ** and *pnChangeset to the size of the changeset in bytes before returning
210 ** SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to
211 ** zero and return an SQLite error code.
212 **
213 ** A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes,
214 ** each representing a change to a single row of an attached table. An INSERT
215 ** change contains the values of each field of a new database row. A DELETE
216 ** contains the original values of each field of a deleted database row. An
217 ** UPDATE change contains the original values of each field of an updated
218 ** database row along with the updated values for each updated non-primary-key
219 ** column. It is not possible for an UPDATE change to represent a change that
220 ** modifies the values of primary key columns. If such a change is made, it
221 ** is represented in a changeset as a DELETE followed by an INSERT.
222 **
223 ** Changes are not recorded for rows that have NULL values stored in one or
224 ** more of their PRIMARY KEY columns. If such a row is inserted or deleted,
225 ** no corresponding change is present in the changesets returned by this
226 ** function. If an existing row with one or more NULL values stored in
227 ** PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL,
228 ** only an INSERT is appears in the changeset. Similarly, if an existing row
229 ** with non-NULL PRIMARY KEY values is updated so that one or more of its
230 ** PRIMARY KEY columns are set to NULL, the resulting changeset contains a
231 ** DELETE change only.
232 **
233 ** The contents of a changeset may be traversed using an iterator created
234 ** using the [sqlite3changeset_start()] API. A changeset may be applied to
235 ** a database with a compatible schema using the [sqlite3changeset_apply()]
236 ** API.
237 **
238 ** Within a changeset generated by this function, all changes related to a
239 ** single table are grouped together. In other words, when iterating through
240 ** a changeset or when applying a changeset to a database, all changes related
241 ** to a single table are processed before moving on to the next table. Tables
242 ** are sorted in the same order in which they were attached (or auto-attached)
243 ** to the sqlite3_session object. The order in which the changes related to
244 ** a single table are stored is undefined.
245 **
246 ** Following a successful call to this function, it is the responsibility of
247 ** the caller to eventually free the buffer that *ppChangeset points to using
248 ** [sqlite3_free()].
249 **
250 ** <h3>Changeset Generation</h3>
251 **
252 ** Once a table has been attached to a session object, the session object
253 ** records the primary key values of all new rows inserted into the table.
254 ** It also records the original primary key and other column values of any
255 ** deleted or updated rows. For each unique primary key value, data is only
256 ** recorded once - the first time a row with said primary key is inserted,
257 ** updated or deleted in the lifetime of the session.
258 **
259 ** There is one exception to the previous paragraph: when a row is inserted,
260 ** updated or deleted, if one or more of its primary key columns contain a
261 ** NULL value, no record of the change is made.
262 **
263 ** The session object therefore accumulates two types of records - those
264 ** that consist of primary key values only (created when the user inserts
265 ** a new record) and those that consist of the primary key values and the
266 ** original values of other table columns (created when the users deletes
267 ** or updates a record).
268 **
269 ** When this function is called, the requested changeset is created using
270 ** both the accumulated records and the current contents of the database
271 ** file. Specifically:
272 **
273 ** <ul>
274 ** <li> For each record generated by an insert, the database is queried
275 ** for a row with a matching primary key. If one is found, an INSERT
276 ** change is added to the changeset. If no such row is found, no change
277 ** is added to the changeset.
278 **
279 ** <li> For each record generated by an update or delete, the database is
280 ** queried for a row with a matching primary key. If such a row is
281 ** found and one or more of the non-primary key fields have been
282 ** modified from their original values, an UPDATE change is added to
283 ** the changeset. Or, if no such row is found in the table, a DELETE
284 ** change is added to the changeset. If there is a row with a matching
285 ** primary key in the database, but all fields contain their original
286 ** values, no change is added to the changeset.
287 ** </ul>
288 **
289 ** This means, amongst other things, that if a row is inserted and then later
290 ** deleted while a session object is active, neither the insert nor the delete
291 ** will be present in the changeset. Or if a row is deleted and then later a
292 ** row with the same primary key values inserted while a session object is
293 ** active, the resulting changeset will contain an UPDATE change instead of
294 ** a DELETE and an INSERT.
295 **
296 ** When a session object is disabled (see the [sqlite3session_enable()] API),
297 ** it does not accumulate records when rows are inserted, updated or deleted.
298 ** This may appear to have some counter-intuitive effects if a single row
299 ** is written to more than once during a session. For example, if a row
300 ** is inserted while a session object is enabled, then later deleted while
301 ** the same session object is disabled, no INSERT record will appear in the
302 ** changeset, even though the delete took place while the session was disabled.
303 ** Or, if one field of a row is updated while a session is disabled, and
304 ** another field of the same row is updated while the session is enabled, the
305 ** resulting changeset will contain an UPDATE change that updates both fields.
306 */
311 );
313 /*
314 ** CAPI3REF: Load The Difference Between Tables Into A Session
315 **
316 ** If it is not already attached to the session object passed as the first
317 ** argument, this function attaches table zTbl in the same manner as the
318 ** [sqlite3session_attach()] function. If zTbl does not exist, or if it
319 ** does not have a primary key, this function is a no-op (but does not return
320 ** an error).
321 **
322 ** Argument zFromDb must be the name of a database ("main", "temp" etc.)
323 ** attached to the same database handle as the session object that contains
324 ** a table compatible with the table attached to the session by this function.
325 ** A table is considered compatible if it:
326 **
327 ** <ul>
328 ** <li> Has the same name,
329 ** <li> Has the same set of columns declared in the same order, and
330 ** <li> Has the same PRIMARY KEY definition.
331 ** </ul>
332 **
333 ** If the tables are not compatible, SQLITE_SCHEMA is returned. If the tables
334 ** are compatible but do not have any PRIMARY KEY columns, it is not an error
335 ** but no changes are added to the session object. As with other session
336 ** APIs, tables without PRIMARY KEYs are simply ignored.
337 **
338 ** This function adds a set of changes to the session object that could be
339 ** used to update the table in database zFrom (call this the "from-table")
340 ** so that its content is the same as the table attached to the session
341 ** object (call this the "to-table"). Specifically:
342 **
343 ** <ul>
344 ** <li> For each row (primary key) that exists in the to-table but not in
345 ** the from-table, an INSERT record is added to the session object.
346 **
347 ** <li> For each row (primary key) that exists in the to-table but not in
348 ** the from-table, a DELETE record is added to the session object.
349 **
350 ** <li> For each row (primary key) that exists in both tables, but features
351 ** different non-PK values in each, an UPDATE record is added to the
352 ** session.
353 ** </ul>
354 **
355 ** To clarify, if this function is called and then a changeset constructed
356 ** using [sqlite3session_changeset()], then after applying that changeset to
357 ** database zFrom the contents of the two compatible tables would be
358 ** identical.
359 **
360 ** It an error if database zFrom does not exist or does not contain the
361 ** required compatible table.
362 **
363 ** If the operation successful, SQLITE_OK is returned. Otherwise, an SQLite
364 ** error code. In this case, if argument pzErrMsg is not NULL, *pzErrMsg
365 ** may be set to point to a buffer containing an English language error
366 ** message. It is the responsibility of the caller to free this buffer using
367 ** sqlite3_free().
368 */
374 );
377 /*
378 ** CAPI3REF: Generate A Patchset From A Session Object
379 **
380 ** The differences between a patchset and a changeset are that:
381 **
382 ** <ul>
383 ** <li> DELETE records consist of the primary key fields only. The
384 ** original values of other fields are omitted.
385 ** <li> The original values of any modified fields are omitted from
386 ** UPDATE records.
387 ** </ul>
388 **
389 ** A patchset blob may be used with up to date versions of all
390 ** sqlite3changeset_xxx API functions except for sqlite3changeset_invert(),
391 ** which returns SQLITE_CORRUPT if it is passed a patchset. Similarly,
392 ** attempting to use a patchset blob with old versions of the
393 ** sqlite3changeset_xxx APIs also provokes an SQLITE_CORRUPT error.
394 **
395 ** Because the non-primary key "old.*" fields are omitted, no
396 ** SQLITE_CHANGESET_DATA conflicts can be detected or reported if a patchset
397 ** is passed to the sqlite3changeset_apply() API. Other conflict types work
398 ** in the same way as for changesets.
399 **
400 ** Changes within a patchset are ordered in the same way as for changesets
401 ** generated by the sqlite3session_changeset() function (i.e. all changes for
402 ** a single table are grouped together, tables appear in the order in which
403 ** they were attached to the session object).
404 */
409 );
411 /*
412 ** CAPI3REF: Test if a changeset has recorded any changes.
413 **
414 ** Return non-zero if no changes to attached tables have been recorded by
415 ** the session object passed as the first argument. Otherwise, if one or
416 ** more changes have been recorded, return zero.
417 **
418 ** Even if this function returns zero, it is possible that calling
419 ** [sqlite3session_changeset()] on the session handle may still return a
420 ** changeset that contains no changes. This can happen when a row in
421 ** an attached table is modified and then later on the original values
422 ** are restored. However, if this function returns non-zero, then it is
423 ** guaranteed that a call to sqlite3session_changeset() will return a
424 ** changeset containing zero changes.
425 */
428 /*
429 ** CAPI3REF: Create An Iterator To Traverse A Changeset
430 **
431 ** Create an iterator used to iterate through the contents of a changeset.
432 ** If successful, *pp is set to point to the iterator handle and SQLITE_OK
433 ** is returned. Otherwise, if an error occurs, *pp is set to zero and an
434 ** SQLite error code is returned.
435 **
436 ** The following functions can be used to advance and query a changeset
437 ** iterator created by this function:
438 **
439 ** <ul>
440 ** <li> [sqlite3changeset_next()]
441 ** <li> [sqlite3changeset_op()]
442 ** <li> [sqlite3changeset_new()]
443 ** <li> [sqlite3changeset_old()]
444 ** </ul>
445 **
446 ** It is the responsibility of the caller to eventually destroy the iterator
447 ** by passing it to [sqlite3changeset_finalize()]. The buffer containing the
448 ** changeset (pChangeset) must remain valid until after the iterator is
449 ** destroyed.
450 **
451 ** Assuming the changeset blob was created by one of the
452 ** [sqlite3session_changeset()], [sqlite3changeset_concat()] or
453 ** [sqlite3changeset_invert()] functions, all changes within the changeset
454 ** that apply to a single table are grouped together. This means that when
455 ** an application iterates through a changeset using an iterator created by
456 ** this function, all changes that relate to a single table are visited
457 ** consecutively. There is no chance that the iterator will visit a change
458 ** the applies to table X, then one for table Y, and then later on visit
459 ** another change for table X.
460 */
465 );
468 /*
469 ** CAPI3REF: Advance A Changeset Iterator
470 **
471 ** This function may only be used with iterators created by function
472 ** [sqlite3changeset_start()]. If it is called on an iterator passed to
473 ** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE
474 ** is returned and the call has no effect.
475 **
476 ** Immediately after an iterator is created by sqlite3changeset_start(), it
477 ** does not point to any change in the changeset. Assuming the changeset
478 ** is not empty, the first call to this function advances the iterator to
479 ** point to the first change in the changeset. Each subsequent call advances
480 ** the iterator to point to the next change in the changeset (if any). If
481 ** no error occurs and the iterator points to a valid change after a call
482 ** to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned.
483 ** Otherwise, if all changes in the changeset have already been visited,
484 ** SQLITE_DONE is returned.
485 **
486 ** If an error occurs, an SQLite error code is returned. Possible error
487 ** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or
488 ** SQLITE_NOMEM.
489 */
492 /*
493 ** CAPI3REF: Obtain The Current Operation From A Changeset Iterator
494 **
495 ** The pIter argument passed to this function may either be an iterator
496 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
497 ** created by [sqlite3changeset_start()]. In the latter case, the most recent
498 ** call to [sqlite3changeset_next()] must have returned [SQLITE_ROW]. If this
499 ** is not the case, this function returns [SQLITE_MISUSE].
500 **
501 ** If argument pzTab is not NULL, then *pzTab is set to point to a
502 ** nul-terminated utf-8 encoded string containing the name of the table
503 ** affected by the current change. The buffer remains valid until either
504 ** sqlite3changeset_next() is called on the iterator or until the
505 ** conflict-handler function returns. If pnCol is not NULL, then *pnCol is
506 ** set to the number of columns in the table affected by the change. If
507 ** pbIncorrect is not NULL, then *pbIndirect is set to true (1) if the change
508 ** is an indirect change, or false (0) otherwise. See the documentation for
509 ** [sqlite3session_indirect()] for a description of direct and indirect
510 ** changes. Finally, if pOp is not NULL, then *pOp is set to one of
511 ** [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], depending on the
512 ** type of change that the iterator currently points to.
513 **
514 ** If no error occurs, SQLITE_OK is returned. If an error does occur, an
515 ** SQLite error code is returned. The values of the output variables may not
516 ** be trusted in this case.
517 */
524 );
526 /*
527 ** CAPI3REF: Obtain The Primary Key Definition Of A Table
528 **
529 ** For each modified table, a changeset includes the following:
530 **
531 ** <ul>
532 ** <li> The number of columns in the table, and
533 ** <li> Which of those columns make up the tables PRIMARY KEY.
534 ** </ul>
535 **
536 ** This function is used to find which columns comprise the PRIMARY KEY of
537 ** the table modified by the change that iterator pIter currently points to.
538 ** If successful, *pabPK is set to point to an array of nCol entries, where
539 ** nCol is the number of columns in the table. Elements of *pabPK are set to
540 ** 0x01 if the corresponding column is part of the tables primary key, or
541 ** 0x00 if it is not.
542 **
543 ** If argument pnCol is not NULL, then *pnCol is set to the number of columns
544 ** in the table.
545 **
546 ** If this function is called when the iterator does not point to a valid
547 ** entry, SQLITE_MISUSE is returned and the output variables zeroed. Otherwise,
548 ** SQLITE_OK is returned and the output variables populated as described
549 ** above.
550 */
555 );
557 /*
558 ** CAPI3REF: Obtain old.* Values From A Changeset Iterator
559 **
560 ** The pIter argument passed to this function may either be an iterator
561 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
562 ** created by [sqlite3changeset_start()]. In the latter case, the most recent
563 ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.
564 ** Furthermore, it may only be called if the type of change that the iterator
565 ** currently points to is either [SQLITE_DELETE] or [SQLITE_UPDATE]. Otherwise,
566 ** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.
567 **
568 ** Argument iVal must be greater than or equal to 0, and less than the number
569 ** of columns in the table affected by the current change. Otherwise,
570 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
571 **
572 ** If successful, this function sets *ppValue to point to a protected
573 ** sqlite3_value object containing the iVal'th value from the vector of
574 ** original row values stored as part of the UPDATE or DELETE change and
575 ** returns SQLITE_OK. The name of the function comes from the fact that this
576 ** is similar to the "old.*" columns available to update or delete triggers.
577 **
578 ** If some other error occurs (e.g. an OOM condition), an SQLite error code
579 ** is returned and *ppValue is set to NULL.
580 */
585 );
587 /*
588 ** CAPI3REF: Obtain new.* Values From A Changeset Iterator
589 **
590 ** The pIter argument passed to this function may either be an iterator
591 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
592 ** created by [sqlite3changeset_start()]. In the latter case, the most recent
593 ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.
594 ** Furthermore, it may only be called if the type of change that the iterator
595 ** currently points to is either [SQLITE_UPDATE] or [SQLITE_INSERT]. Otherwise,
596 ** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.
597 **
598 ** Argument iVal must be greater than or equal to 0, and less than the number
599 ** of columns in the table affected by the current change. Otherwise,
600 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
601 **
602 ** If successful, this function sets *ppValue to point to a protected
603 ** sqlite3_value object containing the iVal'th value from the vector of
604 ** new row values stored as part of the UPDATE or INSERT change and
605 ** returns SQLITE_OK. If the change is an UPDATE and does not include
606 ** a new value for the requested column, *ppValue is set to NULL and
607 ** SQLITE_OK returned. The name of the function comes from the fact that
608 ** this is similar to the "new.*" columns available to update or delete
609 ** triggers.
610 **
611 ** If some other error occurs (e.g. an OOM condition), an SQLite error code
612 ** is returned and *ppValue is set to NULL.
613 */
618 );
620 /*
621 ** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator
622 **
623 ** This function should only be used with iterator objects passed to a
624 ** conflict-handler callback by [sqlite3changeset_apply()] with either
625 ** [SQLITE_CHANGESET_DATA] or [SQLITE_CHANGESET_CONFLICT]. If this function
626 ** is called on any other iterator, [SQLITE_MISUSE] is returned and *ppValue
627 ** is set to NULL.
628 **
629 ** Argument iVal must be greater than or equal to 0, and less than the number
630 ** of columns in the table affected by the current change. Otherwise,
631 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
632 **
633 ** If successful, this function sets *ppValue to point to a protected
634 ** sqlite3_value object containing the iVal'th value from the
635 ** "conflicting row" associated with the current conflict-handler callback
636 ** and returns SQLITE_OK.
637 **
638 ** If some other error occurs (e.g. an OOM condition), an SQLite error code
639 ** is returned and *ppValue is set to NULL.
640 */
645 );
647 /*
648 ** CAPI3REF: Determine The Number Of Foreign Key Constraint Violations
649 **
650 ** This function may only be called with an iterator passed to an
651 ** SQLITE_CHANGESET_FOREIGN_KEY conflict handler callback. In this case
652 ** it sets the output variable to the total number of known foreign key
653 ** violations in the destination database and returns SQLITE_OK.
654 **
655 ** In all other cases this function returns SQLITE_MISUSE.
656 */
660 );
663 /*
664 ** CAPI3REF: Finalize A Changeset Iterator
665 **
666 ** This function is used to finalize an iterator allocated with
667 ** [sqlite3changeset_start()].
668 **
669 ** This function should only be called on iterators created using the
670 ** [sqlite3changeset_start()] function. If an application calls this
671 ** function with an iterator passed to a conflict-handler by
672 ** [sqlite3changeset_apply()], [SQLITE_MISUSE] is immediately returned and the
673 ** call has no effect.
674 **
675 ** If an error was encountered within a call to an sqlite3changeset_xxx()
676 ** function (for example an [SQLITE_CORRUPT] in [sqlite3changeset_next()] or an
677 ** [SQLITE_NOMEM] in [sqlite3changeset_new()]) then an error code corresponding
678 ** to that error is returned by this function. Otherwise, SQLITE_OK is
679 ** returned. This is to allow the following pattern (pseudo-code):
680 **
681 ** sqlite3changeset_start();
682 ** while( SQLITE_ROW==sqlite3changeset_next() ){
683 ** // Do something with change.
684 ** }
685 ** rc = sqlite3changeset_finalize();
686 ** if( rc!=SQLITE_OK ){
687 ** // An error has occurred
688 ** }
689 */
692 /*
693 ** CAPI3REF: Invert A Changeset
694 **
695 ** This function is used to "invert" a changeset object. Applying an inverted
696 ** changeset to a database reverses the effects of applying the uninverted
697 ** changeset. Specifically:
698 **
699 ** <ul>
700 ** <li> Each DELETE change is changed to an INSERT, and
701 ** <li> Each INSERT change is changed to a DELETE, and
702 ** <li> For each UPDATE change, the old.* and new.* values are exchanged.
703 ** </ul>
704 **
705 ** This function does not change the order in which changes appear within
706 ** the changeset. It merely reverses the sense of each individual change.
707 **
708 ** If successful, a pointer to a buffer containing the inverted changeset
709 ** is stored in *ppOut, the size of the same buffer is stored in *pnOut, and
710 ** SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are
711 ** zeroed and an SQLite error code returned.
712 **
713 ** It is the responsibility of the caller to eventually call sqlite3_free()
714 ** on the *ppOut pointer to free the buffer allocation following a successful
715 ** call to this function.
716 **
717 ** WARNING/TODO: This function currently assumes that the input is a valid
718 ** changeset. If it is not, the results are undefined.
719 */
723 );
725 /*
726 ** CAPI3REF: Concatenate Two Changeset Objects
727 **
728 ** This function is used to concatenate two changesets, A and B, into a
729 ** single changeset. The result is a changeset equivalent to applying
730 ** changeset A followed by changeset B.
731 **
732 ** This function combines the two input changesets using an
733 ** sqlite3_changegroup object. Calling it produces similar results as the
734 ** following code fragment:
735 **
736 ** sqlite3_changegroup *pGrp;
737 ** rc = sqlite3_changegroup_new(&pGrp);
738 ** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nA, pA);
739 ** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nB, pB);
740 ** if( rc==SQLITE_OK ){
741 ** rc = sqlite3changegroup_output(pGrp, pnOut, ppOut);
742 ** }else{
743 ** *ppOut = 0;
744 ** *pnOut = 0;
745 ** }
746 **
747 ** Refer to the sqlite3_changegroup documentation below for details.
748 */
756 );
759 /*
760 ** CAPI3REF: Changegroup Handle
761 */
764 /*
765 ** CAPI3REF: Create A New Changegroup Object
766 **
767 ** An sqlite3_changegroup object is used to combine two or more changesets
768 ** (or patchsets) into a single changeset (or patchset). A single changegroup
769 ** object may combine changesets or patchsets, but not both. The output is
770 ** always in the same format as the input.
771 **
772 ** If successful, this function returns SQLITE_OK and populates (*pp) with
773 ** a pointer to a new sqlite3_changegroup object before returning. The caller
774 ** should eventually free the returned object using a call to
775 ** sqlite3changegroup_delete(). If an error occurs, an SQLite error code
776 ** (i.e. SQLITE_NOMEM) is returned and *pp is set to NULL.
777 **
778 ** The usual usage pattern for an sqlite3_changegroup object is as follows:
779 **
780 ** <ul>
781 ** <li> It is created using a call to sqlite3changegroup_new().
782 **
783 ** <li> Zero or more changesets (or patchsets) are added to the object
784 ** by calling sqlite3changegroup_add().
785 **
786 ** <li> The result of combining all input changesets together is obtained
787 ** by the application via a call to sqlite3changegroup_output().
788 **
789 ** <li> The object is deleted using a call to sqlite3changegroup_delete().
790 ** </ul>
791 **
792 ** Any number of calls to add() and output() may be made between the calls to
793 ** new() and delete(), and in any order.
794 **
795 ** As well as the regular sqlite3changegroup_add() and
796 ** sqlite3changegroup_output() functions, also available are the streaming
797 ** versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm().
798 */
801 /*
802 ** CAPI3REF: Add A Changeset To A Changegroup
803 **
804 ** Add all changes within the changeset (or patchset) in buffer pData (size
805 ** nData bytes) to the changegroup.
806 **
807 ** If the buffer contains a patchset, then all prior calls to this function
808 ** on the same changegroup object must also have specified patchsets. Or, if
809 ** the buffer contains a changeset, so must have the earlier calls to this
810 ** function. Otherwise, SQLITE_ERROR is returned and no changes are added
811 ** to the changegroup.
812 **
813 ** Rows within the changeset and changegroup are identified by the values in
814 ** their PRIMARY KEY columns. A change in the changeset is considered to
815 ** apply to the same row as a change already present in the changegroup if
816 ** the two rows have the same primary key.
817 **
818 ** Changes to rows that do not already appear in the changegroup are
819 ** simply copied into it. Or, if both the new changeset and the changegroup
820 ** contain changes that apply to a single row, the final contents of the
821 ** changegroup depends on the type of each change, as follows:
822 **
823 ** <table border=1 style="margin-left:8ex;margin-right:8ex">
824 ** <tr><th style="white-space:pre">Existing Change </th>
825 ** <th style="white-space:pre">New Change </th>
826 ** <th>Output Change
827 ** <tr><td>INSERT <td>INSERT <td>
828 ** The new change is ignored. This case does not occur if the new
829 ** changeset was recorded immediately after the changesets already
830 ** added to the changegroup.
831 ** <tr><td>INSERT <td>UPDATE <td>
832 ** The INSERT change remains in the changegroup. The values in the
833 ** INSERT change are modified as if the row was inserted by the
834 ** existing change and then updated according to the new change.
835 ** <tr><td>INSERT <td>DELETE <td>
836 ** The existing INSERT is removed from the changegroup. The DELETE is
837 ** not added.
838 ** <tr><td>UPDATE <td>INSERT <td>
839 ** The new change is ignored. This case does not occur if the new
840 ** changeset was recorded immediately after the changesets already
841 ** added to the changegroup.
842 ** <tr><td>UPDATE <td>UPDATE <td>
843 ** The existing UPDATE remains within the changegroup. It is amended
844 ** so that the accompanying values are as if the row was updated once
845 ** by the existing change and then again by the new change.
846 ** <tr><td>UPDATE <td>DELETE <td>
847 ** The existing UPDATE is replaced by the new DELETE within the
848 ** changegroup.
849 ** <tr><td>DELETE <td>INSERT <td>
850 ** If one or more of the column values in the row inserted by the
851 ** new change differ from those in the row deleted by the existing
852 ** change, the existing DELETE is replaced by an UPDATE within the
853 ** changegroup. Otherwise, if the inserted row is exactly the same
854 ** as the deleted row, the existing DELETE is simply discarded.
855 ** <tr><td>DELETE <td>UPDATE <td>
856 ** The new change is ignored. This case does not occur if the new
857 ** changeset was recorded immediately after the changesets already
858 ** added to the changegroup.
859 ** <tr><td>DELETE <td>DELETE <td>
860 ** The new change is ignored. This case does not occur if the new
861 ** changeset was recorded immediately after the changesets already
862 ** added to the changegroup.
863 ** </table>
864 **
865 ** If the new changeset contains changes to a table that is already present
866 ** in the changegroup, then the number of columns and the position of the
867 ** primary key columns for the table must be consistent. If this is not the
868 ** case, this function fails with SQLITE_SCHEMA. If the input changeset
869 ** appears to be corrupt and the corruption is detected, SQLITE_CORRUPT is
870 ** returned. Or, if an out-of-memory condition occurs during processing, this
871 ** function returns SQLITE_NOMEM. In all cases, if an error occurs the
872 ** final contents of the changegroup is undefined.
873 **
874 ** If no error occurs, SQLITE_OK is returned.
875 */
878 /*
879 ** CAPI3REF: Obtain A Composite Changeset From A Changegroup
880 **
881 ** Obtain a buffer containing a changeset (or patchset) representing the
882 ** current contents of the changegroup. If the inputs to the changegroup
883 ** were themselves changesets, the output is a changeset. Or, if the
884 ** inputs were patchsets, the output is also a patchset.
885 **
886 ** As with the output of the sqlite3session_changeset() and
887 ** sqlite3session_patchset() functions, all changes related to a single
888 ** table are grouped together in the output of this function. Tables appear
889 ** in the same order as for the very first changeset added to the changegroup.
890 ** If the second or subsequent changesets added to the changegroup contain
891 ** changes for tables that do not appear in the first changeset, they are
892 ** appended onto the end of the output changeset, again in the order in
893 ** which they are first encountered.
894 **
895 ** If an error occurs, an SQLite error code is returned and the output
896 ** variables (*pnData) and (*ppData) are set to 0. Otherwise, SQLITE_OK
897 ** is returned and the output variables are set to the size of and a
898 ** pointer to the output buffer, respectively. In this case it is the
899 ** responsibility of the caller to eventually free the buffer using a
900 ** call to sqlite3_free().
901 */
903 sqlite3_changegroup*,
906 );
908 /*
909 ** CAPI3REF: Delete A Changegroup Object
910 */
913 /*
914 ** CAPI3REF: Apply A Changeset To A Database
915 **
916 ** Apply a changeset to a database. This function attempts to update the
917 ** "main" database attached to handle db with the changes found in the
918 ** changeset passed via the second and third arguments.
919 **
920 ** The fourth argument (xFilter) passed to this function is the "filter
921 ** callback". If it is not NULL, then for each table affected by at least one
922 ** change in the changeset, the filter callback is invoked with
923 ** the table name as the second argument, and a copy of the context pointer
924 ** passed as the sixth argument to this function as the first. If the "filter
925 ** callback" returns zero, then no attempt is made to apply any changes to
926 ** the table. Otherwise, if the return value is non-zero or the xFilter
927 ** argument to this function is NULL, all changes related to the table are
928 ** attempted.
929 **
930 ** For each table that is not excluded by the filter callback, this function
931 ** tests that the target database contains a compatible table. A table is
932 ** considered compatible if all of the following are true:
933 **
934 ** <ul>
935 ** <li> The table has the same name as the name recorded in the
936 ** changeset, and
937 ** <li> The table has at least as many columns as recorded in the
938 ** changeset, and
939 ** <li> The table has primary key columns in the same position as
940 ** recorded in the changeset.
941 ** </ul>
942 **
943 ** If there is no compatible table, it is not an error, but none of the
944 ** changes associated with the table are applied. A warning message is issued
945 ** via the sqlite3_log() mechanism with the error code SQLITE_SCHEMA. At most
946 ** one such warning is issued for each table in the changeset.
947 **
948 ** For each change for which there is a compatible table, an attempt is made
949 ** to modify the table contents according to the UPDATE, INSERT or DELETE
950 ** change. If a change cannot be applied cleanly, the conflict handler
951 ** function passed as the fifth argument to sqlite3changeset_apply() may be
952 ** invoked. A description of exactly when the conflict handler is invoked for
953 ** each type of change is below.
954 **
955 ** Unlike the xFilter argument, xConflict may not be passed NULL. The results
956 ** of passing anything other than a valid function pointer as the xConflict
957 ** argument are undefined.
958 **
959 ** Each time the conflict handler function is invoked, it must return one
960 ** of [SQLITE_CHANGESET_OMIT], [SQLITE_CHANGESET_ABORT] or
961 ** [SQLITE_CHANGESET_REPLACE]. SQLITE_CHANGESET_REPLACE may only be returned
962 ** if the second argument passed to the conflict handler is either
963 ** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler
964 ** returns an illegal value, any changes already made are rolled back and
965 ** the call to sqlite3changeset_apply() returns SQLITE_MISUSE. Different
966 ** actions are taken by sqlite3changeset_apply() depending on the value
967 ** returned by each invocation of the conflict-handler function. Refer to
968 ** the documentation for the three
969 ** [SQLITE_CHANGESET_OMIT|available return values] for details.
970 **
971 ** <dl>
972 ** <dt>DELETE Changes<dd>
973 ** For each DELETE change, this function checks if the target database
974 ** contains a row with the same primary key value (or values) as the
975 ** original row values stored in the changeset. If it does, and the values
976 ** stored in all non-primary key columns also match the values stored in
977 ** the changeset the row is deleted from the target database.
978 **
979 ** If a row with matching primary key values is found, but one or more of
980 ** the non-primary key fields contains a value different from the original
981 ** row value stored in the changeset, the conflict-handler function is
982 ** invoked with [SQLITE_CHANGESET_DATA] as the second argument. If the
983 ** database table has more columns than are recorded in the changeset,
984 ** only the values of those non-primary key fields are compared against
985 ** the current database contents - any trailing database table columns
986 ** are ignored.
987 **
988 ** If no row with matching primary key values is found in the database,
989 ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
990 ** passed as the second argument.
991 **
992 ** If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT
993 ** (which can only happen if a foreign key constraint is violated), the
994 ** conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT]
995 ** passed as the second argument. This includes the case where the DELETE
996 ** operation is attempted because an earlier call to the conflict handler
997 ** function returned [SQLITE_CHANGESET_REPLACE].
998 **
999 ** <dt>INSERT Changes<dd>
1000 ** For each INSERT change, an attempt is made to insert the new row into
1001 ** the database. If the changeset row contains fewer fields than the
1002 ** database table, the trailing fields are populated with their default
1003 ** values.
1004 **
1005 ** If the attempt to insert the row fails because the database already
1006 ** contains a row with the same primary key values, the conflict handler
1007 ** function is invoked with the second argument set to
1008 ** [SQLITE_CHANGESET_CONFLICT].
1009 **
1010 ** If the attempt to insert the row fails because of some other constraint
1011 ** violation (e.g. NOT NULL or UNIQUE), the conflict handler function is
1012 ** invoked with the second argument set to [SQLITE_CHANGESET_CONSTRAINT].
1013 ** This includes the case where the INSERT operation is re-attempted because
1014 ** an earlier call to the conflict handler function returned
1015 ** [SQLITE_CHANGESET_REPLACE].
1016 **
1017 ** <dt>UPDATE Changes<dd>
1018 ** For each UPDATE change, this function checks if the target database
1019 ** contains a row with the same primary key value (or values) as the
1020 ** original row values stored in the changeset. If it does, and the values
1021 ** stored in all modified non-primary key columns also match the values
1022 ** stored in the changeset the row is updated within the target database.
1023 **
1024 ** If a row with matching primary key values is found, but one or more of
1025 ** the modified non-primary key fields contains a value different from an
1026 ** original row value stored in the changeset, the conflict-handler function
1027 ** is invoked with [SQLITE_CHANGESET_DATA] as the second argument. Since
1028 ** UPDATE changes only contain values for non-primary key fields that are
1029 ** to be modified, only those fields need to match the original values to
1030 ** avoid the SQLITE_CHANGESET_DATA conflict-handler callback.
1031 **
1032 ** If no row with matching primary key values is found in the database,
1033 ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
1034 ** passed as the second argument.
1035 **
1036 ** If the UPDATE operation is attempted, but SQLite returns
1037 ** SQLITE_CONSTRAINT, the conflict-handler function is invoked with
1038 ** [SQLITE_CHANGESET_CONSTRAINT] passed as the second argument.
1039 ** This includes the case where the UPDATE operation is attempted after
1040 ** an earlier call to the conflict handler function returned
1041 ** [SQLITE_CHANGESET_REPLACE].
1042 ** </dl>
1043 **
1044 ** It is safe to execute SQL statements, including those that write to the
1045 ** table that the callback related to, from within the xConflict callback.
1046 ** This can be used to further customize the applications conflict
1047 ** resolution strategy.
1048 **
1049 ** All changes made by this function are enclosed in a savepoint transaction.
1050 ** If any other error (aside from a constraint failure when attempting to
1051 ** write to the target database) occurs, then the savepoint transaction is
1052 ** rolled back, restoring the target database to its original state, and an
1053 ** SQLite error code returned.
1054 */
1062 ),
1067 ),
1069 );
1071 /*
1072 ** CAPI3REF: Constants Passed To The Conflict Handler
1073 **
1074 ** Values that may be passed as the second argument to a conflict-handler.
1075 **
1076 ** <dl>
1077 ** <dt>SQLITE_CHANGESET_DATA<dd>
1078 ** The conflict handler is invoked with CHANGESET_DATA as the second argument
1079 ** when processing a DELETE or UPDATE change if a row with the required
1080 ** PRIMARY KEY fields is present in the database, but one or more other
1081 ** (non primary-key) fields modified by the update do not contain the
1082 ** expected "before" values.
1083 **
1084 ** The conflicting row, in this case, is the database row with the matching
1085 ** primary key.
1086 **
1087 ** <dt>SQLITE_CHANGESET_NOTFOUND<dd>
1088 ** The conflict handler is invoked with CHANGESET_NOTFOUND as the second
1089 ** argument when processing a DELETE or UPDATE change if a row with the
1090 ** required PRIMARY KEY fields is not present in the database.
1091 **
1092 ** There is no conflicting row in this case. The results of invoking the
1093 ** sqlite3changeset_conflict() API are undefined.
1094 **
1095 ** <dt>SQLITE_CHANGESET_CONFLICT<dd>
1096 ** CHANGESET_CONFLICT is passed as the second argument to the conflict
1097 ** handler while processing an INSERT change if the operation would result
1098 ** in duplicate primary key values.
1099 **
1100 ** The conflicting row in this case is the database row with the matching
1101 ** primary key.
1102 **
1103 ** <dt>SQLITE_CHANGESET_FOREIGN_KEY<dd>
1104 ** If foreign key handling is enabled, and applying a changeset leaves the
1105 ** database in a state containing foreign key violations, the conflict
1106 ** handler is invoked with CHANGESET_FOREIGN_KEY as the second argument
1107 ** exactly once before the changeset is committed. If the conflict handler
1108 ** returns CHANGESET_OMIT, the changes, including those that caused the
1109 ** foreign key constraint violation, are committed. Or, if it returns
1110 ** CHANGESET_ABORT, the changeset is rolled back.
1111 **
1112 ** No current or conflicting row information is provided. The only function
1113 ** it is possible to call on the supplied sqlite3_changeset_iter handle
1114 ** is sqlite3changeset_fk_conflicts().
1115 **
1116 ** <dt>SQLITE_CHANGESET_CONSTRAINT<dd>
1117 ** If any other constraint violation occurs while applying a change (i.e.
1118 ** a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is
1119 ** invoked with CHANGESET_CONSTRAINT as the second argument.
1120 **
1121 ** There is no conflicting row in this case. The results of invoking the
1122 ** sqlite3changeset_conflict() API are undefined.
1123 **
1124 ** </dl>
1125 */
1126 #define SQLITE_CHANGESET_DATA 1
1127 #define SQLITE_CHANGESET_NOTFOUND 2
1128 #define SQLITE_CHANGESET_CONFLICT 3
1129 #define SQLITE_CHANGESET_CONSTRAINT 4
1130 #define SQLITE_CHANGESET_FOREIGN_KEY 5
1132 /*
1133 ** CAPI3REF: Constants Returned By The Conflict Handler
1134 **
1135 ** A conflict handler callback must return one of the following three values.
1136 **
1137 ** <dl>
1138 ** <dt>SQLITE_CHANGESET_OMIT<dd>
1139 ** If a conflict handler returns this value no special action is taken. The
1140 ** change that caused the conflict is not applied. The session module
1141 ** continues to the next change in the changeset.
1142 **
1143 ** <dt>SQLITE_CHANGESET_REPLACE<dd>
1144 ** This value may only be returned if the second argument to the conflict
1145 ** handler was SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this
1146 ** is not the case, any changes applied so far are rolled back and the
1147 ** call to sqlite3changeset_apply() returns SQLITE_MISUSE.
1148 **
1149 ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_DATA conflict
1150 ** handler, then the conflicting row is either updated or deleted, depending
1151 ** on the type of change.
1152 **
1153 ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_CONFLICT conflict
1154 ** handler, then the conflicting row is removed from the database and a
1155 ** second attempt to apply the change is made. If this second attempt fails,
1156 ** the original row is restored to the database before continuing.
1157 **
1158 ** <dt>SQLITE_CHANGESET_ABORT<dd>
1159 ** If this value is returned, any changes applied so far are rolled back
1160 ** and the call to sqlite3changeset_apply() returns SQLITE_ABORT.
1161 ** </dl>
1162 */
1163 #define SQLITE_CHANGESET_OMIT 0
1164 #define SQLITE_CHANGESET_REPLACE 1
1165 #define SQLITE_CHANGESET_ABORT 2
1167 /*
1168 ** CAPI3REF: Streaming Versions of API functions.
1169 **
1170 ** The six streaming API xxx_strm() functions serve similar purposes to the
1171 ** corresponding non-streaming API functions:
1172 **
1173 ** <table border=1 style="margin-left:8ex;margin-right:8ex">
1174 ** <tr><th>Streaming function<th>Non-streaming equivalent</th>
1175 ** <tr><td>sqlite3changeset_apply_strm<td>[sqlite3changeset_apply]
1176 ** <tr><td>sqlite3changeset_concat_strm<td>[sqlite3changeset_concat]
1177 ** <tr><td>sqlite3changeset_invert_strm<td>[sqlite3changeset_invert]
1178 ** <tr><td>sqlite3changeset_start_strm<td>[sqlite3changeset_start]
1179 ** <tr><td>sqlite3session_changeset_strm<td>[sqlite3session_changeset]
1180 ** <tr><td>sqlite3session_patchset_strm<td>[sqlite3session_patchset]
1181 ** </table>
1182 **
1183 ** Non-streaming functions that accept changesets (or patchsets) as input
1184 ** require that the entire changeset be stored in a single buffer in memory.
1185 ** Similarly, those that return a changeset or patchset do so by returning
1186 ** a pointer to a single large buffer allocated using sqlite3_malloc().
1187 ** Normally this is convenient. However, if an application running in a
1188 ** low-memory environment is required to handle very large changesets, the
1189 ** large contiguous memory allocations required can become onerous.
1190 **
1191 ** In order to avoid this problem, instead of a single large buffer, input
1192 ** is passed to a streaming API functions by way of a callback function that
1193 ** the sessions module invokes to incrementally request input data as it is
1194 ** required. In all cases, a pair of API function parameters such as
1195 **
1196 ** <pre>
1197 ** int nChangeset,
1198 ** void *pChangeset,
1199 ** </pre>
1200 **
1201 ** Is replaced by:
1202 **
1203 ** <pre>
1204 ** int (*xInput)(void *pIn, void *pData, int *pnData),
1205 ** void *pIn,
1206 ** </pre>
1207 **
1208 ** Each time the xInput callback is invoked by the sessions module, the first
1209 ** argument passed is a copy of the supplied pIn context pointer. The second
1210 ** argument, pData, points to a buffer (*pnData) bytes in size. Assuming no
1211 ** error occurs the xInput method should copy up to (*pnData) bytes of data
1212 ** into the buffer and set (*pnData) to the actual number of bytes copied
1213 ** before returning SQLITE_OK. If the input is completely exhausted, (*pnData)
1214 ** should be set to zero to indicate this. Or, if an error occurs, an SQLite
1215 ** error code should be returned. In all cases, if an xInput callback returns
1216 ** an error, all processing is abandoned and the streaming API function
1217 ** returns a copy of the error code to the caller.
1218 **
1219 ** In the case of sqlite3changeset_start_strm(), the xInput callback may be
1220 ** invoked by the sessions module at any point during the lifetime of the
1221 ** iterator. If such an xInput callback returns an error, the iterator enters
1222 ** an error state, whereby all subsequent calls to iterator functions
1223 ** immediately fail with the same error code as returned by xInput.
1224 **
1225 ** Similarly, streaming API functions that return changesets (or patchsets)
1226 ** return them in chunks by way of a callback function instead of via a
1227 ** pointer to a single large buffer. In this case, a pair of parameters such
1228 ** as:
1229 **
1230 ** <pre>
1231 ** int *pnChangeset,
1232 ** void **ppChangeset,
1233 ** </pre>
1234 **
1235 ** Is replaced by:
1236 **
1237 ** <pre>
1238 ** int (*xOutput)(void *pOut, const void *pData, int nData),
1239 ** void *pOut
1240 ** </pre>
1241 **
1242 ** The xOutput callback is invoked zero or more times to return data to
1243 ** the application. The first parameter passed to each call is a copy of the
1244 ** pOut pointer supplied by the application. The second parameter, pData,
1245 ** points to a buffer nData bytes in size containing the chunk of output
1246 ** data being returned. If the xOutput callback successfully processes the
1247 ** supplied data, it should return SQLITE_OK to indicate success. Otherwise,
1248 ** it should return some other SQLite error code. In this case processing
1249 ** is immediately abandoned and the streaming API function returns a copy
1250 ** of the xOutput error code to the application.
1251 **
1252 ** The sessions module never invokes an xOutput callback with the third
1253 ** parameter set to a value less than or equal to zero. Other than this,
1254 ** no guarantees are made as to the size of the chunks of data returned.
1255 */
1263 ),
1268 ),
1270 );
1278 );
1284 );
1289 );
1294 );
1299 );
1303 );
1307 );
1310 /*
1311 ** Make sure we can call this stuff from C++.
1312 */
1313 #ifdef __cplusplus
1314 }
1315 #endif