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