From c807542bcfd2c9ea27530d274b25400521f7c4bd Mon Sep 17 00:00:00 2001 From: drh Date: Wed, 10 Sep 2008 13:09:23 +0000 Subject: [PATCH] Documentation updates: Describe recursion capabilities for the various callbacks. (CVS 5688) FossilOrigin-Name: edd80811d702bc0d7a25199d193c04ea057df4de --- manifest | 14 +++---- manifest.uuid | 2 +- src/sqlite.h.in | 101 +++++++++++++++++++++++++++++++++++------------- 3 files changed, 83 insertions(+), 34 deletions(-) diff --git a/manifest b/manifest index 8a37d47e4c..753ef2656f 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Avoid\sdeleting\sa\sfile\swhile\sit\sis\sstill\sopen\sin\scorrupt2.test.\sNot\sall\splatforms\ssupport\sthis.\s(CVS\s5687) -D 2008-09-10T11:28:38 +C Documentation\supdates:\s\sDescribe\srecursion\scapabilities\sfor\sthe\svarious\ncallbacks.\s(CVS\s5688) +D 2008-09-10T13:09:24 F Makefile.arm-wince-mingw32ce-gcc fcd5e9cd67fe88836360bb4f9ef4cb7f8e2fb5a0 F Makefile.in d15a7ebfe5e057a72a49805ffb302dbb601c8329 F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654 @@ -149,7 +149,7 @@ F src/random.c 11bbdf7def3746a762fbdb56c9d04648135ad6d8 F src/resolve.c a6abf83125bce0c80ba04acc27c3565155ad305c F src/select.c eec7c5f28a0c75fdd8500630435af176bba73219 F src/shell.c d83b578a8ccdd3e0e7fef4388a0887ce9f810967 -F src/sqlite.h.in 7da6a0d39221affca458b4ba305be3eb1590bb8e +F src/sqlite.h.in 81dc1e8e50fb5c7cccf0a67a34cb796efc1d2a1e F src/sqlite3ext.h 1e3887c9bd3ae66cb599e922824b04cd0d0f2c3e F src/sqliteInt.h 4a43cd9dcb7d5a6664a981f08e64d555acbca1bc F src/sqliteLimit.h f435e728c6b620ef7312814d660a81f9356eb5c8 @@ -634,7 +634,7 @@ F tool/speedtest16.c c8a9c793df96db7e4933f0852abb7a03d48f2e81 F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff F tool/speedtest8.c 1dbced29de5f59ba2ebf877edcadf171540374d1 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e -P 300a64b725a111ee66e38de099314f03b064c6eb -R 2fc115d04cd9022ed9994d800543641d -U danielk1977 -Z 65ea31ed57297840fa2eea42aecf71f5 +P 099adfd31167a78d803e2992e5f50cf4e292dd43 +R 7853a8a5ccb659e8bb6ea1c2c2871c9f +U drh +Z d85bcb69ec2b69991a86141e52428a8c diff --git a/manifest.uuid b/manifest.uuid index 3f2c3c4074..756864d5e9 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -099adfd31167a78d803e2992e5f50cf4e292dd43 \ No newline at end of file +edd80811d702bc0d7a25199d193c04ea057df4de \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index de30080ece..6850f2bcba 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -30,7 +30,7 @@ ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** -** @(#) $Id: sqlite.h.in,v 1.397 2008/09/02 21:35:03 drh Exp $ +** @(#) $Id: sqlite.h.in,v 1.398 2008/09/10 13:09:24 drh Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ @@ -1575,6 +1575,10 @@ int sqlite3_complete16(const void *sql); ** previously set handler. Note that calling [sqlite3_busy_timeout()] ** will also set or clear the busy handler. ** +** The busy callback should not take any actions which modify the +** database connection that invoked the busy handler. Any such actions +** result in undefined behavior. +** ** INVARIANTS: ** ** {H12311} The [sqlite3_busy_handler(D,C,A)] function shall replace @@ -2103,6 +2107,11 @@ void sqlite3_randomness(int N, void *P); ** previous call. Disable the authorizer by installing a NULL callback. ** The authorizer is disabled by default. ** +** The authorizer callback must not do anything that will modify +** the database connection that invoked the authorizer callback. +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their +** database connections for the meaning of "modify" in this paragraph. +** ** When [sqlite3_prepare_v2()] is used to prepare a statement, the ** statement might be reprepared during [sqlite3_step()] due to a ** schema change. Hence, the application should ensure that the @@ -2327,7 +2336,12 @@ SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*, ** ** If the progress callback returns non-zero, the operation is ** interrupted. This feature can be used to implement a -** "Cancel" button on a GUI dialog box. +** "Cancel" button on a GUI progress dialog box. +** +** The progress handler must not do anything that will modify +** the database connection that invoked the progress handler. +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their +** database connections for the meaning of "modify" in this paragraph. ** ** INVARIANTS: ** @@ -3837,7 +3851,8 @@ int sqlite3_reset(sqlite3_stmt *pStmt); ** characters. Any attempt to create a function with a longer name ** will result in [SQLITE_ERROR] being returned. ** -** The third parameter is the number of arguments that the SQL function or +** The third parameter (nArg) +** is the number of arguments that the SQL function or ** aggregate takes. If this parameter is negative, then the SQL function or ** aggregate may take any number of arguments. ** @@ -3868,72 +3883,91 @@ int sqlite3_reset(sqlite3_stmt *pStmt); ** functions with the same name but with either differing numbers of ** arguments or differing preferred text encodings. SQLite will use ** the implementation most closely matches the way in which the -** SQL function is used. +** SQL function is used. A function implementation with a non-negative +** nArg parameter is a better match than a function implementation with +** a negative nArg. A function where the preferred text encoding +** matches the database encoding is a better +** match than a function where the encoding is different. +** A function where the encoding difference is between UTF16le and UTF16be +** is a closer match than a function where the encoding difference is +** between UTF8 and UTF16. +** +** Built-in functions may be overloaded by new application-defined functions. +** The first application-defined function with a given name overrides all +** built-in functions in the same [database connection] with the same name. +** Subsequent application-defined functions of the same name only override +** prior application-defined functions that are an exact match for the +** number of parameters and preferred encoding. +** +** An application-defined function is permitted to call other +** SQLite interfaces. However, such calls must not +** close the database connection nor finalize or reset the prepared +** statement in which the function is running. ** ** INVARIANTS: ** -** {H16103} The [sqlite3_create_function16()] interface behaves exactly -** like [sqlite3_create_function()] in every way except that it -** interprets the zFunctionName argument as zero-terminated UTF-16 +** {H16103} The [sqlite3_create_function16(D,X,...)] interface shall behave +** as [sqlite3_create_function(D,X,...)] in every way except that it +** interprets the X argument as zero-terminated UTF-16 ** native byte order instead of as zero-terminated UTF-8. ** -** {H16106} A successful invocation of -** the [sqlite3_create_function(D,X,N,E,...)] interface registers +** {H16106} A successful invocation of the +** [sqlite3_create_function(D,X,N,E,...)] interface shall register ** or replaces callback functions in the [database connection] D ** used to implement the SQL function named X with N parameters ** and having a preferred text encoding of E. ** ** {H16109} A successful call to [sqlite3_create_function(D,X,N,E,P,F,S,L)] -** replaces the P, F, S, and L values from any prior calls with +** shall replace the P, F, S, and L values from any prior calls with ** the same D, X, N, and E values. ** -** {H16112} The [sqlite3_create_function(D,X,...)] interface fails with -** a return code of [SQLITE_ERROR] if the SQL function name X is +** {H16112} The [sqlite3_create_function(D,X,...)] interface shall fail +** if the SQL function name X is ** longer than 255 bytes exclusive of the zero terminator. ** -** {H16118} Either F must be NULL and S and L are non-NULL or else F -** is non-NULL and S and L are NULL, otherwise -** [sqlite3_create_function(D,X,N,E,P,F,S,L)] returns [SQLITE_ERROR]. +** {H16118} The [sqlite3_create_function(D,X,N,E,P,F,S,L)] interface +** shall fail unless either F is NULL and S and L are non-NULL or +*** F is non-NULL and S and L are NULL. ** -** {H16121} The [sqlite3_create_function(D,...)] interface fails with an +** {H16121} The [sqlite3_create_function(D,...)] interface shall fails with an ** error code of [SQLITE_BUSY] if there exist [prepared statements] ** associated with the [database connection] D. ** -** {H16124} The [sqlite3_create_function(D,X,N,...)] interface fails with an -** error code of [SQLITE_ERROR] if parameter N (specifying the number -** of arguments to the SQL function being registered) is less +** {H16124} The [sqlite3_create_function(D,X,N,...)] interface shall fail with +** an error code of [SQLITE_ERROR] if parameter N is less ** than -1 or greater than 127. ** ** {H16127} When N is non-negative, the [sqlite3_create_function(D,X,N,...)] -** interface causes callbacks to be invoked for the SQL function +** interface shall register callbacks to be invoked for the +** SQL function ** named X when the number of arguments to the SQL function is ** exactly N. ** ** {H16130} When N is -1, the [sqlite3_create_function(D,X,N,...)] -** interface causes callbacks to be invoked for the SQL function -** named X with any number of arguments. +** interface shall register callbacks to be invoked for the SQL +** function named X with any number of arguments. ** ** {H16133} When calls to [sqlite3_create_function(D,X,N,...)] ** specify multiple implementations of the same function X ** and when one implementation has N>=0 and the other has N=(-1) -** the implementation with a non-zero N is preferred. +** the implementation with a non-zero N shall be preferred. ** ** {H16136} When calls to [sqlite3_create_function(D,X,N,E,...)] ** specify multiple implementations of the same function X with ** the same number of arguments N but with different ** encodings E, then the implementation where E matches the -** database encoding is preferred. +** database encoding shall preferred. ** ** {H16139} For an aggregate SQL function created using ** [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finalizer -** function L will always be invoked exactly once if the +** function L shall always be invoked exactly once if the ** step function S is called one or more times. ** ** {H16142} When SQLite invokes either the xFunc or xStep function of ** an application-defined SQL function or aggregate created ** by [sqlite3_create_function()] or [sqlite3_create_function16()], ** then the array of [sqlite3_value] objects passed as the -** third parameter are always [protected sqlite3_value] objects. +** third parameter shall be [protected sqlite3_value] objects. */ int sqlite3_create_function( sqlite3 *db, @@ -4845,6 +4879,14 @@ sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt); ** If another function was previously registered, its ** pArg value is returned. Otherwise NULL is returned. ** +** The callback implementation must not do anything that will modify +** the database connection that invoked the callback. Any actions +** to modify the database connection must be deferred until after the +** completion of the [sqlite3_step()] call that triggered the commit +** or rollback hook in the first place. +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their +** database connections for the meaning of "modify" in this paragraph. +** ** Registering a NULL function disables the callback. ** ** For the purposes of this API, a transaction is said to have been @@ -4919,6 +4961,13 @@ void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); ** The update hook is not invoked when internal system tables are ** modified (i.e. sqlite_master and sqlite_sequence). ** +** The update hook implementation must not do anything that will modify +** the database connection that invoked the update hook. Any actions +** to modify the database connection must be deferred until after the +** completion of the [sqlite3_step()] call that triggered the update hook. +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their +** database connections for the meaning of "modify" in this paragraph. +** ** If another function was previously registered, its pArg value ** is returned. Otherwise NULL is returned. ** -- 2.47.3