/ Check-in [e73e9082]
Login

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

Overview
Comment:Update comments in sqlite3session.h. More to come.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | sessions
Files: files | file ages | folders
SHA1: e73e9082f3b14088752717193a10dd7657deb8af
User & Date: dan 2011-03-18 13:05:15
Context
2011-03-18
15:13
Fix a memory allocation issues in the preupdate hook so that the hook.test script runs clean in valgrind. check-in: bd94f4c8 user: drh tags: sessions
13:05
Update comments in sqlite3session.h. More to come. check-in: e73e9082 user: dan tags: sessions
12:35
Merge all the latest trunk enhancements into the sessions branch. check-in: 94fd5bb6 user: drh tags: sessions
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to ext/session/sqlite3session.h.

    14     14   typedef struct sqlite3_session sqlite3_session;
    15     15   typedef struct sqlite3_changeset_iter sqlite3_changeset_iter;
    16     16   
    17     17   /*
    18     18   ** Create a new session object attached to database handle db. If successful,
    19     19   ** a pointer to the new object is written to *ppSession and SQLITE_OK is
    20     20   ** returned. If an error occurs, *ppSession is set to NULL and an SQLite
    21         -** error code (e.g. [SQLITE_NOMEM]) is returned.
           21  +** error code (e.g. SQLITE_NOMEM) is returned.
    22     22   **
    23     23   ** It is possible to create multiple session objects attached to a single
    24     24   ** database handle.
    25     25   **
    26     26   ** Session objects created using this function should be deleted using the
    27     27   ** [sqlite3session_delete()] function before the database handle that they
    28     28   ** are attached to is itself closed. If the database handle is closed before
................................................................................
    60     60   */
    61     61   void sqlite3session_delete(sqlite3_session *pSession);
    62     62   
    63     63   /*
    64     64   ** Enable or disable the recording of changes by a session object. When
    65     65   ** enabled, a session object records changes made to the database. When
    66     66   ** disabled - it does not. A newly created session object is enabled.
           67  +** Refer to the documentation for [sqlite3session_changeset()] for further
           68  +** details regarding how enabling and disabling a session object affects
           69  +** the eventual changesets.
    67     70   **
    68     71   ** Passing zero to this function disables the session. Passing a value
    69     72   ** greater than zero enables it. Passing a value less than zero is a 
    70     73   ** no-op, and may be used to query the current state of the session.
    71     74   **
    72     75   ** The return value indicates the final state of the session object: 0 if 
    73     76   ** the session is disabled, or 1 if it is enabled.
    74     77   */
    75     78   int sqlite3session_enable(sqlite3_session *pSession, int bEnable);
    76     79   
    77     80   /*
    78     81   ** Attach a table to a session. All subsequent changes made to the table
    79         -** while the session object is enabled will be recorded.
           82  +** while the session object is enabled will be recorded. See documentation
           83  +** for [sqlite3session_changeset()] for further details.
    80     84   **
    81         -** Only tables that have a PRIMARY KEY defined may be attached. It does
    82         -** not matter if the PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias)
    83         -** or not.
           85  +** Changes can only be recorded for tables that have a PRIMARY KEY explicitly
           86  +** defined as part of their CREATE TABLE statement. It does not matter if the 
           87  +** PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY
           88  +** KEY may consist of a single column, or may be a composite key.
           89  +** 
           90  +** It is not an error if the named table does not exist in the database. Nor
           91  +** is it an error if the named table does not have a PRIMARY KEY. However,
           92  +** no changes will be recorded in either of these scenarios.
           93  +**
           94  +** SQLITE_OK is returned if the table is successfully attached to the session
           95  +** object. Or, if an error occurs, an SQLite error code (e.g. SQLITE_NOMEM)
           96  +** is returned.
    84     97   */
    85     98   int sqlite3session_attach(
    86     99     sqlite3_session *pSession,      /* Session object */
    87    100     const char *zTab                /* Table name */
    88    101   );
    89    102   
    90    103   /*
    91    104   ** Obtain a changeset containing changes to the tables attached to the 
    92    105   ** session object passed as the first argument. If successful, 
    93    106   ** set *ppChangeset to point to a buffer containing the changeset 
    94    107   ** and *pnChangeset to the size of the changeset in bytes before returning
    95    108   ** SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to
    96    109   ** zero and return an SQLite error code.
          110  +**
          111  +** A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes,
          112  +** each representing a change to a single row of an attached table. An INSERT
          113  +** change contains the values of each field of a new database row. A DELETE
          114  +** contains the original values of each field of a deleted database row. An
          115  +** UPDATE change contains the original values of each field of an updated
          116  +** database row along with the updated values for each updated non-primary-key
          117  +** column. It is not possible for an UPDATE change to represent a change that
          118  +** modifies the values of primary key columns. If such a change is made, it
          119  +** is represented in a changeset as a DELETE followed by an INSERT.
          120  +**
          121  +** The contents of a changeset may be traversed using an iterator created
          122  +** using the [sqlite3changeset_start()] API. A changeset may be applied to
          123  +** a database with a compatible schema using the [sqlite3changset_apply()]
          124  +** API.
    97    125   **
    98    126   ** Following a successful call to this function, it is the responsibility of
    99    127   ** the caller to eventually free the buffer that *ppChangeset points to using
   100    128   ** [sqlite3_free()].
          129  +**
          130  +** <h2>Changeset Generation</h2>
          131  +**
          132  +** Once a table has been attached to a session object, the session object
          133  +** records the primary key values of all new rows inserted into the table.
          134  +** It also records the original primary key and other column values of any
          135  +** deleted or updated rows. For each unique primary key value, data is only
          136  +** recorded once - the first time a row with said primary key is inserted,
          137  +** updated or deleted in the lifetime of the session.
          138  +**
          139  +** The session object therefore accumulates two types of records - those
          140  +** that consist of primary key values only (created when the user inserts
          141  +** a new record) and those that consist of the primary key values and the
          142  +** original values of other table columns (created when the users deletes
          143  +** or updates a record).
          144  +**
          145  +** When this function is called, the requested changeset is created using
          146  +** both the accumulated records and the current contents of the database
          147  +** file. Specifically:
          148  +**
          149  +** <ul>
          150  +**   <li> For each record generated by an insert, the database is queried
          151  +**        for a row with a matching primary key. If one is found, an INSERT
          152  +**        change is added to the changeset. If no such row is found, no change 
          153  +**        is added to the changeset.
          154  +**
          155  +**   <li> For each record generated by an update or delete, the database is 
          156  +**        queried for a row with a matching primary key. If such a row is
          157  +**        found and one or more of the non-primary key fields have been
          158  +**        modified from their original values, an UPDATE change is added to 
          159  +**        the changeset. Or, if no such row is found in the table, a DELETE 
          160  +**        change is added to the changeset. If there is a row with a matching
          161  +**        primary key in the database, but all fields contain their original
          162  +**        values, no change is added to the changeset.
          163  +** </ul>
          164  +**
          165  +** This means, amongst other things, that if a row is inserted and then later
          166  +** deleted while a session object is active, neither the insert or the delete
          167  +** will be present in the changeset. Or if a row is deleted and then later a 
          168  +** row with the same primary key values inserted while a session object is
          169  +** active, the resulting changeset will contain an UPDATE change instead of
          170  +** a DELETE and an INSERT.
          171  +**
          172  +** When a session object is disabled (see the [sqlite3session_enable()] API),
          173  +** it does not accumulate records when rows are inserted, updated or deleted.
          174  +** This may appear to have some counter-intuitive effects if a single row
          175  +** is written to more than once during a session. For example, if a row
          176  +** is inserted while a session object is enabled, then later deleted while 
          177  +** the same session object is disabled, no INSERT record will appear in the
          178  +** changeset, even though the delete took place while the session was disabled.
          179  +** Or, if one field of a row is updated while a session is disabled, and 
          180  +** another field of the same row is updated while the session is enabled, the
          181  +** resulting changeset will contain an UPDATE change that updates both fields.
   101    182   */
   102    183   int sqlite3session_changeset(
   103    184     sqlite3_session *pSession,      /* Session object */
   104    185     int *pnChangeset,               /* OUT: Size of buffer at *ppChangeset */
   105    186     void **ppChangeset              /* OUT: Buffer containing changeset */
   106    187   );
   107    188   
   108    189   /*
   109    190   ** Create an iterator used to iterate through the contents of a changeset.
          191  +** If successful, *pp is set to point to the iterator handle and SQLITE_OK
          192  +** is returned. Otherwise, if an error occurs, *pp is set to zero and an
          193  +** SQLite error code is returned.
          194  +**
          195  +** The following functions can be used to advance and query a changeset 
          196  +** iterator created by this function:
          197  +**
          198  +** <ul>
          199  +**   <li> [sqlite3changeset_next()]
          200  +**   <li> [sqlite3changeset_op()]
          201  +**   <li> [sqlite3changeset_new()]
          202  +**   <li> [sqlite3changeset_old()]
          203  +** </ul>
          204  +**
          205  +** It is the responsibility of the caller to eventually destroy the iterator
          206  +** by passing it to [sqlite3changeset_finalize()]. The buffer containing the
          207  +** changeset (pChangeset) must remain valid until after the iterator is
          208  +** destroyed.
   110    209   */
   111    210   int sqlite3changeset_start(
   112         -  sqlite3_changeset_iter **ppIter,
   113         -  int nChangeset, 
   114         -  void *pChangeset
          211  +  sqlite3_changeset_iter **pp,    /* OUT: New changeset iterator handle */
          212  +  int nChangeset,                 /* Size of changeset blob in bytes */
          213  +  void *pChangeset                /* Pointer to blob containing changeset */
   115    214   );
   116    215   
   117    216   /*
   118         -** Advance an iterator created by sqlite3changeset_start() to the next
   119         -** change in the changeset. This function may return SQLITE_ROW, SQLITE_DONE
   120         -** or SQLITE_CORRUPT.
          217  +** This function may only be used with iterators created by function
          218  +** [sqlite3changeset_start()]. If it is called on an iterator passed to
          219  +** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE
          220  +** is returned and the call has no effect.
   121    221   **
   122         -** This function may not be called on iterators passed to a conflict handler
   123         -** callback by changeset_apply().
          222  +** Immediately after an iterator is created by sqlite3changeset_start(), it
          223  +** does not point to any change in the changeset. Assuming the changeset
          224  +** is not empty, the first call to this function advances the iterator to
          225  +** point to the first change in the changeset. Each subsequent call advances
          226  +** the iterator to point to the next change in the changeset (if any). If
          227  +** no error occurs and the iterator points to a valid change after a call
          228  +** to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned. 
          229  +** Otherwise, if all changes in the changeset have already been visited,
          230  +** SQLITE_DONE is returned.
          231  +**
          232  +** If an error occurs, an SQLite error code is returned. Possible error 
          233  +** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or 
          234  +** SQLITE_NOMEM.
   124    235   */
   125    236   int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
   126    237   
   127    238   /*
   128         -** The following three functions extract information on the current change
   129         -** from a changeset iterator. They may only be called after changeset_next()
   130         -** has returned SQLITE_ROW.
          239  +** The pIter argument passed to this function may either be an iterator
          240  +** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
          241  +** created by [sqlite3changeset_start()]. In the latter case, the most recent
          242  +** call to [sqlite3changeset_next()] must have returned SQLITE_ROW. If this
          243  +** is not the case, this function returns SQLITE_MISUSE.
          244  +**
          245  +** If argument pzTab is not NULL, then *pzTab is set to point to a
          246  +** nul-terminated utf-8 encoded string containing the name of the table
          247  +** affected by the current change. The buffer remains valid until either
          248  +** sqlite3changeset_next() is called on the iterator or until the 
          249  +** conflict-handler function returns. If pnCol is not NULL, then *pnCol is 
          250  +** set to the number of columns in the table affected by the change. Finally,
          251  +** if pOp is not NULL, then *pOp is set to one of SQLITE_INSERT, SQLITE_DELETE
          252  +** or SQLITE_UPDATE, depending on the type of change that the iterator
          253  +** currently points to.
          254  +**
          255  +** If no error occurs, SQLITE_OK is returned. If an error does occur, an
          256  +** SQLite error code is returned. The values of the output variables may not
          257  +** be trusted in this case.
   131    258   */
   132    259   int sqlite3changeset_op(
   133    260     sqlite3_changeset_iter *pIter,  /* Iterator object */
   134    261     const char **pzTab,             /* OUT: Pointer to table name */
   135    262     int *pnCol,                     /* OUT: Number of columns in table */
   136    263     int *pOp                        /* OUT: SQLITE_INSERT, DELETE or UPDATE */
   137    264   );
          265  +
          266  +/*
          267  +** The pIter argument passed to this function may either be an iterator
          268  +** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
          269  +** created by [sqlite3changeset_start()]. In the latter case, the most recent
          270  +** call to [sqlite3changeset_next()] must have returned SQLITE_ROW. 
          271  +** Furthermore, it may only be called if the type of change that the iterator
          272  +** currently points to is either SQLITE_DELETE or SQLITE_UPDATE. Otherwise,
          273  +** this function returns SQLITE_MISUSE and sets *ppValue to NULL.
          274  +**
          275  +** Argument iVal must be greater than or equal to 0, and less than the number
          276  +** of columns in the table affected by the current change. Otherwise,
          277  +** SQLITE_RANGE is returned and *ppValue is set to NULL.
          278  +**
          279  +** If successful, this function sets *ppValue to point to a protected
          280  +** sqlite3_value object containing the iVal'th value from the vector of 
          281  +** original row values stored as part of the UPDATE or DELETE change and
          282  +** returns SQLITE_OK. The name of the function comes from the fact that this 
          283  +** is similar to the "old.*" columns available to update or delete triggers.
          284  +**
          285  +** If some other error occurs (e.g. an OOM condition), an SQLite error code
          286  +** is returned and *ppValue is set to NULL.
          287  +*/
   138    288   int sqlite3changeset_old(
   139    289     sqlite3_changeset_iter *pIter,  /* Changeset iterator */
   140    290     int iVal,                       /* Column number */
   141    291     sqlite3_value **ppValue         /* OUT: Old value (or NULL pointer) */
   142    292   );
          293  +
          294  +/*
          295  +** The pIter argument passed to this function may either be an iterator
          296  +** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
          297  +** created by [sqlite3changeset_start()]. In the latter case, the most recent
          298  +** call to [sqlite3changeset_next()] must have returned SQLITE_ROW. 
          299  +** Furthermore, it may only be called if the type of change that the iterator
          300  +** currently points to is either SQLITE_UPDATE or SQLITE_INSERT. Otherwise,
          301  +** this function returns SQLITE_MISUSE and sets *ppValue to NULL.
          302  +**
          303  +** Argument iVal must be greater than or equal to 0, and less than the number
          304  +** of columns in the table affected by the current change. Otherwise,
          305  +** SQLITE_RANGE is returned and *ppValue is set to NULL.
          306  +**
          307  +** If successful, this function sets *ppValue to point to a protected
          308  +** sqlite3_value object containing the iVal'th value from the vector of 
          309  +** new row values stored as part of the UPDATE or INSERT change and
          310  +** returns SQLITE_OK. If the change is an UPDATE and does not include
          311  +** a new value for the requested column, *ppValue is set to NULL and 
          312  +** SQLITE_OK returned. The name of the function comes from the fact that 
          313  +** this is similar to the "new.*" columns available to update or delete 
          314  +** triggers.
          315  +**
          316  +** If some other error occurs (e.g. an OOM condition), an SQLite error code
          317  +** is returned and *ppValue is set to NULL.
          318  +*/
   143    319   int sqlite3changeset_new(
   144    320     sqlite3_changeset_iter *pIter,  /* Changeset iterator */
   145    321     int iVal,                       /* Column number */
   146    322     sqlite3_value **ppValue         /* OUT: New value (or NULL pointer) */
   147    323   );
   148    324   
   149    325   /*
   150         -** This function is only usable with sqlite3_changeset_iter objects passed
   151         -** to the xConflict callback by sqlite3changeset_apply(). It cannot be used
   152         -** with iterators created using sqlite3changeset_start().
          326  +** This function should only be used with iterator objects passed to a
          327  +** conflict-handler callback by [sqlite3changeset_apply()] with either
          328  +** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this function
          329  +** is called on any other iterator, SQLITE_MISUSE is returned and *ppValue
          330  +** is set to NULL.
          331  +**
          332  +** Argument iVal must be greater than or equal to 0, and less than the number
          333  +** of columns in the table affected by the current change. Otherwise,
          334  +** SQLITE_RANGE is returned and *ppValue is set to NULL.
          335  +**
          336  +** If successful, this function sets *ppValue to point to a protected
          337  +** sqlite3_value object containing the iVal'th value from the 
          338  +** "conflicting row" associated with the current conflict-handler callback
          339  +** and returns SQLITE_OK.
   153    340   **
   154         -** It is used to access the "conflicting row" information available to the
   155         -** conflict handler if the second argument is either SQLITE_CHANGESET_DATA
   156         -** or SQLITE_CHANGESET_CONFLICT.
          341  +** If some other error occurs (e.g. an OOM condition), an SQLite error code
          342  +** is returned and *ppValue is set to NULL.
   157    343   */
   158    344   int sqlite3changeset_conflict(
   159    345     sqlite3_changeset_iter *pIter,  /* Changeset iterator */
   160    346     int iVal,                       /* Column number */
   161    347     sqlite3_value **ppValue         /* OUT: Value from conflicting row */
   162    348   );
   163    349   
   164    350   
   165    351   /*
   166    352   ** Finalize an iterator allocated with sqlite3changeset_start().
   167    353   **
   168         -** This function may not be called on iterators passed to a conflict handler
   169         -** callback by changeset_apply().
          354  +** This function should only be called on iterators created using the
          355  +** [sqlite3changeset_start()] function. If an application calls this
          356  +** function with an iterator passed to a conflict-handler by
          357  +** [sqlite3changeset_apply()], SQLITE_MISUSE is immediately returned and the
          358  +** call has no effect.
          359  +**
          360  +** If an error was encountered within a call to an sqlite3changeset_xxx()
          361  +** function (for example an SQLITE_CORRUPT in sqlite3changeset_next() or an 
          362  +** SQLITE_NOMEM in sqlite3changeset_new()) then an error code corresponding
          363  +** to that error is returned by this function. Otherwise, SQLITE_OK is
          364  +** returned. This is to allow the following pattern (pseudo-code):
          365  +**
          366  +**   sqlite3changeset_start();
          367  +**   while( SQLITE_ROW==sqlite3changeset_next() ){
          368  +**     // Do something with change.
          369  +**   }
          370  +**   rc = sqlite3changeset_finalize();
          371  +**   if( rc!=SQLITE_OK ){
          372  +**     // An error has occurred 
          373  +**   }
   170    374   */
   171    375   int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);
   172    376   
   173    377   /*
   174    378   ** Invert a changeset object.
   175    379   */
   176    380   int sqlite3changeset_invert(

install-sh became a regular file.


test/progress.test became executable.


tool/mkopts.tcl became executable.