/ Check-in [e0117775]
Login

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

Overview
Comment:Enhance the sessions documentation to show the methods of the various objects.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: e01177754ad6d9e2d38adddddd2e2e212094dac1154bda5fcee61ca8b678ae0f
User & Date: drh 2018-02-28 22:21:29
Context
2018-03-01
12:05
Fix some crashes in the sqlite3changeset_apply() function that could be caused by corrupt changeset blobs. check-in: 745a9a7f user: dan tags: trunk
2018-02-28
22:21
Enhance the sessions documentation to show the methods of the various objects. check-in: e0117775 user: drh tags: trunk
21:50
Use <pre> around code snippets in the documentation for sessions interfaces. This is a documentation change only with no changes to code. check-in: c949b915 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to ext/session/sqlite3session.h.

     9      9   extern "C" {
    10     10   #endif
    11     11   
    12     12   #include "sqlite3.h"
    13     13   
    14     14   /*
    15     15   ** CAPI3REF: Session Object Handle
           16  +**
           17  +** An instance of this object is a [session] that can be used to
           18  +** record changes to a database.
    16     19   */
    17     20   typedef struct sqlite3_session sqlite3_session;
    18     21   
    19     22   /*
    20     23   ** CAPI3REF: Changeset Iterator Handle
           24  +**
           25  +** An instance of this object is as as a cursor for iterating
           26  +** over the elements of a [changeset] or [patchset].
    21     27   */
    22     28   typedef struct sqlite3_changeset_iter sqlite3_changeset_iter;
    23     29   
    24     30   /*
    25     31   ** CAPI3REF: Create A New Session Object
           32  +** CONSTRUCTOR: sqlite3_session
    26     33   **
    27     34   ** Create a new session object attached to database handle db. If successful,
    28     35   ** a pointer to the new object is written to *ppSession and SQLITE_OK is
    29     36   ** returned. If an error occurs, *ppSession is set to NULL and an SQLite
    30     37   ** error code (e.g. SQLITE_NOMEM) is returned.
    31     38   **
    32     39   ** It is possible to create multiple session objects attached to a single
................................................................................
    55     62     sqlite3 *db,                    /* Database handle */
    56     63     const char *zDb,                /* Name of db (e.g. "main") */
    57     64     sqlite3_session **ppSession     /* OUT: New session object */
    58     65   );
    59     66   
    60     67   /*
    61     68   ** CAPI3REF: Delete A Session Object
           69  +** DESTRUCTOR: sqlite3_session
    62     70   **
    63     71   ** Delete a session object previously allocated using 
    64     72   ** [sqlite3session_create()]. Once a session object has been deleted, the
    65     73   ** results of attempting to use pSession with any other session module
    66     74   ** function are undefined.
    67     75   **
    68     76   ** Session objects must be deleted before the database handle to which they
................................................................................
    70     78   ** [sqlite3session_create()] for details.
    71     79   */
    72     80   void sqlite3session_delete(sqlite3_session *pSession);
    73     81   
    74     82   
    75     83   /*
    76     84   ** CAPI3REF: Enable Or Disable A Session Object
           85  +** METHOD: sqlite3_session
    77     86   **
    78     87   ** Enable or disable the recording of changes by a session object. When
    79     88   ** enabled, a session object records changes made to the database. When
    80     89   ** disabled - it does not. A newly created session object is enabled.
    81     90   ** Refer to the documentation for [sqlite3session_changeset()] for further
    82     91   ** details regarding how enabling and disabling a session object affects
    83     92   ** the eventual changesets.
................................................................................
    89     98   ** The return value indicates the final state of the session object: 0 if 
    90     99   ** the session is disabled, or 1 if it is enabled.
    91    100   */
    92    101   int sqlite3session_enable(sqlite3_session *pSession, int bEnable);
    93    102   
    94    103   /*
    95    104   ** CAPI3REF: Set Or Clear the Indirect Change Flag
          105  +** METHOD: sqlite3_session
    96    106   **
    97    107   ** Each change recorded by a session object is marked as either direct or
    98    108   ** indirect. A change is marked as indirect if either:
    99    109   **
   100    110   ** <ul>
   101    111   **   <li> The session object "indirect" flag is set when the change is
   102    112   **        made, or
................................................................................
   118    128   ** The return value indicates the final state of the indirect flag: 0 if 
   119    129   ** it is clear, or 1 if it is set.
   120    130   */
   121    131   int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect);
   122    132   
   123    133   /*
   124    134   ** CAPI3REF: Attach A Table To A Session Object
          135  +** METHOD: sqlite3_session
   125    136   **
   126    137   ** If argument zTab is not NULL, then it is the name of a table to attach
   127    138   ** to the session object passed as the first argument. All subsequent changes 
   128    139   ** made to the table while the session object is enabled will be recorded. See 
   129    140   ** documentation for [sqlite3session_changeset()] for further details.
   130    141   **
   131    142   ** Or, if argument zTab is NULL, then changes are recorded for all tables
................................................................................
   180    191   int sqlite3session_attach(
   181    192     sqlite3_session *pSession,      /* Session object */
   182    193     const char *zTab                /* Table name */
   183    194   );
   184    195   
   185    196   /*
   186    197   ** CAPI3REF: Set a table filter on a Session Object.
          198  +** METHOD: sqlite3_session
   187    199   **
   188    200   ** The second argument (xFilter) is the "filter callback". For changes to rows 
   189    201   ** in tables that are not attached to the Session object, the filter is called
   190    202   ** to determine whether changes to the table's rows should be tracked or not. 
   191    203   ** If xFilter returns 0, changes is not tracked. Note that once a table is 
   192    204   ** attached, xFilter will not be called again.
   193    205   */
................................................................................
   198    210       const char *zTab              /* Table name */
   199    211     ),
   200    212     void *pCtx                      /* First argument passed to xFilter */
   201    213   );
   202    214   
   203    215   /*
   204    216   ** CAPI3REF: Generate A Changeset From A Session Object
          217  +** METHOD: sqlite3_session
   205    218   **
   206    219   ** Obtain a changeset containing changes to the tables attached to the 
   207    220   ** session object passed as the first argument. If successful, 
   208    221   ** set *ppChangeset to point to a buffer containing the changeset 
   209    222   ** and *pnChangeset to the size of the changeset in bytes before returning
   210    223   ** SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to
   211    224   ** zero and return an SQLite error code.
................................................................................
   307    320   int sqlite3session_changeset(
   308    321     sqlite3_session *pSession,      /* Session object */
   309    322     int *pnChangeset,               /* OUT: Size of buffer at *ppChangeset */
   310    323     void **ppChangeset              /* OUT: Buffer containing changeset */
   311    324   );
   312    325   
   313    326   /*
   314         -** CAPI3REF: Load The Difference Between Tables Into A Session 
          327  +** CAPI3REF: Load The Difference Between Tables Into A Session
          328  +** METHOD: sqlite3_session
   315    329   **
   316    330   ** If it is not already attached to the session object passed as the first
   317    331   ** argument, this function attaches table zTbl in the same manner as the
   318    332   ** [sqlite3session_attach()] function. If zTbl does not exist, or if it
   319    333   ** does not have a primary key, this function is a no-op (but does not return
   320    334   ** an error).
   321    335   **
................................................................................
   372    386     const char *zTbl,
   373    387     char **pzErrMsg
   374    388   );
   375    389   
   376    390   
   377    391   /*
   378    392   ** CAPI3REF: Generate A Patchset From A Session Object
          393  +** METHOD: sqlite3_session
   379    394   **
   380    395   ** The differences between a patchset and a changeset are that:
   381    396   **
   382    397   ** <ul>
   383    398   **   <li> DELETE records consist of the primary key fields only. The 
   384    399   **        original values of other fields are omitted.
   385    400   **   <li> The original values of any modified fields are omitted from 
................................................................................
   423    438   ** guaranteed that a call to sqlite3session_changeset() will return a 
   424    439   ** changeset containing zero changes.
   425    440   */
   426    441   int sqlite3session_isempty(sqlite3_session *pSession);
   427    442   
   428    443   /*
   429    444   ** CAPI3REF: Create An Iterator To Traverse A Changeset 
          445  +** CONSTRUCTOR: sqlite3_changeset_iter
   430    446   **
   431    447   ** Create an iterator used to iterate through the contents of a changeset.
   432    448   ** If successful, *pp is set to point to the iterator handle and SQLITE_OK
   433    449   ** is returned. Otherwise, if an error occurs, *pp is set to zero and an
   434    450   ** SQLite error code is returned.
   435    451   **
   436    452   ** The following functions can be used to advance and query a changeset 
................................................................................
   463    479     int nChangeset,                 /* Size of changeset blob in bytes */
   464    480     void *pChangeset                /* Pointer to blob containing changeset */
   465    481   );
   466    482   
   467    483   
   468    484   /*
   469    485   ** CAPI3REF: Advance A Changeset Iterator
          486  +** METHOD: sqlite3_changeset_iter
   470    487   **
   471    488   ** This function may only be used with iterators created by function
   472    489   ** [sqlite3changeset_start()]. If it is called on an iterator passed to
   473    490   ** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE
   474    491   ** is returned and the call has no effect.
   475    492   **
   476    493   ** Immediately after an iterator is created by sqlite3changeset_start(), it
................................................................................
   487    504   ** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or 
   488    505   ** SQLITE_NOMEM.
   489    506   */
   490    507   int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
   491    508   
   492    509   /*
   493    510   ** CAPI3REF: Obtain The Current Operation From A Changeset Iterator
          511  +** METHOD: sqlite3_changeset_iter
   494    512   **
   495    513   ** The pIter argument passed to this function may either be an iterator
   496    514   ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
   497    515   ** created by [sqlite3changeset_start()]. In the latter case, the most recent
   498    516   ** call to [sqlite3changeset_next()] must have returned [SQLITE_ROW]. If this
   499    517   ** is not the case, this function returns [SQLITE_MISUSE].
   500    518   **
................................................................................
   521    539     int *pnCol,                     /* OUT: Number of columns in table */
   522    540     int *pOp,                       /* OUT: SQLITE_INSERT, DELETE or UPDATE */
   523    541     int *pbIndirect                 /* OUT: True for an 'indirect' change */
   524    542   );
   525    543   
   526    544   /*
   527    545   ** CAPI3REF: Obtain The Primary Key Definition Of A Table
          546  +** METHOD: sqlite3_changeset_iter
   528    547   **
   529    548   ** For each modified table, a changeset includes the following:
   530    549   **
   531    550   ** <ul>
   532    551   **   <li> The number of columns in the table, and
   533    552   **   <li> Which of those columns make up the tables PRIMARY KEY.
   534    553   ** </ul>
................................................................................
   552    571     sqlite3_changeset_iter *pIter,  /* Iterator object */
   553    572     unsigned char **pabPK,          /* OUT: Array of boolean - true for PK cols */
   554    573     int *pnCol                      /* OUT: Number of entries in output array */
   555    574   );
   556    575   
   557    576   /*
   558    577   ** CAPI3REF: Obtain old.* Values From A Changeset Iterator
          578  +** METHOD: sqlite3_changeset_iter
   559    579   **
   560    580   ** The pIter argument passed to this function may either be an iterator
   561    581   ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
   562    582   ** created by [sqlite3changeset_start()]. In the latter case, the most recent
   563    583   ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW. 
   564    584   ** Furthermore, it may only be called if the type of change that the iterator
   565    585   ** currently points to is either [SQLITE_DELETE] or [SQLITE_UPDATE]. Otherwise,
................................................................................
   582    602     sqlite3_changeset_iter *pIter,  /* Changeset iterator */
   583    603     int iVal,                       /* Column number */
   584    604     sqlite3_value **ppValue         /* OUT: Old value (or NULL pointer) */
   585    605   );
   586    606   
   587    607   /*
   588    608   ** CAPI3REF: Obtain new.* Values From A Changeset Iterator
          609  +** METHOD: sqlite3_changeset_iter
   589    610   **
   590    611   ** The pIter argument passed to this function may either be an iterator
   591    612   ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
   592    613   ** created by [sqlite3changeset_start()]. In the latter case, the most recent
   593    614   ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW. 
   594    615   ** Furthermore, it may only be called if the type of change that the iterator
   595    616   ** currently points to is either [SQLITE_UPDATE] or [SQLITE_INSERT]. Otherwise,
................................................................................
   615    636     sqlite3_changeset_iter *pIter,  /* Changeset iterator */
   616    637     int iVal,                       /* Column number */
   617    638     sqlite3_value **ppValue         /* OUT: New value (or NULL pointer) */
   618    639   );
   619    640   
   620    641   /*
   621    642   ** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator
          643  +** METHOD: sqlite3_changeset_iter
   622    644   **
   623    645   ** This function should only be used with iterator objects passed to a
   624    646   ** conflict-handler callback by [sqlite3changeset_apply()] with either
   625    647   ** [SQLITE_CHANGESET_DATA] or [SQLITE_CHANGESET_CONFLICT]. If this function
   626    648   ** is called on any other iterator, [SQLITE_MISUSE] is returned and *ppValue
   627    649   ** is set to NULL.
   628    650   **
................................................................................
   642    664     sqlite3_changeset_iter *pIter,  /* Changeset iterator */
   643    665     int iVal,                       /* Column number */
   644    666     sqlite3_value **ppValue         /* OUT: Value from conflicting row */
   645    667   );
   646    668   
   647    669   /*
   648    670   ** CAPI3REF: Determine The Number Of Foreign Key Constraint Violations
          671  +** METHOD: sqlite3_changeset_iter
   649    672   **
   650    673   ** This function may only be called with an iterator passed to an
   651    674   ** SQLITE_CHANGESET_FOREIGN_KEY conflict handler callback. In this case
   652    675   ** it sets the output variable to the total number of known foreign key
   653    676   ** violations in the destination database and returns SQLITE_OK.
   654    677   **
   655    678   ** In all other cases this function returns SQLITE_MISUSE.
................................................................................
   658    681     sqlite3_changeset_iter *pIter,  /* Changeset iterator */
   659    682     int *pnOut                      /* OUT: Number of FK violations */
   660    683   );
   661    684   
   662    685   
   663    686   /*
   664    687   ** CAPI3REF: Finalize A Changeset Iterator
          688  +** METHOD: sqlite3_changeset_iter
   665    689   **
   666    690   ** This function is used to finalize an iterator allocated with
   667    691   ** [sqlite3changeset_start()].
   668    692   **
   669    693   ** This function should only be called on iterators created using the
   670    694   ** [sqlite3changeset_start()] function. If an application calls this
   671    695   ** function with an iterator passed to a conflict-handler by
................................................................................
   758    782     int *pnOut,                     /* OUT: Number of bytes in output changeset */
   759    783     void **ppOut                    /* OUT: Buffer containing output changeset */
   760    784   );
   761    785   
   762    786   
   763    787   /*
   764    788   ** CAPI3REF: Changegroup Handle
          789  +**
          790  +** A changegroup is an object used to combine two or more 
          791  +** [changesets] or [patchsets]
   765    792   */
   766    793   typedef struct sqlite3_changegroup sqlite3_changegroup;
   767    794   
   768    795   /*
   769    796   ** CAPI3REF: Create A New Changegroup Object
          797  +** CONSTRUCTOR: sqlite3_changegroup
   770    798   **
   771    799   ** An sqlite3_changegroup object is used to combine two or more changesets
   772    800   ** (or patchsets) into a single changeset (or patchset). A single changegroup
   773    801   ** object may combine changesets or patchsets, but not both. The output is
   774    802   ** always in the same format as the input.
   775    803   **
   776    804   ** If successful, this function returns SQLITE_OK and populates (*pp) with
................................................................................
   800    828   ** sqlite3changegroup_output() functions, also available are the streaming
   801    829   ** versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm().
   802    830   */
   803    831   int sqlite3changegroup_new(sqlite3_changegroup **pp);
   804    832   
   805    833   /*
   806    834   ** CAPI3REF: Add A Changeset To A Changegroup
          835  +** METHOD: sqlite3_changegroup
   807    836   **
   808    837   ** Add all changes within the changeset (or patchset) in buffer pData (size
   809    838   ** nData bytes) to the changegroup. 
   810    839   **
   811    840   ** If the buffer contains a patchset, then all prior calls to this function
   812    841   ** on the same changegroup object must also have specified patchsets. Or, if
   813    842   ** the buffer contains a changeset, so must have the earlier calls to this
................................................................................
   877    906   **
   878    907   ** If no error occurs, SQLITE_OK is returned.
   879    908   */
   880    909   int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pData);
   881    910   
   882    911   /*
   883    912   ** CAPI3REF: Obtain A Composite Changeset From A Changegroup
          913  +** METHOD: sqlite3_changegroup
   884    914   **
   885    915   ** Obtain a buffer containing a changeset (or patchset) representing the
   886    916   ** current contents of the changegroup. If the inputs to the changegroup
   887    917   ** were themselves changesets, the output is a changeset. Or, if the
   888    918   ** inputs were patchsets, the output is also a patchset.
   889    919   **
   890    920   ** As with the output of the sqlite3session_changeset() and
................................................................................
   907    937     sqlite3_changegroup*,
   908    938     int *pnData,                    /* OUT: Size of output buffer in bytes */
   909    939     void **ppData                   /* OUT: Pointer to output buffer */
   910    940   );
   911    941   
   912    942   /*
   913    943   ** CAPI3REF: Delete A Changegroup Object
          944  +** DESTRUCTOR: sqlite3_changegroup
   914    945   */
   915    946   void sqlite3changegroup_delete(sqlite3_changegroup*);
   916    947   
   917    948   /*
   918    949   ** CAPI3REF: Apply A Changeset To A Database
   919    950   **
   920    951   ** Apply a changeset to a database. This function attempts to update the