drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 1 | /* |
drh | b19a2bc | 2001-09-16 00:13:26 +0000 | [diff] [blame] | 2 | ** 2001 September 15 |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 3 | ** |
drh | b19a2bc | 2001-09-16 00:13:26 +0000 | [diff] [blame] | 4 | ** The author disclaims copyright to this source code. In place of |
| 5 | ** a legal notice, here is a blessing: |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 6 | ** |
drh | b19a2bc | 2001-09-16 00:13:26 +0000 | [diff] [blame] | 7 | ** May you do good and not evil. |
| 8 | ** May you find forgiveness for yourself and forgive others. |
| 9 | ** May you share freely, never taking more than you give. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 10 | ** |
| 11 | ************************************************************************* |
drh | b19a2bc | 2001-09-16 00:13:26 +0000 | [diff] [blame] | 12 | ** This header file defines the interface that the SQLite library |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 13 | ** presents to client programs. If a C-function, structure, datatype, |
| 14 | ** or constant definition does not appear in this file, then it is |
| 15 | ** not a published API of SQLite, is subject to change without |
| 16 | ** notice, and should not be referenced by programs that use SQLite. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 17 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 18 | ** Some of the definitions that are in this file are marked as |
| 19 | ** "experimental". Experimental interfaces are normally new |
| 20 | ** features recently added to SQLite. We do not anticipate changes |
| 21 | ** to experimental interfaces but reserve to make minor changes if |
| 22 | ** experience from use "in the wild" suggest such changes are prudent. |
| 23 | ** |
| 24 | ** The official C-language API documentation for SQLite is derived |
| 25 | ** from comments in this file. This file is the authoritative source |
| 26 | ** on how SQLite interfaces are suppose to operate. |
| 27 | ** |
| 28 | ** The name of this file under configuration management is "sqlite.h.in". |
| 29 | ** The makefile makes some minor changes to this file (such as inserting |
| 30 | ** the version number) and changes its name to "sqlite3.h" as |
| 31 | ** part of the build process. |
| 32 | ** |
drh | 605264d | 2007-08-21 15:13:19 +0000 | [diff] [blame^] | 33 | ** @(#) $Id: sqlite.h.in,v 1.232 2007/08/21 15:13:19 drh Exp $ |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 34 | */ |
drh | 12057d5 | 2004-09-06 17:34:12 +0000 | [diff] [blame] | 35 | #ifndef _SQLITE3_H_ |
| 36 | #define _SQLITE3_H_ |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 37 | #include <stdarg.h> /* Needed for the definition of va_list */ |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 38 | |
| 39 | /* |
drh | 382c024 | 2001-10-06 16:33:02 +0000 | [diff] [blame] | 40 | ** Make sure we can call this stuff from C++. |
| 41 | */ |
| 42 | #ifdef __cplusplus |
| 43 | extern "C" { |
| 44 | #endif |
| 45 | |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 46 | |
drh | 382c024 | 2001-10-06 16:33:02 +0000 | [diff] [blame] | 47 | /* |
drh | 73be501 | 2007-08-08 12:11:21 +0000 | [diff] [blame] | 48 | ** Add the ability to override 'extern' |
| 49 | */ |
| 50 | #ifndef SQLITE_EXTERN |
| 51 | # define SQLITE_EXTERN extern |
| 52 | #endif |
| 53 | |
| 54 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 55 | ** Make sure these symbols where not defined by some previous header |
| 56 | ** file. |
drh | b86ccfb | 2003-01-28 23:13:10 +0000 | [diff] [blame] | 57 | */ |
drh | 1e284f4 | 2004-10-06 15:52:01 +0000 | [diff] [blame] | 58 | #ifdef SQLITE_VERSION |
| 59 | # undef SQLITE_VERSION |
drh | 1e284f4 | 2004-10-06 15:52:01 +0000 | [diff] [blame] | 60 | #endif |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 61 | #ifdef SQLITE_VERSION_NUMBER |
| 62 | # undef SQLITE_VERSION_NUMBER |
| 63 | #endif |
danielk1977 | 99ba19e | 2005-02-05 07:33:34 +0000 | [diff] [blame] | 64 | |
| 65 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 66 | ** CAPI3REF: Compile-Time Library Version Numbers |
| 67 | ** |
| 68 | ** The version of the SQLite library is contained in the sqlite3.h |
| 69 | ** header file in a #define named SQLITE_VERSION. The SQLITE_VERSION |
| 70 | ** macro resolves to a string constant. |
| 71 | ** |
| 72 | ** The format of the version string is "X.Y.Z", where |
danielk1977 | 99ba19e | 2005-02-05 07:33:34 +0000 | [diff] [blame] | 73 | ** X is the major version number, Y is the minor version number and Z |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 74 | ** is the release number. The X.Y.Z might be followed by "alpha" or "beta". |
danielk1977 | 99ba19e | 2005-02-05 07:33:34 +0000 | [diff] [blame] | 75 | ** For example "3.1.1beta". |
| 76 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 77 | ** The X value is always 3 in SQLite. The X value only changes when |
| 78 | ** backwards compatibility is broken and we intend to never break |
| 79 | ** backwards compatibility. The Y value only changes when |
| 80 | ** there are major feature enhancements that are forwards compatible |
| 81 | ** but not backwards compatible. The Z value is incremented with |
| 82 | ** each release but resets back to 0 when Y is incremented. |
| 83 | ** |
danielk1977 | 99ba19e | 2005-02-05 07:33:34 +0000 | [diff] [blame] | 84 | ** The SQLITE_VERSION_NUMBER is an integer with the value |
danielk1977 | e48b1f1 | 2007-05-24 09:44:10 +0000 | [diff] [blame] | 85 | ** (X*1000000 + Y*1000 + Z). For example, for version "3.1.1beta", |
danielk1977 | 99ba19e | 2005-02-05 07:33:34 +0000 | [diff] [blame] | 86 | ** SQLITE_VERSION_NUMBER is set to 3001001. To detect if they are using |
| 87 | ** version 3.1.1 or greater at compile time, programs may use the test |
| 88 | ** (SQLITE_VERSION_NUMBER>=3001001). |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 89 | ** |
| 90 | ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()]. |
danielk1977 | 99ba19e | 2005-02-05 07:33:34 +0000 | [diff] [blame] | 91 | */ |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 92 | #define SQLITE_VERSION "--VERS--" |
danielk1977 | 99ba19e | 2005-02-05 07:33:34 +0000 | [diff] [blame] | 93 | #define SQLITE_VERSION_NUMBER --VERSION-NUMBER-- |
drh | b86ccfb | 2003-01-28 23:13:10 +0000 | [diff] [blame] | 94 | |
| 95 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 96 | ** CAPI3REF: Run-Time Library Version Numbers |
| 97 | ** |
| 98 | ** These routines return values equivalent to the header constants |
| 99 | ** [SQLITE_VERSION] and [SQLITE_VERSION_NUMBER]. The values returned |
| 100 | ** by this routines should only be different from the header values |
| 101 | ** if you compile your program using an sqlite3.h header from a |
| 102 | ** different version of SQLite that the version of the library you |
| 103 | ** link against. |
| 104 | ** |
| 105 | ** The sqlite3_version[] string constant contains the text of the |
| 106 | ** [SQLITE_VERSION] string. The sqlite3_libversion() function returns |
| 107 | ** a poiner to the sqlite3_version[] string constant. The function |
| 108 | ** is provided for DLL users who can only access functions and not |
| 109 | ** constants within the DLL. |
drh | b217a57 | 2000-08-22 13:40:18 +0000 | [diff] [blame] | 110 | */ |
drh | 73be501 | 2007-08-08 12:11:21 +0000 | [diff] [blame] | 111 | SQLITE_EXTERN const char sqlite3_version[]; |
drh | a3f70cb | 2004-09-30 14:24:50 +0000 | [diff] [blame] | 112 | const char *sqlite3_libversion(void); |
danielk1977 | 99ba19e | 2005-02-05 07:33:34 +0000 | [diff] [blame] | 113 | int sqlite3_libversion_number(void); |
| 114 | |
| 115 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 116 | ** CAPI3REF: Database Connection Handle |
| 117 | ** |
| 118 | ** Each open SQLite database is represented by pointer to an instance of the |
| 119 | ** opaque structure named "sqlite3". It is useful to think of an sqlite3 |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 120 | ** pointer as an object. The [sqlite3_open], [sqlite3_open16], and |
| 121 | ** [sqlite3_open_v2] interfaces are its constructors |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 122 | ** and [sqlite3_close] is its destructor. There are many other interfaces |
| 123 | ** (such as [sqlite3_prepare_v2], [sqlite3_create_function], and |
| 124 | ** [sqlite3_busy_timeout] to name but three) that are methods on this |
| 125 | ** object. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 126 | */ |
drh | 9bb575f | 2004-09-06 17:24:11 +0000 | [diff] [blame] | 127 | typedef struct sqlite3 sqlite3; |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 128 | |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 129 | |
| 130 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 131 | ** CAPI3REF: 64-Bit Integer Types |
| 132 | ** |
drh | efad999 | 2004-06-22 12:13:55 +0000 | [diff] [blame] | 133 | ** Some compilers do not support the "long long" datatype. So we have |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 134 | ** to do compiler-specific typedefs for 64-bit signed and unsigned integers. |
| 135 | ** |
| 136 | ** Many SQLite interface functions require a 64-bit integer arguments. |
| 137 | ** Those interfaces are declared using this typedef. |
drh | efad999 | 2004-06-22 12:13:55 +0000 | [diff] [blame] | 138 | */ |
drh | 27436af | 2006-03-28 23:57:17 +0000 | [diff] [blame] | 139 | #ifdef SQLITE_INT64_TYPE |
drh | 9b8f447 | 2006-04-04 01:54:55 +0000 | [diff] [blame] | 140 | typedef SQLITE_INT64_TYPE sqlite_int64; |
drh | 27436af | 2006-03-28 23:57:17 +0000 | [diff] [blame] | 141 | typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; |
| 142 | #elif defined(_MSC_VER) || defined(__BORLANDC__) |
drh | efad999 | 2004-06-22 12:13:55 +0000 | [diff] [blame] | 143 | typedef __int64 sqlite_int64; |
drh | 1211de3 | 2004-07-26 12:24:22 +0000 | [diff] [blame] | 144 | typedef unsigned __int64 sqlite_uint64; |
drh | efad999 | 2004-06-22 12:13:55 +0000 | [diff] [blame] | 145 | #else |
| 146 | typedef long long int sqlite_int64; |
drh | 1211de3 | 2004-07-26 12:24:22 +0000 | [diff] [blame] | 147 | typedef unsigned long long int sqlite_uint64; |
drh | efad999 | 2004-06-22 12:13:55 +0000 | [diff] [blame] | 148 | #endif |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 149 | typedef sqlite_int64 sqlite3_int64; |
| 150 | typedef sqlite_uint64 sqlite3_uint64; |
drh | efad999 | 2004-06-22 12:13:55 +0000 | [diff] [blame] | 151 | |
drh | b37df7b | 2005-10-13 02:09:49 +0000 | [diff] [blame] | 152 | /* |
| 153 | ** If compiling for a processor that lacks floating point support, |
| 154 | ** substitute integer for floating-point |
| 155 | */ |
| 156 | #ifdef SQLITE_OMIT_FLOATING_POINT |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 157 | # define double sqlite3_int64 |
drh | b37df7b | 2005-10-13 02:09:49 +0000 | [diff] [blame] | 158 | #endif |
drh | efad999 | 2004-06-22 12:13:55 +0000 | [diff] [blame] | 159 | |
| 160 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 161 | ** CAPI3REF: Closing A Database Connection |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 162 | ** |
| 163 | ** Call this function with a pointer to a structure that was previously |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 164 | ** returned from [sqlite3_open()], [sqlite3_open16()], or |
| 165 | ** [sqlite3_open_v2()] and the corresponding database will by |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 166 | ** closed. |
danielk1977 | 96d81f9 | 2004-06-19 03:33:57 +0000 | [diff] [blame] | 167 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 168 | ** All SQL statements prepared using [sqlite3_prepare_v2()] or |
| 169 | ** [sqlite3_prepare16_v2()] must be destroyed using [sqlite3_finalize()] |
| 170 | ** before this routine is called. Otherwise, SQLITE_BUSY is returned and the |
danielk1977 | 96d81f9 | 2004-06-19 03:33:57 +0000 | [diff] [blame] | 171 | ** database connection remains open. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 172 | */ |
danielk1977 | f9d64d2 | 2004-06-19 08:18:07 +0000 | [diff] [blame] | 173 | int sqlite3_close(sqlite3 *); |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 174 | |
| 175 | /* |
| 176 | ** The type for a callback function. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 177 | ** This is legacy and deprecated. It is included for historical |
| 178 | ** compatibility and is not documented. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 179 | */ |
drh | 12057d5 | 2004-09-06 17:34:12 +0000 | [diff] [blame] | 180 | typedef int (*sqlite3_callback)(void*,int,char**, char**); |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 181 | |
| 182 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 183 | ** CAPI3REF: One-Step Query Execution Interface |
| 184 | ** |
| 185 | ** This interface is used to do a one-time evaluatation of zero |
| 186 | ** or more SQL statements. UTF-8 text of the SQL statements to |
| 187 | ** be evaluted is passed in as the second parameter. The statements |
| 188 | ** are prepared one by one using [sqlite3_prepare()], evaluated |
| 189 | ** using [sqlite3_step()], then destroyed using [sqlite3_finalize()]. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 190 | ** |
| 191 | ** If one or more of the SQL statements are queries, then |
| 192 | ** the callback function specified by the 3rd parameter is |
| 193 | ** invoked once for each row of the query result. This callback |
| 194 | ** should normally return 0. If the callback returns a non-zero |
| 195 | ** value then the query is aborted, all subsequent SQL statements |
danielk1977 | 6f8a503 | 2004-05-10 10:34:51 +0000 | [diff] [blame] | 196 | ** are skipped and the sqlite3_exec() function returns the SQLITE_ABORT. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 197 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 198 | ** The 4th parameter to this interface is an arbitrary pointer that is |
| 199 | ** passed through to the callback function as its first parameter. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 200 | ** |
| 201 | ** The 2nd parameter to the callback function is the number of |
drh | b19a2bc | 2001-09-16 00:13:26 +0000 | [diff] [blame] | 202 | ** columns in the query result. The 3rd parameter to the callback |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 203 | ** is an array of strings holding the values for each column |
| 204 | ** as extracted using [sqlite3_column_text()]. |
| 205 | ** The 4th parameter to the callback is an array of strings |
| 206 | ** obtained using [sqlite3_column_name()] and holding |
drh | b19a2bc | 2001-09-16 00:13:26 +0000 | [diff] [blame] | 207 | ** the names of each column. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 208 | ** |
| 209 | ** The callback function may be NULL, even for queries. A NULL |
| 210 | ** callback is not an error. It just means that no callback |
| 211 | ** will be invoked. |
| 212 | ** |
| 213 | ** If an error occurs while parsing or evaluating the SQL (but |
| 214 | ** not while executing the callback) then an appropriate error |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 215 | ** message is written into memory obtained from [sqlite3_malloc()] and |
drh | b19a2bc | 2001-09-16 00:13:26 +0000 | [diff] [blame] | 216 | ** *errmsg is made to point to that message. The calling function |
| 217 | ** is responsible for freeing the memory that holds the error |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 218 | ** message. Use [sqlite3_free()] for this. If errmsg==NULL, |
drh | b86ccfb | 2003-01-28 23:13:10 +0000 | [diff] [blame] | 219 | ** then no error message is ever written. |
drh | b19a2bc | 2001-09-16 00:13:26 +0000 | [diff] [blame] | 220 | ** |
| 221 | ** The return value is is SQLITE_OK if there are no errors and |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 222 | ** some other [SQLITE_OK | return code] if there is an error. |
| 223 | ** The particular return value depends on the type of error. |
drh | 58b9576 | 2000-06-02 01:17:37 +0000 | [diff] [blame] | 224 | ** |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 225 | */ |
danielk1977 | 6f8a503 | 2004-05-10 10:34:51 +0000 | [diff] [blame] | 226 | int sqlite3_exec( |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 227 | sqlite3*, /* An open database */ |
| 228 | const char *sql, /* SQL to be evaluted */ |
| 229 | int (*callback)(void*,int,char**,char**), /* Callback function */ |
| 230 | void *, /* 1st argument to callback */ |
| 231 | char **errmsg /* Error msg written here */ |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 232 | ); |
| 233 | |
drh | 58b9576 | 2000-06-02 01:17:37 +0000 | [diff] [blame] | 234 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 235 | ** CAPI3REF: Result Codes |
| 236 | ** KEYWORDS: SQLITE_OK |
| 237 | ** |
| 238 | ** Many SQLite functions return an integer result code from the set shown |
| 239 | ** above in order to indicates success or failure. |
| 240 | ** |
| 241 | ** The result codes above are the only ones returned by SQLite in its |
| 242 | ** default configuration. However, the [sqlite3_extended_result_codes()] |
| 243 | ** API can be used to set a database connectoin to return more detailed |
| 244 | ** result codes. |
| 245 | ** |
| 246 | ** See also: [SQLITE_IOERR_READ | extended result codes] |
| 247 | ** |
drh | 58b9576 | 2000-06-02 01:17:37 +0000 | [diff] [blame] | 248 | */ |
drh | 717e640 | 2001-09-27 03:22:32 +0000 | [diff] [blame] | 249 | #define SQLITE_OK 0 /* Successful result */ |
drh | 15b9a15 | 2006-01-31 20:49:13 +0000 | [diff] [blame] | 250 | /* beginning-of-error-codes */ |
drh | 717e640 | 2001-09-27 03:22:32 +0000 | [diff] [blame] | 251 | #define SQLITE_ERROR 1 /* SQL error or missing database */ |
drh | 2db0bbc | 2005-08-11 02:10:18 +0000 | [diff] [blame] | 252 | #define SQLITE_INTERNAL 2 /* NOT USED. Internal logic error in SQLite */ |
drh | 717e640 | 2001-09-27 03:22:32 +0000 | [diff] [blame] | 253 | #define SQLITE_PERM 3 /* Access permission denied */ |
| 254 | #define SQLITE_ABORT 4 /* Callback routine requested an abort */ |
| 255 | #define SQLITE_BUSY 5 /* The database file is locked */ |
| 256 | #define SQLITE_LOCKED 6 /* A table in the database is locked */ |
| 257 | #define SQLITE_NOMEM 7 /* A malloc() failed */ |
| 258 | #define SQLITE_READONLY 8 /* Attempt to write a readonly database */ |
drh | 24cd67e | 2004-05-10 16:18:47 +0000 | [diff] [blame] | 259 | #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/ |
drh | 717e640 | 2001-09-27 03:22:32 +0000 | [diff] [blame] | 260 | #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ |
| 261 | #define SQLITE_CORRUPT 11 /* The database disk image is malformed */ |
drh | 2db0bbc | 2005-08-11 02:10:18 +0000 | [diff] [blame] | 262 | #define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */ |
drh | 717e640 | 2001-09-27 03:22:32 +0000 | [diff] [blame] | 263 | #define SQLITE_FULL 13 /* Insertion failed because database is full */ |
| 264 | #define SQLITE_CANTOPEN 14 /* Unable to open the database file */ |
drh | 4f0ee68 | 2007-03-30 20:43:40 +0000 | [diff] [blame] | 265 | #define SQLITE_PROTOCOL 15 /* NOT USED. Database lock protocol error */ |
drh | 24cd67e | 2004-05-10 16:18:47 +0000 | [diff] [blame] | 266 | #define SQLITE_EMPTY 16 /* Database is empty */ |
drh | 717e640 | 2001-09-27 03:22:32 +0000 | [diff] [blame] | 267 | #define SQLITE_SCHEMA 17 /* The database schema changed */ |
drh | c797d4d | 2007-05-08 01:08:49 +0000 | [diff] [blame] | 268 | #define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */ |
drh | 717e640 | 2001-09-27 03:22:32 +0000 | [diff] [blame] | 269 | #define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */ |
drh | 8aff101 | 2001-12-22 14:49:24 +0000 | [diff] [blame] | 270 | #define SQLITE_MISMATCH 20 /* Data type mismatch */ |
drh | 247be43 | 2002-05-10 05:44:55 +0000 | [diff] [blame] | 271 | #define SQLITE_MISUSE 21 /* Library used incorrectly */ |
drh | 8766c34 | 2002-11-09 00:33:15 +0000 | [diff] [blame] | 272 | #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ |
drh | ed6c867 | 2003-01-12 18:02:16 +0000 | [diff] [blame] | 273 | #define SQLITE_AUTH 23 /* Authorization denied */ |
drh | 1c2d841 | 2003-03-31 00:30:47 +0000 | [diff] [blame] | 274 | #define SQLITE_FORMAT 24 /* Auxiliary database format error */ |
danielk1977 | 6f8a503 | 2004-05-10 10:34:51 +0000 | [diff] [blame] | 275 | #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */ |
drh | c602f9a | 2004-02-12 19:01:04 +0000 | [diff] [blame] | 276 | #define SQLITE_NOTADB 26 /* File opened that is not a database file */ |
danielk1977 | 6f8a503 | 2004-05-10 10:34:51 +0000 | [diff] [blame] | 277 | #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ |
| 278 | #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ |
drh | 15b9a15 | 2006-01-31 20:49:13 +0000 | [diff] [blame] | 279 | /* end-of-error-codes */ |
drh | 717e640 | 2001-09-27 03:22:32 +0000 | [diff] [blame] | 280 | |
drh | af9ff33 | 2002-01-16 21:00:27 +0000 | [diff] [blame] | 281 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 282 | ** CAPI3REF: Extended Result Codes |
drh | 4ac285a | 2006-09-15 07:28:50 +0000 | [diff] [blame] | 283 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 284 | ** In its default configuration, SQLite API routines return one of 26 integer |
| 285 | ** result codes described at result-codes. However, experience has shown that |
| 286 | ** many of these result codes are too course-grained. They do not provide as |
| 287 | ** much information about problems as users might like. In an effort to |
| 288 | ** address this, newer versions of SQLite (version 3.3.8 and later) include |
| 289 | ** support for additional result codes that provide more detailed information |
| 290 | ** about errors. The extended result codes are enabled (or disabled) for |
| 291 | ** each database |
| 292 | ** connection using the [sqlite3_extended_result_codes()] API. |
| 293 | ** |
| 294 | ** Some of the available extended result codes are listed above. |
| 295 | ** We expect the number of extended result codes will be expand |
| 296 | ** over time. Software that uses extended result codes should expect |
| 297 | ** to see new result codes in future releases of SQLite. |
| 298 | ** |
| 299 | ** The symbolic name for an extended result code always contains a related |
| 300 | ** primary result code as a prefix. Primary result codes contain a single |
| 301 | ** "_" character. Extended result codes contain two or more "_" characters. |
| 302 | ** The numeric value of an extended result code can be converted to its |
| 303 | ** corresponding primary result code by masking off the lower 8 bytes. |
drh | 4ac285a | 2006-09-15 07:28:50 +0000 | [diff] [blame] | 304 | ** |
| 305 | ** The SQLITE_OK result code will never be extended. It will always |
| 306 | ** be exactly zero. |
drh | 4ac285a | 2006-09-15 07:28:50 +0000 | [diff] [blame] | 307 | */ |
| 308 | #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) |
| 309 | #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) |
| 310 | #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) |
| 311 | #define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) |
| 312 | #define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) |
| 313 | #define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) |
| 314 | #define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) |
| 315 | #define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) |
| 316 | #define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) |
danielk1977 | 979f38e | 2007-03-27 16:19:51 +0000 | [diff] [blame] | 317 | #define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) |
danielk1977 | e965ac7 | 2007-06-13 15:22:28 +0000 | [diff] [blame] | 318 | #define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8)) |
drh | 4ac285a | 2006-09-15 07:28:50 +0000 | [diff] [blame] | 319 | |
| 320 | /* |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 321 | ** CAPI3REF: Flags For File Open Operations |
| 322 | ** |
| 323 | ** Combination of the following bit values are used as the |
| 324 | ** third argument to the [sqlite3_open_v2()] interface and |
| 325 | ** as fourth argument to the xOpen method of the |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 326 | ** [sqlite3_vfs] object. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 327 | ** |
| 328 | */ |
| 329 | #define SQLITE_OPEN_READONLY 0x00000001 |
| 330 | #define SQLITE_OPEN_READWRITE 0x00000002 |
| 331 | #define SQLITE_OPEN_CREATE 0x00000004 |
| 332 | #define SQLITE_OPEN_DELETEONCLOSE 0x00000008 |
| 333 | #define SQLITE_OPEN_EXCLUSIVE 0x00000010 |
| 334 | #define SQLITE_OPEN_MAIN_DB 0x00000100 |
| 335 | #define SQLITE_OPEN_TEMP_DB 0x00000200 |
| 336 | #define SQLITE_OPEN_MAIN_JOURNAL 0x00000300 |
| 337 | #define SQLITE_OPEN_TEMP_JOURNAL 0x00000400 |
| 338 | #define SQLITE_OPEN_SUBJOURNAL 0x00000500 |
| 339 | #define SQLITE_OPEN_MASTER_JOURNAL 0x00000600 |
| 340 | |
| 341 | /* |
| 342 | ** CAPI3REF: Device Characteristics |
| 343 | ** |
| 344 | ** The xDeviceCapabilities method of the [sqlite3_io_methods] |
| 345 | ** object returns an integer which is a vector of the following |
| 346 | ** bit values expressing I/O characteristics of the mass storage |
| 347 | ** device that holds the file that the [sqlite3_io_methods] |
| 348 | ** refers to. |
| 349 | ** |
| 350 | ** The SQLITE_IOCAP_ATOMIC property means that all writes of |
| 351 | ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values |
| 352 | ** mean that writes of blocks that are nnn bytes in size and |
| 353 | ** are aligned to an address which is an integer multiple of |
| 354 | ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means |
| 355 | ** that when data is appended to a file, the data is appended |
| 356 | ** first then the size of the file is extended, never the other |
| 357 | ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that |
| 358 | ** information is written to disk in the same order as calls |
| 359 | ** to xWrite(). |
| 360 | */ |
| 361 | #define SQLITE_IOCAP_ATOMIC 0x00000001 |
| 362 | #define SQLITE_IOCAP_ATOMIC512 0x00000002 |
| 363 | #define SQLITE_IOCAP_ATOMIC1K 0x00000004 |
| 364 | #define SQLITE_IOCAP_ATOMIC2K 0x00000008 |
| 365 | #define SQLITE_IOCAP_ATOMIC4K 0x00000010 |
| 366 | #define SQLITE_IOCAP_ATOMIC8K 0x00000020 |
| 367 | #define SQLITE_IOCAP_ATOMIC16K 0x00000040 |
| 368 | #define SQLITE_IOCAP_ATOMIC32K 0x00000080 |
| 369 | #define SQLITE_IOCAP_ATOMIC64K 0x00000100 |
| 370 | #define SQLITE_IOCAP_SAFE_APPEND 0x00000200 |
| 371 | #define SQLITE_IOCAP_SEQUENTIAL 0x00000400 |
| 372 | |
| 373 | /* |
| 374 | ** CAPI3REF: File Locking Levels |
| 375 | ** |
| 376 | ** SQLite uses one of the following integer values as the second |
| 377 | ** argument to calls it makes to the xLock() and xUnlock() methods |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 378 | ** of an [sqlite3_io_methods] object. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 379 | */ |
| 380 | #define SQLITE_LOCK_NONE 0 |
| 381 | #define SQLITE_LOCK_SHARED 1 |
| 382 | #define SQLITE_LOCK_RESERVED 2 |
| 383 | #define SQLITE_LOCK_PENDING 3 |
| 384 | #define SQLITE_LOCK_EXCLUSIVE 4 |
| 385 | |
| 386 | /* |
| 387 | ** CAPI3REF: Synchronization Type Flags |
| 388 | ** |
| 389 | ** When SQLite invokes the xSync() method of an [sqlite3_io_methods] |
| 390 | ** object it uses a combination of the following integer values as |
| 391 | ** the second argument. |
| 392 | ** |
| 393 | ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the |
| 394 | ** sync operation only needs to flush data to mass storage. Inode |
| 395 | ** information need not be flushed. The SQLITE_SYNC_BARRIER flag |
| 396 | ** means that the nothing actually needs to be synched to mass storage, |
| 397 | ** but all write operations that occur before the barrier must complete |
| 398 | ** before any write operations that occur after the barrier begin. |
| 399 | ** The SQLITE_SYNC_NORMAL means to use normal fsync() semantics. |
| 400 | ** The SQLITE_SYNC_FULL flag means to use Mac OS-X style fullsync |
| 401 | ** instead of fsync(). |
| 402 | */ |
| 403 | #define SQLITE_SYNC_BARRIER 0x00001 |
| 404 | #define SQLITE_SYNC_NORMAL 0x00002 |
| 405 | #define SQLITE_SYNC_FULL 0x00003 |
| 406 | #define SQLITE_SYNC_DATAONLY 0x00010 |
| 407 | |
| 408 | |
| 409 | /* |
| 410 | ** CAPI3REF: OS Interface Open File Handle |
| 411 | ** |
| 412 | ** An [sqlite3_file] object represents an open file in the OS |
| 413 | ** interface layer. Individual OS interface implementations will |
| 414 | ** want to subclass this object by appending additional fields |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 415 | ** of their own use. The pMethods entry is a pointer to an |
| 416 | ** [sqlite3_io_methods] object that defines methods for performing |
| 417 | ** I/O operations on the open file. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 418 | */ |
| 419 | typedef struct sqlite3_file sqlite3_file; |
| 420 | struct sqlite3_file { |
| 421 | struct sqlite3_io_methods *pMethods; /* Methods against the open file */ |
| 422 | }; |
| 423 | |
| 424 | /* |
| 425 | ** CAPI3REF: OS Interface File Virtual Methods Object |
| 426 | ** |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 427 | ** Every open file in the [sqlite3_vfs] xOpen method contains a pointer to |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 428 | ** an instance of the following object. This object defines the |
| 429 | ** methods used to perform various operations against the open file. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 430 | ** |
| 431 | ** The flags argument to xSync may be one of SQLITE_SYNC_BARRIER, |
| 432 | ** SQLITE_SYNC_NORMAL, SQLITE_SYNC_FULL. The first choice means that |
| 433 | ** data is not necessarily synced to disk completely, only that |
| 434 | ** all writes that occur before the sync complete before any |
| 435 | ** writes that occur after the sync. The second flag is the |
| 436 | ** normal fsync(). The third flag is a OS-X style fullsync. |
| 437 | ** The SQLITE_SYNC_DATA flag may be ORed in to indicate that only |
| 438 | ** the data of the file and not its inode needs to be synced. |
| 439 | ** |
| 440 | ** The integer values to xLock() and xUnlock() are one of |
| 441 | ** SQLITE_LOCK_NONE, SQLITE_LOCK_READ, SQLITE_LOCK_RESERVED, |
| 442 | ** SQLITE_LOCK_PENDING, or SQLITE_LOCK_EXCLUSIVE. xLock() |
| 443 | ** increases the lock. xUnlock() decreases the lock. |
| 444 | ** The xCheckReservedLock() method looks |
| 445 | ** to see if any database connection, either in this |
| 446 | ** process or in some other process, is holding an RESERVED, |
| 447 | ** PENDING, or EXCLUSIVE lock on the file. It returns true |
| 448 | ** if such a lock exists and false if not. |
| 449 | ** |
| 450 | ** xBreakLock() attempts to break a lock held by another process. |
| 451 | ** This can be used to remove a stale dot-file lock, for example. |
| 452 | ** It returns 0 on success and non-zero for a failure. |
| 453 | ** |
| 454 | ** The xSectorSize() method returns the sector size of the |
| 455 | ** device that underlies the file. The sector size is the |
| 456 | ** minimum write that can be performed without disturbing |
| 457 | ** other bytes in the file. The xDeviceCharacteristics() |
| 458 | ** method returns a bit vector describing behaviors of the |
| 459 | ** underlying device: |
| 460 | ** |
| 461 | ** <ul> |
| 462 | ** <li> SQLITE_IOCAP_ATOMIC |
| 463 | ** <li> SQLITE_IOCAP_ATOMIC512 |
| 464 | ** <li> SQLITE_IOCAP_ATOMIC1K |
| 465 | ** <li> SQLITE_IOCAP_ATOMIC2K |
| 466 | ** <li> SQLITE_IOCAP_ATOMIC4K |
| 467 | ** <li> SQLITE_IOCAP_ATOMIC8K |
| 468 | ** <li> SQLITE_IOCAP_ATOMIC16K |
| 469 | ** <li> SQLITE_IOCAP_ATOMIC32K |
| 470 | ** <li> SQLITE_IOCAP_ATOMIC64K |
| 471 | ** <li> SQLITE_IOCAP_SAFE_APPEND |
| 472 | ** <li> SQLITE_IOCAP_SEQUENTIAL |
| 473 | ** </ul> |
| 474 | ** |
| 475 | ** The SQLITE_IOCAP_ATOMIC property means that all writes of |
| 476 | ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values |
| 477 | ** mean that writes of blocks that are nnn bytes in size and |
| 478 | ** are aligned to an address which is an integer multiple of |
| 479 | ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means |
| 480 | ** that when data is appended to a file, the data is appended |
| 481 | ** first then the size of the file is extended, never the other |
| 482 | ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that |
| 483 | ** information is written to disk in the same order as calls |
| 484 | ** to xWrite(). |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 485 | */ |
| 486 | typedef struct sqlite3_io_methods sqlite3_io_methods; |
| 487 | struct sqlite3_io_methods { |
| 488 | int iVersion; |
| 489 | int (*xClose)(sqlite3_file*); |
| 490 | int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite_int64 iOfst); |
danielk1977 | 6207906 | 2007-08-15 17:08:46 +0000 | [diff] [blame] | 491 | int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite_int64 iOfst); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 492 | int (*xTruncate)(sqlite3_file*, sqlite_int64 size); |
| 493 | int (*xSync)(sqlite3_file*, int flags); |
| 494 | int (*xFileSize)(sqlite3_file*, sqlite_int64 *pSize); |
| 495 | int (*xLock)(sqlite3_file*, int); |
| 496 | int (*xUnlock)(sqlite3_file*, int); |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 497 | int (*xCheckReservedLock)(sqlite3_file*); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 498 | int (*xBreakLock)(sqlite3_file*); |
danielk1977 | 90949c2 | 2007-08-17 16:50:38 +0000 | [diff] [blame] | 499 | int (*xLockState)(sqlite3_file *); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 500 | int (*xSectorSize)(sqlite3_file*); |
| 501 | int (*xDeviceCharacteristics)(sqlite3_file*); |
| 502 | /* Additional methods may be added in future releases */ |
| 503 | }; |
| 504 | |
| 505 | /* |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 506 | ** CAPI3REF: Mutex Handle |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 507 | ** |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 508 | ** The mutex module within SQLite defines [sqlite3_mutex] to be an |
| 509 | ** abstract type for a mutex object. The SQLite core never looks |
| 510 | ** at the internal representation of an [sqlite3_mutex]. It only |
| 511 | ** deals with pointers to the [sqlite3_mutex] object. |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 512 | ** |
| 513 | ** Mutexes are created using [sqlite3_mutex_alloc()]. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 514 | */ |
| 515 | typedef struct sqlite3_mutex sqlite3_mutex; |
| 516 | |
| 517 | /* |
| 518 | ** CAPI3REF: OS Interface Object |
| 519 | ** |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 520 | ** An instance of this object defines the interface between the |
| 521 | ** SQLite core and the underlying operating system. The "vfs" |
| 522 | ** in the name of the object stands for "virtual file system". |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 523 | ** |
| 524 | ** The iVersion field is initially 1 but may be larger for future |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 525 | ** versions of SQLite. Additional fields may be appended to this |
| 526 | ** object when the iVersion value is increased. |
| 527 | ** |
| 528 | ** The szOsFile field is the size of the subclassed sqlite3_file |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 529 | ** structure used by this VFS. mxPathname is the maximum length of |
| 530 | ** a pathname in this VFS. |
| 531 | ** |
| 532 | ** The nRef field is incremented and decremented by SQLite to keep |
| 533 | ** count of the number of users of the VFS. This field and |
| 534 | ** vfsMutex, pNext, and pPrev are the only fields in the sqlite3_vfs |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 535 | ** structure that SQLite will ever modify. SQLite will only access |
| 536 | ** or modify these fields while holding a particular static mutex. |
| 537 | ** The application should never modify any fields of the sqlite3_vfs |
| 538 | ** object once the object has been registered. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 539 | ** |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 540 | ** The sqlite3_vfs.vfsMutex is a mutex used by the OS interface. |
| 541 | ** It should initially be NULL. SQLite will initialize this field |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 542 | ** using sqlite3_mutex_alloc() upon first use of the adaptor |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 543 | ** by sqlite3_open_v2() and will deallocate the mutex when the |
| 544 | ** last user closes. In other words, vfsMutex will be allocated |
| 545 | ** when nRef transitions from 0 to 1 and will be deallocated when |
| 546 | ** nRef transitions from 1 to 0. |
| 547 | ** |
| 548 | ** Registered vfs modules are kept on a linked list formed by |
| 549 | ** the pNext and pPrev pointers. The [sqlite3_register_vfs()] |
| 550 | ** and [sqlite3_unregister_vfs()] interfaces manage this list |
drh | d677b3d | 2007-08-20 22:48:41 +0000 | [diff] [blame] | 551 | ** in a thread-safe way. The [sqlite3_acquire_vfs()] searches the |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 552 | ** list. |
| 553 | ** |
| 554 | ** The zName field holds the name of the VFS module. The name must |
| 555 | ** be unique across all VFS modules. |
| 556 | ** |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 557 | ** SQLite will guarantee that the zFilename string passed to |
| 558 | ** xOpen() is a full pathname as generated by xFullPathname() and |
| 559 | ** that the string will be valid and unchanged until xClose() is |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 560 | ** called. So the sqlite3_file can store a pointer to the |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 561 | ** filename if it needs to remember the filename for some reason. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 562 | ** |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 563 | ** The flags argument to xOpen() is a copy of the flags argument |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 564 | ** to sqlite3_open_v2(). If sqlite3_open() or sqlite3_open16() |
| 565 | ** is used, then flags is SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 566 | ** If xOpen() opens a file read-only then it sets *pOutFlags to |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 567 | ** include SQLITE_OPEN_READONLY. Other bits in *pOutFlags may be |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 568 | ** set. |
| 569 | ** |
| 570 | ** SQLite will also add one of the following flags to the xOpen() |
| 571 | ** call, depending on the object being opened: |
| 572 | ** |
| 573 | ** <ul> |
| 574 | ** <li> [SQLITE_OPEN_MAIN_DB] |
| 575 | ** <li> [SQLITE_OPEN_MAIN_JOURNAL] |
| 576 | ** <li> [SQLITE_OPEN_TEMP_DB] |
| 577 | ** <li> [SQLITE_OPEN_TEMP_JOURNAL] |
| 578 | ** <li> [SQLITE_OPEN_SUBJOURNAL] |
| 579 | ** <li> [SQLITE_OPEN_MASTER_JOURNAL] |
| 580 | ** </ul> |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 581 | ** |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 582 | ** The file I/O implementation can use the object type flags to |
| 583 | ** changes the way it deals with files. For example, an application |
| 584 | ** that does not care about crash recovery or rollback, might make |
| 585 | ** the open of a journal file a no-op. Writes to this journal are |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 586 | ** also a no-op. Any attempt to read the journal return SQLITE_IOERR. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 587 | ** Or the implementation might recognize the a database file will |
| 588 | ** be doing page-aligned sector reads and writes in a random order |
| 589 | ** and set up its I/O subsystem accordingly. |
| 590 | ** |
| 591 | ** SQLite might also add one of the following flags to the xOpen |
| 592 | ** method: |
| 593 | ** |
| 594 | ** <ul> |
| 595 | ** <li> [SQLITE_OPEN_DELETEONCLOSE] |
| 596 | ** <li> [SQLITE_OPEN_EXCLUSIVE] |
| 597 | ** </ul> |
| 598 | ** |
| 599 | ** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be |
| 600 | ** deleted when it is closed. This will always be set for TEMP |
| 601 | ** databases and journals and for subjournals. The |
| 602 | ** [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened |
| 603 | ** for exclusive access. This flag is set for all files except |
| 604 | ** for the main database file. |
| 605 | ** |
| 606 | ** The sqlite3_file structure passed as the third argument to |
| 607 | ** xOpen is allocated by the caller. xOpen just fills it in. The |
| 608 | ** caller allocates a minimum of szOsFile bytes for the sqlite3_file |
| 609 | ** structure. |
| 610 | ** |
| 611 | ** The flags argument to xAccess() may be 0 (to test for the |
| 612 | ** existance of a file) or SQLITE_ACCESS_READWRITE to test to see |
| 613 | ** if a file is readable and writable, or SQLITE_ACCESS_READONLY |
| 614 | ** to test to see if a file is read-only. The file can be a |
| 615 | ** directory. |
| 616 | ** |
| 617 | ** SQLite will always allocate at least mxPathname+1 byte for |
| 618 | ** the output buffers for xGetTempName and xFullPathname. |
| 619 | ** |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 620 | ** The xRandomness(), xSleep(), and xCurrentTime() interfaces |
| 621 | ** are not strictly a part of the filesystem, but they are |
| 622 | ** included in the VFS structure for completeness. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 623 | ** The xRandomness() function attempts to return nBytes bytes |
| 624 | ** of good-quality randomness into zOut. The return value is |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 625 | ** the actual number of bytes of randomness generated. The |
| 626 | ** xSleep() method cause the calling thread to sleep for at |
| 627 | ** least the number of microseconds given. The xCurrentTime() |
| 628 | ** method returns a Julian Day Number for the current date and |
| 629 | ** time. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 630 | */ |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 631 | typedef struct sqlite3_vfs sqlite3_vfs; |
| 632 | struct sqlite3_vfs { |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 633 | int iVersion; /* Structure version number */ |
| 634 | int szOsFile; /* Size of subclassed sqlite3_file */ |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 635 | int mxPathname; /* Maximum file pathname length */ |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 636 | int nRef; /* Number of references to this structure */ |
| 637 | sqlite3_mutex *vfsMutex; /* A mutex for this VFS */ |
| 638 | sqlite3_vfs *pNext; /* Next registered VFS */ |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 639 | const char *zName; /* Name of this virtual file system */ |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 640 | void *pAppData; /* Application context */ |
| 641 | int (*xOpen)(void *pAppData, const char *zName, sqlite3_file*, |
| 642 | int flags, int *pOutFlags); |
danielk1977 | fee2d25 | 2007-08-18 10:59:19 +0000 | [diff] [blame] | 643 | int (*xDelete)(void *pAppData, const char *zName, int syncDir); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 644 | int (*xAccess)(void *pAppData, const char *zName, int flags); |
| 645 | int (*xGetTempName)(void *pAppData, char *zOut); |
| 646 | int (*xFullPathname)(void *pAppData, const char *zName, char *zOut); |
danielk1977 | b4b4741 | 2007-08-17 15:53:36 +0000 | [diff] [blame] | 647 | void *(*xDlOpen)(void *pAppData, const char *zFilename); |
| 648 | void (*xDlError)(void *pAppData, int nByte, char *zErrMsg); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 649 | void *(*xDlSym)(void*, const char *zSymbol); |
danielk1977 | b4b4741 | 2007-08-17 15:53:36 +0000 | [diff] [blame] | 650 | void (*xDlClose)(void*); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 651 | int (*xRandomness)(void *pAppData, int nByte, char *zOut); |
| 652 | int (*xSleep)(void *pAppData, int microseconds); |
| 653 | int (*xCurrentTime)(void *pAppData, double*); |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 654 | /* New fields may be appended in figure versions. The iVersion |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 655 | ** value will increment whenever this happens. */ |
| 656 | }; |
| 657 | |
danielk1977 | b4b4741 | 2007-08-17 15:53:36 +0000 | [diff] [blame] | 658 | #define SQLITE_ACCESS_EXISTS 0 |
| 659 | #define SQLITE_ACCESS_READWRITE 1 |
| 660 | #define SQLITE_ACCESS_READONLY 2 |
| 661 | |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 662 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 663 | ** CAPI3REF: Enable Or Disable Extended Result Codes |
| 664 | ** |
| 665 | ** This routine enables or disables the |
| 666 | ** [SQLITE_IOERR_READ | extended result codes] feature. |
| 667 | ** By default, SQLite API routines return one of only 26 integer |
| 668 | ** [SQLITE_OK | result codes]. When extended result codes |
| 669 | ** are enabled by this routine, the repetoire of result codes can be |
| 670 | ** much larger and can (hopefully) provide more detailed information |
| 671 | ** about the cause of an error. |
| 672 | ** |
| 673 | ** The second argument is a boolean value that turns extended result |
| 674 | ** codes on and off. Extended result codes are off by default for |
| 675 | ** backwards compatibility with older versions of SQLite. |
drh | 4ac285a | 2006-09-15 07:28:50 +0000 | [diff] [blame] | 676 | */ |
| 677 | int sqlite3_extended_result_codes(sqlite3*, int onoff); |
| 678 | |
| 679 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 680 | ** CAPI3REF: Last Insert Rowid |
| 681 | ** |
| 682 | ** Each entry in an SQLite table has a unique 64-bit signed integer key |
| 683 | ** called the "rowid". The rowid is always available as an undeclared |
| 684 | ** column named ROWID, OID, or _ROWID_. If the table has a column of |
| 685 | ** type INTEGER PRIMARY KEY then that column is another an alias for the |
| 686 | ** rowid. |
| 687 | ** |
| 688 | ** This routine returns the rowid of the most recent INSERT into |
| 689 | ** the database from the database connection given in the first |
| 690 | ** argument. If no inserts have ever occurred on this database |
| 691 | ** connection, zero is returned. |
| 692 | ** |
| 693 | ** If an INSERT occurs within a trigger, then the rowid of the |
| 694 | ** inserted row is returned by this routine as long as the trigger |
| 695 | ** is running. But once the trigger terminates, the value returned |
| 696 | ** by this routine reverts to the last value inserted before the |
| 697 | ** trigger fired. |
drh | af9ff33 | 2002-01-16 21:00:27 +0000 | [diff] [blame] | 698 | */ |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 699 | sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); |
drh | af9ff33 | 2002-01-16 21:00:27 +0000 | [diff] [blame] | 700 | |
drh | c8d30ac | 2002-04-12 10:08:59 +0000 | [diff] [blame] | 701 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 702 | ** CAPI3REF: Count The Number Of Rows Modified |
| 703 | ** |
drh | c8d30ac | 2002-04-12 10:08:59 +0000 | [diff] [blame] | 704 | ** This function returns the number of database rows that were changed |
drh | 930cc58 | 2007-03-28 13:07:40 +0000 | [diff] [blame] | 705 | ** (or inserted or deleted) by the most recent SQL statement. Only |
| 706 | ** changes that are directly specified by the INSERT, UPDATE, or |
| 707 | ** DELETE statement are counted. Auxiliary changes caused by |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 708 | ** triggers are not counted. Use the [sqlite3_total_changes()] function |
| 709 | ** to find the total number of changes including changes caused by triggers. |
| 710 | ** |
| 711 | ** Within the body of a trigger, the sqlite3_changes() interface can be |
| 712 | ** called to find the number of |
drh | 930cc58 | 2007-03-28 13:07:40 +0000 | [diff] [blame] | 713 | ** changes in the most recently completed INSERT, UPDATE, or DELETE |
| 714 | ** statement within the body of the trigger. |
drh | c8d30ac | 2002-04-12 10:08:59 +0000 | [diff] [blame] | 715 | ** |
| 716 | ** All changes are counted, even if they were later undone by a |
| 717 | ** ROLLBACK or ABORT. Except, changes associated with creating and |
| 718 | ** dropping tables are not counted. |
| 719 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 720 | ** If a callback invokes [sqlite3_exec()] or [sqlite3_step()] recursively, |
drh | 930cc58 | 2007-03-28 13:07:40 +0000 | [diff] [blame] | 721 | ** then the changes in the inner, recursive call are counted together |
| 722 | ** with the changes in the outer call. |
drh | c8d30ac | 2002-04-12 10:08:59 +0000 | [diff] [blame] | 723 | ** |
| 724 | ** SQLite implements the command "DELETE FROM table" without a WHERE clause |
| 725 | ** by dropping and recreating the table. (This is much faster than going |
drh | a6b81ba | 2007-06-27 10:21:38 +0000 | [diff] [blame] | 726 | ** through and deleting individual elements from the table.) Because of |
drh | c8d30ac | 2002-04-12 10:08:59 +0000 | [diff] [blame] | 727 | ** this optimization, the change count for "DELETE FROM table" will be |
| 728 | ** zero regardless of the number of elements that were originally in the |
| 729 | ** table. To get an accurate count of the number of rows deleted, use |
| 730 | ** "DELETE FROM table WHERE 1" instead. |
| 731 | */ |
danielk1977 | f9d64d2 | 2004-06-19 08:18:07 +0000 | [diff] [blame] | 732 | int sqlite3_changes(sqlite3*); |
drh | c8d30ac | 2002-04-12 10:08:59 +0000 | [diff] [blame] | 733 | |
rdc | f146a77 | 2004-02-25 22:51:06 +0000 | [diff] [blame] | 734 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 735 | ** CAPI3REF: Total Number Of Rows Modified |
| 736 | *** |
danielk1977 | b28af71 | 2004-06-21 06:50:26 +0000 | [diff] [blame] | 737 | ** This function returns the number of database rows that have been |
| 738 | ** modified by INSERT, UPDATE or DELETE statements since the database handle |
| 739 | ** was opened. This includes UPDATE, INSERT and DELETE statements executed |
| 740 | ** as part of trigger programs. All changes are counted as soon as the |
| 741 | ** statement that makes them is completed (when the statement handle is |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 742 | ** passed to [sqlite3_reset()] or [sqlite3_finalise()]). |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 743 | ** |
| 744 | ** See also the [sqlite3_change()] interface. |
rdc | f146a77 | 2004-02-25 22:51:06 +0000 | [diff] [blame] | 745 | ** |
| 746 | ** SQLite implements the command "DELETE FROM table" without a WHERE clause |
| 747 | ** by dropping and recreating the table. (This is much faster than going |
| 748 | ** through and deleting individual elements form the table.) Because of |
| 749 | ** this optimization, the change count for "DELETE FROM table" will be |
| 750 | ** zero regardless of the number of elements that were originally in the |
| 751 | ** table. To get an accurate count of the number of rows deleted, use |
| 752 | ** "DELETE FROM table WHERE 1" instead. |
rdc | f146a77 | 2004-02-25 22:51:06 +0000 | [diff] [blame] | 753 | */ |
danielk1977 | b28af71 | 2004-06-21 06:50:26 +0000 | [diff] [blame] | 754 | int sqlite3_total_changes(sqlite3*); |
| 755 | |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 756 | /* |
| 757 | ** CAPI3REF: Interrupt A Long-Running Query |
| 758 | ** |
| 759 | ** This function causes any pending database operation to abort and |
drh | 4c50439 | 2000-10-16 22:06:40 +0000 | [diff] [blame] | 760 | ** return at its earliest opportunity. This routine is typically |
drh | 66b89c8 | 2000-11-28 20:47:17 +0000 | [diff] [blame] | 761 | ** called in response to a user action such as pressing "Cancel" |
drh | 4c50439 | 2000-10-16 22:06:40 +0000 | [diff] [blame] | 762 | ** or Ctrl-C where the user wants a long query operation to halt |
| 763 | ** immediately. |
drh | 930cc58 | 2007-03-28 13:07:40 +0000 | [diff] [blame] | 764 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 765 | ** It is safe to call this routine from a thread different from the |
drh | 871f6ca | 2007-08-14 18:03:14 +0000 | [diff] [blame] | 766 | ** thread that is currently running the database operation. But it |
| 767 | ** is not safe to call this routine with a database connection that |
| 768 | ** is closed or might close before sqlite3_interrupt() returns. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 769 | ** |
| 770 | ** The SQL operation that is interrupted will return [SQLITE_INTERRUPT]. |
| 771 | ** If an interrupted operation was an update that is inside an |
| 772 | ** explicit transaction, then the entire transaction will be rolled |
| 773 | ** back automatically. |
drh | 4c50439 | 2000-10-16 22:06:40 +0000 | [diff] [blame] | 774 | */ |
danielk1977 | f9d64d2 | 2004-06-19 08:18:07 +0000 | [diff] [blame] | 775 | void sqlite3_interrupt(sqlite3*); |
drh | 4c50439 | 2000-10-16 22:06:40 +0000 | [diff] [blame] | 776 | |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 777 | /* |
| 778 | ** CAPI3REF: Determine If An SQL Statement Is Complete |
| 779 | ** |
| 780 | ** These functions return true if the given input string comprises |
danielk1977 | 61de0d1 | 2004-05-27 23:56:16 +0000 | [diff] [blame] | 781 | ** one or more complete SQL statements. For the sqlite3_complete() call, |
| 782 | ** the parameter must be a nul-terminated UTF-8 string. For |
| 783 | ** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string |
| 784 | ** is required. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 785 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 786 | ** These routines are useful for command-line input to determine if the |
| 787 | ** currently entered text forms one or more complete SQL statements or |
| 788 | ** if additional input is needed before sending the statements into |
| 789 | ** SQLite for parsing. The algorithm is simple. If the |
drh | 930cc58 | 2007-03-28 13:07:40 +0000 | [diff] [blame] | 790 | ** last token other than spaces and comments is a semicolon, then return |
| 791 | ** true. Actually, the algorithm is a little more complicated than that |
| 792 | ** in order to deal with triggers, but the basic idea is the same: the |
| 793 | ** statement is not complete unless it ends in a semicolon. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 794 | */ |
danielk1977 | 6f8a503 | 2004-05-10 10:34:51 +0000 | [diff] [blame] | 795 | int sqlite3_complete(const char *sql); |
danielk1977 | 61de0d1 | 2004-05-27 23:56:16 +0000 | [diff] [blame] | 796 | int sqlite3_complete16(const void *sql); |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 797 | |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 798 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 799 | ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors |
| 800 | ** |
| 801 | ** This routine identifies a callback function that might be invoked |
| 802 | ** whenever an attempt is made to open a database table |
| 803 | ** that another thread or process has locked. |
| 804 | ** If the busy callback is NULL, then [SQLITE_BUSY] |
| 805 | ** (or sometimes [SQLITE_IOERR_BLOCKED]) |
| 806 | ** is returned immediately upon encountering the lock. |
| 807 | ** If the busy callback is not NULL, then the |
| 808 | ** callback will be invoked with two arguments. The |
drh | 86939b5 | 2007-01-10 12:54:51 +0000 | [diff] [blame] | 809 | ** first argument to the handler is a copy of the void* pointer which |
| 810 | ** is the third argument to this routine. The second argument to |
| 811 | ** the handler is the number of times that the busy handler has |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 812 | ** been invoked for this locking event. If the |
| 813 | ** busy callback returns 0, then no additional attempts are made to |
| 814 | ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned. |
| 815 | ** If the callback returns non-zero, then another attempt is made to open the |
| 816 | ** database for reading and the cycle repeats. |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 817 | ** |
drh | 86939b5 | 2007-01-10 12:54:51 +0000 | [diff] [blame] | 818 | ** The presence of a busy handler does not guarantee that |
| 819 | ** it will be invoked when there is lock contention. |
| 820 | ** If SQLite determines that invoking the busy handler could result in |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 821 | ** a deadlock, it will return [SQLITE_BUSY] instead. |
drh | 86939b5 | 2007-01-10 12:54:51 +0000 | [diff] [blame] | 822 | ** Consider a scenario where one process is holding a read lock that |
| 823 | ** it is trying to promote to a reserved lock and |
| 824 | ** a second process is holding a reserved lock that it is trying |
| 825 | ** to promote to an exclusive lock. The first process cannot proceed |
| 826 | ** because it is blocked by the second and the second process cannot |
| 827 | ** proceed because it is blocked by the first. If both processes |
| 828 | ** invoke the busy handlers, neither will make any progress. Therefore, |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 829 | ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this |
drh | 86939b5 | 2007-01-10 12:54:51 +0000 | [diff] [blame] | 830 | ** will induce the first process to release its read lock and allow |
| 831 | ** the second process to proceed. |
| 832 | ** |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 833 | ** The default busy callback is NULL. |
| 834 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 835 | ** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED] when |
| 836 | ** SQLite is in the middle of a large transaction where all the |
| 837 | ** changes will not fit into the in-memory cache. SQLite will |
| 838 | ** already hold a RESERVED lock on the database file, but it needs |
| 839 | ** to promote this lock to EXCLUSIVE so that it can spill cache |
| 840 | ** pages into the database file without harm to concurrent |
| 841 | ** readers. If it is unable to promote the lock, then the in-memory |
| 842 | ** cache will be left in an inconsistent state and so the error |
| 843 | ** code is promoted from the relatively benign [SQLITE_BUSY] to |
| 844 | ** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion |
| 845 | ** forces an automatic rollback of the changes. See the |
| 846 | ** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError"> |
| 847 | ** CorruptionFollowingBusyError</a> wiki page for a discussion of why |
| 848 | ** this is important. |
| 849 | ** |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 850 | ** Sqlite is re-entrant, so the busy handler may start a new query. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 851 | ** (It is not clear why anyone would every want to do this, but it |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 852 | ** is allowed, in theory.) But the busy handler may not close the |
| 853 | ** database. Closing the database from a busy handler will delete |
| 854 | ** data structures out from under the executing query and will |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 855 | ** probably result in a segmentation fault or other runtime error. |
| 856 | ** |
| 857 | ** There can only be a single busy handler defined for each database |
| 858 | ** connection. Setting a new busy handler clears any previous one. |
| 859 | ** Note that calling [sqlite3_busy_timeout()] will also set or clear |
| 860 | ** the busy handler. |
drh | d677b3d | 2007-08-20 22:48:41 +0000 | [diff] [blame] | 861 | ** |
| 862 | ** When operating in [sqlite3_enable_shared_cache | shared cache mode], |
| 863 | ** only a single busy handler can be defined for each database file. |
| 864 | ** So if two database connections share a single cache, then changing |
| 865 | ** the busy handler on one connection will also change the busy |
| 866 | ** handler in the other connection. The busy handler is invoked |
| 867 | ** in the thread that was running when the SQLITE_BUSY was hit. |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 868 | */ |
danielk1977 | f9d64d2 | 2004-06-19 08:18:07 +0000 | [diff] [blame] | 869 | int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 870 | |
| 871 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 872 | ** CAPI3REF: Set A Busy Timeout |
| 873 | ** |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 874 | ** This routine sets a busy handler that sleeps for a while when a |
| 875 | ** table is locked. The handler will sleep multiple times until |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 876 | ** at least "ms" milliseconds of sleeping have been done. After |
| 877 | ** "ms" milliseconds of sleeping, the handler returns 0 which |
| 878 | ** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]. |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 879 | ** |
| 880 | ** Calling this routine with an argument less than or equal to zero |
| 881 | ** turns off all busy handlers. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 882 | ** |
| 883 | ** There can only be a single busy handler for a particular database |
| 884 | ** connection. If another busy handler was defined |
| 885 | ** (using [sqlite3_busy_handler()]) prior to calling |
| 886 | ** this routine, that other busy handler is cleared. |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 887 | */ |
danielk1977 | f9d64d2 | 2004-06-19 08:18:07 +0000 | [diff] [blame] | 888 | int sqlite3_busy_timeout(sqlite3*, int ms); |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 889 | |
drh | e371033 | 2000-09-29 13:30:53 +0000 | [diff] [blame] | 890 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 891 | ** CAPI3REF: Convenience Routines For Running Queries |
| 892 | ** |
| 893 | ** This next routine is a convenience wrapper around [sqlite3_exec()]. |
drh | e371033 | 2000-09-29 13:30:53 +0000 | [diff] [blame] | 894 | ** Instead of invoking a user-supplied callback for each row of the |
| 895 | ** result, this routine remembers each row of the result in memory |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 896 | ** obtained from [sqlite3_malloc()], then returns all of the result after the |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 897 | ** query has finished. |
| 898 | ** |
| 899 | ** As an example, suppose the query result where this table: |
| 900 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 901 | ** <pre> |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 902 | ** Name | Age |
| 903 | ** ----------------------- |
| 904 | ** Alice | 43 |
| 905 | ** Bob | 28 |
| 906 | ** Cindy | 21 |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 907 | ** </pre> |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 908 | ** |
| 909 | ** If the 3rd argument were &azResult then after the function returns |
drh | 98699b5 | 2000-10-09 12:57:00 +0000 | [diff] [blame] | 910 | ** azResult will contain the following data: |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 911 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 912 | ** <pre> |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 913 | ** azResult[0] = "Name"; |
| 914 | ** azResult[1] = "Age"; |
| 915 | ** azResult[2] = "Alice"; |
| 916 | ** azResult[3] = "43"; |
| 917 | ** azResult[4] = "Bob"; |
| 918 | ** azResult[5] = "28"; |
| 919 | ** azResult[6] = "Cindy"; |
| 920 | ** azResult[7] = "21"; |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 921 | ** </pre> |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 922 | ** |
| 923 | ** Notice that there is an extra row of data containing the column |
| 924 | ** headers. But the *nrow return value is still 3. *ncolumn is |
| 925 | ** set to 2. In general, the number of values inserted into azResult |
| 926 | ** will be ((*nrow) + 1)*(*ncolumn). |
| 927 | ** |
| 928 | ** After the calling function has finished using the result, it should |
danielk1977 | 6f8a503 | 2004-05-10 10:34:51 +0000 | [diff] [blame] | 929 | ** pass the result data pointer to sqlite3_free_table() in order to |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 930 | ** release the memory that was malloc-ed. Because of the way the |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 931 | ** [sqlite3_malloc()] happens, the calling function must not try to call |
| 932 | ** [sqlite3_free()] directly. Only [sqlite3_free_table()] is able to release |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 933 | ** the memory properly and safely. |
drh | e371033 | 2000-09-29 13:30:53 +0000 | [diff] [blame] | 934 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 935 | ** The return value of this routine is the same as from [sqlite3_exec()]. |
drh | e371033 | 2000-09-29 13:30:53 +0000 | [diff] [blame] | 936 | */ |
danielk1977 | 6f8a503 | 2004-05-10 10:34:51 +0000 | [diff] [blame] | 937 | int sqlite3_get_table( |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 938 | sqlite3*, /* An open database */ |
drh | 9f71c2e | 2001-11-03 23:57:09 +0000 | [diff] [blame] | 939 | const char *sql, /* SQL to be executed */ |
drh | e371033 | 2000-09-29 13:30:53 +0000 | [diff] [blame] | 940 | char ***resultp, /* Result written to a char *[] that this points to */ |
| 941 | int *nrow, /* Number of result rows written here */ |
| 942 | int *ncolumn, /* Number of result columns written here */ |
| 943 | char **errmsg /* Error msg written here */ |
| 944 | ); |
danielk1977 | 6f8a503 | 2004-05-10 10:34:51 +0000 | [diff] [blame] | 945 | void sqlite3_free_table(char **result); |
drh | e371033 | 2000-09-29 13:30:53 +0000 | [diff] [blame] | 946 | |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 947 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 948 | ** CAPI3REF: Formatted String Printing Functions |
| 949 | ** |
| 950 | ** These routines are workalikes of the "printf()" family of functions |
| 951 | ** from the standard C library. |
| 952 | ** |
| 953 | ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 954 | ** results into memory obtained from [sqlite3_malloc()]. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 955 | ** The strings returned by these two routines should be |
| 956 | ** released by [sqlite3_free()]. Both routines return a |
| 957 | ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough |
| 958 | ** memory to hold the resulting string. |
| 959 | ** |
| 960 | ** In sqlite3_snprintf() routine is similar to "snprintf()" from |
| 961 | ** the standard C library. The result is written into the |
| 962 | ** buffer supplied as the second parameter whose size is given by |
| 963 | ** the first parameter. Note that the order of the |
| 964 | ** first two parameters is reversed from snprintf(). This is an |
| 965 | ** historical accident that cannot be fixed without breaking |
| 966 | ** backwards compatibility. Note also that sqlite3_snprintf() |
| 967 | ** returns a pointer to its buffer instead of the number of |
| 968 | ** characters actually written into the buffer. We admit that |
| 969 | ** the number of characters written would be a more useful return |
| 970 | ** value but we cannot change the implementation of sqlite3_snprintf() |
| 971 | ** now without breaking compatibility. |
| 972 | ** |
| 973 | ** As long as the buffer size is greater than zero, sqlite3_snprintf() |
| 974 | ** guarantees that the buffer is always zero-terminated. The first |
| 975 | ** parameter "n" is the total size of the buffer, including space for |
| 976 | ** the zero terminator. So the longest string that can be completely |
| 977 | ** written will be n-1 characters. |
| 978 | ** |
| 979 | ** These routines all implement some additional formatting |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 980 | ** options that are useful for constructing SQL statements. |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 981 | ** All of the usual printf formatting options apply. In addition, there |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 982 | ** is are "%q" and "%Q" options. |
| 983 | ** |
| 984 | ** The %q option works like %s in that it substitutes a null-terminated |
drh | 66b89c8 | 2000-11-28 20:47:17 +0000 | [diff] [blame] | 985 | ** string from the argument list. But %q also doubles every '\'' character. |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 986 | ** %q is designed for use inside a string literal. By doubling each '\'' |
drh | 66b89c8 | 2000-11-28 20:47:17 +0000 | [diff] [blame] | 987 | ** character it escapes that character and allows it to be inserted into |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 988 | ** the string. |
| 989 | ** |
| 990 | ** For example, so some string variable contains text as follows: |
| 991 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 992 | ** <blockquote><pre> |
| 993 | ** char *zText = "It's a happy day!"; |
| 994 | ** </pre></blockquote> |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 995 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 996 | ** One can use this text in an SQL statement as follows: |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 997 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 998 | ** <blockquote><pre> |
| 999 | ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText); |
| 1000 | ** sqlite3_exec(db, zSQL, 0, 0, 0); |
| 1001 | ** sqlite3_free(zSQL); |
| 1002 | ** </pre></blockquote> |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1003 | ** |
| 1004 | ** Because the %q format string is used, the '\'' character in zText |
| 1005 | ** is escaped and the SQL generated is as follows: |
| 1006 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1007 | ** <blockquote><pre> |
| 1008 | ** INSERT INTO table1 VALUES('It''s a happy day!') |
| 1009 | ** </pre></blockquote> |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1010 | ** |
| 1011 | ** This is correct. Had we used %s instead of %q, the generated SQL |
| 1012 | ** would have looked like this: |
| 1013 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1014 | ** <blockquote><pre> |
| 1015 | ** INSERT INTO table1 VALUES('It's a happy day!'); |
| 1016 | ** </pre></blockquote> |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1017 | ** |
| 1018 | ** This second example is an SQL syntax error. As a general rule you |
| 1019 | ** should always use %q instead of %s when inserting text into a string |
| 1020 | ** literal. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1021 | ** |
| 1022 | ** The %Q option works like %q except it also adds single quotes around |
| 1023 | ** the outside of the total string. Or if the parameter in the argument |
| 1024 | ** list is a NULL pointer, %Q substitutes the text "NULL" (without single |
| 1025 | ** quotes) in place of the %Q option. So, for example, one could say: |
| 1026 | ** |
| 1027 | ** <blockquote><pre> |
| 1028 | ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText); |
| 1029 | ** sqlite3_exec(db, zSQL, 0, 0, 0); |
| 1030 | ** sqlite3_free(zSQL); |
| 1031 | ** </pre></blockquote> |
| 1032 | ** |
| 1033 | ** The code above will render a correct SQL statement in the zSQL |
| 1034 | ** variable even if the zText variable is a NULL pointer. |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1035 | */ |
danielk1977 | 6f8a503 | 2004-05-10 10:34:51 +0000 | [diff] [blame] | 1036 | char *sqlite3_mprintf(const char*,...); |
| 1037 | char *sqlite3_vmprintf(const char*, va_list); |
drh | feac5f8 | 2004-08-01 00:10:45 +0000 | [diff] [blame] | 1038 | char *sqlite3_snprintf(int,char*,const char*, ...); |
drh | 5191b7e | 2002-03-08 02:12:00 +0000 | [diff] [blame] | 1039 | |
drh | 28dd479 | 2006-06-26 21:35:44 +0000 | [diff] [blame] | 1040 | /* |
drh | 90f6a5b | 2007-08-15 13:04:54 +0000 | [diff] [blame] | 1041 | ** CAPI3REF: Memory Allocation Subsystem |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 1042 | ** |
| 1043 | ** The SQLite core uses these three routines for all of its own |
| 1044 | ** internal memory allocation needs. The default implementation |
| 1045 | ** of the memory allocation subsystem uses the malloc(), realloc() |
| 1046 | ** and free() provided by the standard C library. However, if |
| 1047 | ** SQLite is compiled with the following C preprocessor macro |
| 1048 | ** |
drh | 90f6a5b | 2007-08-15 13:04:54 +0000 | [diff] [blame] | 1049 | ** <blockquote> SQLITE_OMIT_MEMORY_ALLOCATION </blockquote> |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 1050 | ** |
| 1051 | ** then no implementation is provided for these routines by |
| 1052 | ** SQLite. The application that links against SQLite is |
| 1053 | ** expected to provide its own implementation. |
drh | 28dd479 | 2006-06-26 21:35:44 +0000 | [diff] [blame] | 1054 | */ |
drh | 90f6a5b | 2007-08-15 13:04:54 +0000 | [diff] [blame] | 1055 | void *sqlite3_malloc(unsigned int); |
| 1056 | void *sqlite3_realloc(void*, unsigned int); |
drh | 28dd479 | 2006-06-26 21:35:44 +0000 | [diff] [blame] | 1057 | void sqlite3_free(void*); |
| 1058 | |
drh | 5191b7e | 2002-03-08 02:12:00 +0000 | [diff] [blame] | 1059 | /* |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 1060 | ** CAPI3REF: Memory Allocator Statistics |
| 1061 | ** |
| 1062 | ** In addition to the basic three allocation routines |
| 1063 | ** [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()], |
| 1064 | ** the memory allocation subsystem included with the SQLite |
| 1065 | ** sources provides the interfaces shown below. |
| 1066 | ** |
| 1067 | ** The first of these two routines returns the amount of memory |
| 1068 | ** currently outstanding (malloced but not freed). The second |
| 1069 | ** returns the largest instantaneous amount of outstanding |
| 1070 | ** memory. The highwater mark is reset if the argument is |
| 1071 | ** true. The SQLite core does not use either of these routines |
| 1072 | ** and so they do not have to be implemented by the application |
| 1073 | ** if SQLITE_OMIT_MEMORY_ALLOCATION is defined. These routines |
| 1074 | ** are provided by the default memory subsystem for diagnostic |
| 1075 | ** purposes. |
| 1076 | */ |
| 1077 | sqlite3_uint64 sqlite3_memory_used(void); |
| 1078 | sqlite3_uint64 sqlite3_memory_highwater(int resetFlag); |
| 1079 | |
| 1080 | /* |
| 1081 | ** CAPI3REF: Memory Allocation Alarms |
| 1082 | ** |
| 1083 | ** The [sqlite3_memory_alarm] routine is used to register |
| 1084 | ** a callback on memory allocation events. |
| 1085 | ** |
| 1086 | ** This routine registers or clears a callbacks that fires when |
| 1087 | ** the amount of memory allocated exceeds iThreshold. Only |
| 1088 | ** a single callback can be registered at a time. Each call |
| 1089 | ** to [sqlite3_memory_alarm()] overwrites the previous callback. |
| 1090 | ** The callback is disabled by setting xCallback to a NULL |
| 1091 | ** pointer. |
| 1092 | ** |
| 1093 | ** The parameters to the callback are the pArg value, the |
| 1094 | ** amount of memory currently in use, and the size of the |
| 1095 | ** allocation that provoked the callback. The callback will |
| 1096 | ** presumably invoke [sqlite3_free()] to free up memory space. |
| 1097 | ** The callback may invoke [sqlite3_malloc()] or [sqlite3_realloc()] |
| 1098 | ** but if it does, no additional callbacks will be invoked by |
| 1099 | ** the recursive calls. |
| 1100 | ** |
| 1101 | ** The [sqlite3_soft_heap_limit()] interface works by registering |
| 1102 | ** a memory alarm at the soft heap limit and invoking |
| 1103 | ** [sqlite3_release_memory()] in the alarm callback. Application |
| 1104 | ** programs should not attempt to use the [sqlite3_memory_alarm()] |
| 1105 | ** interface because doing so will interfere with the |
| 1106 | ** [sqlite3_soft_heap_limit()] module. |
| 1107 | */ |
| 1108 | int sqlite3_memory_alarm( |
| 1109 | void(*xCallback)(void *pArg, sqlite3_uint64 used, unsigned int N), |
| 1110 | void *pArg, |
| 1111 | sqlite3_uint64 iThreshold |
| 1112 | ); |
| 1113 | |
| 1114 | |
| 1115 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1116 | ** CAPI3REF: Compile-Time Authorization Callbacks |
| 1117 | *** |
| 1118 | ** This routine registers a authorizer callback with the SQLite library. |
| 1119 | ** The authorizer callback is invoked as SQL statements are being compiled |
| 1120 | ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()], |
| 1121 | ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various |
| 1122 | ** points during the compilation process, as logic is being created |
| 1123 | ** to perform various actions, the authorizer callback is invoked to |
| 1124 | ** see if those actions are allowed. The authorizer callback should |
| 1125 | ** return SQLITE_OK to allow the action, [SQLITE_IGNORE] to disallow the |
| 1126 | ** specific action but allow the SQL statement to continue to be |
| 1127 | ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be |
| 1128 | ** rejected with an error. |
| 1129 | ** |
| 1130 | ** Depending on the action, the [SQLITE_IGNORE] and [SQLITE_DENY] return |
| 1131 | ** codes might mean something different or they might mean the same |
| 1132 | ** thing. If the action is, for example, to perform a delete opertion, |
| 1133 | ** then [SQLITE_IGNORE] and [SQLITE_DENY] both cause the statement compilation |
| 1134 | ** to fail with an error. But if the action is to read a specific column |
| 1135 | ** from a specific table, then [SQLITE_DENY] will cause the entire |
| 1136 | ** statement to fail but [SQLITE_IGNORE] will cause a NULL value to be |
| 1137 | ** read instead of the actual column value. |
| 1138 | ** |
| 1139 | ** The first parameter to the authorizer callback is a copy of |
| 1140 | ** the third parameter to the sqlite3_set_authorizer() interface. |
| 1141 | ** The second parameter to the callback is an integer |
| 1142 | ** [SQLITE_COPY | action code] that specifies the particular action |
| 1143 | ** to be authorized. The available action codes are |
| 1144 | ** [SQLITE_COPY | documented separately]. The third through sixth |
| 1145 | ** parameters to the callback are strings that contain additional |
| 1146 | ** details about the action to be authorized. |
| 1147 | ** |
| 1148 | ** An authorizer is used when preparing SQL statements from an untrusted |
| 1149 | ** source, to ensure that the SQL statements do not try to access data |
| 1150 | ** that they are not allowed to see, or that they do not try to |
| 1151 | ** execute malicious statements that damage the database. For |
| 1152 | ** example, an application may allow a user to enter arbitrary |
| 1153 | ** SQL queries for evaluation by a database. But the application does |
| 1154 | ** not want the user to be able to make arbitrary changes to the |
| 1155 | ** database. An authorizer could then be put in place while the |
| 1156 | ** user-entered SQL is being prepared that disallows everything |
| 1157 | ** except SELECT statements. |
| 1158 | ** |
| 1159 | ** Only a single authorizer can be in place on a database connection |
| 1160 | ** at a time. Each call to sqlite3_set_authorizer overrides the |
| 1161 | ** previous call. A NULL authorizer means that no authorization |
| 1162 | ** callback is invoked. The default authorizer is NULL. |
| 1163 | ** |
| 1164 | ** Note that the authorizer callback is invoked only during |
| 1165 | ** [sqlite3_prepare()] or its variants. Authorization is not |
| 1166 | ** performed during statement evaluation in [sqlite3_step()]. |
drh | ed6c867 | 2003-01-12 18:02:16 +0000 | [diff] [blame] | 1167 | */ |
danielk1977 | 6f8a503 | 2004-05-10 10:34:51 +0000 | [diff] [blame] | 1168 | int sqlite3_set_authorizer( |
danielk1977 | f9d64d2 | 2004-06-19 08:18:07 +0000 | [diff] [blame] | 1169 | sqlite3*, |
drh | e22a334 | 2003-04-22 20:30:37 +0000 | [diff] [blame] | 1170 | int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), |
drh | e5f9c64 | 2003-01-13 23:27:31 +0000 | [diff] [blame] | 1171 | void *pUserData |
drh | ed6c867 | 2003-01-12 18:02:16 +0000 | [diff] [blame] | 1172 | ); |
| 1173 | |
| 1174 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1175 | ** CAPI3REF: Authorizer Return Codes |
| 1176 | ** |
| 1177 | ** The [sqlite3_set_authorizer | authorizer callback function] must |
| 1178 | ** return either [SQLITE_OK] or one of these two constants in order |
| 1179 | ** to signal SQLite whether or not the action is permitted. See the |
| 1180 | ** [sqlite3_set_authorizer | authorizer documentation] for additional |
| 1181 | ** information. |
| 1182 | */ |
| 1183 | #define SQLITE_DENY 1 /* Abort the SQL statement with an error */ |
| 1184 | #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ |
| 1185 | |
| 1186 | /* |
| 1187 | ** CAPI3REF: Authorizer Action Codes |
| 1188 | ** |
| 1189 | ** The [sqlite3_set_authorizer()] interface registers a callback function |
| 1190 | ** that is invoked to authorizer certain SQL statement actions. The |
| 1191 | ** second parameter to the callback is an integer code that specifies |
| 1192 | ** what action is being authorized. These are the integer action codes that |
| 1193 | ** the authorizer callback may be passed. |
| 1194 | ** |
| 1195 | ** These action code values signify what kind of operation is to be |
| 1196 | ** authorized. The 3rd and 4th parameters to the authorization callback |
| 1197 | ** function will be parameters or NULL depending on which of these |
| 1198 | ** codes is used as the second parameter. The 5th parameter to the |
| 1199 | ** authorizer callback is the name of the database ("main", "temp", |
| 1200 | ** etc.) if applicable. The 6th parameter to the authorizer callback |
drh | 5cf590c | 2003-04-24 01:45:04 +0000 | [diff] [blame] | 1201 | ** is the name of the inner-most trigger or view that is responsible for |
| 1202 | ** the access attempt or NULL if this access attempt is directly from |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1203 | ** top-level SQL code. |
drh | ed6c867 | 2003-01-12 18:02:16 +0000 | [diff] [blame] | 1204 | */ |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1205 | /******************************************* 3rd ************ 4th ***********/ |
drh | e5f9c64 | 2003-01-13 23:27:31 +0000 | [diff] [blame] | 1206 | #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ |
| 1207 | #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */ |
| 1208 | #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */ |
| 1209 | #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */ |
drh | 77ad4e4 | 2003-01-14 02:49:27 +0000 | [diff] [blame] | 1210 | #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */ |
drh | e5f9c64 | 2003-01-13 23:27:31 +0000 | [diff] [blame] | 1211 | #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */ |
drh | 77ad4e4 | 2003-01-14 02:49:27 +0000 | [diff] [blame] | 1212 | #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */ |
drh | e5f9c64 | 2003-01-13 23:27:31 +0000 | [diff] [blame] | 1213 | #define SQLITE_CREATE_VIEW 8 /* View Name NULL */ |
| 1214 | #define SQLITE_DELETE 9 /* Table Name NULL */ |
drh | 77ad4e4 | 2003-01-14 02:49:27 +0000 | [diff] [blame] | 1215 | #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */ |
drh | e5f9c64 | 2003-01-13 23:27:31 +0000 | [diff] [blame] | 1216 | #define SQLITE_DROP_TABLE 11 /* Table Name NULL */ |
drh | 77ad4e4 | 2003-01-14 02:49:27 +0000 | [diff] [blame] | 1217 | #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */ |
drh | e5f9c64 | 2003-01-13 23:27:31 +0000 | [diff] [blame] | 1218 | #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */ |
drh | 77ad4e4 | 2003-01-14 02:49:27 +0000 | [diff] [blame] | 1219 | #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */ |
drh | e5f9c64 | 2003-01-13 23:27:31 +0000 | [diff] [blame] | 1220 | #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */ |
drh | 77ad4e4 | 2003-01-14 02:49:27 +0000 | [diff] [blame] | 1221 | #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */ |
drh | e5f9c64 | 2003-01-13 23:27:31 +0000 | [diff] [blame] | 1222 | #define SQLITE_DROP_VIEW 17 /* View Name NULL */ |
| 1223 | #define SQLITE_INSERT 18 /* Table Name NULL */ |
| 1224 | #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */ |
| 1225 | #define SQLITE_READ 20 /* Table Name Column Name */ |
| 1226 | #define SQLITE_SELECT 21 /* NULL NULL */ |
| 1227 | #define SQLITE_TRANSACTION 22 /* NULL NULL */ |
| 1228 | #define SQLITE_UPDATE 23 /* Table Name Column Name */ |
drh | 81e293b | 2003-06-06 19:00:42 +0000 | [diff] [blame] | 1229 | #define SQLITE_ATTACH 24 /* Filename NULL */ |
| 1230 | #define SQLITE_DETACH 25 /* Database Name NULL */ |
danielk1977 | 1c8c23c | 2004-11-12 15:53:37 +0000 | [diff] [blame] | 1231 | #define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */ |
danielk1977 | 1d54df8 | 2004-11-23 15:41:16 +0000 | [diff] [blame] | 1232 | #define SQLITE_REINDEX 27 /* Index Name NULL */ |
drh | e6e0496 | 2005-07-23 02:17:03 +0000 | [diff] [blame] | 1233 | #define SQLITE_ANALYZE 28 /* Table Name NULL */ |
danielk1977 | f1a381e | 2006-06-16 08:01:02 +0000 | [diff] [blame] | 1234 | #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ |
| 1235 | #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ |
drh | 5169bbc | 2006-08-24 14:59:45 +0000 | [diff] [blame] | 1236 | #define SQLITE_FUNCTION 31 /* Function Name NULL */ |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1237 | #define SQLITE_COPY 0 /* No longer used */ |
drh | ed6c867 | 2003-01-12 18:02:16 +0000 | [diff] [blame] | 1238 | |
| 1239 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1240 | ** CAPI3REF: Tracing And Profiling Functions |
| 1241 | ** |
| 1242 | ** These routines register callback functions that can be used for |
| 1243 | ** tracing and profiling the execution of SQL statements. |
| 1244 | ** The callback function registered by sqlite3_trace() is invoked |
| 1245 | ** at the first [sqlite3_step()] for the evaluation of an SQL statement. |
| 1246 | ** The callback function registered by sqlite3_profile() is invoked |
| 1247 | ** as each SQL statement finishes and includes |
drh | 19e2d37 | 2005-08-29 23:00:03 +0000 | [diff] [blame] | 1248 | ** information on how long that statement ran. |
| 1249 | ** |
| 1250 | ** The sqlite3_profile() API is currently considered experimental and |
| 1251 | ** is subject to change. |
drh | 18de482 | 2003-01-16 16:28:53 +0000 | [diff] [blame] | 1252 | */ |
danielk1977 | f9d64d2 | 2004-06-19 08:18:07 +0000 | [diff] [blame] | 1253 | void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); |
drh | 19e2d37 | 2005-08-29 23:00:03 +0000 | [diff] [blame] | 1254 | void *sqlite3_profile(sqlite3*, |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1255 | void(*xProfile)(void*,const char*,sqlite3_uint64), void*); |
drh | 18de482 | 2003-01-16 16:28:53 +0000 | [diff] [blame] | 1256 | |
danielk1977 | 348bb5d | 2003-10-18 09:37:26 +0000 | [diff] [blame] | 1257 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1258 | ** CAPI3REF: Query Progress Callbacks |
| 1259 | ** |
danielk1977 | 348bb5d | 2003-10-18 09:37:26 +0000 | [diff] [blame] | 1260 | ** This routine configures a callback function - the progress callback - that |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1261 | ** is invoked periodically during long running calls to [sqlite3_exec()], |
| 1262 | ** [sqlite3_step()] and [sqlite3_get_table()]. An example use for this |
| 1263 | ** interface is to keep a GUI updated during a large query. |
danielk1977 | 348bb5d | 2003-10-18 09:37:26 +0000 | [diff] [blame] | 1264 | ** |
| 1265 | ** The progress callback is invoked once for every N virtual machine opcodes, |
| 1266 | ** where N is the second argument to this function. The progress callback |
| 1267 | ** itself is identified by the third argument to this function. The fourth |
| 1268 | ** argument to this function is a void pointer passed to the progress callback |
| 1269 | ** function each time it is invoked. |
| 1270 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1271 | ** If a call to [sqlite3_exec()], [sqlite3_step()], or [sqlite3_get_table()] |
| 1272 | ** results in fewer than N opcodes being executed, then the progress |
| 1273 | ** callback is never invoked. |
danielk1977 | 348bb5d | 2003-10-18 09:37:26 +0000 | [diff] [blame] | 1274 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1275 | ** Only a single progress callback function may be registered for each |
| 1276 | ** open database connection. Every call to sqlite3_progress_handler() |
| 1277 | ** overwrites the results of the previous call. |
danielk1977 | 348bb5d | 2003-10-18 09:37:26 +0000 | [diff] [blame] | 1278 | ** To remove the progress callback altogether, pass NULL as the third |
| 1279 | ** argument to this function. |
| 1280 | ** |
| 1281 | ** If the progress callback returns a result other than 0, then the current |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1282 | ** query is immediately terminated and any database changes rolled back. |
| 1283 | ** The containing [sqlite3_exec()], [sqlite3_step()], or |
| 1284 | ** [sqlite3_get_table()] call returns SQLITE_INTERRUPT. This feature |
| 1285 | ** can be used, for example, to implement the "Cancel" button on a |
| 1286 | ** progress dialog box in a GUI. |
danielk1977 | 348bb5d | 2003-10-18 09:37:26 +0000 | [diff] [blame] | 1287 | */ |
danielk1977 | f9d64d2 | 2004-06-19 08:18:07 +0000 | [diff] [blame] | 1288 | void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); |
danielk1977 | 348bb5d | 2003-10-18 09:37:26 +0000 | [diff] [blame] | 1289 | |
drh | aa940ea | 2004-01-15 02:44:03 +0000 | [diff] [blame] | 1290 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1291 | ** CAPI3REF: Opening A New Database Connection |
drh | aa940ea | 2004-01-15 02:44:03 +0000 | [diff] [blame] | 1292 | ** |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1293 | ** Open the sqlite database file "filename". The "filename" is UTF-8 |
| 1294 | ** encoded for sqlite3_open() and UTF-16 encoded in the native byte order |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1295 | ** for sqlite3_open16(). An [sqlite3*] handle is returned in *ppDb, even |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1296 | ** if an error occurs. If the database is opened (or created) successfully, |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1297 | ** then [SQLITE_OK] is returned. Otherwise an error code is returned. The |
| 1298 | ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1299 | ** an English language description of the error. |
drh | 22fbcb8 | 2004-02-01 01:22:50 +0000 | [diff] [blame] | 1300 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1301 | ** If the database file does not exist, then a new database will be created |
| 1302 | ** as needed. The default encoding for the database will be UTF-8 if |
| 1303 | ** sqlite3_open() is called and UTF-16 if sqlite3_open16 is used. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1304 | ** |
| 1305 | ** Whether or not an error occurs when it is opened, resources associated |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1306 | ** with the [sqlite3*] handle should be released by passing it to |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1307 | ** [sqlite3_close()] when it is no longer required. |
| 1308 | ** |
| 1309 | ** The sqlite3_open_v2() interface works like sqlite3_open() except that |
| 1310 | ** provides two additional parameters for additional control over the |
| 1311 | ** new database connection. The flags parameter can be one of: |
| 1312 | ** |
| 1313 | ** <ol> |
| 1314 | ** <li> [SQLITE_OPEN_READONLY] |
| 1315 | ** <li> [SQLITE_OPEN_READWRITE] |
| 1316 | ** <li> [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE] |
| 1317 | ** </ol> |
| 1318 | ** |
| 1319 | ** The first value opens the database read-only. If the database does |
| 1320 | ** not previously exist, an error is returned. The second option opens |
| 1321 | ** the database for reading and writing but the database must already |
| 1322 | ** exist or an error is returned. The third option opens the database |
| 1323 | ** for reading and writing and creates it if it does not already exist. |
| 1324 | ** The third options is behavior that is used always for sqlite3_open() |
| 1325 | ** and sqlite3_open16(). |
| 1326 | ** |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 1327 | ** The fourth parameter to sqlite3_open_v2() is the name of the |
| 1328 | ** [sqlite3_vfs] object that defines the operating system |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1329 | ** interface that the new database connection should use. If the |
| 1330 | ** fourth parameter is a NULL pointer then a default suitable for |
| 1331 | ** the host environment is substituted. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1332 | ** |
| 1333 | ** Note to windows users: The encoding used for the filename argument |
| 1334 | ** of sqlite3_open() must be UTF-8, not whatever codepage is currently |
| 1335 | ** defined. Filenames containing international characters must be converted |
| 1336 | ** to UTF-8 prior to passing them into sqlite3_open(). |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1337 | */ |
| 1338 | int sqlite3_open( |
| 1339 | const char *filename, /* Database filename (UTF-8) */ |
danielk1977 | 4f057f9 | 2004-06-08 00:02:33 +0000 | [diff] [blame] | 1340 | sqlite3 **ppDb /* OUT: SQLite db handle */ |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1341 | ); |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1342 | int sqlite3_open16( |
| 1343 | const void *filename, /* Database filename (UTF-16) */ |
danielk1977 | 4f057f9 | 2004-06-08 00:02:33 +0000 | [diff] [blame] | 1344 | sqlite3 **ppDb /* OUT: SQLite db handle */ |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1345 | ); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1346 | int sqlite3_open_v2( |
| 1347 | const void *filename, /* Database filename (UTF-16) */ |
| 1348 | sqlite3 **ppDb, /* OUT: SQLite db handle */ |
| 1349 | int flags, /* Flags */ |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 1350 | const char *zVfs /* Name of VFS module to use */ |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1351 | ); |
danielk1977 | 295ba55 | 2004-05-19 10:34:51 +0000 | [diff] [blame] | 1352 | |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1353 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1354 | ** CAPI3REF: Error Codes And Messages |
| 1355 | ** |
| 1356 | ** The sqlite3_errcode() interface returns the numeric |
| 1357 | ** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code] |
| 1358 | ** for the most recent failed sqlite3_* API call associated |
| 1359 | ** with [sqlite3] handle 'db'. If a prior API call failed but the |
| 1360 | ** most recent API call succeeded, the return value from sqlite3_errcode() |
| 1361 | ** is undefined. |
| 1362 | ** |
| 1363 | ** The sqlite3_errmsg() and sqlite3_errmsg16() return English-langauge |
| 1364 | ** text that describes the error, as either UTF8 or UTF16 respectively. |
| 1365 | ** Memory to hold the error message string is managed internally. The |
| 1366 | ** string may be overwritten or deallocated by subsequent calls to SQLite |
| 1367 | ** interface functions. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1368 | ** |
| 1369 | ** Calls to many sqlite3_* functions set the error code and string returned |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1370 | ** by [sqlite3_errcode()], [sqlite3_errmsg()], and [sqlite3_errmsg16()] |
| 1371 | ** (overwriting the previous values). Note that calls to [sqlite3_errcode()], |
| 1372 | ** [sqlite3_errmsg()], and [sqlite3_errmsg16()] themselves do not affect the |
| 1373 | ** results of future invocations. Calls to API routines that do not return |
| 1374 | ** an error code (examples: [sqlite3_data_count()] or [sqlite3_mprintf()]) do |
| 1375 | ** not change the error code returned by this routine. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1376 | ** |
| 1377 | ** Assuming no other intervening sqlite3_* API calls are made, the error |
| 1378 | ** code returned by this function is associated with the same error as |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1379 | ** the strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()]. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1380 | */ |
| 1381 | int sqlite3_errcode(sqlite3 *db); |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1382 | const char *sqlite3_errmsg(sqlite3*); |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1383 | const void *sqlite3_errmsg16(sqlite3*); |
| 1384 | |
| 1385 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1386 | ** CAPI3REF: SQL Statement Object |
| 1387 | ** |
| 1388 | ** Instance of this object represent single SQL statements. This |
| 1389 | ** is variously known as a "prepared statement" or a |
| 1390 | ** "compiled SQL statement" or simply as a "statement". |
| 1391 | ** |
| 1392 | ** The life of a statement object goes something like this: |
| 1393 | ** |
| 1394 | ** <ol> |
| 1395 | ** <li> Create the object using [sqlite3_prepare_v2()] or a related |
| 1396 | ** function. |
| 1397 | ** <li> Bind values to host parameters using |
| 1398 | ** [sqlite3_bind_blob | sqlite3_bind_* interfaces]. |
| 1399 | ** <li> Run the SQL by calling [sqlite3_step()] one or more times. |
| 1400 | ** <li> Reset the statement using [sqlite3_reset()] then go back |
| 1401 | ** to step 2. Do this zero or more times. |
| 1402 | ** <li> Destroy the object using [sqlite3_finalize()]. |
| 1403 | ** </ol> |
| 1404 | ** |
| 1405 | ** Refer to documentation on individual methods above for additional |
| 1406 | ** information. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1407 | */ |
danielk1977 | fc57d7b | 2004-05-26 02:04:57 +0000 | [diff] [blame] | 1408 | typedef struct sqlite3_stmt sqlite3_stmt; |
| 1409 | |
danielk1977 | e3209e4 | 2004-05-20 01:40:18 +0000 | [diff] [blame] | 1410 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1411 | ** CAPI3REF: Compiling An SQL Statement |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1412 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1413 | ** To execute an SQL query, it must first be compiled into a byte-code |
| 1414 | ** program using one of these routines. |
| 1415 | ** |
| 1416 | ** The first argument "db" is an [sqlite3 | SQLite database handle] |
| 1417 | ** obtained from a prior call to [sqlite3_open()] or [sqlite3_open16()]. |
| 1418 | ** The second argument "zSql" is the statement to be compiled, encoded |
| 1419 | ** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() |
| 1420 | ** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2() |
drh | 21f0672 | 2007-07-19 12:41:39 +0000 | [diff] [blame] | 1421 | ** use UTF-16. |
| 1422 | ** |
| 1423 | ** If the nByte argument is less |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1424 | ** than zero, then zSql is read up to the first zero terminator. If |
drh | 21f0672 | 2007-07-19 12:41:39 +0000 | [diff] [blame] | 1425 | ** nByte is non-negative, then it is the maximum number of |
| 1426 | ** bytes read from zSql. When nByte is non-negative, the |
| 1427 | ** zSql string ends at either the first '\000' character or |
| 1428 | ** until the nByte-th byte, whichever comes first. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1429 | ** |
| 1430 | ** *pzTail is made to point to the first byte past the end of the first |
| 1431 | ** SQL statement in zSql. This routine only compiles the first statement |
| 1432 | ** in zSql, so *pzTail is left pointing to what remains uncompiled. |
| 1433 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1434 | ** *ppStmt is left pointing to a compiled |
| 1435 | ** [sqlite3_stmt | SQL statement structure] that can be |
| 1436 | ** executed using [sqlite3_step()]. Or if there is an error, *ppStmt may be |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1437 | ** set to NULL. If the input text contained no SQL (if the input is and |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1438 | ** empty string or a comment) then *ppStmt is set to NULL. The calling |
| 1439 | ** procedure is responsible for deleting the compiled SQL statement |
| 1440 | ** using [sqlite3_finalize()] after it has finished with it. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1441 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1442 | ** On success, [SQLITE_OK] is returned. Otherwise an |
| 1443 | ** [SQLITE_ERROR | error code] is returned. |
| 1444 | ** |
| 1445 | ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are |
| 1446 | ** recommended for all new programs. The two older interfaces are retained |
| 1447 | ** for backwards compatibility, but their use is discouraged. |
| 1448 | ** In the "v2" interfaces, the prepared statement |
| 1449 | ** that is returned (the [sqlite3_stmt] object) contains a copy of the |
| 1450 | ** original SQL text. This causes the [sqlite3_step()] interface to |
| 1451 | ** behave a differently in two ways: |
| 1452 | ** |
| 1453 | ** <ol> |
| 1454 | ** <li> |
| 1455 | ** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it |
| 1456 | ** always used to do, [sqlite3_step()] will automatically recompile the SQL |
| 1457 | ** statement and try to run it again. If the schema has changed in a way |
| 1458 | ** that makes the statement no longer valid, [sqlite3_step()] will still |
| 1459 | ** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is |
| 1460 | ** now a fatal error. Calling [sqlite3_prepare_v2()] again will not make the |
| 1461 | ** error go away. Note: use [sqlite3_errmsg()] to find the text of the parsing |
| 1462 | ** error that results in an [SQLITE_SCHEMA] return. |
| 1463 | ** </li> |
| 1464 | ** |
| 1465 | ** <li> |
| 1466 | ** When an error occurs, |
| 1467 | ** [sqlite3_step()] will return one of the detailed |
| 1468 | ** [SQLITE_ERROR | result codes] or |
| 1469 | ** [SQLITE_IOERR_READ | extended result codes] such as directly. |
| 1470 | ** The legacy behavior was that [sqlite3_step()] would only return a generic |
| 1471 | ** [SQLITE_ERROR] result code and you would have to make a second call to |
| 1472 | ** [sqlite3_reset()] in order to find the underlying cause of the problem. |
| 1473 | ** With the "v2" prepare interfaces, the underlying reason for the error is |
| 1474 | ** returned immediately. |
| 1475 | ** </li> |
| 1476 | ** </ol> |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1477 | */ |
| 1478 | int sqlite3_prepare( |
| 1479 | sqlite3 *db, /* Database handle */ |
| 1480 | const char *zSql, /* SQL statement, UTF-8 encoded */ |
drh | 21f0672 | 2007-07-19 12:41:39 +0000 | [diff] [blame] | 1481 | int nByte, /* Maximum length of zSql in bytes. */ |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1482 | sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
| 1483 | const char **pzTail /* OUT: Pointer to unused portion of zSql */ |
| 1484 | ); |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1485 | int sqlite3_prepare_v2( |
| 1486 | sqlite3 *db, /* Database handle */ |
| 1487 | const char *zSql, /* SQL statement, UTF-8 encoded */ |
drh | 21f0672 | 2007-07-19 12:41:39 +0000 | [diff] [blame] | 1488 | int nByte, /* Maximum length of zSql in bytes. */ |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1489 | sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
| 1490 | const char **pzTail /* OUT: Pointer to unused portion of zSql */ |
| 1491 | ); |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1492 | int sqlite3_prepare16( |
| 1493 | sqlite3 *db, /* Database handle */ |
| 1494 | const void *zSql, /* SQL statement, UTF-16 encoded */ |
drh | 21f0672 | 2007-07-19 12:41:39 +0000 | [diff] [blame] | 1495 | int nByte, /* Maximum length of zSql in bytes. */ |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1496 | sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
| 1497 | const void **pzTail /* OUT: Pointer to unused portion of zSql */ |
| 1498 | ); |
drh | b900aaf | 2006-11-09 00:24:53 +0000 | [diff] [blame] | 1499 | int sqlite3_prepare16_v2( |
| 1500 | sqlite3 *db, /* Database handle */ |
| 1501 | const void *zSql, /* SQL statement, UTF-16 encoded */ |
drh | 21f0672 | 2007-07-19 12:41:39 +0000 | [diff] [blame] | 1502 | int nByte, /* Maximum length of zSql in bytes. */ |
drh | b900aaf | 2006-11-09 00:24:53 +0000 | [diff] [blame] | 1503 | sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
| 1504 | const void **pzTail /* OUT: Pointer to unused portion of zSql */ |
| 1505 | ); |
| 1506 | |
| 1507 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1508 | ** CAPI3REF: Dynamically Typed Value Object |
| 1509 | ** |
| 1510 | ** SQLite uses dynamic typing for the values it stores. Values can |
| 1511 | ** be integers, floating point values, strings, BLOBs, or NULL. When |
| 1512 | ** passing around values internally, each value is represented as |
| 1513 | ** an instance of the sqlite3_value object. |
drh | f447950 | 2004-05-27 03:12:53 +0000 | [diff] [blame] | 1514 | */ |
drh | f447950 | 2004-05-27 03:12:53 +0000 | [diff] [blame] | 1515 | typedef struct Mem sqlite3_value; |
| 1516 | |
| 1517 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1518 | ** CAPI3REF: SQL Function Context Object |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1519 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1520 | ** The context in which an SQL function executes is stored in an |
| 1521 | ** sqlite3_context object. A pointer to such an object is the |
| 1522 | ** first parameter to user-defined SQL functions. |
| 1523 | */ |
| 1524 | typedef struct sqlite3_context sqlite3_context; |
| 1525 | |
| 1526 | /* |
| 1527 | ** CAPI3REF: Binding Values To Prepared Statements |
| 1528 | ** |
| 1529 | ** In the SQL strings input to [sqlite3_prepare_v2()] and its variants, |
| 1530 | ** one or more literals can be replace by a parameter in one of these |
| 1531 | ** forms: |
| 1532 | ** |
| 1533 | ** <ul> |
| 1534 | ** <li> ? |
| 1535 | ** <li> ?NNN |
| 1536 | ** <li> :AAA |
| 1537 | ** <li> @AAA |
| 1538 | ** <li> $VVV |
| 1539 | ** </ul> |
| 1540 | ** |
| 1541 | ** In the parameter forms shown above NNN is an integer literal, |
| 1542 | ** AAA is an alphanumeric identifier and VVV is a variable name according |
| 1543 | ** to the syntax rules of the TCL programming language. |
| 1544 | ** The values of these parameters (also called "host parameter names") |
| 1545 | ** can be set using the sqlite3_bind_*() routines defined here. |
| 1546 | ** |
| 1547 | ** The first argument to the sqlite3_bind_*() routines always is a pointer |
| 1548 | ** to the [sqlite3_stmt] object returned from [sqlite3_prepare_v2()] or |
| 1549 | ** its variants. The second |
| 1550 | ** argument is the index of the parameter to be set. The first parameter has |
| 1551 | ** an index of 1. When the same named parameter is used more than once, second |
| 1552 | ** and subsequent |
| 1553 | ** occurrences have the same index as the first occurrence. The index for |
| 1554 | ** named parameters can be looked up using the |
| 1555 | ** [sqlite3_bind_parameter_name()] API if desired. The index for "?NNN" |
| 1556 | ** parametes is the value of NNN. |
| 1557 | ** The NNN value must be between 1 and the compile-time |
| 1558 | ** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999). |
| 1559 | ** See <a href="limits.html">limits.html</a> for additional information. |
| 1560 | ** |
| 1561 | ** The third argument is the value to bind to the parameter. |
| 1562 | ** |
| 1563 | ** In those |
| 1564 | ** routines that have a fourth argument, its value is the number of bytes |
| 1565 | ** in the parameter. To be clear: the value is the number of bytes in the |
| 1566 | ** string, not the number of characters. The number |
| 1567 | ** of bytes does not include the zero-terminator at the end of strings. |
| 1568 | ** If the fourth parameter is negative, the length of the string is |
| 1569 | ** number of bytes up to the first zero terminator. |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1570 | ** |
drh | 930cc58 | 2007-03-28 13:07:40 +0000 | [diff] [blame] | 1571 | ** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and |
drh | 900dfba | 2004-07-21 15:21:36 +0000 | [diff] [blame] | 1572 | ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or |
| 1573 | ** text after SQLite has finished with it. If the fifth argument is the |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1574 | ** special value [SQLITE_STATIC], then the library assumes that the information |
drh | 900dfba | 2004-07-21 15:21:36 +0000 | [diff] [blame] | 1575 | ** is in static, unmanaged space and does not need to be freed. If the |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1576 | ** fifth argument has the value [SQLITE_TRANSIENT], then SQLite makes its |
| 1577 | ** own private copy of the data immediately, before the sqlite3_bind_*() |
| 1578 | ** routine returns. |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1579 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1580 | ** The sqlite3_bind_zeroblob() routine binds a BLOB of length n that |
| 1581 | ** is filled with zeros. A zeroblob uses a fixed amount of memory |
| 1582 | ** (just an integer to hold it size) while it is being processed. |
| 1583 | ** Zeroblobs are intended to serve as place-holders for BLOBs whose |
| 1584 | ** content is later written using |
| 1585 | ** [sqlite3_blob_open | increment BLOB I/O] routines. |
| 1586 | ** |
| 1587 | ** The sqlite3_bind_*() routines must be called after |
| 1588 | ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and |
| 1589 | ** before [sqlite3_step()]. |
| 1590 | ** Bindings are not cleared by the [sqlite3_reset()] routine. |
| 1591 | ** Unbound parameters are interpreted as NULL. |
| 1592 | ** |
| 1593 | ** These routines return [SQLITE_OK] on success or an error code if |
| 1594 | ** anything goes wrong. [SQLITE_RANGE] is returned if the parameter |
| 1595 | ** index is out of range. [SQLITE_NOMEM] is returned if malloc fails. |
| 1596 | ** [SQLITE_MISUSE] is returned if these routines are called on a virtual |
| 1597 | ** machine that is the wrong state or which has already been finalized. |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1598 | */ |
danielk1977 | d812336 | 2004-06-12 09:25:12 +0000 | [diff] [blame] | 1599 | int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); |
drh | f447950 | 2004-05-27 03:12:53 +0000 | [diff] [blame] | 1600 | int sqlite3_bind_double(sqlite3_stmt*, int, double); |
| 1601 | int sqlite3_bind_int(sqlite3_stmt*, int, int); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1602 | int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); |
drh | f447950 | 2004-05-27 03:12:53 +0000 | [diff] [blame] | 1603 | int sqlite3_bind_null(sqlite3_stmt*, int); |
danielk1977 | d812336 | 2004-06-12 09:25:12 +0000 | [diff] [blame] | 1604 | int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); |
| 1605 | int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); |
drh | f447950 | 2004-05-27 03:12:53 +0000 | [diff] [blame] | 1606 | int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); |
drh | b026e05 | 2007-05-02 01:34:31 +0000 | [diff] [blame] | 1607 | int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1608 | |
| 1609 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1610 | ** CAPI3REF: Number Of Host Parameters |
| 1611 | ** |
| 1612 | ** Return the largest host parameter index in the precompiled statement given |
| 1613 | ** as the argument. When the host parameters are of the forms like ":AAA" |
| 1614 | ** or "?", then they are assigned sequential increasing numbers beginning |
| 1615 | ** with one, so the value returned is the number of parameters. However |
| 1616 | ** if the same host parameter name is used multiple times, each occurrance |
| 1617 | ** is given the same number, so the value returned in that case is the number |
| 1618 | ** of unique host parameter names. If host parameters of the form "?NNN" |
| 1619 | ** are used (where NNN is an integer) then there might be gaps in the |
| 1620 | ** numbering and the value returned by this interface is the index of the |
| 1621 | ** host parameter with the largest index value. |
drh | 605264d | 2007-08-21 15:13:19 +0000 | [diff] [blame^] | 1622 | ** |
| 1623 | ** The prepared statement must not not be [sqlite3_finalize | finalized] |
| 1624 | ** prior to this routine returnning. Otherwise the results are undefined |
| 1625 | ** and probably undesirable. |
drh | 75f6a03 | 2004-07-15 14:15:00 +0000 | [diff] [blame] | 1626 | */ |
| 1627 | int sqlite3_bind_parameter_count(sqlite3_stmt*); |
| 1628 | |
| 1629 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1630 | ** CAPI3REF: Name Of A Host Parameter |
| 1631 | ** |
| 1632 | ** This routine returns a pointer to the name of the n-th parameter in a |
| 1633 | ** [sqlite3_stmt | prepared statement]. |
| 1634 | ** Host parameters of the form ":AAA" or "@AAA" or "$VVV" have a name |
| 1635 | ** which is the string ":AAA" or "@AAA" or "$VVV". |
| 1636 | ** In other words, the initial ":" or "$" or "@" |
| 1637 | ** is included as part of the name. |
| 1638 | ** Parameters of the form "?" or "?NNN" have no name. |
| 1639 | ** |
| 1640 | ** The first bound parameter has an index of 1, not 0. |
| 1641 | ** |
| 1642 | ** If the value n is out of range or if the n-th parameter is nameless, |
| 1643 | ** then NULL is returned. The returned string is always in the |
| 1644 | ** UTF-8 encoding even if the named parameter was originally specified |
| 1645 | ** as UTF-16 in [sqlite3_prepare16()] or [sqlite3_prepare16_v2()]. |
drh | 895d747 | 2004-08-20 16:02:39 +0000 | [diff] [blame] | 1646 | */ |
| 1647 | const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); |
| 1648 | |
| 1649 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1650 | ** CAPI3REF: Index Of A Parameter With A Given Name |
| 1651 | ** |
| 1652 | ** This routine returns the index of a host parameter with the given name. |
| 1653 | ** The name must match exactly. If no parameter with the given name is |
| 1654 | ** found, return 0. Parameter names must be UTF8. |
drh | fa6bc00 | 2004-09-07 16:19:52 +0000 | [diff] [blame] | 1655 | */ |
| 1656 | int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); |
| 1657 | |
| 1658 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1659 | ** CAPI3REF: Reset All Bindings On A Prepared Statement |
| 1660 | ** |
| 1661 | ** Contrary to the intuition of many, [sqlite3_reset()] does not |
| 1662 | ** reset the [sqlite3_bind_blob | bindings] on a |
| 1663 | ** [sqlite3_stmt | prepared statement]. Use this routine to |
| 1664 | ** reset all host parameters to NULL. |
danielk1977 | 600dd0b | 2005-01-20 01:14:23 +0000 | [diff] [blame] | 1665 | */ |
| 1666 | int sqlite3_clear_bindings(sqlite3_stmt*); |
| 1667 | |
| 1668 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1669 | ** CAPI3REF: Number Of Columns In A Result Set |
| 1670 | ** |
| 1671 | ** Return the number of columns in the result set returned by the |
| 1672 | ** [sqlite3_stmt | compiled SQL statement]. This routine returns 0 |
| 1673 | ** if pStmt is an SQL statement that does not return data (for |
| 1674 | ** example an UPDATE). |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1675 | */ |
| 1676 | int sqlite3_column_count(sqlite3_stmt *pStmt); |
| 1677 | |
| 1678 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1679 | ** CAPI3REF: Column Names In A Result Set |
| 1680 | ** |
| 1681 | ** These routines return the name assigned to a particular column |
| 1682 | ** in the result set of a SELECT statement. The sqlite3_column_name() |
| 1683 | ** interface returns a pointer to a UTF8 string and sqlite3_column_name16() |
| 1684 | ** returns a pointer to a UTF16 string. The first parameter is the |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1685 | ** [sqlite3_stmt | prepared statement] that implements the SELECT statement. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1686 | ** The second parameter is the column number. The left-most column is |
| 1687 | ** number 0. |
| 1688 | ** |
| 1689 | ** The returned string pointer is valid until either the |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1690 | ** [sqlite3_stmt | prepared statement] is destroyed by [sqlite3_finalize()] |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1691 | ** or until the next call sqlite3_column_name() or sqlite3_column_name16() |
| 1692 | ** on the same column. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1693 | */ |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1694 | const char *sqlite3_column_name(sqlite3_stmt*, int N); |
| 1695 | const void *sqlite3_column_name16(sqlite3_stmt*, int N); |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1696 | |
| 1697 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1698 | ** CAPI3REF: Source Of Data In A Query Result |
| 1699 | ** |
| 1700 | ** These routines provide a means to determine what column of what |
| 1701 | ** table in which database a result of a SELECT statement comes from. |
| 1702 | ** The name of the database or table or column can be returned as |
drh | bf2564f | 2007-06-21 15:25:05 +0000 | [diff] [blame] | 1703 | ** either a UTF8 or UTF16 string. The _database_ routines return |
| 1704 | ** the database name, the _table_ routines return the table name, and |
| 1705 | ** the origin_ routines return the column name. |
| 1706 | ** The returned string is valid until |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1707 | ** the [sqlite3_stmt | prepared statement] is destroyed using |
| 1708 | ** [sqlite3_finalize()] or until the same information is requested |
drh | bf2564f | 2007-06-21 15:25:05 +0000 | [diff] [blame] | 1709 | ** again in a different encoding. |
| 1710 | ** |
| 1711 | ** The names returned are the original un-aliased names of the |
| 1712 | ** database, table, and column. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1713 | ** |
| 1714 | ** The first argument to the following calls is a |
| 1715 | ** [sqlite3_stmt | compiled SQL statement]. |
danielk1977 | 955de52 | 2006-02-10 02:27:42 +0000 | [diff] [blame] | 1716 | ** These functions return information about the Nth column returned by |
| 1717 | ** the statement, where N is the second function argument. |
| 1718 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1719 | ** If the Nth column returned by the statement is an expression |
| 1720 | ** or subquery and is not a column value, then all of these functions |
| 1721 | ** return NULL. Otherwise, they return the |
| 1722 | ** name of the attached database, table and column that query result |
| 1723 | ** column was extracted from. |
danielk1977 | 955de52 | 2006-02-10 02:27:42 +0000 | [diff] [blame] | 1724 | ** |
| 1725 | ** As with all other SQLite APIs, those postfixed with "16" return UTF-16 |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1726 | ** encoded strings, the other functions return UTF-8. |
danielk1977 | 4b1ae99 | 2006-02-10 03:06:10 +0000 | [diff] [blame] | 1727 | ** |
| 1728 | ** These APIs are only available if the library was compiled with the |
| 1729 | ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. |
danielk1977 | 955de52 | 2006-02-10 02:27:42 +0000 | [diff] [blame] | 1730 | */ |
| 1731 | const char *sqlite3_column_database_name(sqlite3_stmt*,int); |
| 1732 | const void *sqlite3_column_database_name16(sqlite3_stmt*,int); |
| 1733 | const char *sqlite3_column_table_name(sqlite3_stmt*,int); |
| 1734 | const void *sqlite3_column_table_name16(sqlite3_stmt*,int); |
| 1735 | const char *sqlite3_column_origin_name(sqlite3_stmt*,int); |
| 1736 | const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); |
| 1737 | |
| 1738 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1739 | ** CAPI3REF: Declared Datatype Of A Query Result |
| 1740 | ** |
| 1741 | ** The first parameter is a [sqlite3_stmt | compiled SQL statement]. |
| 1742 | ** If this statement is a SELECT statement and the Nth column of the |
| 1743 | ** returned result set of that SELECT is a table column (not an |
| 1744 | ** expression or subquery) then the declared type of the table |
| 1745 | ** column is returned. If the Nth column of the result set is an |
| 1746 | ** expression or subquery, then a NULL pointer is returned. |
| 1747 | ** The returned string is always UTF-8 encoded. For example, in |
| 1748 | ** the database schema: |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1749 | ** |
| 1750 | ** CREATE TABLE t1(c1 VARIANT); |
| 1751 | ** |
| 1752 | ** And the following statement compiled: |
| 1753 | ** |
danielk1977 | 955de52 | 2006-02-10 02:27:42 +0000 | [diff] [blame] | 1754 | ** SELECT c1 + 1, c1 FROM t1; |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1755 | ** |
| 1756 | ** Then this routine would return the string "VARIANT" for the second |
| 1757 | ** result column (i==1), and a NULL pointer for the first result column |
| 1758 | ** (i==0). |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1759 | ** |
| 1760 | ** SQLite uses dynamic run-time typing. So just because a column |
| 1761 | ** is declared to contain a particular type does not mean that the |
| 1762 | ** data stored in that column is of the declared type. SQLite is |
| 1763 | ** strongly typed, but the typing is dynamic not static. Type |
| 1764 | ** is associated with individual values, not with the containers |
| 1765 | ** used to hold those values. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1766 | */ |
| 1767 | const char *sqlite3_column_decltype(sqlite3_stmt *, int i); |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1768 | const void *sqlite3_column_decltype16(sqlite3_stmt*,int); |
| 1769 | |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 1770 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1771 | ** CAPI3REF: Evaluate An SQL Statement |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 1772 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1773 | ** After an [sqlite3_stmt | SQL statement] has been prepared with a call |
| 1774 | ** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of |
| 1775 | ** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], |
| 1776 | ** then this function must be called one or more times to evaluate the |
| 1777 | ** statement. |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 1778 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1779 | ** The details of the behavior of this sqlite3_step() interface depend |
| 1780 | ** on whether the statement was prepared using the newer "v2" interface |
| 1781 | ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy |
| 1782 | ** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the |
| 1783 | ** new "v2" interface is recommended for new applications but the legacy |
| 1784 | ** interface will continue to be supported. |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 1785 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1786 | ** In the lagacy interface, the return value will be either [SQLITE_BUSY], |
| 1787 | ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE]. |
| 1788 | ** With the "v2" interface, any of the other [SQLITE_OK | result code] |
| 1789 | ** or [SQLITE_IOERR_READ | extended result code] might be returned as |
| 1790 | ** well. |
| 1791 | ** |
| 1792 | ** [SQLITE_BUSY] means that the database engine was unable to acquire the |
| 1793 | ** database locks it needs to do its job. If the statement is a COMMIT |
| 1794 | ** or occurs outside of an explicit transaction, then you can retry the |
| 1795 | ** statement. If the statement is not a COMMIT and occurs within a |
| 1796 | ** explicit transaction then you should rollback the transaction before |
| 1797 | ** continuing. |
| 1798 | ** |
| 1799 | ** [SQLITE_DONE] means that the statement has finished executing |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 1800 | ** successfully. sqlite3_step() should not be called again on this virtual |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1801 | ** machine without first calling [sqlite3_reset()] to reset the virtual |
| 1802 | ** machine back to its initial state. |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 1803 | ** |
| 1804 | ** If the SQL statement being executed returns any data, then |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1805 | ** [SQLITE_ROW] is returned each time a new row of data is ready |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 1806 | ** for processing by the caller. The values may be accessed using |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1807 | ** the [sqlite3_column_int | column access functions]. |
| 1808 | ** sqlite3_step() is called again to retrieve the next row of data. |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 1809 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1810 | ** [SQLITE_ERROR] means that a run-time error (such as a constraint |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 1811 | ** violation) has occurred. sqlite3_step() should not be called again on |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1812 | ** the VM. More information may be found by calling [sqlite3_errmsg()]. |
| 1813 | ** With the legacy interface, a more specific error code (example: |
| 1814 | ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth) |
| 1815 | ** can be obtained by calling [sqlite3_reset()] on the |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1816 | ** [sqlite3_stmt | prepared statement]. In the "v2" interface, |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1817 | ** the more specific error code is returned directly by sqlite3_step(). |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 1818 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1819 | ** [SQLITE_MISUSE] means that the this routine was called inappropriately. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1820 | ** Perhaps it was called on a [sqlite3_stmt | prepared statement] that has |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1821 | ** already been [sqlite3_finalize | finalized] or on one that had |
| 1822 | ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could |
| 1823 | ** be the case that the same database connection is being used by two or |
| 1824 | ** more threads at the same moment in time. |
| 1825 | ** |
| 1826 | ** <b>Goofy Interface Alert:</b> |
| 1827 | ** In the legacy interface, |
| 1828 | ** the sqlite3_step() API always returns a generic error code, |
| 1829 | ** [SQLITE_ERROR], following any error other than [SQLITE_BUSY] |
| 1830 | ** and [SQLITE_MISUSE]. You must call [sqlite3_reset()] or |
| 1831 | ** [sqlite3_finalize()] in order to find one of the specific |
| 1832 | ** [SQLITE_ERROR | result codes] that better describes the error. |
| 1833 | ** We admit that this is a goofy design. The problem has been fixed |
| 1834 | ** with the "v2" interface. If you prepare all of your SQL statements |
| 1835 | ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead |
| 1836 | ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the |
| 1837 | ** more specific [SQLITE_ERROR | result codes] are returned directly |
| 1838 | ** by sqlite3_step(). The use of the "v2" interface is recommended. |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 1839 | */ |
danielk1977 | 17240fd | 2004-05-26 00:07:25 +0000 | [diff] [blame] | 1840 | int sqlite3_step(sqlite3_stmt*); |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 1841 | |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 1842 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1843 | ** CAPI3REF: |
| 1844 | ** |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 1845 | ** Return the number of values in the current row of the result set. |
| 1846 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1847 | ** After a call to [sqlite3_step()] that returns [SQLITE_ROW], this routine |
| 1848 | ** will return the same value as the [sqlite3_column_count()] function. |
| 1849 | ** After [sqlite3_step()] has returned an [SQLITE_DONE], [SQLITE_BUSY], or |
| 1850 | ** a [SQLITE_ERROR | error code], or before [sqlite3_step()] has been |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1851 | ** called on the [sqlite3_stmt | prepared statement] for the first time, |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1852 | ** this routine returns zero. |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 1853 | */ |
danielk1977 | 93d4675 | 2004-05-23 13:30:58 +0000 | [diff] [blame] | 1854 | int sqlite3_data_count(sqlite3_stmt *pStmt); |
danielk1977 | 4adee20 | 2004-05-08 08:23:19 +0000 | [diff] [blame] | 1855 | |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1856 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1857 | ** CAPI3REF: Fundamental Datatypes |
| 1858 | ** |
| 1859 | ** Every value in SQLite has one of five fundamental datatypes: |
| 1860 | ** |
| 1861 | ** <ul> |
| 1862 | ** <li> 64-bit signed integer |
| 1863 | ** <li> 64-bit IEEE floating point number |
| 1864 | ** <li> string |
| 1865 | ** <li> BLOB |
| 1866 | ** <li> NULL |
| 1867 | ** </ul> |
| 1868 | ** |
| 1869 | ** These constants are codes for each of those types. |
| 1870 | ** |
| 1871 | ** Note that the SQLITE_TEXT constant was also used in SQLite version 2 |
| 1872 | ** for a completely different meaning. Software that links against both |
| 1873 | ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT not |
| 1874 | ** SQLITE_TEXT. |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1875 | */ |
drh | 9c05483 | 2004-05-31 18:51:57 +0000 | [diff] [blame] | 1876 | #define SQLITE_INTEGER 1 |
| 1877 | #define SQLITE_FLOAT 2 |
drh | 9c05483 | 2004-05-31 18:51:57 +0000 | [diff] [blame] | 1878 | #define SQLITE_BLOB 4 |
| 1879 | #define SQLITE_NULL 5 |
drh | 1e284f4 | 2004-10-06 15:52:01 +0000 | [diff] [blame] | 1880 | #ifdef SQLITE_TEXT |
| 1881 | # undef SQLITE_TEXT |
| 1882 | #else |
| 1883 | # define SQLITE_TEXT 3 |
| 1884 | #endif |
| 1885 | #define SQLITE3_TEXT 3 |
| 1886 | |
| 1887 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1888 | ** CAPI3REF: Results Values From A Query |
| 1889 | ** |
| 1890 | ** These routines return information about the information |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1891 | ** in a single column of the current result row of a query. In every |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1892 | ** case the first argument is a pointer to the |
| 1893 | ** [sqlite3_stmt | SQL statement] that is being |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1894 | ** evaluate (the [sqlite3_stmt*] that was returned from |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1895 | ** [sqlite3_prepare_v2()] or one of its variants) and |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1896 | ** the second argument is the index of the column for which information |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1897 | ** should be returned. The left-most column has an index of 0. |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 1898 | ** |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1899 | ** If the SQL statement is not currently point to a valid row, or if the |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1900 | ** the column index is out of range, the result is undefined. |
| 1901 | ** |
| 1902 | ** The sqlite3_column_type() routine returns |
| 1903 | ** [SQLITE_INTEGER | datatype code] for the initial data type |
| 1904 | ** of the result column. The returned value is one of [SQLITE_INTEGER], |
| 1905 | ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value |
| 1906 | ** returned by sqlite3_column_type() is only meaningful if no type |
| 1907 | ** conversions have occurred as described below. After a type conversion, |
| 1908 | ** the value returned by sqlite3_column_type() is undefined. Future |
| 1909 | ** versions of SQLite may change the behavior of sqlite3_column_type() |
| 1910 | ** following a type conversion. |
| 1911 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1912 | ** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() |
| 1913 | ** routine returns the number of bytes in that BLOB or string. |
| 1914 | ** If the result is a UTF-16 string, then sqlite3_column_bytes() converts |
| 1915 | ** the string to UTF-8 and then returns the number of bytes. |
| 1916 | ** If the result is a numeric value then sqlite3_column_bytes() uses |
| 1917 | ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns |
| 1918 | ** the number of bytes in that string. |
| 1919 | ** The value returned does not include the zero terminator at the end |
| 1920 | ** of the string. For clarity: the value returned is the number of |
| 1921 | ** bytes in the string, not the number of characters. |
| 1922 | ** |
| 1923 | ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes() |
| 1924 | ** but leaves the result in UTF-16 instead of UTF-8. |
| 1925 | ** The zero terminator is not included in this count. |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1926 | ** |
| 1927 | ** These routines attempt to convert the value where appropriate. For |
| 1928 | ** example, if the internal representation is FLOAT and a text result |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1929 | ** is requested, [sqlite3_snprintf()] is used internally to do the conversion |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1930 | ** automatically. The following table details the conversions that |
| 1931 | ** are applied: |
| 1932 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1933 | ** <blockquote> |
| 1934 | ** <table border="1"> |
| 1935 | ** <tr><th> Internal <th> Requested <th> |
| 1936 | ** <tr><th> Type <th> Type <th> Conversion |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1937 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1938 | ** <tr><td> NULL <td> INTEGER <td> Result is 0 |
| 1939 | ** <tr><td> NULL <td> FLOAT <td> Result is 0.0 |
| 1940 | ** <tr><td> NULL <td> TEXT <td> Result is NULL pointer |
| 1941 | ** <tr><td> NULL <td> BLOB <td> Result is NULL pointer |
| 1942 | ** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float |
| 1943 | ** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer |
| 1944 | ** <tr><td> INTEGER <td> BLOB <td> Same as for INTEGER->TEXT |
| 1945 | ** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer |
| 1946 | ** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float |
| 1947 | ** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT |
| 1948 | ** <tr><td> TEXT <td> INTEGER <td> Use atoi() |
| 1949 | ** <tr><td> TEXT <td> FLOAT <td> Use atof() |
| 1950 | ** <tr><td> TEXT <td> BLOB <td> No change |
| 1951 | ** <tr><td> BLOB <td> INTEGER <td> Convert to TEXT then use atoi() |
| 1952 | ** <tr><td> BLOB <td> FLOAT <td> Convert to TEXT then use atof() |
| 1953 | ** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed |
| 1954 | ** </table> |
| 1955 | ** </blockquote> |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1956 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1957 | ** The table above makes reference to standard C library functions atoi() |
| 1958 | ** and atof(). SQLite does not really use these functions. It has its |
| 1959 | ** on equavalent internal routines. The atoi() and atof() names are |
| 1960 | ** used in the table for brevity and because they are familiar to most |
| 1961 | ** C programmers. |
| 1962 | ** |
| 1963 | ** Note that when type conversions occur, pointers returned by prior |
| 1964 | ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or |
| 1965 | ** sqlite3_column_text16() may be invalidated. |
| 1966 | ** Type conversions and pointer invalidations might occur |
| 1967 | ** in the following cases: |
| 1968 | ** |
| 1969 | ** <ul> |
| 1970 | ** <li><p> The initial content is a BLOB and sqlite3_column_text() |
| 1971 | ** or sqlite3_column_text16() is called. A zero-terminator might |
| 1972 | ** need to be added to the string.</p></li> |
| 1973 | ** |
| 1974 | ** <li><p> The initial content is UTF-8 text and sqlite3_column_bytes16() or |
| 1975 | ** sqlite3_column_text16() is called. The content must be converted |
| 1976 | ** to UTF-16.</p></li> |
| 1977 | ** |
| 1978 | ** <li><p> The initial content is UTF-16 text and sqlite3_column_bytes() or |
| 1979 | ** sqlite3_column_text() is called. The content must be converted |
| 1980 | ** to UTF-8.</p></li> |
| 1981 | ** </ul> |
| 1982 | ** |
| 1983 | ** Conversions between UTF-16be and UTF-16le are always done in place and do |
| 1984 | ** not invalidate a prior pointer, though of course the content of the buffer |
| 1985 | ** that the prior pointer points to will have been modified. Other kinds |
| 1986 | ** of conversion are done in place when it is possible, but sometime it is |
| 1987 | ** not possible and in those cases prior pointers are invalidated. |
| 1988 | ** |
| 1989 | ** The safest and easiest to remember policy is to invoke these routines |
| 1990 | ** in one of the following ways: |
| 1991 | ** |
| 1992 | ** <ul> |
| 1993 | ** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li> |
| 1994 | ** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li> |
| 1995 | ** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li> |
| 1996 | ** </ul> |
| 1997 | ** |
| 1998 | ** In other words, you should call sqlite3_column_text(), sqlite3_column_blob(), |
| 1999 | ** or sqlite3_column_text16() first to force the result into the desired |
| 2000 | ** format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to |
| 2001 | ** find the size of the result. Do not mix call to sqlite3_column_text() or |
| 2002 | ** sqlite3_column_blob() with calls to sqlite3_column_bytes16(). And do not |
| 2003 | ** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes(). |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 2004 | */ |
drh | f447950 | 2004-05-27 03:12:53 +0000 | [diff] [blame] | 2005 | const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); |
| 2006 | int sqlite3_column_bytes(sqlite3_stmt*, int iCol); |
| 2007 | int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); |
| 2008 | double sqlite3_column_double(sqlite3_stmt*, int iCol); |
| 2009 | int sqlite3_column_int(sqlite3_stmt*, int iCol); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 2010 | sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); |
drh | f447950 | 2004-05-27 03:12:53 +0000 | [diff] [blame] | 2011 | const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); |
| 2012 | const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 2013 | int sqlite3_column_type(sqlite3_stmt*, int iCol); |
drh | 4be8b51 | 2006-06-13 23:51:34 +0000 | [diff] [blame] | 2014 | sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); |
danielk1977 | 4adee20 | 2004-05-08 08:23:19 +0000 | [diff] [blame] | 2015 | |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2016 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2017 | ** CAPI3REF: Destroy A Prepared Statement Object |
| 2018 | ** |
| 2019 | ** The sqlite3_finalize() function is called to delete a |
| 2020 | ** [sqlite3_stmt | compiled SQL statement]. If the statement was |
| 2021 | ** executed successfully, or not executed at all, then SQLITE_OK is returned. |
| 2022 | ** If execution of the statement failed then an |
| 2023 | ** [SQLITE_ERROR | error code] or [SQLITE_IOERR_READ | extended error code] |
| 2024 | ** is returned. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2025 | ** |
| 2026 | ** This routine can be called at any point during the execution of the |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2027 | ** [sqlite3_stmt | virtual machine]. If the virtual machine has not |
| 2028 | ** completed execution when this routine is called, that is like |
| 2029 | ** encountering an error or an interrupt. (See [sqlite3_interrupt()].) |
| 2030 | ** Incomplete updates may be rolled back and transactions cancelled, |
| 2031 | ** depending on the circumstances, and the |
| 2032 | ** [SQLITE_ERROR | result code] returned will be [SQLITE_ABORT]. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2033 | */ |
| 2034 | int sqlite3_finalize(sqlite3_stmt *pStmt); |
| 2035 | |
| 2036 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2037 | ** CAPI3REF: Reset A Prepared Statement Object |
| 2038 | ** |
| 2039 | ** The sqlite3_reset() function is called to reset a |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 2040 | ** [sqlite3_stmt | compiled SQL statement] object. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2041 | ** back to it's initial state, ready to be re-executed. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2042 | ** Any SQL statement variables that had values bound to them using |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2043 | ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values. |
| 2044 | ** Use [sqlite3_clear_bindings()] to reset the bindings. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2045 | */ |
| 2046 | int sqlite3_reset(sqlite3_stmt *pStmt); |
| 2047 | |
| 2048 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2049 | ** CAPI3REF: Create Or Redefine SQL Functions |
| 2050 | ** |
| 2051 | ** The following two functions are used to add SQL functions or aggregates |
| 2052 | ** or to redefine the behavior of existing SQL functions or aggregates. The |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2053 | ** difference only between the two is that the second parameter, the |
| 2054 | ** name of the (scalar) function or aggregate, is encoded in UTF-8 for |
| 2055 | ** sqlite3_create_function() and UTF-16 for sqlite3_create_function16(). |
| 2056 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2057 | ** The first argument is the [sqlite3 | database handle] that holds the |
| 2058 | ** SQL function or aggregate is to be added or redefined. If a single |
| 2059 | ** program uses more than one database handle internally, then SQL |
| 2060 | ** functions or aggregates must be added individually to each database |
| 2061 | ** handle with which they will be used. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2062 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2063 | ** The second parameter is the name of the SQL function to be created |
| 2064 | ** or redefined. |
| 2065 | ** The length of the name is limited to 255 bytes, exclusive of the |
| 2066 | ** zero-terminator. Note that the name length limit is in bytes, not |
| 2067 | ** characters. Any attempt to create a function with a longer name |
| 2068 | ** will result in an SQLITE_ERROR error. |
| 2069 | ** |
| 2070 | ** The third parameter is the number of arguments that the SQL function or |
| 2071 | ** aggregate takes. If this parameter is negative, then the SQL function or |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2072 | ** aggregate may take any number of arguments. |
| 2073 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2074 | ** The fourth parameter, eTextRep, specifies what |
| 2075 | ** [SQLITE_UTF8 | text encoding] this SQL function prefers for |
| 2076 | ** its parameters. Any SQL function implementation should be able to work |
| 2077 | ** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be |
| 2078 | ** more efficient with one encoding than another. It is allowed to |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 2079 | ** invoke sqlite3_create_function() or sqlite3_create_function16() multiple |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2080 | ** times with the same function but with different values of eTextRep. |
| 2081 | ** When multiple implementations of the same function are available, SQLite |
| 2082 | ** will pick the one that involves the least amount of data conversion. |
| 2083 | ** If there is only a single implementation which does not care what |
| 2084 | ** text encoding is used, then the fourth argument should be |
| 2085 | ** [SQLITE_ANY]. |
| 2086 | ** |
| 2087 | ** The fifth parameter is an arbitrary pointer. The implementation |
| 2088 | ** of the function can gain access to this pointer using |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 2089 | ** [sqlite3_user_data()]. |
danielk1977 | d02eb1f | 2004-06-06 09:44:03 +0000 | [diff] [blame] | 2090 | ** |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2091 | ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2092 | ** pointers to C-language functions that implement the SQL |
| 2093 | ** function or aggregate. A scalar SQL function requires an implementation of |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2094 | ** the xFunc callback only, NULL pointers should be passed as the xStep |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2095 | ** and xFinal parameters. An aggregate SQL function requires an implementation |
| 2096 | ** of xStep and xFinal and NULL should be passed for xFunc. To delete an |
| 2097 | ** existing SQL function or aggregate, pass NULL for all three function |
| 2098 | ** callback. |
| 2099 | ** |
| 2100 | ** It is permitted to register multiple implementations of the same |
| 2101 | ** functions with the same name but with either differing numbers of |
| 2102 | ** arguments or differing perferred text encodings. SQLite will use |
| 2103 | ** the implementation most closely matches the way in which the |
| 2104 | ** SQL function is used. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2105 | */ |
| 2106 | int sqlite3_create_function( |
| 2107 | sqlite3 *, |
| 2108 | const char *zFunctionName, |
| 2109 | int nArg, |
| 2110 | int eTextRep, |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2111 | void*, |
| 2112 | void (*xFunc)(sqlite3_context*,int,sqlite3_value**), |
| 2113 | void (*xStep)(sqlite3_context*,int,sqlite3_value**), |
| 2114 | void (*xFinal)(sqlite3_context*) |
| 2115 | ); |
| 2116 | int sqlite3_create_function16( |
| 2117 | sqlite3*, |
| 2118 | const void *zFunctionName, |
| 2119 | int nArg, |
| 2120 | int eTextRep, |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2121 | void*, |
| 2122 | void (*xFunc)(sqlite3_context*,int,sqlite3_value**), |
| 2123 | void (*xStep)(sqlite3_context*,int,sqlite3_value**), |
| 2124 | void (*xFinal)(sqlite3_context*) |
| 2125 | ); |
| 2126 | |
| 2127 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2128 | ** CAPI3REF: Text Encodings |
| 2129 | ** |
| 2130 | ** These constant define integer codes that represent the various |
| 2131 | ** text encodings supported by SQLite. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2132 | */ |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2133 | #define SQLITE_UTF8 1 |
| 2134 | #define SQLITE_UTF16LE 2 |
| 2135 | #define SQLITE_UTF16BE 3 |
| 2136 | #define SQLITE_UTF16 4 /* Use native byte order */ |
| 2137 | #define SQLITE_ANY 5 /* sqlite3_create_function only */ |
| 2138 | #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2139 | |
danielk1977 | 0ffba6b | 2004-05-24 09:10:10 +0000 | [diff] [blame] | 2140 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2141 | ** CAPI3REF: Obsolete Functions |
| 2142 | ** |
| 2143 | ** These functions are all now obsolete. In order to maintain |
| 2144 | ** backwards compatibility with older code, we continue to support |
| 2145 | ** these functions. However, new development projects should avoid |
| 2146 | ** the use of these functions. To help encourage people to avoid |
| 2147 | ** using these functions, we are not going to tell you want they do. |
| 2148 | */ |
| 2149 | int sqlite3_aggregate_count(sqlite3_context*); |
| 2150 | int sqlite3_expired(sqlite3_stmt*); |
| 2151 | int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); |
| 2152 | int sqlite3_global_recover(void); |
| 2153 | |
| 2154 | |
| 2155 | /* |
| 2156 | ** CAPI3REF: Obtaining SQL Function Parameter Values |
| 2157 | ** |
| 2158 | ** The C-language implementation of SQL functions and aggregates uses |
| 2159 | ** this set of interface routines to access the parameter values on |
| 2160 | ** the function or aggregate. |
| 2161 | ** |
| 2162 | ** The xFunc (for scalar functions) or xStep (for aggregates) parameters |
| 2163 | ** to [sqlite3_create_function()] and [sqlite3_create_function16()] |
| 2164 | ** define callbacks that implement the SQL functions and aggregates. |
| 2165 | ** The 4th parameter to these callbacks is an array of pointers to |
| 2166 | ** [sqlite3_value] objects. There is one [sqlite3_value] object for |
| 2167 | ** each parameter to the SQL function. These routines are used to |
| 2168 | ** extract values from the [sqlite3_value] objects. |
| 2169 | ** |
| 2170 | ** These routines work just like the corresponding |
| 2171 | ** [sqlite3_column_blob | sqlite3_column_* routines] except that |
| 2172 | ** these routines take a single [sqlite3_value*] pointer instead |
| 2173 | ** of an [sqlite3_stmt*] pointer and an integer column number. |
| 2174 | ** |
| 2175 | ** The sqlite3_value_text16() interface extracts a UTF16 string |
| 2176 | ** in the native byte-order of the host machine. The |
| 2177 | ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces |
| 2178 | ** extract UTF16 strings as big-endian and little-endian respectively. |
| 2179 | ** |
| 2180 | ** The sqlite3_value_numeric_type() interface attempts to apply |
| 2181 | ** numeric affinity to the value. This means that an attempt is |
| 2182 | ** made to convert the value to an integer or floating point. If |
| 2183 | ** such a conversion is possible without loss of information (in order |
| 2184 | ** words if the value is original a string that looks like a number) |
| 2185 | ** then it is done. Otherwise no conversion occurs. The |
| 2186 | ** [SQLITE_INTEGER | datatype] after conversion is returned. |
| 2187 | ** |
| 2188 | ** Please pay particular attention to the fact that the pointer that |
| 2189 | ** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or |
| 2190 | ** [sqlite3_value_text16()] can be invalidated by a subsequent call to |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 2191 | ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()], |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2192 | ** or [sqlite3_value_text16()]. |
drh | e53831d | 2007-08-17 01:14:38 +0000 | [diff] [blame] | 2193 | ** |
| 2194 | ** These routines must be called from the same thread as |
| 2195 | ** the SQL function that supplied the sqlite3_value* parameters. |
danielk1977 | 0ffba6b | 2004-05-24 09:10:10 +0000 | [diff] [blame] | 2196 | */ |
drh | f447950 | 2004-05-27 03:12:53 +0000 | [diff] [blame] | 2197 | const void *sqlite3_value_blob(sqlite3_value*); |
| 2198 | int sqlite3_value_bytes(sqlite3_value*); |
| 2199 | int sqlite3_value_bytes16(sqlite3_value*); |
| 2200 | double sqlite3_value_double(sqlite3_value*); |
| 2201 | int sqlite3_value_int(sqlite3_value*); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 2202 | sqlite3_int64 sqlite3_value_int64(sqlite3_value*); |
drh | f447950 | 2004-05-27 03:12:53 +0000 | [diff] [blame] | 2203 | const unsigned char *sqlite3_value_text(sqlite3_value*); |
| 2204 | const void *sqlite3_value_text16(sqlite3_value*); |
danielk1977 | d812336 | 2004-06-12 09:25:12 +0000 | [diff] [blame] | 2205 | const void *sqlite3_value_text16le(sqlite3_value*); |
| 2206 | const void *sqlite3_value_text16be(sqlite3_value*); |
danielk1977 | 93d4675 | 2004-05-23 13:30:58 +0000 | [diff] [blame] | 2207 | int sqlite3_value_type(sqlite3_value*); |
drh | 29d7210 | 2006-02-09 22:13:41 +0000 | [diff] [blame] | 2208 | int sqlite3_value_numeric_type(sqlite3_value*); |
danielk1977 | 0ffba6b | 2004-05-24 09:10:10 +0000 | [diff] [blame] | 2209 | |
| 2210 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2211 | ** CAPI3REF: Obtain Aggregate Function Context |
| 2212 | ** |
| 2213 | ** The implementation of aggregate SQL functions use this routine to allocate |
danielk1977 | 0ae8b83 | 2004-05-25 12:05:56 +0000 | [diff] [blame] | 2214 | ** a structure for storing their state. The first time this routine |
| 2215 | ** is called for a particular aggregate, a new structure of size nBytes |
| 2216 | ** is allocated, zeroed, and returned. On subsequent calls (for the |
| 2217 | ** same aggregate instance) the same buffer is returned. The implementation |
| 2218 | ** of the aggregate can use the returned buffer to accumulate data. |
| 2219 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2220 | ** The buffer allocated is freed automatically by SQLite whan the aggregate |
| 2221 | ** query concludes. |
| 2222 | ** |
| 2223 | ** The first parameter should be a copy of the |
| 2224 | ** [sqlite3_context | SQL function context] that is the first |
| 2225 | ** parameter to the callback routine that implements the aggregate |
| 2226 | ** function. |
drh | e53831d | 2007-08-17 01:14:38 +0000 | [diff] [blame] | 2227 | ** |
| 2228 | ** This routine must be called from the same thread in which |
drh | 605264d | 2007-08-21 15:13:19 +0000 | [diff] [blame^] | 2229 | ** the aggregate SQL function is running. |
danielk1977 | 0ae8b83 | 2004-05-25 12:05:56 +0000 | [diff] [blame] | 2230 | */ |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 2231 | void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); |
danielk1977 | 7e18c25 | 2004-05-25 11:47:24 +0000 | [diff] [blame] | 2232 | |
| 2233 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2234 | ** CAPI3REF: User Data For Functions |
| 2235 | ** |
| 2236 | ** The pUserData parameter to the [sqlite3_create_function()] |
| 2237 | ** and [sqlite3_create_function16()] routines |
| 2238 | ** used to register user functions is available to |
drh | c0f2a01 | 2005-07-09 02:39:40 +0000 | [diff] [blame] | 2239 | ** the implementation of the function using this call. |
drh | e53831d | 2007-08-17 01:14:38 +0000 | [diff] [blame] | 2240 | ** |
| 2241 | ** This routine must be called from the same thread in which |
| 2242 | ** the SQL function was originally invoked. |
danielk1977 | 7e18c25 | 2004-05-25 11:47:24 +0000 | [diff] [blame] | 2243 | */ |
| 2244 | void *sqlite3_user_data(sqlite3_context*); |
| 2245 | |
| 2246 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2247 | ** CAPI3REF: Function Auxiliary Data |
| 2248 | ** |
| 2249 | ** The following two functions may be used by scalar SQL functions to |
danielk1977 | 682f68b | 2004-06-05 10:22:17 +0000 | [diff] [blame] | 2250 | ** associate meta-data with argument values. If the same value is passed to |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2251 | ** multiple invocations of the same SQL function during query execution, under |
danielk1977 | 682f68b | 2004-06-05 10:22:17 +0000 | [diff] [blame] | 2252 | ** some circumstances the associated meta-data may be preserved. This may |
| 2253 | ** be used, for example, to add a regular-expression matching scalar |
| 2254 | ** function. The compiled version of the regular expression is stored as |
| 2255 | ** meta-data associated with the SQL value passed as the regular expression |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2256 | ** pattern. The compiled regular expression can be reused on multiple |
| 2257 | ** invocations of the same function so that the original pattern string |
| 2258 | ** does not need to be recompiled on each invocation. |
danielk1977 | 682f68b | 2004-06-05 10:22:17 +0000 | [diff] [blame] | 2259 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2260 | ** The sqlite3_get_auxdata() interface returns a pointer to the meta-data |
| 2261 | ** associated with the Nth argument value to the current SQL function |
danielk1977 | 682f68b | 2004-06-05 10:22:17 +0000 | [diff] [blame] | 2262 | ** call, where N is the second parameter. If no meta-data has been set for |
| 2263 | ** that value, then a NULL pointer is returned. |
| 2264 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2265 | ** The sqlite3_set_auxdata() is used to associate meta-data with an SQL |
| 2266 | ** function argument. The third parameter is a pointer to the meta-data |
danielk1977 | 682f68b | 2004-06-05 10:22:17 +0000 | [diff] [blame] | 2267 | ** to be associated with the Nth user function argument value. The fourth |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2268 | ** parameter specifies a destructor that will be called on the meta- |
| 2269 | ** data pointer to release it when it is no longer required. If the |
| 2270 | ** destructor is NULL, it is not invoked. |
danielk1977 | 682f68b | 2004-06-05 10:22:17 +0000 | [diff] [blame] | 2271 | ** |
| 2272 | ** In practice, meta-data is preserved between function calls for |
| 2273 | ** expressions that are constant at compile time. This includes literal |
| 2274 | ** values and SQL variables. |
drh | e53831d | 2007-08-17 01:14:38 +0000 | [diff] [blame] | 2275 | ** |
| 2276 | ** These routine must be called from the same thread in which |
| 2277 | ** the SQL function was originally invoked. |
danielk1977 | 682f68b | 2004-06-05 10:22:17 +0000 | [diff] [blame] | 2278 | */ |
| 2279 | void *sqlite3_get_auxdata(sqlite3_context*, int); |
| 2280 | void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*)); |
| 2281 | |
drh | a285422 | 2004-06-17 19:04:17 +0000 | [diff] [blame] | 2282 | |
| 2283 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2284 | ** CAPI3REF: Constants Defining Special Destructor Behavior |
| 2285 | ** |
drh | a285422 | 2004-06-17 19:04:17 +0000 | [diff] [blame] | 2286 | ** These are special value for the destructor that is passed in as the |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2287 | ** final argument to routines like [sqlite3_result_blob()]. If the destructor |
drh | a285422 | 2004-06-17 19:04:17 +0000 | [diff] [blame] | 2288 | ** argument is SQLITE_STATIC, it means that the content pointer is constant |
| 2289 | ** and will never change. It does not need to be destroyed. The |
| 2290 | ** SQLITE_TRANSIENT value means that the content will likely change in |
| 2291 | ** the near future and that SQLite should make its own private copy of |
| 2292 | ** the content before returning. |
drh | 6c9121a | 2007-01-26 00:51:43 +0000 | [diff] [blame] | 2293 | ** |
| 2294 | ** The typedef is necessary to work around problems in certain |
| 2295 | ** C++ compilers. See ticket #2191. |
drh | a285422 | 2004-06-17 19:04:17 +0000 | [diff] [blame] | 2296 | */ |
drh | 6c9121a | 2007-01-26 00:51:43 +0000 | [diff] [blame] | 2297 | typedef void (*sqlite3_destructor_type)(void*); |
| 2298 | #define SQLITE_STATIC ((sqlite3_destructor_type)0) |
| 2299 | #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) |
danielk1977 | d812336 | 2004-06-12 09:25:12 +0000 | [diff] [blame] | 2300 | |
danielk1977 | 682f68b | 2004-06-05 10:22:17 +0000 | [diff] [blame] | 2301 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2302 | ** CAPI3REF: Setting The Result Of An SQL Function |
| 2303 | ** |
| 2304 | ** These routines are used by the xFunc or xFinal callbacks that |
| 2305 | ** implement SQL functions and aggregates. See |
| 2306 | ** [sqlite3_create_function()] and [sqlite3_create_function16()] |
| 2307 | ** for additional information. |
| 2308 | ** |
| 2309 | ** These functions work very much like the |
| 2310 | ** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used |
| 2311 | ** to bind values to host parameters in prepared statements. |
| 2312 | ** Refer to the |
| 2313 | ** [sqlite3_bind_blob | sqlite3_bind_* documentation] for |
| 2314 | ** additional information. |
| 2315 | ** |
| 2316 | ** The sqlite3_result_error() and sqlite3_result_error16() functions |
| 2317 | ** cause the implemented SQL function to throw an exception. The |
| 2318 | ** parameter to sqlite3_result_error() or sqlite3_result_error16() |
| 2319 | ** is the text of an error message. |
| 2320 | ** |
| 2321 | ** The sqlite3_result_toobig() cause the function implementation |
| 2322 | ** to throw and error indicating that a string or BLOB is to long |
| 2323 | ** to represent. |
drh | e53831d | 2007-08-17 01:14:38 +0000 | [diff] [blame] | 2324 | ** |
| 2325 | ** These routines must be called from within the same thread as |
| 2326 | ** the SQL function associated with the [sqlite3_context] pointer. |
danielk1977 | 7e18c25 | 2004-05-25 11:47:24 +0000 | [diff] [blame] | 2327 | */ |
danielk1977 | d812336 | 2004-06-12 09:25:12 +0000 | [diff] [blame] | 2328 | void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 2329 | void sqlite3_result_double(sqlite3_context*, double); |
danielk1977 | 7e18c25 | 2004-05-25 11:47:24 +0000 | [diff] [blame] | 2330 | void sqlite3_result_error(sqlite3_context*, const char*, int); |
| 2331 | void sqlite3_result_error16(sqlite3_context*, const void*, int); |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2332 | void sqlite3_result_error_toobig(sqlite3_context*); |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 2333 | void sqlite3_result_int(sqlite3_context*, int); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 2334 | void sqlite3_result_int64(sqlite3_context*, sqlite3_int64); |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 2335 | void sqlite3_result_null(sqlite3_context*); |
danielk1977 | d812336 | 2004-06-12 09:25:12 +0000 | [diff] [blame] | 2336 | void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); |
| 2337 | void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); |
| 2338 | void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); |
| 2339 | void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 2340 | void sqlite3_result_value(sqlite3_context*, sqlite3_value*); |
drh | b026e05 | 2007-05-02 01:34:31 +0000 | [diff] [blame] | 2341 | void sqlite3_result_zeroblob(sqlite3_context*, int n); |
drh | f9b596e | 2004-05-26 16:54:42 +0000 | [diff] [blame] | 2342 | |
drh | 52619df | 2004-06-11 17:48:02 +0000 | [diff] [blame] | 2343 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2344 | ** CAPI3REF: Define New Collating Sequences |
| 2345 | ** |
| 2346 | ** These functions are used to add new collation sequences to the |
| 2347 | ** [sqlite3*] handle specified as the first argument. |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 2348 | ** |
| 2349 | ** The name of the new collation sequence is specified as a UTF-8 string |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2350 | ** for sqlite3_create_collation() and sqlite3_create_collation_v2() |
| 2351 | ** and a UTF-16 string for sqlite3_create_collation16(). In all cases |
| 2352 | ** the name is passed as the second function argument. |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 2353 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2354 | ** The third argument must be one of the constants [SQLITE_UTF8], |
| 2355 | ** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 2356 | ** routine expects to be passed pointers to strings encoded using UTF-8, |
| 2357 | ** UTF-16 little-endian or UTF-16 big-endian respectively. |
| 2358 | ** |
| 2359 | ** A pointer to the user supplied routine must be passed as the fifth |
| 2360 | ** argument. If it is NULL, this is the same as deleting the collation |
| 2361 | ** sequence (so that SQLite cannot call it anymore). Each time the user |
| 2362 | ** supplied function is invoked, it is passed a copy of the void* passed as |
| 2363 | ** the fourth argument to sqlite3_create_collation() or |
| 2364 | ** sqlite3_create_collation16() as its first parameter. |
| 2365 | ** |
| 2366 | ** The remaining arguments to the user-supplied routine are two strings, |
| 2367 | ** each represented by a [length, data] pair and encoded in the encoding |
| 2368 | ** that was passed as the third argument when the collation sequence was |
| 2369 | ** registered. The user routine should return negative, zero or positive if |
| 2370 | ** the first string is less than, equal to, or greater than the second |
| 2371 | ** string. i.e. (STRING1 - STRING2). |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2372 | ** |
| 2373 | ** The sqlite3_create_collation_v2() works like sqlite3_create_collation() |
| 2374 | ** excapt that it takes an extra argument which is a destructor for |
| 2375 | ** the collation. The destructor is called when the collation is |
| 2376 | ** destroyed and is passed a copy of the fourth parameter void* pointer |
| 2377 | ** of the sqlite3_create_collation_v2(). Collations are destroyed when |
| 2378 | ** they are overridden by later calls to the collation creation functions |
| 2379 | ** or when the [sqlite3*] database handle is closed using [sqlite3_close()]. |
| 2380 | ** |
| 2381 | ** The sqlite3_create_collation_v2() interface is experimental and |
| 2382 | ** subject to change in future releases. The other collation creation |
| 2383 | ** functions are stable. |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 2384 | */ |
danielk1977 | 0202b29 | 2004-06-09 09:55:16 +0000 | [diff] [blame] | 2385 | int sqlite3_create_collation( |
| 2386 | sqlite3*, |
| 2387 | const char *zName, |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 2388 | int eTextRep, |
danielk1977 | 0202b29 | 2004-06-09 09:55:16 +0000 | [diff] [blame] | 2389 | void*, |
| 2390 | int(*xCompare)(void*,int,const void*,int,const void*) |
| 2391 | ); |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2392 | int sqlite3_create_collation_v2( |
| 2393 | sqlite3*, |
| 2394 | const char *zName, |
| 2395 | int eTextRep, |
| 2396 | void*, |
| 2397 | int(*xCompare)(void*,int,const void*,int,const void*), |
| 2398 | void(*xDestroy)(void*) |
| 2399 | ); |
danielk1977 | 0202b29 | 2004-06-09 09:55:16 +0000 | [diff] [blame] | 2400 | int sqlite3_create_collation16( |
| 2401 | sqlite3*, |
| 2402 | const char *zName, |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 2403 | int eTextRep, |
danielk1977 | 0202b29 | 2004-06-09 09:55:16 +0000 | [diff] [blame] | 2404 | void*, |
| 2405 | int(*xCompare)(void*,int,const void*,int,const void*) |
| 2406 | ); |
| 2407 | |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 2408 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2409 | ** CAPI3REF: Collation Needed Callbacks |
danielk1977 | a393c03 | 2007-05-07 14:58:53 +0000 | [diff] [blame] | 2410 | ** |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 2411 | ** To avoid having to register all collation sequences before a database |
| 2412 | ** can be used, a single callback function may be registered with the |
| 2413 | ** database handle to be called whenever an undefined collation sequence is |
| 2414 | ** required. |
| 2415 | ** |
| 2416 | ** If the function is registered using the sqlite3_collation_needed() API, |
| 2417 | ** then it is passed the names of undefined collation sequences as strings |
| 2418 | ** encoded in UTF-8. If sqlite3_collation_needed16() is used, the names |
| 2419 | ** are passed as UTF-16 in machine native byte order. A call to either |
| 2420 | ** function replaces any existing callback. |
| 2421 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2422 | ** When the callback is invoked, the first argument passed is a copy |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 2423 | ** of the second argument to sqlite3_collation_needed() or |
| 2424 | ** sqlite3_collation_needed16(). The second argument is the database |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2425 | ** handle. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], or |
| 2426 | ** [SQLITE_UTF16LE], indicating the most desirable form of the collation |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 2427 | ** sequence function required. The fourth parameter is the name of the |
| 2428 | ** required collation sequence. |
| 2429 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2430 | ** The callback function should register the desired collation using |
| 2431 | ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or |
| 2432 | ** [sqlite3_create_collation_v2()]. |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 2433 | */ |
| 2434 | int sqlite3_collation_needed( |
| 2435 | sqlite3*, |
| 2436 | void*, |
| 2437 | void(*)(void*,sqlite3*,int eTextRep,const char*) |
| 2438 | ); |
| 2439 | int sqlite3_collation_needed16( |
| 2440 | sqlite3*, |
| 2441 | void*, |
| 2442 | void(*)(void*,sqlite3*,int eTextRep,const void*) |
| 2443 | ); |
| 2444 | |
drh | 2011d5f | 2004-07-22 02:40:37 +0000 | [diff] [blame] | 2445 | /* |
| 2446 | ** Specify the key for an encrypted database. This routine should be |
| 2447 | ** called right after sqlite3_open(). |
| 2448 | ** |
| 2449 | ** The code to implement this API is not available in the public release |
| 2450 | ** of SQLite. |
| 2451 | */ |
| 2452 | int sqlite3_key( |
| 2453 | sqlite3 *db, /* Database to be rekeyed */ |
| 2454 | const void *pKey, int nKey /* The key */ |
| 2455 | ); |
| 2456 | |
| 2457 | /* |
| 2458 | ** Change the key on an open database. If the current database is not |
| 2459 | ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the |
| 2460 | ** database is decrypted. |
| 2461 | ** |
| 2462 | ** The code to implement this API is not available in the public release |
| 2463 | ** of SQLite. |
| 2464 | */ |
| 2465 | int sqlite3_rekey( |
| 2466 | sqlite3 *db, /* Database to be rekeyed */ |
| 2467 | const void *pKey, int nKey /* The new key */ |
| 2468 | ); |
danielk1977 | 0202b29 | 2004-06-09 09:55:16 +0000 | [diff] [blame] | 2469 | |
drh | ab3f9fe | 2004-08-14 17:10:10 +0000 | [diff] [blame] | 2470 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2471 | ** CAPI3REF: Suspend Execution For A Short Time |
| 2472 | ** |
danielk1977 | d84d483 | 2007-06-20 09:09:47 +0000 | [diff] [blame] | 2473 | ** This function causes the current thread to suspend execution |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2474 | ** a number of milliseconds specified in its parameter. |
danielk1977 | 600dd0b | 2005-01-20 01:14:23 +0000 | [diff] [blame] | 2475 | ** |
| 2476 | ** If the operating system does not support sleep requests with |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2477 | ** millisecond time resolution, then the time will be rounded up to |
| 2478 | ** the nearest second. The number of milliseconds of sleep actually |
danielk1977 | 600dd0b | 2005-01-20 01:14:23 +0000 | [diff] [blame] | 2479 | ** requested from the operating system is returned. |
danielk1977 | 600dd0b | 2005-01-20 01:14:23 +0000 | [diff] [blame] | 2480 | */ |
| 2481 | int sqlite3_sleep(int); |
| 2482 | |
| 2483 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2484 | ** CAPI3REF: Name Of The Folder Holding Temporary Files |
drh | d89bd00 | 2005-01-22 03:03:54 +0000 | [diff] [blame] | 2485 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2486 | ** If this global variable is made to point to a string which is |
| 2487 | ** the name of a folder (a.ka. directory), then all temporary files |
drh | ab3f9fe | 2004-08-14 17:10:10 +0000 | [diff] [blame] | 2488 | ** created by SQLite will be placed in that directory. If this variable |
| 2489 | ** is NULL pointer, then SQLite does a search for an appropriate temporary |
| 2490 | ** file directory. |
| 2491 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2492 | ** Once [sqlite3_open()] has been called, changing this variable will |
| 2493 | ** invalidate the current temporary database, if any. Generally speaking, |
| 2494 | ** it is not safe to invoke this routine after [sqlite3_open()] has |
| 2495 | ** been called. |
drh | ab3f9fe | 2004-08-14 17:10:10 +0000 | [diff] [blame] | 2496 | */ |
drh | 73be501 | 2007-08-08 12:11:21 +0000 | [diff] [blame] | 2497 | SQLITE_EXTERN char *sqlite3_temp_directory; |
drh | ab3f9fe | 2004-08-14 17:10:10 +0000 | [diff] [blame] | 2498 | |
danielk1977 | 6b456a2 | 2005-03-21 04:04:02 +0000 | [diff] [blame] | 2499 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2500 | ** CAPI3REF: Test To See If The Databse Is In Auto-Commit Mode |
danielk1977 | 6b456a2 | 2005-03-21 04:04:02 +0000 | [diff] [blame] | 2501 | ** |
drh | 3e1d8e6 | 2005-05-26 16:23:34 +0000 | [diff] [blame] | 2502 | ** Test to see whether or not the database connection is in autocommit |
| 2503 | ** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on |
| 2504 | ** by default. Autocommit is disabled by a BEGIN statement and reenabled |
| 2505 | ** by the next COMMIT or ROLLBACK. |
drh | 3e1d8e6 | 2005-05-26 16:23:34 +0000 | [diff] [blame] | 2506 | */ |
| 2507 | int sqlite3_get_autocommit(sqlite3*); |
| 2508 | |
drh | 51942bc | 2005-06-12 22:01:42 +0000 | [diff] [blame] | 2509 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2510 | ** CAPI3REF: Find The Database Handle Associated With A Prepared Statement |
| 2511 | ** |
| 2512 | ** Return the [sqlite3*] database handle to which a |
| 2513 | ** [sqlite3_stmt | prepared statement] belongs. |
| 2514 | ** This is the same database handle that was |
| 2515 | ** the first argument to the [sqlite3_prepare_v2()] or its variants |
| 2516 | ** that was used to create the statement in the first place. |
drh | 51942bc | 2005-06-12 22:01:42 +0000 | [diff] [blame] | 2517 | */ |
| 2518 | sqlite3 *sqlite3_db_handle(sqlite3_stmt*); |
drh | 3e1d8e6 | 2005-05-26 16:23:34 +0000 | [diff] [blame] | 2519 | |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2520 | |
drh | b37df7b | 2005-10-13 02:09:49 +0000 | [diff] [blame] | 2521 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2522 | ** CAPI3REF: Commit And Rollback Notification Callbacks |
| 2523 | ** |
| 2524 | ** These routines |
| 2525 | ** register callback functions to be invoked whenever a transaction |
| 2526 | ** is committed or rolled back. The pArg argument is passed through |
| 2527 | ** to the callback. If the callback on a commit hook function |
| 2528 | ** returns non-zero, then the commit is converted into a rollback. |
| 2529 | ** |
| 2530 | ** If another function was previously registered, its pArg value is returned. |
| 2531 | ** Otherwise NULL is returned. |
| 2532 | ** |
| 2533 | ** Registering a NULL function disables the callback. |
| 2534 | ** |
| 2535 | ** For the purposes of this API, a transaction is said to have been |
| 2536 | ** rolled back if an explicit "ROLLBACK" statement is executed, or |
| 2537 | ** an error or constraint causes an implicit rollback to occur. The |
| 2538 | ** callback is not invoked if a transaction is automatically rolled |
| 2539 | ** back because the database connection is closed. |
| 2540 | ** |
| 2541 | ** These are experimental interfaces and are subject to change. |
| 2542 | */ |
| 2543 | void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); |
| 2544 | void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); |
| 2545 | |
| 2546 | /* |
| 2547 | ** CAPI3REF: Data Change Notification Callbacks |
| 2548 | ** |
danielk1977 | 94eb6a1 | 2005-12-15 15:22:08 +0000 | [diff] [blame] | 2549 | ** Register a callback function with the database connection identified by the |
| 2550 | ** first argument to be invoked whenever a row is updated, inserted or deleted. |
| 2551 | ** Any callback set by a previous call to this function for the same |
| 2552 | ** database connection is overridden. |
| 2553 | ** |
| 2554 | ** The second argument is a pointer to the function to invoke when a |
| 2555 | ** row is updated, inserted or deleted. The first argument to the callback is |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2556 | ** a copy of the third argument to sqlite3_update_hook(). The second callback |
danielk1977 | 94eb6a1 | 2005-12-15 15:22:08 +0000 | [diff] [blame] | 2557 | ** argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending |
| 2558 | ** on the operation that caused the callback to be invoked. The third and |
| 2559 | ** fourth arguments to the callback contain pointers to the database and |
| 2560 | ** table name containing the affected row. The final callback parameter is |
| 2561 | ** the rowid of the row. In the case of an update, this is the rowid after |
| 2562 | ** the update takes place. |
| 2563 | ** |
| 2564 | ** The update hook is not invoked when internal system tables are |
| 2565 | ** modified (i.e. sqlite_master and sqlite_sequence). |
danielk1977 | 71fd80b | 2005-12-16 06:54:01 +0000 | [diff] [blame] | 2566 | ** |
| 2567 | ** If another function was previously registered, its pArg value is returned. |
| 2568 | ** Otherwise NULL is returned. |
danielk1977 | 94eb6a1 | 2005-12-15 15:22:08 +0000 | [diff] [blame] | 2569 | */ |
danielk1977 | 71fd80b | 2005-12-16 06:54:01 +0000 | [diff] [blame] | 2570 | void *sqlite3_update_hook( |
danielk1977 | 94eb6a1 | 2005-12-15 15:22:08 +0000 | [diff] [blame] | 2571 | sqlite3*, |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 2572 | void(*)(void *,int ,char const *,char const *,sqlite3_int64), |
danielk1977 | 94eb6a1 | 2005-12-15 15:22:08 +0000 | [diff] [blame] | 2573 | void* |
| 2574 | ); |
danielk1977 | 13a68c3 | 2005-12-15 10:11:30 +0000 | [diff] [blame] | 2575 | |
danielk1977 | f3f06bb | 2005-12-16 15:24:28 +0000 | [diff] [blame] | 2576 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2577 | ** CAPI3REF: Enable Or Disable Shared Pager Cache |
danielk1977 | f3f06bb | 2005-12-16 15:24:28 +0000 | [diff] [blame] | 2578 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2579 | ** This routine enables or disables the sharing of the database cache |
| 2580 | ** and schema data structures between connections to the same database. |
| 2581 | ** Sharing is enabled if the argument is true and disabled if the argument |
| 2582 | ** is false. |
danielk1977 | f3f06bb | 2005-12-16 15:24:28 +0000 | [diff] [blame] | 2583 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2584 | ** Cache sharing is enabled and disabled on a thread-by-thread basis. |
| 2585 | ** Each call to this routine enables or disables cache sharing only for |
| 2586 | ** connections created in the same thread in which this routine is called. |
| 2587 | ** There is no mechanism for sharing cache between database connections |
| 2588 | ** running in different threads. |
| 2589 | ** |
| 2590 | ** Sharing must be disabled prior to shutting down a thread or else |
| 2591 | ** the thread will leak memory. Call this routine with an argument of |
| 2592 | ** 0 to turn off sharing. Or use the sqlite3_thread_cleanup() API. |
| 2593 | ** |
| 2594 | ** This routine must not be called when any database connections |
| 2595 | ** are active in the current thread. Enabling or disabling shared |
| 2596 | ** cache while there are active database connections will result |
| 2597 | ** in memory corruption. |
| 2598 | ** |
| 2599 | ** When the shared cache is enabled, the |
| 2600 | ** following routines must always be called from the same thread: |
| 2601 | ** [sqlite3_open()], [sqlite3_prepare_v2()], [sqlite3_step()], |
| 2602 | ** [sqlite3_reset()], [sqlite3_finalize()], and [sqlite3_close()]. |
| 2603 | ** This is due to the fact that the shared cache makes use of |
| 2604 | ** thread-specific storage so that it will be available for sharing |
| 2605 | ** with other connections. |
| 2606 | ** |
| 2607 | ** Virtual tables cannot be used with a shared cache. When shared |
| 2608 | ** cache is enabled, the sqlite3_create_module() API used to register |
| 2609 | ** virtual tables will always return an error. |
| 2610 | ** |
| 2611 | ** This routine returns [SQLITE_OK] if shared cache was |
| 2612 | ** enabled or disabled successfully. An [SQLITE_ERROR | error code] |
| 2613 | ** is returned otherwise. |
| 2614 | ** |
| 2615 | ** Shared cache is disabled by default for backward compatibility. |
danielk1977 | aef0bf6 | 2005-12-30 16:28:01 +0000 | [diff] [blame] | 2616 | */ |
| 2617 | int sqlite3_enable_shared_cache(int); |
| 2618 | |
| 2619 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2620 | ** CAPI3REF: Attempt To Free Heap Memory |
| 2621 | ** |
danielk1977 | 5262282 | 2006-01-09 09:59:49 +0000 | [diff] [blame] | 2622 | ** Attempt to free N bytes of heap memory by deallocating non-essential |
| 2623 | ** memory allocations held by the database library (example: memory |
| 2624 | ** used to cache database pages to improve performance). |
| 2625 | ** |
drh | 6f7adc8 | 2006-01-11 21:41:20 +0000 | [diff] [blame] | 2626 | ** This function is not a part of standard builds. It is only created |
| 2627 | ** if SQLite is compiled with the SQLITE_ENABLE_MEMORY_MANAGEMENT macro. |
danielk1977 | 5262282 | 2006-01-09 09:59:49 +0000 | [diff] [blame] | 2628 | */ |
| 2629 | int sqlite3_release_memory(int); |
| 2630 | |
| 2631 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2632 | ** CAPI3REF: Impose A Limit On Heap Size |
| 2633 | ** |
danielk1977 | 5262282 | 2006-01-09 09:59:49 +0000 | [diff] [blame] | 2634 | ** Place a "soft" limit on the amount of heap memory that may be allocated by |
| 2635 | ** SQLite within the current thread. If an internal allocation is requested |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2636 | ** that would exceed the specified limit, [sqlite3_release_memory()] is invoked |
danielk1977 | 5262282 | 2006-01-09 09:59:49 +0000 | [diff] [blame] | 2637 | ** one or more times to free up some space before the allocation is made. |
| 2638 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2639 | ** The limit is called "soft", because if [sqlite3_release_memory()] cannot free |
danielk1977 | 5262282 | 2006-01-09 09:59:49 +0000 | [diff] [blame] | 2640 | ** sufficient memory to prevent the limit from being exceeded, the memory is |
| 2641 | ** allocated anyway and the current operation proceeds. |
| 2642 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2643 | ** Prior to shutting down a thread sqlite3_soft_heap_limit() must be set to |
| 2644 | ** zero (the default) or else the thread will leak memory. Alternatively, use |
| 2645 | ** the [sqlite3_thread_cleanup()] API. |
| 2646 | ** |
| 2647 | ** A negative or zero value for N means that there is no soft heap limit and |
| 2648 | ** [sqlite3_release_memory()] will only be called when memory is exhaused. |
| 2649 | ** The default value for the soft heap limit is zero. |
| 2650 | ** |
| 2651 | ** SQLite makes a best effort to honor the soft heap limit. But if it |
| 2652 | ** is unable to reduce memory usage below the soft limit, execution will |
| 2653 | ** continue without error or notification. This is why the limit is |
| 2654 | ** called a "soft" limit. It is advisory only. |
| 2655 | ** |
drh | 6f7adc8 | 2006-01-11 21:41:20 +0000 | [diff] [blame] | 2656 | ** This function is only available if the library was compiled with the |
| 2657 | ** SQLITE_ENABLE_MEMORY_MANAGEMENT option set. |
danielk1977 | 5262282 | 2006-01-09 09:59:49 +0000 | [diff] [blame] | 2658 | ** memory-management has been enabled. |
| 2659 | */ |
drh | d2d4a6b | 2006-01-10 15:18:27 +0000 | [diff] [blame] | 2660 | void sqlite3_soft_heap_limit(int); |
danielk1977 | 5262282 | 2006-01-09 09:59:49 +0000 | [diff] [blame] | 2661 | |
| 2662 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2663 | ** CAPI3REF: Clean Up Thread Local Storage |
| 2664 | ** |
drh | 6f7adc8 | 2006-01-11 21:41:20 +0000 | [diff] [blame] | 2665 | ** This routine makes sure that all thread-local storage has been |
| 2666 | ** deallocated for the current thread. |
| 2667 | ** |
| 2668 | ** This routine is not technically necessary. All thread-local storage |
| 2669 | ** will be automatically deallocated once memory-management and |
| 2670 | ** shared-cache are disabled and the soft heap limit has been set |
| 2671 | ** to zero. This routine is provided as a convenience for users who |
| 2672 | ** want to make absolutely sure they have not forgotten something |
| 2673 | ** prior to killing off a thread. |
| 2674 | */ |
| 2675 | void sqlite3_thread_cleanup(void); |
| 2676 | |
| 2677 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2678 | ** CAPI3REF: Extract Metadata About A Column Of A Table |
| 2679 | ** |
| 2680 | ** This routine |
| 2681 | ** returns meta-data about a specific column of a specific database |
danielk1977 | deb802c | 2006-02-09 13:43:28 +0000 | [diff] [blame] | 2682 | ** table accessible using the connection handle passed as the first function |
| 2683 | ** argument. |
| 2684 | ** |
| 2685 | ** The column is identified by the second, third and fourth parameters to |
| 2686 | ** this function. The second parameter is either the name of the database |
| 2687 | ** (i.e. "main", "temp" or an attached database) containing the specified |
| 2688 | ** table or NULL. If it is NULL, then all attached databases are searched |
| 2689 | ** for the table using the same algorithm as the database engine uses to |
| 2690 | ** resolve unqualified table references. |
| 2691 | ** |
| 2692 | ** The third and fourth parameters to this function are the table and column |
| 2693 | ** name of the desired column, respectively. Neither of these parameters |
| 2694 | ** may be NULL. |
| 2695 | ** |
| 2696 | ** Meta information is returned by writing to the memory locations passed as |
| 2697 | ** the 5th and subsequent parameters to this function. Any of these |
| 2698 | ** arguments may be NULL, in which case the corresponding element of meta |
| 2699 | ** information is ommitted. |
| 2700 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2701 | ** <pre> |
danielk1977 | deb802c | 2006-02-09 13:43:28 +0000 | [diff] [blame] | 2702 | ** Parameter Output Type Description |
| 2703 | ** ----------------------------------- |
| 2704 | ** |
| 2705 | ** 5th const char* Data type |
| 2706 | ** 6th const char* Name of the default collation sequence |
| 2707 | ** 7th int True if the column has a NOT NULL constraint |
| 2708 | ** 8th int True if the column is part of the PRIMARY KEY |
| 2709 | ** 9th int True if the column is AUTOINCREMENT |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2710 | ** </pre> |
danielk1977 | deb802c | 2006-02-09 13:43:28 +0000 | [diff] [blame] | 2711 | ** |
| 2712 | ** |
| 2713 | ** The memory pointed to by the character pointers returned for the |
| 2714 | ** declaration type and collation sequence is valid only until the next |
| 2715 | ** call to any sqlite API function. |
| 2716 | ** |
| 2717 | ** If the specified table is actually a view, then an error is returned. |
| 2718 | ** |
| 2719 | ** If the specified column is "rowid", "oid" or "_rowid_" and an |
| 2720 | ** INTEGER PRIMARY KEY column has been explicitly declared, then the output |
| 2721 | ** parameters are set for the explicitly declared column. If there is no |
| 2722 | ** explicitly declared IPK column, then the output parameters are set as |
| 2723 | ** follows: |
| 2724 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2725 | ** <pre> |
danielk1977 | deb802c | 2006-02-09 13:43:28 +0000 | [diff] [blame] | 2726 | ** data type: "INTEGER" |
| 2727 | ** collation sequence: "BINARY" |
| 2728 | ** not null: 0 |
| 2729 | ** primary key: 1 |
| 2730 | ** auto increment: 0 |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2731 | ** </pre> |
danielk1977 | deb802c | 2006-02-09 13:43:28 +0000 | [diff] [blame] | 2732 | ** |
| 2733 | ** This function may load one or more schemas from database files. If an |
| 2734 | ** error occurs during this process, or if the requested table or column |
| 2735 | ** cannot be found, an SQLITE error code is returned and an error message |
| 2736 | ** left in the database handle (to be retrieved using sqlite3_errmsg()). |
danielk1977 | 4b1ae99 | 2006-02-10 03:06:10 +0000 | [diff] [blame] | 2737 | ** |
| 2738 | ** This API is only available if the library was compiled with the |
| 2739 | ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. |
danielk1977 | deb802c | 2006-02-09 13:43:28 +0000 | [diff] [blame] | 2740 | */ |
| 2741 | int sqlite3_table_column_metadata( |
| 2742 | sqlite3 *db, /* Connection handle */ |
| 2743 | const char *zDbName, /* Database name or NULL */ |
| 2744 | const char *zTableName, /* Table name */ |
| 2745 | const char *zColumnName, /* Column name */ |
| 2746 | char const **pzDataType, /* OUTPUT: Declared data type */ |
| 2747 | char const **pzCollSeq, /* OUTPUT: Collation sequence name */ |
| 2748 | int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ |
| 2749 | int *pPrimaryKey, /* OUTPUT: True if column part of PK */ |
| 2750 | int *pAutoinc /* OUTPUT: True if colums is auto-increment */ |
| 2751 | ); |
| 2752 | |
| 2753 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2754 | ** CAPI3REF: Load An Extension |
drh | 1e397f8 | 2006-06-08 15:28:43 +0000 | [diff] [blame] | 2755 | ** |
| 2756 | ** Attempt to load an SQLite extension library contained in the file |
| 2757 | ** zFile. The entry point is zProc. zProc may be 0 in which case the |
drh | c2e87a3 | 2006-06-27 15:16:14 +0000 | [diff] [blame] | 2758 | ** name of the entry point defaults to "sqlite3_extension_init". |
drh | 1e397f8 | 2006-06-08 15:28:43 +0000 | [diff] [blame] | 2759 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2760 | ** Return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. |
drh | 1e397f8 | 2006-06-08 15:28:43 +0000 | [diff] [blame] | 2761 | ** |
| 2762 | ** If an error occurs and pzErrMsg is not 0, then fill *pzErrMsg with |
| 2763 | ** error message text. The calling function should free this memory |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2764 | ** by calling [sqlite3_free()]. |
drh | 1e397f8 | 2006-06-08 15:28:43 +0000 | [diff] [blame] | 2765 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2766 | ** Extension loading must be enabled using [sqlite3_enable_load_extension()] |
drh | c2e87a3 | 2006-06-27 15:16:14 +0000 | [diff] [blame] | 2767 | ** prior to calling this API or an error will be returned. |
drh | 1e397f8 | 2006-06-08 15:28:43 +0000 | [diff] [blame] | 2768 | */ |
| 2769 | int sqlite3_load_extension( |
| 2770 | sqlite3 *db, /* Load the extension into this database connection */ |
| 2771 | const char *zFile, /* Name of the shared library containing extension */ |
| 2772 | const char *zProc, /* Entry point. Derived from zFile if 0 */ |
| 2773 | char **pzErrMsg /* Put error message here if not 0 */ |
| 2774 | ); |
| 2775 | |
| 2776 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2777 | ** CAPI3REF: Enable Or Disable Extension Loading |
| 2778 | ** |
drh | c2e87a3 | 2006-06-27 15:16:14 +0000 | [diff] [blame] | 2779 | ** So as not to open security holes in older applications that are |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2780 | ** unprepared to deal with extension loading, and as a means of disabling |
| 2781 | ** extension loading while evaluating user-entered SQL, the following |
| 2782 | ** API is provided to turn the [sqlite3_load_extension()] mechanism on and |
drh | c2e87a3 | 2006-06-27 15:16:14 +0000 | [diff] [blame] | 2783 | ** off. It is off by default. See ticket #1863. |
| 2784 | ** |
| 2785 | ** Call this routine with onoff==1 to turn extension loading on |
| 2786 | ** and call it with onoff==0 to turn it back off again. |
| 2787 | */ |
| 2788 | int sqlite3_enable_load_extension(sqlite3 *db, int onoff); |
| 2789 | |
| 2790 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2791 | ** CAPI3REF: Make Arrangements To Automatically Load An Extension |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 2792 | ** |
drh | 1409be6 | 2006-08-23 20:07:20 +0000 | [diff] [blame] | 2793 | ** Register an extension entry point that is automatically invoked |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2794 | ** whenever a new database connection is opened using |
drh | 605264d | 2007-08-21 15:13:19 +0000 | [diff] [blame^] | 2795 | ** [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()]. |
drh | 1409be6 | 2006-08-23 20:07:20 +0000 | [diff] [blame] | 2796 | ** |
| 2797 | ** This API can be invoked at program startup in order to register |
| 2798 | ** one or more statically linked extensions that will be available |
| 2799 | ** to all new database connections. |
| 2800 | ** |
| 2801 | ** Duplicate extensions are detected so calling this routine multiple |
| 2802 | ** times with the same extension is harmless. |
| 2803 | ** |
| 2804 | ** This routine stores a pointer to the extension in an array |
| 2805 | ** that is obtained from malloc(). If you run a memory leak |
| 2806 | ** checker on your program and it reports a leak because of this |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2807 | ** array, then invoke [sqlite3_automatic_extension_reset()] prior |
drh | 1409be6 | 2006-08-23 20:07:20 +0000 | [diff] [blame] | 2808 | ** to shutdown to free the memory. |
| 2809 | ** |
| 2810 | ** Automatic extensions apply across all threads. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2811 | ** |
| 2812 | ** This interface is experimental and is subject to change or |
| 2813 | ** removal in future releases of SQLite. |
drh | 1409be6 | 2006-08-23 20:07:20 +0000 | [diff] [blame] | 2814 | */ |
| 2815 | int sqlite3_auto_extension(void *xEntryPoint); |
| 2816 | |
| 2817 | |
| 2818 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2819 | ** CAPI3REF: Reset Automatic Extension Loading |
drh | 1409be6 | 2006-08-23 20:07:20 +0000 | [diff] [blame] | 2820 | ** |
| 2821 | ** Disable all previously registered automatic extensions. This |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2822 | ** routine undoes the effect of all prior [sqlite3_automatic_extension()] |
drh | 1409be6 | 2006-08-23 20:07:20 +0000 | [diff] [blame] | 2823 | ** calls. |
| 2824 | ** |
| 2825 | ** This call disabled automatic extensions in all threads. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2826 | ** |
| 2827 | ** This interface is experimental and is subject to change or |
| 2828 | ** removal in future releases of SQLite. |
drh | 1409be6 | 2006-08-23 20:07:20 +0000 | [diff] [blame] | 2829 | */ |
| 2830 | void sqlite3_reset_auto_extension(void); |
| 2831 | |
| 2832 | |
| 2833 | /* |
| 2834 | ****** EXPERIMENTAL - subject to change without notice ************** |
| 2835 | ** |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 2836 | ** The interface to the virtual-table mechanism is currently considered |
| 2837 | ** to be experimental. The interface might change in incompatible ways. |
| 2838 | ** If this is a problem for you, do not use the interface at this time. |
| 2839 | ** |
| 2840 | ** When the virtual-table mechanism stablizes, we will declare the |
| 2841 | ** interface fixed, support it indefinitely, and remove this comment. |
| 2842 | */ |
| 2843 | |
| 2844 | /* |
| 2845 | ** Structures used by the virtual table interface |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 2846 | */ |
| 2847 | typedef struct sqlite3_vtab sqlite3_vtab; |
| 2848 | typedef struct sqlite3_index_info sqlite3_index_info; |
| 2849 | typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor; |
| 2850 | typedef struct sqlite3_module sqlite3_module; |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 2851 | |
| 2852 | /* |
| 2853 | ** A module is a class of virtual tables. Each module is defined |
| 2854 | ** by an instance of the following structure. This structure consists |
| 2855 | ** mostly of methods for the module. |
| 2856 | */ |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 2857 | struct sqlite3_module { |
| 2858 | int iVersion; |
danielk1977 | 9da9d47 | 2006-06-14 06:58:15 +0000 | [diff] [blame] | 2859 | int (*xCreate)(sqlite3*, void *pAux, |
drh | e410296 | 2006-09-11 00:34:22 +0000 | [diff] [blame] | 2860 | int argc, const char *const*argv, |
drh | 4ca8aac | 2006-09-10 17:31:58 +0000 | [diff] [blame] | 2861 | sqlite3_vtab **ppVTab, char**); |
danielk1977 | 9da9d47 | 2006-06-14 06:58:15 +0000 | [diff] [blame] | 2862 | int (*xConnect)(sqlite3*, void *pAux, |
drh | e410296 | 2006-09-11 00:34:22 +0000 | [diff] [blame] | 2863 | int argc, const char *const*argv, |
drh | 4ca8aac | 2006-09-10 17:31:58 +0000 | [diff] [blame] | 2864 | sqlite3_vtab **ppVTab, char**); |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 2865 | int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*); |
| 2866 | int (*xDisconnect)(sqlite3_vtab *pVTab); |
| 2867 | int (*xDestroy)(sqlite3_vtab *pVTab); |
| 2868 | int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor); |
| 2869 | int (*xClose)(sqlite3_vtab_cursor*); |
drh | 4be8b51 | 2006-06-13 23:51:34 +0000 | [diff] [blame] | 2870 | int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr, |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 2871 | int argc, sqlite3_value **argv); |
| 2872 | int (*xNext)(sqlite3_vtab_cursor*); |
danielk1977 | a298e90 | 2006-06-22 09:53:48 +0000 | [diff] [blame] | 2873 | int (*xEof)(sqlite3_vtab_cursor*); |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 2874 | int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 2875 | int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid); |
| 2876 | int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *); |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 2877 | int (*xBegin)(sqlite3_vtab *pVTab); |
| 2878 | int (*xSync)(sqlite3_vtab *pVTab); |
| 2879 | int (*xCommit)(sqlite3_vtab *pVTab); |
| 2880 | int (*xRollback)(sqlite3_vtab *pVTab); |
drh | b7f6f68 | 2006-07-08 17:06:43 +0000 | [diff] [blame] | 2881 | int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, |
drh | e94b0c3 | 2006-07-08 18:09:15 +0000 | [diff] [blame] | 2882 | void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), |
| 2883 | void **ppArg); |
danielk1977 | 182c4ba | 2007-06-27 15:53:34 +0000 | [diff] [blame] | 2884 | |
| 2885 | int (*xRename)(sqlite3_vtab *pVtab, const char *zNew); |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 2886 | }; |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 2887 | |
| 2888 | /* |
| 2889 | ** The sqlite3_index_info structure and its substructures is used to |
| 2890 | ** pass information into and receive the reply from the xBestIndex |
| 2891 | ** method of an sqlite3_module. The fields under **Inputs** are the |
| 2892 | ** inputs to xBestIndex and are read-only. xBestIndex inserts its |
| 2893 | ** results into the **Outputs** fields. |
| 2894 | ** |
| 2895 | ** The aConstraint[] array records WHERE clause constraints of the |
| 2896 | ** form: |
| 2897 | ** |
| 2898 | ** column OP expr |
| 2899 | ** |
| 2900 | ** Where OP is =, <, <=, >, or >=. The particular operator is stored |
| 2901 | ** in aConstraint[].op. The index of the column is stored in |
| 2902 | ** aConstraint[].iColumn. aConstraint[].usable is TRUE if the |
| 2903 | ** expr on the right-hand side can be evaluated (and thus the constraint |
| 2904 | ** is usable) and false if it cannot. |
| 2905 | ** |
| 2906 | ** The optimizer automatically inverts terms of the form "expr OP column" |
| 2907 | ** and makes other simplificatinos to the WHERE clause in an attempt to |
| 2908 | ** get as many WHERE clause terms into the form shown above as possible. |
| 2909 | ** The aConstraint[] array only reports WHERE clause terms in the correct |
| 2910 | ** form that refer to the particular virtual table being queried. |
| 2911 | ** |
| 2912 | ** Information about the ORDER BY clause is stored in aOrderBy[]. |
| 2913 | ** Each term of aOrderBy records a column of the ORDER BY clause. |
| 2914 | ** |
| 2915 | ** The xBestIndex method must fill aConstraintUsage[] with information |
danielk1977 | 5fac9f8 | 2006-06-13 14:16:58 +0000 | [diff] [blame] | 2916 | ** about what parameters to pass to xFilter. If argvIndex>0 then |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 2917 | ** the right-hand side of the corresponding aConstraint[] is evaluated |
| 2918 | ** and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit |
| 2919 | ** is true, then the constraint is assumed to be fully handled by the |
| 2920 | ** virtual table and is not checked again by SQLite. |
| 2921 | ** |
drh | 4be8b51 | 2006-06-13 23:51:34 +0000 | [diff] [blame] | 2922 | ** The idxNum and idxPtr values are recorded and passed into xFilter. |
| 2923 | ** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true. |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 2924 | ** |
| 2925 | ** The orderByConsumed means that output from xFilter will occur in |
| 2926 | ** the correct order to satisfy the ORDER BY clause so that no separate |
| 2927 | ** sorting step is required. |
| 2928 | ** |
| 2929 | ** The estimatedCost value is an estimate of the cost of doing the |
| 2930 | ** particular lookup. A full scan of a table with N entries should have |
| 2931 | ** a cost of N. A binary search of a table of N entries should have a |
| 2932 | ** cost of approximately log(N). |
| 2933 | */ |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 2934 | struct sqlite3_index_info { |
| 2935 | /* Inputs */ |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 2936 | const int nConstraint; /* Number of entries in aConstraint */ |
| 2937 | const struct sqlite3_index_constraint { |
| 2938 | int iColumn; /* Column on left-hand side of constraint */ |
| 2939 | unsigned char op; /* Constraint operator */ |
| 2940 | unsigned char usable; /* True if this constraint is usable */ |
| 2941 | int iTermOffset; /* Used internally - xBestIndex should ignore */ |
| 2942 | } *const aConstraint; /* Table of WHERE clause constraints */ |
| 2943 | const int nOrderBy; /* Number of terms in the ORDER BY clause */ |
| 2944 | const struct sqlite3_index_orderby { |
| 2945 | int iColumn; /* Column number */ |
| 2946 | unsigned char desc; /* True for DESC. False for ASC. */ |
| 2947 | } *const aOrderBy; /* The ORDER BY clause */ |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 2948 | |
| 2949 | /* Outputs */ |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 2950 | struct sqlite3_index_constraint_usage { |
| 2951 | int argvIndex; /* if >0, constraint is part of argv to xFilter */ |
| 2952 | unsigned char omit; /* Do not code a test for this constraint */ |
| 2953 | } *const aConstraintUsage; |
drh | 4be8b51 | 2006-06-13 23:51:34 +0000 | [diff] [blame] | 2954 | int idxNum; /* Number used to identify the index */ |
| 2955 | char *idxStr; /* String, possibly obtained from sqlite3_malloc */ |
| 2956 | int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */ |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 2957 | int orderByConsumed; /* True if output is already ordered */ |
| 2958 | double estimatedCost; /* Estimated cost of using this index */ |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 2959 | }; |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 2960 | #define SQLITE_INDEX_CONSTRAINT_EQ 2 |
| 2961 | #define SQLITE_INDEX_CONSTRAINT_GT 4 |
| 2962 | #define SQLITE_INDEX_CONSTRAINT_LE 8 |
| 2963 | #define SQLITE_INDEX_CONSTRAINT_LT 16 |
| 2964 | #define SQLITE_INDEX_CONSTRAINT_GE 32 |
| 2965 | #define SQLITE_INDEX_CONSTRAINT_MATCH 64 |
| 2966 | |
| 2967 | /* |
| 2968 | ** This routine is used to register a new module name with an SQLite |
| 2969 | ** connection. Module names must be registered before creating new |
| 2970 | ** virtual tables on the module, or before using preexisting virtual |
| 2971 | ** tables of the module. |
| 2972 | */ |
drh | b9bb7c1 | 2006-06-11 23:41:55 +0000 | [diff] [blame] | 2973 | int sqlite3_create_module( |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 2974 | sqlite3 *db, /* SQLite connection to register module with */ |
| 2975 | const char *zName, /* Name of the module */ |
danielk1977 | d1ab1ba | 2006-06-15 04:28:13 +0000 | [diff] [blame] | 2976 | const sqlite3_module *, /* Methods for the module */ |
| 2977 | void * /* Client data for xCreate/xConnect */ |
drh | b9bb7c1 | 2006-06-11 23:41:55 +0000 | [diff] [blame] | 2978 | ); |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 2979 | |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 2980 | /* |
danielk1977 | 832a58a | 2007-06-22 15:21:15 +0000 | [diff] [blame] | 2981 | ** This routine is identical to the sqlite3_create_module() method above, |
| 2982 | ** except that it allows a destructor function to be specified. It is |
| 2983 | ** even more experimental than the rest of the virtual tables API. |
| 2984 | */ |
| 2985 | int sqlite3_create_module_v2( |
| 2986 | sqlite3 *db, /* SQLite connection to register module with */ |
| 2987 | const char *zName, /* Name of the module */ |
| 2988 | const sqlite3_module *, /* Methods for the module */ |
| 2989 | void *, /* Client data for xCreate/xConnect */ |
| 2990 | void(*xDestroy)(void*) /* Module destructor function */ |
| 2991 | ); |
| 2992 | |
| 2993 | /* |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 2994 | ** Every module implementation uses a subclass of the following structure |
| 2995 | ** to describe a particular instance of the module. Each subclass will |
| 2996 | ** be taylored to the specific needs of the module implementation. The |
| 2997 | ** purpose of this superclass is to define certain fields that are common |
| 2998 | ** to all module implementations. |
drh | fe1368e | 2006-09-10 17:08:29 +0000 | [diff] [blame] | 2999 | ** |
| 3000 | ** Virtual tables methods can set an error message by assigning a |
| 3001 | ** string obtained from sqlite3_mprintf() to zErrMsg. The method should |
| 3002 | ** take care that any prior string is freed by a call to sqlite3_free() |
| 3003 | ** prior to assigning a new string to zErrMsg. After the error message |
| 3004 | ** is delivered up to the client application, the string will be automatically |
| 3005 | ** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note |
| 3006 | ** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field |
| 3007 | ** since virtual tables are commonly implemented in loadable extensions which |
| 3008 | ** do not have access to sqlite3MPrintf() or sqlite3Free(). |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 3009 | */ |
| 3010 | struct sqlite3_vtab { |
drh | a967e88 | 2006-06-13 01:04:52 +0000 | [diff] [blame] | 3011 | const sqlite3_module *pModule; /* The module for this virtual table */ |
danielk1977 | be71889 | 2006-06-23 08:05:19 +0000 | [diff] [blame] | 3012 | int nRef; /* Used internally */ |
drh | 4ca8aac | 2006-09-10 17:31:58 +0000 | [diff] [blame] | 3013 | char *zErrMsg; /* Error message from sqlite3_mprintf() */ |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 3014 | /* Virtual table implementations will typically add additional fields */ |
| 3015 | }; |
| 3016 | |
| 3017 | /* Every module implementation uses a subclass of the following structure |
| 3018 | ** to describe cursors that point into the virtual table and are used |
| 3019 | ** to loop through the virtual table. Cursors are created using the |
| 3020 | ** xOpen method of the module. Each module implementation will define |
| 3021 | ** the content of a cursor structure to suit its own needs. |
| 3022 | ** |
| 3023 | ** This superclass exists in order to define fields of the cursor that |
| 3024 | ** are common to all implementations. |
| 3025 | */ |
| 3026 | struct sqlite3_vtab_cursor { |
| 3027 | sqlite3_vtab *pVtab; /* Virtual table of this cursor */ |
| 3028 | /* Virtual table implementations will typically add additional fields */ |
| 3029 | }; |
| 3030 | |
| 3031 | /* |
| 3032 | ** The xCreate and xConnect methods of a module use the following API |
| 3033 | ** to declare the format (the names and datatypes of the columns) of |
| 3034 | ** the virtual tables they implement. |
| 3035 | */ |
danielk1977 | 7e6ebfb | 2006-06-12 11:24:37 +0000 | [diff] [blame] | 3036 | int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 3037 | |
| 3038 | /* |
drh | b7481e7 | 2006-09-16 21:45:14 +0000 | [diff] [blame] | 3039 | ** Virtual tables can provide alternative implementations of functions |
| 3040 | ** using the xFindFunction method. But global versions of those functions |
| 3041 | ** must exist in order to be overloaded. |
| 3042 | ** |
| 3043 | ** This API makes sure a global version of a function with a particular |
| 3044 | ** name and number of parameters exists. If no such function exists |
| 3045 | ** before this API is called, a new function is created. The implementation |
| 3046 | ** of the new function always causes an exception to be thrown. So |
| 3047 | ** the new function is not good for anything by itself. Its only |
| 3048 | ** purpose is to be a place-holder function that can be overloaded |
| 3049 | ** by virtual tables. |
| 3050 | ** |
| 3051 | ** This API should be considered part of the virtual table interface, |
| 3052 | ** which is experimental and subject to change. |
| 3053 | */ |
| 3054 | int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); |
| 3055 | |
| 3056 | /* |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 3057 | ** The interface to the virtual-table mechanism defined above (back up |
| 3058 | ** to a comment remarkably similar to this one) is currently considered |
| 3059 | ** to be experimental. The interface might change in incompatible ways. |
| 3060 | ** If this is a problem for you, do not use the interface at this time. |
| 3061 | ** |
| 3062 | ** When the virtual-table mechanism stablizes, we will declare the |
| 3063 | ** interface fixed, support it indefinitely, and remove this comment. |
| 3064 | ** |
| 3065 | ****** EXPERIMENTAL - subject to change without notice ************** |
| 3066 | */ |
| 3067 | |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3068 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3069 | ** CAPI3REF: A Handle To An Open BLOB |
| 3070 | ** |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3071 | ** An instance of the following opaque structure is used to |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3072 | ** represent an blob-handle. A blob-handle is created by |
| 3073 | ** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()]. |
| 3074 | ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces |
| 3075 | ** can be used to read or write small subsections of the blob. |
| 3076 | ** The [sqltie3_blob_size()] interface returns the size of the |
| 3077 | ** blob in bytes. |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3078 | */ |
danielk1977 | b4e9af9 | 2007-05-01 17:49:49 +0000 | [diff] [blame] | 3079 | typedef struct sqlite3_blob sqlite3_blob; |
| 3080 | |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3081 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3082 | ** CAPI3REF: Open A BLOB For Incremental I/O |
| 3083 | ** |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3084 | ** Open a handle to the blob located in row iRow,, column zColumn, |
| 3085 | ** table zTable in database zDb. i.e. the same blob that would |
| 3086 | ** be selected by: |
| 3087 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3088 | ** <pre> |
| 3089 | ** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow; |
| 3090 | ** </pre> |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3091 | ** |
| 3092 | ** If the flags parameter is non-zero, the blob is opened for |
| 3093 | ** read and write access. If it is zero, the blob is opened for read |
| 3094 | ** access. |
| 3095 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3096 | ** On success, [SQLITE_OK] is returned and the new |
| 3097 | ** [sqlite3_blob | blob handle] is written to *ppBlob. |
| 3098 | ** Otherwise an error code is returned and |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3099 | ** any value written to *ppBlob should not be used by the caller. |
| 3100 | ** This function sets the database-handle error code and message |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3101 | ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()]. |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3102 | */ |
danielk1977 | b4e9af9 | 2007-05-01 17:49:49 +0000 | [diff] [blame] | 3103 | int sqlite3_blob_open( |
| 3104 | sqlite3*, |
| 3105 | const char *zDb, |
| 3106 | const char *zTable, |
| 3107 | const char *zColumn, |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 3108 | sqlite3_int64 iRow, |
danielk1977 | b4e9af9 | 2007-05-01 17:49:49 +0000 | [diff] [blame] | 3109 | int flags, |
| 3110 | sqlite3_blob **ppBlob |
| 3111 | ); |
| 3112 | |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3113 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3114 | ** CAPI3REF: Close A BLOB Handle |
| 3115 | ** |
| 3116 | ** Close an open [sqlite3_blob | blob handle]. |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3117 | */ |
danielk1977 | b4e9af9 | 2007-05-01 17:49:49 +0000 | [diff] [blame] | 3118 | int sqlite3_blob_close(sqlite3_blob *); |
| 3119 | |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3120 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3121 | ** CAPI3REF: Return The Size Of An Open BLOB |
| 3122 | ** |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3123 | ** Return the size in bytes of the blob accessible via the open |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3124 | ** [sqlite3_blob | blob-handle] passed as an argument. |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3125 | */ |
danielk1977 | b4e9af9 | 2007-05-01 17:49:49 +0000 | [diff] [blame] | 3126 | int sqlite3_blob_bytes(sqlite3_blob *); |
| 3127 | |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 3128 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3129 | ** CAPI3REF: Read Data From A BLOB Incrementally |
| 3130 | ** |
| 3131 | ** This function is used to read data from an open |
| 3132 | ** [sqlite3_blob | blob-handle] into a caller supplied buffer. |
| 3133 | ** n bytes of data are copied into buffer |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3134 | ** z from the open blob, starting at offset iOffset. |
| 3135 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3136 | ** On success, SQLITE_OK is returned. Otherwise, an |
| 3137 | ** [SQLITE_ERROR | SQLite error code] or an |
| 3138 | ** [SQLITE_IOERR_READ | extended error code] is returned. |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3139 | */ |
| 3140 | int sqlite3_blob_read(sqlite3_blob *, void *z, int n, int iOffset); |
| 3141 | |
| 3142 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3143 | ** CAPI3REF: Write Data Into A BLOB Incrementally |
| 3144 | ** |
| 3145 | ** This function is used to write data into an open |
| 3146 | ** [sqlite3_blob | blob-handle] from a user supplied buffer. |
| 3147 | ** n bytes of data are copied from the buffer |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3148 | ** pointed to by z into the open blob, starting at offset iOffset. |
| 3149 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3150 | ** If the [sqlite3_blob | blob-handle] passed as the first argument |
| 3151 | ** was not opened for writing (the flags parameter to [sqlite3_blob_open()] |
| 3152 | *** was zero), this function returns [SQLITE_READONLY]. |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3153 | ** |
| 3154 | ** This function may only modify the contents of the blob, it is |
| 3155 | ** not possible to increase the size of a blob using this API. If |
| 3156 | ** offset iOffset is less than n bytes from the end of the blob, |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3157 | ** [SQLITE_ERROR] is returned and no data is written. |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3158 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3159 | ** On success, SQLITE_OK is returned. Otherwise, an |
| 3160 | ** [SQLITE_ERROR | SQLite error code] or an |
| 3161 | ** [SQLITE_IOERR_READ | extended error code] is returned. |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3162 | */ |
| 3163 | int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); |
| 3164 | |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 3165 | /* |
| 3166 | ** CAPI3REF: Virtual File System Objects |
| 3167 | ** |
| 3168 | ** A virtual filesystem (VFS) is an [sqlite3_vfs] object |
| 3169 | ** that SQLite uses to interact |
| 3170 | ** with the underlying operating system. Most builds come with a |
| 3171 | ** single default VFS that is appropriate for the host computer. |
| 3172 | ** New VFSes can be registered and existing VFSes can be unregistered. |
| 3173 | ** The following interfaces are provided. |
| 3174 | ** |
drh | d677b3d | 2007-08-20 22:48:41 +0000 | [diff] [blame] | 3175 | ** The sqlite3_vfs_find() interface returns a pointer to a VFS given its |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 3176 | ** name. Names are case sensitive. If there is no match, a NULL |
| 3177 | ** pointer is returned. If zVfsName is NULL then the default |
drh | d677b3d | 2007-08-20 22:48:41 +0000 | [diff] [blame] | 3178 | ** VFS is returned. If a valid VFS pointer is returned, its |
| 3179 | ** vfsMutex field will have been initialized and nRef will be |
| 3180 | ** greater than zero. The sqlite3_vfs_release() function should |
| 3181 | ** be used to release the VFS when it is no longer needed. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 3182 | ** |
drh | d677b3d | 2007-08-20 22:48:41 +0000 | [diff] [blame] | 3183 | ** New VFSes are registered with sqlite3_vfs_register(). Each |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 3184 | ** new VFS becomes the default VFS if the makeDflt flag is set. |
| 3185 | ** The same VFS can be registered multiple times without injury. |
| 3186 | ** To make an existing VFS into the default VFS, register it again |
| 3187 | ** with the makeDflt flag set. |
| 3188 | ** |
drh | d677b3d | 2007-08-20 22:48:41 +0000 | [diff] [blame] | 3189 | ** Unregister a VFS with the sqlite3_vfs_unregister() interface. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 3190 | ** If the default VFS is unregistered, another VFS is chosen as |
| 3191 | ** the default. The choice for the new VFS is arbitrary. |
| 3192 | */ |
drh | d677b3d | 2007-08-20 22:48:41 +0000 | [diff] [blame] | 3193 | sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); |
| 3194 | int sqlite3_vfs_release(sqlite3_vfs*); |
| 3195 | int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); |
| 3196 | int sqlite3_vfs_unregister(sqlite3_vfs*); |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 3197 | |
| 3198 | /* |
| 3199 | ** CAPI3REF: Mutexes |
| 3200 | ** |
| 3201 | ** The SQLite core uses these routines for thread |
| 3202 | ** synchronization. Though they are intended for internal |
| 3203 | ** use by SQLite, code that links against SQLite is |
| 3204 | ** permitted to use any of these routines. |
| 3205 | ** |
| 3206 | ** The SQLite source code contains multiple implementations |
| 3207 | ** of these mutex routines that can be selected at compile-time |
| 3208 | ** by defining one of the following C preprocessor macros: |
| 3209 | ** |
| 3210 | ** <ul> |
| 3211 | ** <li> SQLITE_MUTEX_PTHREAD |
| 3212 | ** <li> SQLITE_MUTEX_WIN32 |
| 3213 | ** <li> SQLITE_MUTEX_NOOP |
| 3214 | ** <li> SQLITE_MUTEX_APPDEF |
| 3215 | ** </ul> |
| 3216 | ** |
| 3217 | ** If none of the above macros is defined, the code uses |
| 3218 | ** a default implementation. |
| 3219 | ** |
| 3220 | ** The SQLITE_MUTEX_NOOP implementation is a set of routines |
| 3221 | ** that does no real locking and is appropriate for use in |
| 3222 | ** a single-threaded application. |
| 3223 | ** |
| 3224 | ** If the SQLITE_MUTEX_APPDEF is defined, then no mutex |
| 3225 | ** implementation is included with the library. The |
| 3226 | ** mutex interface routines defined above are external |
| 3227 | ** references in the SQLite library for which implementations |
| 3228 | ** must be provided by the application. |
| 3229 | ** |
| 3230 | ** The sqlite3_mutex_alloc() routine allocates a new |
| 3231 | ** mutex and returns a pointer to it. If it returns NULL |
| 3232 | ** that means that a mutex could not be allocated. SQLite |
| 3233 | ** will unwind its stack and return an error. The argument |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 3234 | ** to sqlite3_mutex_alloc() is one of these integer constants: |
| 3235 | ** |
| 3236 | ** <ul> |
| 3237 | ** <li> SQLITE_MUTEX_FAST |
| 3238 | ** <li> SQLITE_MUTEX_RECURSIVE |
| 3239 | ** <li> SQLITE_MUTEX_STATIC_MASTER |
| 3240 | ** <li> SQLITE_MUTEX_STATIC_MEM |
| 3241 | ** <li> SQLITE_MUTEX_STATIC_PRNG |
| 3242 | ** </ul> |
| 3243 | ** |
| 3244 | ** The first two constants cause sqlite3_mutex_alloc() to create |
| 3245 | ** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE |
| 3246 | ** is used but not necessarily so when SQLITE_MUTEX_FAST is used. |
| 3247 | ** The mutex implementation does not need to make a distinction |
| 3248 | ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does |
| 3249 | ** not want to. But SQLite will only request a recursive mutex in |
| 3250 | ** cases where it really needs one. If a faster non-recursive mutex |
| 3251 | ** implementation is available on the host platform, the mutex subsystem |
| 3252 | ** might return such a mutex in response to SQLITE_MUTEX_FAST. |
| 3253 | ** |
| 3254 | ** The other allowed parameters to sqlite3_mutex_alloc() each return |
| 3255 | ** a pointer to a static preexisting mutex. Three static mutexes are |
| 3256 | ** used by the current version of SQLite. Future versions of SQLite |
| 3257 | ** may add additional static mutexes. Static mutexes are for internal |
| 3258 | ** use by SQLite only. Applications that use SQLite mutexes should |
| 3259 | ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or |
| 3260 | ** SQLITE_MUTEX_RECURSIVE. |
| 3261 | ** |
| 3262 | ** Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST |
| 3263 | ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() |
| 3264 | ** returns a different mutex on every call. But for the static |
| 3265 | ** mutex types, the same mutex is returned on every call that has |
| 3266 | ** the same type number. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 3267 | ** |
| 3268 | ** The sqlite3_mutex_free() routine deallocates a previously |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 3269 | ** allocated dynamic mutex. SQLite is careful to deallocate every |
| 3270 | ** dynamic mutex that it allocates. The dynamic mutexes must not be in |
drh | e53831d | 2007-08-17 01:14:38 +0000 | [diff] [blame] | 3271 | ** use when they are deallocated. Attempting to deallocate a static |
| 3272 | ** mutex results in undefined behavior. SQLite never deallocates |
| 3273 | ** a static mutex. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 3274 | ** |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 3275 | ** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt |
| 3276 | ** to enter a mutex. If another thread is already within the mutex, |
| 3277 | ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return |
| 3278 | ** SQLITE_BUSY. The sqlite3_mutex_try() interface returns SQLITE_OK |
| 3279 | ** upon successful entry. Mutexes created using SQLITE_MUTEX_RECURSIVE can |
| 3280 | ** be entered multiple times by the same thread. In such cases the, |
| 3281 | ** mutex must be exited an equal number of times before another thread |
| 3282 | ** can enter. If the same thread tries to enter any other kind of mutex |
| 3283 | ** more than once, the behavior is undefined. SQLite will never exhibit |
| 3284 | ** such behavior in its own use of mutexes. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 3285 | ** |
| 3286 | ** The sqlite3_mutex_exit() routine exits a mutex that was |
| 3287 | ** previously entered by the same thread. The behavior |
| 3288 | ** is undefined if the mutex is not currently entered or |
| 3289 | ** is not currently allocated. SQLite will never do either. |
drh | d677b3d | 2007-08-20 22:48:41 +0000 | [diff] [blame] | 3290 | ** |
| 3291 | ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines |
| 3292 | ** are intended for use inside assert() statements. They should |
| 3293 | ** return true if the mutex in their argument is held or not held, |
| 3294 | ** respectively, by the current thread. The implementation is |
| 3295 | ** not required to provided working implementations of these |
| 3296 | ** routines as their intended use is within assert() statements |
| 3297 | ** only. If the implementation does not provide working |
| 3298 | ** versions of these routines, it must at least provide stubs |
| 3299 | ** that always return true. |
| 3300 | ** |
| 3301 | ** If the argument to sqlite3_mutex_held() is a NULL pointer then |
| 3302 | ** the routine should return 1. This seems counter-intuitive since |
| 3303 | ** clearly the mutex cannot be held if it does not exist. But the |
| 3304 | ** the reason the mutex does not exist is because the build is not |
| 3305 | ** using mutexes. And we do not want the assert() containing the |
| 3306 | ** call to sqlite3_mutex_held() to fail, so a non-zero return is |
| 3307 | ** the appropriate thing to do. The sqlite3_mutex_notheld() |
| 3308 | ** interface should also return 1 when given a NULL pointer. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 3309 | */ |
| 3310 | sqlite3_mutex *sqlite3_mutex_alloc(int); |
| 3311 | void sqlite3_mutex_free(sqlite3_mutex*); |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 3312 | void sqlite3_mutex_enter(sqlite3_mutex*); |
| 3313 | int sqlite3_mutex_try(sqlite3_mutex*); |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 3314 | void sqlite3_mutex_leave(sqlite3_mutex*); |
drh | d677b3d | 2007-08-20 22:48:41 +0000 | [diff] [blame] | 3315 | int sqlite3_mutex_held(sqlite3_mutex*); |
| 3316 | int sqlite3_mutex_notheld(sqlite3_mutex*); |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 3317 | #define SQLITE_MUTEX_FAST 0 |
| 3318 | #define SQLITE_MUTEX_RECURSIVE 1 |
| 3319 | #define SQLITE_MUTEX_STATIC_MASTER 2 |
| 3320 | #define SQLITE_MUTEX_STATIC_MEM 3 |
| 3321 | #define SQLITE_MUTEX_STATIC_PRNG 4 |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 3322 | |
| 3323 | |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 3324 | /* |
drh | b37df7b | 2005-10-13 02:09:49 +0000 | [diff] [blame] | 3325 | ** Undo the hack that converts floating point types to integer for |
| 3326 | ** builds on processors without floating point support. |
| 3327 | */ |
| 3328 | #ifdef SQLITE_OMIT_FLOATING_POINT |
| 3329 | # undef double |
| 3330 | #endif |
| 3331 | |
drh | 382c024 | 2001-10-06 16:33:02 +0000 | [diff] [blame] | 3332 | #ifdef __cplusplus |
| 3333 | } /* End of the 'extern "C"' block */ |
| 3334 | #endif |
danielk1977 | 4adee20 | 2004-05-08 08:23:19 +0000 | [diff] [blame] | 3335 | #endif |