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