/ Check-in [8180f288]
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

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

Overview
Comment:Add documentation to the sqlite3_preupdate_hook() interface and its relatives.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | sessions
Files: files | file ages | folders
SHA1: 8180f2881fa970429e28d4f3258a56cfaabbcabd
User & Date: drh 2011-03-30 17:07:47
Context
2011-03-30
17:25
Disable the truncate optimization if there is a preupdate hook. check-in: d051694e user: drh tags: sessions
17:07
Add documentation to the sqlite3_preupdate_hook() interface and its relatives. check-in: 8180f288 user: drh tags: sessions
02:03
Merge in all the latest changes from trunk. check-in: b11d941e user: drh tags: sessions
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

  1125   1125   **
  1126   1126   ** The sqlite3_db_config() interface is used to make configuration
  1127   1127   ** changes to a [database connection].  The interface is similar to
  1128   1128   ** [sqlite3_config()] except that the changes apply to a single
  1129   1129   ** [database connection] (specified in the first argument).
  1130   1130   **
  1131   1131   ** The second argument to sqlite3_db_config(D,V,...)  is the
  1132         -** [SQLITE_DBCONIG_LOOKASIDE | configuration verb] - an integer code 
         1132  +** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code 
  1133   1133   ** that indicates what aspect of the [database connection] is being configured.
  1134   1134   ** Subsequent arguments vary depending on the configuration verb.
  1135   1135   **
  1136   1136   ** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
  1137   1137   ** the call is considered successful.
  1138   1138   */
  1139   1139   int sqlite3_db_config(sqlite3*, int op, ...);
................................................................................
  4259   4259   ** database connections for the meaning of "modify" in this paragraph.
  4260   4260   **
  4261   4261   ** ^The sqlite3_update_hook(D,C,P) function
  4262   4262   ** returns the P argument from the previous call
  4263   4263   ** on the same [database connection] D, or NULL for
  4264   4264   ** the first call on D.
  4265   4265   **
  4266         -** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()]
  4267         -** interfaces.
         4266  +** See also the [sqlite3_commit_hook()], [sqlite3_rollback_hook()],
         4267  +** and [sqlite3_preupdate_hook()] interfaces.
  4268   4268   */
  4269   4269   void *sqlite3_update_hook(
  4270   4270     sqlite3*, 
  4271   4271     void(*)(void *,int ,char const *,char const *,sqlite3_int64),
  4272   4272     void*
  4273   4273   );
  4274   4274   
................................................................................
  6386   6386   #define SQLITE_CHECKPOINT_PASSIVE 0
  6387   6387   #define SQLITE_CHECKPOINT_FULL    1
  6388   6388   #define SQLITE_CHECKPOINT_RESTART 2
  6389   6389   
  6390   6390   
  6391   6391   /*
  6392   6392   ** CAPI3REF: The pre-update hook.
  6393         -** 
  6394         -** The preupdate_old() API may only be used from within an SQLITE_UPDATE or
  6395         -** SQLITE_DELETE pre-update callback. The preupdate_modified() API may only 
  6396         -** be used from within an SQLITE_UPDATE pre-update callback.
         6393  +** EXPERIMENTAL
         6394  +**
         6395  +** ^The [sqlite3_preupdate_hook()] interface registers a callback function
         6396  +** that is invoked prior to each [INSERT], [UPDATE], and [DELETE] operation.
         6397  +** ^At most one preupdate hook may be registered at a time on a single
         6398  +** [database connection]; each call to [sqlite3_preupdate_hook()] overrides
         6399  +** the previous setting.
         6400  +** ^The preupdate hook is disabled by invoking [sqlite3_preupdate_hook()]
         6401  +** with a NULL pointer as the second parameter.
         6402  +** ^The third parameter to [sqlite3_preupdate_hook()] is passed through as
         6403  +** the first parameter to callbacks.
         6404  +**
         6405  +** ^The preupdate hook only fires for changes to real tables; the preupdate
         6406  +** hook is not invoked for changes to virtual tables.
         6407  +**
         6408  +** ^The second parameter to the preupdate callback is a pointer to
         6409  +** the [database connection] that registered the preupdate hook.
         6410  +** ^The third parameter to the preupdate callback is one of the constants
         6411  +** [SQLITE_INSERT], [SQLITE_DELETE], or [SQLITE_UPDATE] to indentify the
         6412  +** kind of update operation that is about to occur.
         6413  +** ^(The fourth parameter to the preupdate callback is the name of the
         6414  +** database within the database connection that is being modified.  This
         6415  +** will be "main" for the main database or "temp" for TEMP tables or 
         6416  +** the name given after the AS keyword in the [ATTACH] statement for attached
         6417  +** databases.)^
         6418  +** ^The fifth parameter to the preupdate callback is the name of the
         6419  +** table that is being modified.
         6420  +** ^The sixth parameter to the preupdate callback is the initial [rowid] of the
         6421  +** row being changes for SQLITE_UPDATE and SQLITE_DELETE changes and is
         6422  +** undefined for SQLITE_INSERT changes.
         6423  +** ^The seventh parameter to the preupdate callback is the final [rowid] of
         6424  +** the row being changed for SQLITE_UPDATE and SQLITE_INSERT changes and is
         6425  +** undefined for SQLITE_DELETE changes.
         6426  +**
         6427  +** The [sqlite3_preupdate_old()], [sqlite3_preupdate_new()],
         6428  +** [sqlite3_preupdate_count()], and [sqlite3_preupdate_depth()] interfaces
         6429  +** provide additional information about a preupdate event. These routines
         6430  +** may only be called from within a preupdate callback.  Invoking any of
         6431  +** these routines from outside of a preupdate callback or with a
         6432  +** [database connection] pointer that is different from the one supplied
         6433  +** to the preupdate callback results in undefined and probably undesirable
         6434  +** behavior.
         6435  +**
         6436  +** ^The [sqlite3_preupdate_count(D)] interface returns the number of columns
         6437  +** in the row that is being inserted, updated, or deleted.
         6438  +**
         6439  +** ^The [sqlite3_preupdate_old(D,N,P)] interface writes into P a pointer to
         6440  +** a [protected sqlite3_value] that contains the value of the Nth column of
         6441  +** the table row before it is updated.  The N parameter must be between 0
         6442  +** and one less than the number of columns or the behavior will be
         6443  +** undefined. This must only be used within SQLITE_UPDATE and SQLITE_DELETE
         6444  +** preupdate callbacks; if it is used by an SQLITE_INSERT callback then the
         6445  +** behavior is undefined.  The [sqlite3_value] that P points to
         6446  +** will be destroyed when the preupdate callback returns.
         6447  +**
         6448  +** ^The [sqlite3_preupdate_new(D,N,P)] interface writes into P a pointer to
         6449  +** a [protected sqlite3_value] that contains the value of the Nth column of
         6450  +** the table row after it is updated.  The N parameter must be between 0
         6451  +** and one less than the number of columns or the behavior will be
         6452  +** undefined. This must only be used within SQLITE_INSERT and SQLITE_UPDATE
         6453  +** preupdate callbacks; if it is used by an SQLITE_DELETE callback then the
         6454  +** behavior is undefined.  The [sqlite3_value] that P points to
         6455  +** will be destroyed when the preupdate callback returns.
         6456  +**
         6457  +** ^The [sqlite3_preupdate_depth(D)] interface returns 0 if the preupdate
         6458  +** callback was invoked as a result of a direct insert, update, or delete
         6459  +** operation; or 1 for inserts, updates, or deletes invoked by top-level 
         6460  +** triggers; or 2 for changes resulting from triggers called by top-level
         6461  +** triggers; and so forth.
         6462  +**
         6463  +** See also:  [sqlite3_update_hook()]
  6397   6464   */
  6398   6465   SQLITE_EXPERIMENTAL void *sqlite3_preupdate_hook(
  6399   6466     sqlite3 *db,
  6400   6467     void(*xPreUpdate)(
  6401   6468       void *pCtx,                   /* Copy of third arg to preupdate_hook() */
  6402   6469       sqlite3 *db,                  /* Database handle */
  6403   6470       int op,                       /* SQLITE_UPDATE, DELETE or INSERT */