From: drh Date: Wed, 30 Mar 2011 17:07:47 +0000 (+0000) Subject: Add documentation to the sqlite3_preupdate_hook() interface and its relatives. X-Git-Tag: version-3.13.0~148^2~299 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=930e1b6a5d0a8834415cf68c0057b26ddb42936f;p=thirdparty%2Fsqlite.git Add documentation to the sqlite3_preupdate_hook() interface and its relatives. FossilOrigin-Name: 8180f2881fa970429e28d4f3258a56cfaabbcabd --- diff --git a/manifest b/manifest index b427fcf551..35fb6c6035 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Merge\sin\sall\sthe\slatest\schanges\sfrom\strunk. -D 2011-03-30T02:03:12.567 +C Add\sdocumentation\sto\sthe\ssqlite3_preupdate_hook()\sinterface\sand\sits\srelatives. +D 2011-03-30T17:07:47.319 F Makefile.arm-wince-mingw32ce-gcc d6df77f1f48d690bd73162294bbba7f59507c72f F Makefile.in 27701a1653595a1f2187dc61c8117e00a6c1d50f F Makefile.linux-gcc 91d710bdc4998cb015f39edf3cb314ec4f4d7e23 @@ -187,7 +187,7 @@ F src/resolve.c 1c0f32b64f8e3f555fe1f732f9d6f501a7f05706 F src/rowset.c 69afa95a97c524ba6faf3805e717b5b7ae85a697 F src/select.c d24406c45dd2442eb2eeaac413439066b149c944 F src/shell.c 9dc0b4bb59290c0a35256d278cab0f314987ad6a -F src/sqlite.h.in 73512de44f0d3563dd24be2e701542e52c7efe25 +F src/sqlite.h.in 3fef17a4201b068291da874b42599b9e61c0cf68 F src/sqlite3ext.h c90bd5507099f62043832d73f6425d8d5c5da754 F src/sqliteInt.h 7c11f9a648cf82e87330fd2185fcaa1f7c46dfba F src/sqliteLimit.h a17dcd3fb775d63b64a43a55c54cb282f9726f44 @@ -929,7 +929,7 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e F tool/vdbe-compress.tcl d70ea6d8a19e3571d7ab8c9b75cba86d1173ff0f -P 4255a9f609c4fd43582a0874143eabe211199726 3d2de011814002e2e25b7645f94ff8fc7aab9cdd -R 48b479c7a408c0c8015c6f938b7e92a4 +P b11d941e92897663da46160185e6e305d4e28fe6 +R e37cfb6574f4ec186f2c67ceafeda97a U drh -Z 1cd943e96dc4b8cfc7720b21a63156f8 +Z ede135d544f338afa66b4a4b2184647f diff --git a/manifest.uuid b/manifest.uuid index c6b7c703a4..9a70869e00 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -b11d941e92897663da46160185e6e305d4e28fe6 \ No newline at end of file +8180f2881fa970429e28d4f3258a56cfaabbcabd \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index 42ce94be21..c3dc70168f 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -1129,7 +1129,7 @@ int sqlite3_config(int, ...); ** [database connection] (specified in the first argument). ** ** The second argument to sqlite3_db_config(D,V,...) is the -** [SQLITE_DBCONIG_LOOKASIDE | configuration verb] - an integer code +** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code ** that indicates what aspect of the [database connection] is being configured. ** Subsequent arguments vary depending on the configuration verb. ** @@ -4263,8 +4263,8 @@ void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); ** on the same [database connection] D, or NULL for ** the first call on D. ** -** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()] -** interfaces. +** See also the [sqlite3_commit_hook()], [sqlite3_rollback_hook()], +** and [sqlite3_preupdate_hook()] interfaces. */ void *sqlite3_update_hook( sqlite3*, @@ -6390,10 +6390,77 @@ int sqlite3_wal_checkpoint_v2( /* ** CAPI3REF: The pre-update hook. -** -** The preupdate_old() API may only be used from within an SQLITE_UPDATE or -** SQLITE_DELETE pre-update callback. The preupdate_modified() API may only -** be used from within an SQLITE_UPDATE pre-update callback. +** EXPERIMENTAL +** +** ^The [sqlite3_preupdate_hook()] interface registers a callback function +** that is invoked prior to each [INSERT], [UPDATE], and [DELETE] operation. +** ^At most one preupdate hook may be registered at a time on a single +** [database connection]; each call to [sqlite3_preupdate_hook()] overrides +** the previous setting. +** ^The preupdate hook is disabled by invoking [sqlite3_preupdate_hook()] +** with a NULL pointer as the second parameter. +** ^The third parameter to [sqlite3_preupdate_hook()] is passed through as +** the first parameter to callbacks. +** +** ^The preupdate hook only fires for changes to real tables; the preupdate +** hook is not invoked for changes to virtual tables. +** +** ^The second parameter to the preupdate callback is a pointer to +** the [database connection] that registered the preupdate hook. +** ^The third parameter to the preupdate callback is one of the constants +** [SQLITE_INSERT], [SQLITE_DELETE], or [SQLITE_UPDATE] to indentify the +** kind of update operation that is about to occur. +** ^(The fourth parameter to the preupdate callback is the name of the +** database within the database connection that is being modified. This +** will be "main" for the main database or "temp" for TEMP tables or +** the name given after the AS keyword in the [ATTACH] statement for attached +** databases.)^ +** ^The fifth parameter to the preupdate callback is the name of the +** table that is being modified. +** ^The sixth parameter to the preupdate callback is the initial [rowid] of the +** row being changes for SQLITE_UPDATE and SQLITE_DELETE changes and is +** undefined for SQLITE_INSERT changes. +** ^The seventh parameter to the preupdate callback is the final [rowid] of +** the row being changed for SQLITE_UPDATE and SQLITE_INSERT changes and is +** undefined for SQLITE_DELETE changes. +** +** The [sqlite3_preupdate_old()], [sqlite3_preupdate_new()], +** [sqlite3_preupdate_count()], and [sqlite3_preupdate_depth()] interfaces +** provide additional information about a preupdate event. These routines +** may only be called from within a preupdate callback. Invoking any of +** these routines from outside of a preupdate callback or with a +** [database connection] pointer that is different from the one supplied +** to the preupdate callback results in undefined and probably undesirable +** behavior. +** +** ^The [sqlite3_preupdate_count(D)] interface returns the number of columns +** in the row that is being inserted, updated, or deleted. +** +** ^The [sqlite3_preupdate_old(D,N,P)] interface writes into P a pointer to +** a [protected sqlite3_value] that contains the value of the Nth column of +** the table row before it is updated. The N parameter must be between 0 +** and one less than the number of columns or the behavior will be +** undefined. This must only be used within SQLITE_UPDATE and SQLITE_DELETE +** preupdate callbacks; if it is used by an SQLITE_INSERT callback then the +** behavior is undefined. The [sqlite3_value] that P points to +** will be destroyed when the preupdate callback returns. +** +** ^The [sqlite3_preupdate_new(D,N,P)] interface writes into P a pointer to +** a [protected sqlite3_value] that contains the value of the Nth column of +** the table row after it is updated. The N parameter must be between 0 +** and one less than the number of columns or the behavior will be +** undefined. This must only be used within SQLITE_INSERT and SQLITE_UPDATE +** preupdate callbacks; if it is used by an SQLITE_DELETE callback then the +** behavior is undefined. The [sqlite3_value] that P points to +** will be destroyed when the preupdate callback returns. +** +** ^The [sqlite3_preupdate_depth(D)] interface returns 0 if the preupdate +** callback was invoked as a result of a direct insert, update, or delete +** operation; or 1 for inserts, updates, or deletes invoked by top-level +** triggers; or 2 for changes resulting from triggers called by top-level +** triggers; and so forth. +** +** See also: [sqlite3_update_hook()] */ SQLITE_EXPERIMENTAL void *sqlite3_preupdate_hook( sqlite3 *db,