/ Check-in [edd80811]
Login

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

Overview
Comment:Documentation updates: Describe recursion capabilities for the various callbacks. (CVS 5688)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: edd80811d702bc0d7a25199d193c04ea057df4de
User & Date: drh 2008-09-10 13:09:24
Context
2008-09-10
14:45
Fix for handling database files corrupted in such a was as to make a b-tree page a direct or indirect descendant of itself. (CVS 5689) check-in: 93545861 user: danielk1977 tags: trunk
13:09
Documentation updates: Describe recursion capabilities for the various callbacks. (CVS 5688) check-in: edd80811 user: drh tags: trunk
11:28
Avoid deleting a file while it is still open in corrupt2.test. Not all platforms support this. (CVS 5687) check-in: 099adfd3 user: danielk1977 tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

    26     26   ** on how SQLite interfaces are suppose to operate.
    27     27   **
    28     28   ** The name of this file under configuration management is "sqlite.h.in".
    29     29   ** The makefile makes some minor changes to this file (such as inserting
    30     30   ** the version number) and changes its name to "sqlite3.h" as
    31     31   ** part of the build process.
    32     32   **
    33         -** @(#) $Id: sqlite.h.in,v 1.397 2008/09/02 21:35:03 drh Exp $
           33  +** @(#) $Id: sqlite.h.in,v 1.398 2008/09/10 13:09:24 drh Exp $
    34     34   */
    35     35   #ifndef _SQLITE3_H_
    36     36   #define _SQLITE3_H_
    37     37   #include <stdarg.h>     /* Needed for the definition of va_list */
    38     38   
    39     39   /*
    40     40   ** Make sure we can call this stuff from C++.
................................................................................
  1571   1571   ** this is important.
  1572   1572   **
  1573   1573   ** There can only be a single busy handler defined for each
  1574   1574   ** [database connection].  Setting a new busy handler clears any
  1575   1575   ** previously set handler.  Note that calling [sqlite3_busy_timeout()]
  1576   1576   ** will also set or clear the busy handler.
  1577   1577   **
         1578  +** The busy callback should not take any actions which modify the
         1579  +** database connection that invoked the busy handler.  Any such actions
         1580  +** result in undefined behavior.
         1581  +** 
  1578   1582   ** INVARIANTS:
  1579   1583   **
  1580   1584   ** {H12311} The [sqlite3_busy_handler(D,C,A)] function shall replace
  1581   1585   **          busy callback in the [database connection] D with a new
  1582   1586   **          a new busy handler C and application data pointer A.
  1583   1587   **
  1584   1588   ** {H12312} Newly created [database connections] shall have a busy
................................................................................
  2099   2103   ** in addition to using an authorizer.
  2100   2104   **
  2101   2105   ** Only a single authorizer can be in place on a database connection
  2102   2106   ** at a time.  Each call to sqlite3_set_authorizer overrides the
  2103   2107   ** previous call.  Disable the authorizer by installing a NULL callback.
  2104   2108   ** The authorizer is disabled by default.
  2105   2109   **
         2110  +** The authorizer callback must not do anything that will modify
         2111  +** the database connection that invoked the authorizer callback.
         2112  +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
         2113  +** database connections for the meaning of "modify" in this paragraph.
         2114  +**
  2106   2115   ** When [sqlite3_prepare_v2()] is used to prepare a statement, the
  2107   2116   ** statement might be reprepared during [sqlite3_step()] due to a 
  2108   2117   ** schema change.  Hence, the application should ensure that the
  2109   2118   ** correct authorizer callback remains in place during the [sqlite3_step()].
  2110   2119   **
  2111   2120   ** Note that the authorizer callback is invoked only during
  2112   2121   ** [sqlite3_prepare()] or its variants.  Authorization is not
................................................................................
  2323   2332   ** progress callback - that is invoked periodically during long
  2324   2333   ** running calls to [sqlite3_exec()], [sqlite3_step()] and
  2325   2334   ** [sqlite3_get_table()].  An example use for this
  2326   2335   ** interface is to keep a GUI updated during a large query.
  2327   2336   **
  2328   2337   ** If the progress callback returns non-zero, the operation is
  2329   2338   ** interrupted.  This feature can be used to implement a
  2330         -** "Cancel" button on a GUI dialog box.
         2339  +** "Cancel" button on a GUI progress dialog box.
         2340  +**
         2341  +** The progress handler must not do anything that will modify
         2342  +** the database connection that invoked the progress handler.
         2343  +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
         2344  +** database connections for the meaning of "modify" in this paragraph.
  2331   2345   **
  2332   2346   ** INVARIANTS:
  2333   2347   **
  2334   2348   ** {H12911} The callback function registered by sqlite3_progress_handler()
  2335   2349   **          is invoked periodically during long running calls to
  2336   2350   **          [sqlite3_step()].
  2337   2351   **
................................................................................
  3833   3847   **
  3834   3848   ** The second parameter is the name of the SQL function to be created or
  3835   3849   ** redefined.  The length of the name is limited to 255 bytes, exclusive of
  3836   3850   ** the zero-terminator.  Note that the name length limit is in bytes, not
  3837   3851   ** characters.  Any attempt to create a function with a longer name
  3838   3852   ** will result in [SQLITE_ERROR] being returned.
  3839   3853   **
  3840         -** The third parameter is the number of arguments that the SQL function or
         3854  +** The third parameter (nArg)
         3855  +** is the number of arguments that the SQL function or
  3841   3856   ** aggregate takes. If this parameter is negative, then the SQL function or
  3842   3857   ** aggregate may take any number of arguments.
  3843   3858   **
  3844   3859   ** The fourth parameter, eTextRep, specifies what
  3845   3860   ** [SQLITE_UTF8 | text encoding] this SQL function prefers for
  3846   3861   ** its parameters.  Any SQL function implementation should be able to work
  3847   3862   ** work with UTF-8, UTF-16le, or UTF-16be.  But some implementations may be
................................................................................
  3864   3879   ** and xFinal and NULL should be passed for xFunc. To delete an existing
  3865   3880   ** SQL function or aggregate, pass NULL for all three function callbacks.
  3866   3881   **
  3867   3882   ** It is permitted to register multiple implementations of the same
  3868   3883   ** functions with the same name but with either differing numbers of
  3869   3884   ** arguments or differing preferred text encodings.  SQLite will use
  3870   3885   ** the implementation most closely matches the way in which the
  3871         -** SQL function is used.
         3886  +** SQL function is used.  A function implementation with a non-negative
         3887  +** nArg parameter is a better match than a function implementation with
         3888  +** a negative nArg.  A function where the preferred text encoding
         3889  +** matches the database encoding is a better
         3890  +** match than a function where the encoding is different.  
         3891  +** A function where the encoding difference is between UTF16le and UTF16be
         3892  +** is a closer match than a function where the encoding difference is
         3893  +** between UTF8 and UTF16.
         3894  +**
         3895  +** Built-in functions may be overloaded by new application-defined functions.
         3896  +** The first application-defined function with a given name overrides all
         3897  +** built-in functions in the same [database connection] with the same name.
         3898  +** Subsequent application-defined functions of the same name only override 
         3899  +** prior application-defined functions that are an exact match for the
         3900  +** number of parameters and preferred encoding.
         3901  +**
         3902  +** An application-defined function is permitted to call other
         3903  +** SQLite interfaces.  However, such calls must not
         3904  +** close the database connection nor finalize or reset the prepared
         3905  +** statement in which the function is running.
  3872   3906   **
  3873   3907   ** INVARIANTS:
  3874   3908   **
  3875         -** {H16103} The [sqlite3_create_function16()] interface behaves exactly
  3876         -**          like [sqlite3_create_function()] in every way except that it
  3877         -**          interprets the zFunctionName argument as zero-terminated UTF-16
         3909  +** {H16103} The [sqlite3_create_function16(D,X,...)] interface shall behave
         3910  +**          as [sqlite3_create_function(D,X,...)] in every way except that it
         3911  +**          interprets the X argument as zero-terminated UTF-16
  3878   3912   **          native byte order instead of as zero-terminated UTF-8.
  3879   3913   **
  3880         -** {H16106} A successful invocation of
  3881         -**          the [sqlite3_create_function(D,X,N,E,...)] interface registers
         3914  +** {H16106} A successful invocation of the
         3915  +**          [sqlite3_create_function(D,X,N,E,...)] interface shall register
  3882   3916   **          or replaces callback functions in the [database connection] D
  3883   3917   **          used to implement the SQL function named X with N parameters
  3884   3918   **          and having a preferred text encoding of E.
  3885   3919   **
  3886   3920   ** {H16109} A successful call to [sqlite3_create_function(D,X,N,E,P,F,S,L)]
  3887         -**          replaces the P, F, S, and L values from any prior calls with
         3921  +**          shall replace the P, F, S, and L values from any prior calls with
  3888   3922   **          the same D, X, N, and E values.
  3889   3923   **
  3890         -** {H16112} The [sqlite3_create_function(D,X,...)] interface fails with
  3891         -**          a return code of [SQLITE_ERROR] if the SQL function name X is
         3924  +** {H16112} The [sqlite3_create_function(D,X,...)] interface shall fail
         3925  +**          if the SQL function name X is
  3892   3926   **          longer than 255 bytes exclusive of the zero terminator.
  3893   3927   **
  3894         -** {H16118} Either F must be NULL and S and L are non-NULL or else F
  3895         -**          is non-NULL and S and L are NULL, otherwise
  3896         -**          [sqlite3_create_function(D,X,N,E,P,F,S,L)] returns [SQLITE_ERROR].
         3928  +** {H16118} The [sqlite3_create_function(D,X,N,E,P,F,S,L)] interface
         3929  +**          shall fail unless either F is NULL and S and L are non-NULL or
         3930  +***         F is non-NULL and S and L are NULL.
  3897   3931   **
  3898         -** {H16121} The [sqlite3_create_function(D,...)] interface fails with an
         3932  +** {H16121} The [sqlite3_create_function(D,...)] interface shall fails with an
  3899   3933   **          error code of [SQLITE_BUSY] if there exist [prepared statements]
  3900   3934   **          associated with the [database connection] D.
  3901   3935   **
  3902         -** {H16124} The [sqlite3_create_function(D,X,N,...)] interface fails with an
  3903         -**          error code of [SQLITE_ERROR] if parameter N (specifying the number
  3904         -**          of arguments to the SQL function being registered) is less
         3936  +** {H16124} The [sqlite3_create_function(D,X,N,...)] interface shall fail with
         3937  +**          an error code of [SQLITE_ERROR] if parameter N is less
  3905   3938   **          than -1 or greater than 127.
  3906   3939   **
  3907   3940   ** {H16127} When N is non-negative, the [sqlite3_create_function(D,X,N,...)]
  3908         -**          interface causes callbacks to be invoked for the SQL function
         3941  +**          interface shall register callbacks to be invoked for the
         3942  +**          SQL function
  3909   3943   **          named X when the number of arguments to the SQL function is
  3910   3944   **          exactly N.
  3911   3945   **
  3912   3946   ** {H16130} When N is -1, the [sqlite3_create_function(D,X,N,...)]
  3913         -**          interface causes callbacks to be invoked for the SQL function
  3914         -**          named X with any number of arguments.
         3947  +**          interface shall register callbacks to be invoked for the SQL
         3948  +**          function named X with any number of arguments.
  3915   3949   **
  3916   3950   ** {H16133} When calls to [sqlite3_create_function(D,X,N,...)]
  3917   3951   **          specify multiple implementations of the same function X
  3918   3952   **          and when one implementation has N>=0 and the other has N=(-1)
  3919         -**          the implementation with a non-zero N is preferred.
         3953  +**          the implementation with a non-zero N shall be preferred.
  3920   3954   **
  3921   3955   ** {H16136} When calls to [sqlite3_create_function(D,X,N,E,...)]
  3922   3956   **          specify multiple implementations of the same function X with
  3923   3957   **          the same number of arguments N but with different
  3924   3958   **          encodings E, then the implementation where E matches the
  3925         -**          database encoding is preferred.
         3959  +**          database encoding shall preferred.
  3926   3960   **
  3927   3961   ** {H16139} For an aggregate SQL function created using
  3928   3962   **          [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finalizer
  3929         -**          function L will always be invoked exactly once if the
         3963  +**          function L shall always be invoked exactly once if the
  3930   3964   **          step function S is called one or more times.
  3931   3965   **
  3932   3966   ** {H16142} When SQLite invokes either the xFunc or xStep function of
  3933   3967   **          an application-defined SQL function or aggregate created
  3934   3968   **          by [sqlite3_create_function()] or [sqlite3_create_function16()],
  3935   3969   **          then the array of [sqlite3_value] objects passed as the
  3936         -**          third parameter are always [protected sqlite3_value] objects.
         3970  +**          third parameter shall be [protected sqlite3_value] objects.
  3937   3971   */
  3938   3972   int sqlite3_create_function(
  3939   3973     sqlite3 *db,
  3940   3974     const char *zFunctionName,
  3941   3975     int nArg,
  3942   3976     int eTextRep,
  3943   3977     void *pApp,
................................................................................
  4841   4875   ** The pArg argument is passed through to the callback.
  4842   4876   ** If the callback on a commit hook function returns non-zero,
  4843   4877   ** then the commit is converted into a rollback.
  4844   4878   **
  4845   4879   ** If another function was previously registered, its
  4846   4880   ** pArg value is returned.  Otherwise NULL is returned.
  4847   4881   **
         4882  +** The callback implementation must not do anything that will modify
         4883  +** the database connection that invoked the callback.  Any actions
         4884  +** to modify the database connection must be deferred until after the
         4885  +** completion of the [sqlite3_step()] call that triggered the commit
         4886  +** or rollback hook in the first place.
         4887  +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
         4888  +** database connections for the meaning of "modify" in this paragraph.
         4889  +**
  4848   4890   ** Registering a NULL function disables the callback.
  4849   4891   **
  4850   4892   ** For the purposes of this API, a transaction is said to have been
  4851   4893   ** rolled back if an explicit "ROLLBACK" statement is executed, or
  4852   4894   ** an error or constraint causes an implicit rollback to occur.
  4853   4895   ** The rollback callback is not invoked if a transaction is
  4854   4896   ** automatically rolled back because the database connection is closed.
................................................................................
  4914   4956   ** The third and fourth arguments to the callback contain pointers to the
  4915   4957   ** database and table name containing the affected row.
  4916   4958   ** The final callback parameter is the rowid of the row. In the case of
  4917   4959   ** an update, this is the rowid after the update takes place.
  4918   4960   **
  4919   4961   ** The update hook is not invoked when internal system tables are
  4920   4962   ** modified (i.e. sqlite_master and sqlite_sequence).
         4963  +**
         4964  +** The update hook implementation must not do anything that will modify
         4965  +** the database connection that invoked the update hook.  Any actions
         4966  +** to modify the database connection must be deferred until after the
         4967  +** completion of the [sqlite3_step()] call that triggered the update hook.
         4968  +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
         4969  +** database connections for the meaning of "modify" in this paragraph.
  4921   4970   **
  4922   4971   ** If another function was previously registered, its pArg value
  4923   4972   ** is returned.  Otherwise NULL is returned.
  4924   4973   **
  4925   4974   ** INVARIANTS:
  4926   4975   **
  4927   4976   ** {H12971} The [sqlite3_update_hook(D,F,P)] interface causes the callback