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 |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
edd80811d702bc0d7a25199d193c04ea |
User & Date: | drh 2008-09-10 13:09:24.000 |
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: 93545861a7 user: danielk1977 tags: trunk) | |
13:09 | Documentation updates: Describe recursion capabilities for the various callbacks. (CVS 5688) (check-in: edd80811d7 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: 099adfd311 user: danielk1977 tags: trunk) | |
Changes
Changes to src/sqlite.h.in.
︙ | ︙ | |||
26 27 28 29 30 31 32 | ** on how SQLite interfaces are suppose to operate. ** ** The name of this file under configuration management is "sqlite.h.in". ** The makefile makes some minor changes to this file (such as inserting ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** | | | 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | ** on how SQLite interfaces are suppose to operate. ** ** The name of this file under configuration management is "sqlite.h.in". ** The makefile makes some minor changes to this file (such as inserting ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** ** @(#) $Id: sqlite.h.in,v 1.398 2008/09/10 13:09:24 drh Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ #include <stdarg.h> /* Needed for the definition of va_list */ /* ** Make sure we can call this stuff from C++. |
︙ | ︙ | |||
1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 | ** this is important. ** ** There can only be a single busy handler defined for each ** [database connection]. Setting a new busy handler clears any ** previously set handler. Note that calling [sqlite3_busy_timeout()] ** will also set or clear the busy handler. ** ** INVARIANTS: ** ** {H12311} The [sqlite3_busy_handler(D,C,A)] function shall replace ** busy callback in the [database connection] D with a new ** a new busy handler C and application data pointer A. ** ** {H12312} Newly created [database connections] shall have a busy | > > > > | 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 | ** this is important. ** ** There can only be a single busy handler defined for each ** [database connection]. Setting a new busy handler clears any ** 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 ** busy callback in the [database connection] D with a new ** a new busy handler C and application data pointer A. ** ** {H12312} Newly created [database connections] shall have a busy |
︙ | ︙ | |||
2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 | ** in addition to using an authorizer. ** ** Only a single authorizer can be in place on a database connection ** at a time. Each call to sqlite3_set_authorizer overrides the ** previous call. Disable the authorizer by installing a NULL callback. ** The authorizer is disabled by default. ** ** 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 ** correct authorizer callback remains in place during the [sqlite3_step()]. ** ** Note that the authorizer callback is invoked only during ** [sqlite3_prepare()] or its variants. Authorization is not | > > > > > | 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 | ** in addition to using an authorizer. ** ** Only a single authorizer can be in place on a database connection ** at a time. Each call to sqlite3_set_authorizer overrides the ** 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 ** correct authorizer callback remains in place during the [sqlite3_step()]. ** ** Note that the authorizer callback is invoked only during ** [sqlite3_prepare()] or its variants. Authorization is not |
︙ | ︙ | |||
2323 2324 2325 2326 2327 2328 2329 | ** progress callback - that is invoked periodically during long ** running calls to [sqlite3_exec()], [sqlite3_step()] and ** [sqlite3_get_table()]. An example use for this ** interface is to keep a GUI updated during a large query. ** ** If the progress callback returns non-zero, the operation is ** interrupted. This feature can be used to implement a | | > > > > > | 2332 2333 2334 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 | ** progress callback - that is invoked periodically during long ** running calls to [sqlite3_exec()], [sqlite3_step()] and ** [sqlite3_get_table()]. An example use for this ** interface is to keep a GUI updated during a large query. ** ** If the progress callback returns non-zero, the operation is ** interrupted. This feature can be used to implement a ** "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: ** ** {H12911} The callback function registered by sqlite3_progress_handler() ** is invoked periodically during long running calls to ** [sqlite3_step()]. ** |
︙ | ︙ | |||
3833 3834 3835 3836 3837 3838 3839 | ** ** The second parameter is the name of the SQL function to be created or ** redefined. The length of the name is limited to 255 bytes, exclusive of ** the zero-terminator. Note that the name length limit is in bytes, not ** characters. Any attempt to create a function with a longer name ** will result in [SQLITE_ERROR] being returned. ** | > | | 3847 3848 3849 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 | ** ** The second parameter is the name of the SQL function to be created or ** redefined. The length of the name is limited to 255 bytes, exclusive of ** the zero-terminator. Note that the name length limit is in bytes, not ** characters. Any attempt to create a function with a longer name ** will result in [SQLITE_ERROR] being returned. ** ** 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. ** ** The fourth parameter, eTextRep, specifies what ** [SQLITE_UTF8 | text encoding] this SQL function prefers for ** its parameters. Any SQL function implementation should be able to work ** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be |
︙ | ︙ | |||
3864 3865 3866 3867 3868 3869 3870 | ** and xFinal and NULL should be passed for xFunc. To delete an existing ** SQL function or aggregate, pass NULL for all three function callbacks. ** ** It is permitted to register multiple implementations of the same ** 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 | | > > > > > > > > > > > > > > > > > > > | | | | | | | | > | | < | | | < | > | | | | | | | 3879 3880 3881 3882 3883 3884 3885 3886 3887 3888 3889 3890 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 3904 3905 3906 3907 3908 3909 3910 3911 3912 3913 3914 3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3933 3934 3935 3936 3937 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951 3952 3953 3954 3955 3956 3957 3958 3959 3960 3961 3962 3963 3964 3965 3966 3967 3968 3969 3970 3971 3972 3973 3974 3975 3976 3977 | ** and xFinal and NULL should be passed for xFunc. To delete an existing ** SQL function or aggregate, pass NULL for all three function callbacks. ** ** It is permitted to register multiple implementations of the same ** 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. 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(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 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)] ** 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 shall fail ** if the SQL function name X is ** longer than 255 bytes exclusive of the zero terminator. ** ** {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 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 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 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 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 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 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 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 shall be [protected sqlite3_value] objects. */ int sqlite3_create_function( sqlite3 *db, const char *zFunctionName, int nArg, int eTextRep, void *pApp, |
︙ | ︙ | |||
4841 4842 4843 4844 4845 4846 4847 4848 4849 4850 4851 4852 4853 4854 | ** The pArg argument is passed through to the callback. ** If the callback on a commit hook function returns non-zero, ** then the commit is converted into a rollback. ** ** If another function was previously registered, its ** pArg value is returned. Otherwise NULL is returned. ** ** Registering a NULL function disables the callback. ** ** For the purposes of this API, a transaction is said to have been ** rolled back if an explicit "ROLLBACK" statement is executed, or ** an error or constraint causes an implicit rollback to occur. ** The rollback callback is not invoked if a transaction is ** automatically rolled back because the database connection is closed. | > > > > > > > > | 4875 4876 4877 4878 4879 4880 4881 4882 4883 4884 4885 4886 4887 4888 4889 4890 4891 4892 4893 4894 4895 4896 | ** The pArg argument is passed through to the callback. ** If the callback on a commit hook function returns non-zero, ** then the commit is converted into a rollback. ** ** 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 ** rolled back if an explicit "ROLLBACK" statement is executed, or ** an error or constraint causes an implicit rollback to occur. ** The rollback callback is not invoked if a transaction is ** automatically rolled back because the database connection is closed. |
︙ | ︙ | |||
4914 4915 4916 4917 4918 4919 4920 4921 4922 4923 4924 4925 4926 4927 | ** The third and fourth arguments to the callback contain pointers to the ** database and table name containing the affected row. ** The final callback parameter is the rowid of the row. In the case of ** an update, this is the rowid after the update takes place. ** ** The update hook is not invoked when internal system tables are ** modified (i.e. sqlite_master and sqlite_sequence). ** ** If another function was previously registered, its pArg value ** is returned. Otherwise NULL is returned. ** ** INVARIANTS: ** ** {H12971} The [sqlite3_update_hook(D,F,P)] interface causes the callback | > > > > > > > | 4956 4957 4958 4959 4960 4961 4962 4963 4964 4965 4966 4967 4968 4969 4970 4971 4972 4973 4974 4975 4976 | ** The third and fourth arguments to the callback contain pointers to the ** database and table name containing the affected row. ** The final callback parameter is the rowid of the row. In the case of ** an update, this is the rowid after the update takes place. ** ** 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. ** ** INVARIANTS: ** ** {H12971} The [sqlite3_update_hook(D,F,P)] interface causes the callback |
︙ | ︙ |