/ Check-in [f227f602]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Documentation format updates to sqlite3session.h.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | sessions
Files: files | file ages | folders
SHA1: f227f60210fba3930f3050aebb1facee8bac9c0b
User & Date: dan 2011-03-20 11:20:41
Context
2011-03-21
07:23
Fix some typos in sqlite3session.h. check-in: 0853e530 user: dan tags: sessions
2011-03-20
11:20
Documentation format updates to sqlite3session.h. check-in: f227f602 user: dan tags: sessions
2011-03-19
19:19
Fix a problem involving session objects and attached databases. check-in: ad91d300 user: dan tags: sessions
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to ext/session/sqlite3session.h.

     7      7   */
     8      8   #ifdef __cplusplus
     9      9   extern "C" {
    10     10   #endif
    11     11   
    12     12   #include "sqlite3.h"
    13     13   
           14  +/*
           15  +** CAPI3REF: Session Object Handle
           16  +*/
    14     17   typedef struct sqlite3_session sqlite3_session;
           18  +
           19  +/*
           20  +** CAPI3REF: Changeset Iterator Handle
           21  +*/
    15     22   typedef struct sqlite3_changeset_iter sqlite3_changeset_iter;
    16     23   
    17     24   /*
           25  +** CAPI3REF: Create A New Session Object
           26  +**
    18     27   ** Create a new session object attached to database handle db. If successful,
    19     28   ** a pointer to the new object is written to *ppSession and SQLITE_OK is
    20     29   ** returned. If an error occurs, *ppSession is set to NULL and an SQLite
    21     30   ** error code (e.g. SQLITE_NOMEM) is returned.
    22     31   **
    23     32   ** It is possible to create multiple session objects attached to a single
    24     33   ** database handle.
................................................................................
    45     54   int sqlite3session_create(
    46     55     sqlite3 *db,                    /* Database handle */
    47     56     const char *zDb,                /* Name of db (e.g. "main") */
    48     57     sqlite3_session **ppSession     /* OUT: New session object */
    49     58   );
    50     59   
    51     60   /*
           61  +** CAPI3REF: Delete A Session Object
           62  +**
    52     63   ** Delete a session object previously allocated using 
    53     64   ** [sqlite3session_create()]. Once a session object has been deleted, the
    54     65   ** results of attempting to use pSession with any other session module
    55     66   ** function are undefined.
    56     67   **
    57     68   ** Session objects must be deleted before the database handle to which they
    58     69   ** are attached is closed. Refer to the documentation for 
    59     70   ** [sqlite3session_create()] for details.
    60     71   */
    61     72   void sqlite3session_delete(sqlite3_session *pSession);
    62     73   
    63     74   /*
           75  +** CAPI3REF: Enable Or Disable A Session Object
           76  +**
    64     77   ** Enable or disable the recording of changes by a session object. When
    65     78   ** enabled, a session object records changes made to the database. When
    66     79   ** disabled - it does not. A newly created session object is enabled.
    67     80   ** Refer to the documentation for [sqlite3session_changeset()] for further
    68     81   ** details regarding how enabling and disabling a session object affects
    69     82   ** the eventual changesets.
    70     83   **
................................................................................
    74     87   **
    75     88   ** The return value indicates the final state of the session object: 0 if 
    76     89   ** the session is disabled, or 1 if it is enabled.
    77     90   */
    78     91   int sqlite3session_enable(sqlite3_session *pSession, int bEnable);
    79     92   
    80     93   /*
           94  +** CAPI3REF: Attach a Table to a Session Object
           95  +**
    81     96   ** Attach a table to a session. All subsequent changes made to the table
    82     97   ** while the session object is enabled will be recorded. See documentation
    83     98   ** for [sqlite3session_changeset()] for further details.
    84     99   **
    85    100   ** Changes can only be recorded for tables that have a PRIMARY KEY explicitly
    86    101   ** defined as part of their CREATE TABLE statement. It does not matter if the 
    87    102   ** PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY
................................................................................
    97    112   */
    98    113   int sqlite3session_attach(
    99    114     sqlite3_session *pSession,      /* Session object */
   100    115     const char *zTab                /* Table name */
   101    116   );
   102    117   
   103    118   /*
          119  +** CAPI3REF: Generate A Changeset From A Session Object
          120  +**
   104    121   ** Obtain a changeset containing changes to the tables attached to the 
   105    122   ** session object passed as the first argument. If successful, 
   106    123   ** set *ppChangeset to point to a buffer containing the changeset 
   107    124   ** and *pnChangeset to the size of the changeset in bytes before returning
   108    125   ** SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to
   109    126   ** zero and return an SQLite error code.
   110    127   **
................................................................................
   116    133   ** database row along with the updated values for each updated non-primary-key
   117    134   ** column. It is not possible for an UPDATE change to represent a change that
   118    135   ** modifies the values of primary key columns. If such a change is made, it
   119    136   ** is represented in a changeset as a DELETE followed by an INSERT.
   120    137   **
   121    138   ** The contents of a changeset may be traversed using an iterator created
   122    139   ** using the [sqlite3changeset_start()] API. A changeset may be applied to
   123         -** a database with a compatible schema using the [sqlite3changset_apply()]
          140  +** a database with a compatible schema using the [sqlite3changeset_apply()]
   124    141   ** API.
   125    142   **
   126    143   ** Following a successful call to this function, it is the responsibility of
   127    144   ** the caller to eventually free the buffer that *ppChangeset points to using
   128    145   ** [sqlite3_free()].
   129    146   **
   130         -** <h2>Changeset Generation</h2>
          147  +** <h3>Changeset Generation</h3>
   131    148   **
   132    149   ** Once a table has been attached to a session object, the session object
   133    150   ** records the primary key values of all new rows inserted into the table.
   134    151   ** It also records the original primary key and other column values of any
   135    152   ** deleted or updated rows. For each unique primary key value, data is only
   136    153   ** recorded once - the first time a row with said primary key is inserted,
   137    154   ** updated or deleted in the lifetime of the session.
................................................................................
   183    200   int sqlite3session_changeset(
   184    201     sqlite3_session *pSession,      /* Session object */
   185    202     int *pnChangeset,               /* OUT: Size of buffer at *ppChangeset */
   186    203     void **ppChangeset              /* OUT: Buffer containing changeset */
   187    204   );
   188    205   
   189    206   /*
          207  +** CAPI3REF: Create An Iterator To Traverse A Changeset 
          208  +**
   190    209   ** Create an iterator used to iterate through the contents of a changeset.
   191    210   ** If successful, *pp is set to point to the iterator handle and SQLITE_OK
   192    211   ** is returned. Otherwise, if an error occurs, *pp is set to zero and an
   193    212   ** SQLite error code is returned.
   194    213   **
   195    214   ** The following functions can be used to advance and query a changeset 
   196    215   ** iterator created by this function:
................................................................................
   210    229   int sqlite3changeset_start(
   211    230     sqlite3_changeset_iter **pp,    /* OUT: New changeset iterator handle */
   212    231     int nChangeset,                 /* Size of changeset blob in bytes */
   213    232     void *pChangeset                /* Pointer to blob containing changeset */
   214    233   );
   215    234   
   216    235   /*
          236  +** CAPI3REF: Advance A Changeset Iterator
          237  +**
   217    238   ** This function may only be used with iterators created by function
   218    239   ** [sqlite3changeset_start()]. If it is called on an iterator passed to
   219    240   ** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE
   220    241   ** is returned and the call has no effect.
   221    242   **
   222    243   ** Immediately after an iterator is created by sqlite3changeset_start(), it
   223    244   ** does not point to any change in the changeset. Assuming the changeset
................................................................................
   232    253   ** If an error occurs, an SQLite error code is returned. Possible error 
   233    254   ** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or 
   234    255   ** SQLITE_NOMEM.
   235    256   */
   236    257   int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
   237    258   
   238    259   /*
          260  +** CAPI3REF: Obtain The Current Operation From A Changeset Iterator
          261  +**
   239    262   ** The pIter argument passed to this function may either be an iterator
   240    263   ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
   241    264   ** created by [sqlite3changeset_start()]. In the latter case, the most recent
   242    265   ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW. If this
   243    266   ** is not the case, this function returns SQLITE_MISUSE.
   244    267   **
   245    268   ** If argument pzTab is not NULL, then *pzTab is set to point to a
................................................................................
   260    283     sqlite3_changeset_iter *pIter,  /* Iterator object */
   261    284     const char **pzTab,             /* OUT: Pointer to table name */
   262    285     int *pnCol,                     /* OUT: Number of columns in table */
   263    286     int *pOp                        /* OUT: SQLITE_INSERT, DELETE or UPDATE */
   264    287   );
   265    288   
   266    289   /*
          290  +** CAPI3REF: Obtain old.* Values From A Changeset Iterator
          291  +**
   267    292   ** The pIter argument passed to this function may either be an iterator
   268    293   ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
   269    294   ** created by [sqlite3changeset_start()]. In the latter case, the most recent
   270    295   ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW. 
   271    296   ** Furthermore, it may only be called if the type of change that the iterator
   272    297   ** currently points to is either SQLITE_DELETE or SQLITE_UPDATE. Otherwise,
   273    298   ** this function returns SQLITE_MISUSE and sets *ppValue to NULL.
................................................................................
   288    313   int sqlite3changeset_old(
   289    314     sqlite3_changeset_iter *pIter,  /* Changeset iterator */
   290    315     int iVal,                       /* Column number */
   291    316     sqlite3_value **ppValue         /* OUT: Old value (or NULL pointer) */
   292    317   );
   293    318   
   294    319   /*
          320  +** CAPI3REF: Obtain new.* Values From A Changeset Iterator
          321  +**
   295    322   ** The pIter argument passed to this function may either be an iterator
   296    323   ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
   297    324   ** created by [sqlite3changeset_start()]. In the latter case, the most recent
   298    325   ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW. 
   299    326   ** Furthermore, it may only be called if the type of change that the iterator
   300    327   ** currently points to is either SQLITE_UPDATE or SQLITE_INSERT. Otherwise,
   301    328   ** this function returns SQLITE_MISUSE and sets *ppValue to NULL.
................................................................................
   319    346   int sqlite3changeset_new(
   320    347     sqlite3_changeset_iter *pIter,  /* Changeset iterator */
   321    348     int iVal,                       /* Column number */
   322    349     sqlite3_value **ppValue         /* OUT: New value (or NULL pointer) */
   323    350   );
   324    351   
   325    352   /*
          353  +** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator
          354  +**
   326    355   ** This function should only be used with iterator objects passed to a
   327    356   ** conflict-handler callback by [sqlite3changeset_apply()] with either
   328    357   ** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this function
   329    358   ** is called on any other iterator, SQLITE_MISUSE is returned and *ppValue
   330    359   ** is set to NULL.
   331    360   **
   332    361   ** Argument iVal must be greater than or equal to 0, and less than the number
................................................................................
   345    374     sqlite3_changeset_iter *pIter,  /* Changeset iterator */
   346    375     int iVal,                       /* Column number */
   347    376     sqlite3_value **ppValue         /* OUT: Value from conflicting row */
   348    377   );
   349    378   
   350    379   
   351    380   /*
   352         -** Finalize an iterator allocated with sqlite3changeset_start().
          381  +** CAPI3REF: Finalize a Changeset Iterator
          382  +**
          383  +** This function is used to finalize an iterator allocated with
          384  +** sqlite3changeset_start().
   353    385   **
   354    386   ** This function should only be called on iterators created using the
   355    387   ** [sqlite3changeset_start()] function. If an application calls this
   356    388   ** function with an iterator passed to a conflict-handler by
   357    389   ** [sqlite3changeset_apply()], SQLITE_MISUSE is immediately returned and the
   358    390   ** call has no effect.
   359    391   **
................................................................................
   371    403   **   if( rc!=SQLITE_OK ){
   372    404   **     // An error has occurred 
   373    405   **   }
   374    406   */
   375    407   int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);
   376    408   
   377    409   /*
          410  +** CAPI3REF: Invert A Changeset
          411  +**
   378    412   ** This function is used to "invert" a changeset object. Applying an inverted
   379    413   ** changeset to a database reverses the effects of applying the uninverted
   380    414   ** changeset. Specifically:
   381    415   **
   382    416   ** <ul>
   383    417   **   <li> Each DELETE change is changed to an INSERT, and
   384    418   **   <li> Each INSERT change is changed to a DELETE, and
................................................................................
   396    430   */
   397    431   int sqlite3changeset_invert(
   398    432     int nIn, void *pIn,             /* Input changeset */
   399    433     int *pnOut, void **ppOut        /* OUT: Inverse of input */
   400    434   );
   401    435   
   402    436   /*
          437  +** CAPI3REF: Apply A Changeset To A Database
          438  +**
   403    439   ** Apply a changeset to a database. This function attempts to update the
   404    440   ** "main" database attached to handle db with the changes found in the
   405    441   ** changeset passed via the second and third arguments.
   406    442   **
   407    443   ** For each change in the changeset, this function tests that the target
   408    444   ** database contains a compatible table. A table is considered compatible
   409    445   ** if all of the following are true:
................................................................................
   478    514   **   violation (e.g. NOT NULL or UNIQUE), the conflict handler function is 
   479    515   **   invoked with the second argument set to [SQLITE_CHANGESET_CONSTRAINT].
   480    516   **   This includes the case where the INSERT operation is re-attempted because 
   481    517   **   an earlier call to the conflict handler function returned 
   482    518   **   [SQLITE_CHANGESET_REPLACE].
   483    519   **
   484    520   ** <dt>UPDATE Changes<dd>
   485         -**   For each DELETE change, this function checks if the target database 
          521  +**   For each UPDATE change, this function checks if the target database 
   486    522   **   contains a row with the same primary key value (or values) as the 
   487    523   **   original row values stored in the changeset. If it does, and the values 
   488    524   **   stored in all non-primary key columns also match the values stored in 
   489    525   **   the changeset the row is updated within the target database.
   490    526   **
   491    527   **   If a row with matching primary key values is found, but one or more of
   492    528   **   the non-primary key fields contains a value different from an original
................................................................................
   528    564       int eConflict,                /* DATA, MISSING, CONFLICT, CONSTRAINT */
   529    565       sqlite3_changeset_iter *p     /* Handle describing change and conflict */
   530    566     ),
   531    567     void *pCtx                      /* First argument passed to xConflict */
   532    568   );
   533    569   
   534    570   /* 
          571  +** CAPI3REF: Constants Passed to The Conflict Handler
          572  +**
   535    573   ** Values that may be passed as the second argument to a conflict-handler.
   536    574   **
   537    575   ** <dl>
   538    576   ** <dt>SQLITE_CHANGESET_DATA<dd>
   539    577   **   The conflict handler is invoked with CHANGESET_DATA as the second argument
   540    578   **   when processing a DELETE or UPDATE change if a row with the required
   541    579   **   PRIMARY KEY fields is present in the database, but one or more other 
................................................................................
   572    610   */
   573    611   #define SQLITE_CHANGESET_DATA       1
   574    612   #define SQLITE_CHANGESET_NOTFOUND   2
   575    613   #define SQLITE_CHANGESET_CONFLICT   3
   576    614   #define SQLITE_CHANGESET_CONSTRAINT 4
   577    615   
   578    616   /* 
   579         -** Valid return values from a conflict-handler.
          617  +** CAPI3REF: Constants Returned By The Conflict Handler
          618  +**
          619  +** A conflict handler callback must return one of the following three values.
   580    620   **
   581    621   ** <dl>
   582    622   ** <dt>SQLITE_CHANGESET_OMIT<dd>
   583    623   **   If a conflict handler returns this value no special action is taken. The
   584    624   **   change that caused the conflict is not applied. The session module 
   585    625   **   continues to the next change in the changeset.
   586    626   **