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 | 17eaae7 | 2008-03-03 18:47:28 +0000 | [diff] [blame] | 33 | ** @(#) $Id: sqlite.h.in,v 1.289 2008/03/03 18:47:28 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 | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 66 | ** CAPI3REF: Compile-Time Library Version Numbers {F10010} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 67 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 68 | ** The SQLITE_VERSION and SQLITE_VERSION_NUMBER #defines in |
| 69 | ** the sqlite3.h file specify the version of SQLite with which |
| 70 | ** that header file is associated. |
danielk1977 | 99ba19e | 2005-02-05 07:33:34 +0000 | [diff] [blame] | 71 | ** |
drh | 7663e36 | 2008-02-14 23:24:16 +0000 | [diff] [blame] | 72 | ** The "version" of SQLite is a string of the form "X.Y.Z". |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 73 | ** The phrase "alpha" or "beta" might be appended after the Z. |
| 74 | ** The X value is major version number always 3 in SQLite3. |
| 75 | ** The X value only changes when backwards compatibility is |
| 76 | ** broken and we intend to never break |
| 77 | ** backwards compatibility. The Y value is the minor version |
| 78 | ** number and only changes when |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 79 | ** there are major feature enhancements that are forwards compatible |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 80 | ** but not backwards compatible. The Z value is release number |
| 81 | ** and is incremented with |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 82 | ** each release but resets back to 0 when Y is incremented. |
| 83 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 84 | ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()]. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 85 | ** |
| 86 | ** INVARIANTS: |
| 87 | ** |
| 88 | ** {F10011} The SQLITE_VERSION #define in the sqlite3.h header file |
| 89 | ** evaluates to a string literal that is the SQLite version |
| 90 | ** with which the header file is associated. |
| 91 | ** |
| 92 | ** {F10014} The SQLITE_VERSION_NUMBER #define resolves to an integer |
| 93 | ** with the value (X*1000000 + Y*1000 + Z) where X, Y, and |
| 94 | ** Z are the major version, minor version, and release number. |
danielk1977 | 99ba19e | 2005-02-05 07:33:34 +0000 | [diff] [blame] | 95 | */ |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 96 | #define SQLITE_VERSION "--VERS--" |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 97 | #define SQLITE_VERSION_NUMBER --VERSION-NUMBER-- |
drh | b86ccfb | 2003-01-28 23:13:10 +0000 | [diff] [blame] | 98 | |
| 99 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 100 | ** CAPI3REF: Run-Time Library Version Numbers {F10020} |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 101 | ** KEYWORDS: sqlite3_version |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 102 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 103 | ** These features provide the same information as the [SQLITE_VERSION] |
| 104 | ** and [SQLITE_VERSION_NUMBER] #defines in the header, but are associated |
| 105 | ** with the library instead of the header file. Cautious programmers might |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 106 | ** include a check in their application to verify that |
| 107 | ** sqlite3_libversion_number() always returns the value |
| 108 | ** [SQLITE_VERSION_NUMBER]. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 109 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 110 | ** The sqlite3_libversion() function returns the same information as is |
| 111 | ** in the sqlite3_version[] string constant. The function is provided |
| 112 | ** for use in DLLs since DLL users usually do not have direct access to string |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 113 | ** constants within the DLL. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 114 | ** |
| 115 | ** INVARIANTS: |
| 116 | ** |
| 117 | ** {F10021} The [sqlite3_libversion_number()] interface returns an integer |
| 118 | ** equal to [SQLITE_VERSION_NUMBER]. |
| 119 | ** |
| 120 | ** {F10022} The [sqlite3_version] string constant contains the text of the |
| 121 | ** [SQLITE_VERSION] string. |
| 122 | ** |
| 123 | ** {F10023} The [sqlite3_libversion()] function returns |
| 124 | ** a pointer to the [sqlite3_version] string constant. |
drh | b217a57 | 2000-08-22 13:40:18 +0000 | [diff] [blame] | 125 | */ |
drh | 73be501 | 2007-08-08 12:11:21 +0000 | [diff] [blame] | 126 | SQLITE_EXTERN const char sqlite3_version[]; |
drh | a3f70cb | 2004-09-30 14:24:50 +0000 | [diff] [blame] | 127 | const char *sqlite3_libversion(void); |
danielk1977 | 99ba19e | 2005-02-05 07:33:34 +0000 | [diff] [blame] | 128 | int sqlite3_libversion_number(void); |
| 129 | |
| 130 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 131 | ** CAPI3REF: Test To See If The Library Is Threadsafe {F10100} |
drh | b67e8bf | 2007-08-30 20:09:48 +0000 | [diff] [blame] | 132 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 133 | ** SQLite can be compiled with or without mutexes. When |
| 134 | ** the SQLITE_THREADSAFE C preprocessor macro is true, mutexes |
| 135 | ** are enabled and SQLite is threadsafe. When that macro os false, |
| 136 | ** the mutexes are omitted. Without the mutexes, it is not safe |
| 137 | ** to use SQLite from more than one thread. |
drh | b67e8bf | 2007-08-30 20:09:48 +0000 | [diff] [blame] | 138 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 139 | ** There is a measurable performance penalty for enabling mutexes. |
| 140 | ** So if speed is of utmost importance, it makes sense to disable |
| 141 | ** the mutexes. But for maximum safety, mutexes should be enabled. |
| 142 | ** The default behavior is for mutexes to be enabled. |
| 143 | ** |
| 144 | ** This interface can be used by a program to make sure that the |
| 145 | ** version of SQLite that it is linking against was compiled with |
| 146 | ** the desired setting of the SQLITE_THREADSAFE macro. |
| 147 | ** |
| 148 | ** INVARIANTS: |
| 149 | ** |
| 150 | ** {F10101} The [sqlite3_threadsafe()] function returns nonzero if |
| 151 | ** SQLite was compiled with its mutexes enabled or zero |
| 152 | ** if SQLite was compiled with mutexes disabled. |
drh | b67e8bf | 2007-08-30 20:09:48 +0000 | [diff] [blame] | 153 | */ |
| 154 | int sqlite3_threadsafe(void); |
| 155 | |
| 156 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 157 | ** CAPI3REF: Database Connection Handle {F12000} |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 158 | ** KEYWORDS: {database connection} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 159 | ** |
| 160 | ** Each open SQLite database is represented by pointer to an instance of the |
| 161 | ** opaque structure named "sqlite3". It is useful to think of an sqlite3 |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 162 | ** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and |
| 163 | ** [sqlite3_open_v2()] interfaces are its constructors |
| 164 | ** and [sqlite3_close()] is its destructor. There are many other interfaces |
| 165 | ** (such as [sqlite3_prepare_v2()], [sqlite3_create_function()], and |
| 166 | ** [sqlite3_busy_timeout()] to name but three) that are methods on this |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 167 | ** object. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 168 | */ |
drh | 9bb575f | 2004-09-06 17:24:11 +0000 | [diff] [blame] | 169 | typedef struct sqlite3 sqlite3; |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 170 | |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 171 | |
| 172 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 173 | ** CAPI3REF: 64-Bit Integer Types {F10200} |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 174 | ** KEYWORDS: sqlite_int64 sqlite_uint64 |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 175 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 176 | ** Because there is no cross-platform way to specify 64-bit integer types |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 177 | ** SQLite includes typedefs for 64-bit signed and unsigned integers. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 178 | ** |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 179 | ** The sqlite3_int64 and sqlite3_uint64 are the preferred type |
| 180 | ** definitions. The sqlite_int64 and sqlite_uint64 types are |
| 181 | ** supported for backwards compatibility only. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 182 | ** |
| 183 | ** INVARIANTS: |
| 184 | ** |
| 185 | ** {F10201} The [sqlite_int64] and [sqlite3_int64] types specify a |
| 186 | ** 64-bit signed integer. |
| 187 | ** |
| 188 | ** {F10202} The [sqlite_uint64] and [sqlite3_uint64] types specify |
| 189 | ** a 64-bit unsigned integer. |
drh | efad999 | 2004-06-22 12:13:55 +0000 | [diff] [blame] | 190 | */ |
drh | 27436af | 2006-03-28 23:57:17 +0000 | [diff] [blame] | 191 | #ifdef SQLITE_INT64_TYPE |
drh | 9b8f447 | 2006-04-04 01:54:55 +0000 | [diff] [blame] | 192 | typedef SQLITE_INT64_TYPE sqlite_int64; |
drh | 27436af | 2006-03-28 23:57:17 +0000 | [diff] [blame] | 193 | typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; |
| 194 | #elif defined(_MSC_VER) || defined(__BORLANDC__) |
drh | efad999 | 2004-06-22 12:13:55 +0000 | [diff] [blame] | 195 | typedef __int64 sqlite_int64; |
drh | 1211de3 | 2004-07-26 12:24:22 +0000 | [diff] [blame] | 196 | typedef unsigned __int64 sqlite_uint64; |
drh | efad999 | 2004-06-22 12:13:55 +0000 | [diff] [blame] | 197 | #else |
| 198 | typedef long long int sqlite_int64; |
drh | 1211de3 | 2004-07-26 12:24:22 +0000 | [diff] [blame] | 199 | typedef unsigned long long int sqlite_uint64; |
drh | efad999 | 2004-06-22 12:13:55 +0000 | [diff] [blame] | 200 | #endif |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 201 | typedef sqlite_int64 sqlite3_int64; |
| 202 | typedef sqlite_uint64 sqlite3_uint64; |
drh | efad999 | 2004-06-22 12:13:55 +0000 | [diff] [blame] | 203 | |
drh | b37df7b | 2005-10-13 02:09:49 +0000 | [diff] [blame] | 204 | /* |
| 205 | ** If compiling for a processor that lacks floating point support, |
| 206 | ** substitute integer for floating-point |
| 207 | */ |
| 208 | #ifdef SQLITE_OMIT_FLOATING_POINT |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 209 | # define double sqlite3_int64 |
drh | b37df7b | 2005-10-13 02:09:49 +0000 | [diff] [blame] | 210 | #endif |
drh | efad999 | 2004-06-22 12:13:55 +0000 | [diff] [blame] | 211 | |
| 212 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 213 | ** CAPI3REF: Closing A Database Connection {F12010} |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 214 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 215 | ** This routine is the destructor for the [sqlite3] object. |
| 216 | ** |
| 217 | ** Applications should [sqlite3_finalize | finalize] all |
| 218 | ** [prepared statements] and |
| 219 | ** [sqlite3_blob_close | close] all [sqlite3_blob | BLOBs] |
| 220 | ** associated with the [sqlite3] object prior |
| 221 | ** to attempting to close the [sqlite3] object. |
| 222 | ** |
| 223 | ** <todo>What happens to pending transactions? Are they |
| 224 | ** rolled back, or abandoned?</todo> |
| 225 | ** |
| 226 | ** INVARIANTS: |
| 227 | ** |
| 228 | ** {F12011} The [sqlite3_close()] interface destroys an [sqlite3] object |
| 229 | ** allocated by a prior call to [sqlite3_open()], |
| 230 | ** [sqlite3_open16()], or [sqlite3_open_v2()]. |
| 231 | ** |
| 232 | ** {F12012} The [sqlite3_close()] function releases all memory used by the |
| 233 | ** connection and closes all open files. |
danielk1977 | 96d81f9 | 2004-06-19 03:33:57 +0000 | [diff] [blame] | 234 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 235 | ** {F12013} If the database connection contains |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 236 | ** [prepared statements] that have not been |
| 237 | ** finalized by [sqlite3_finalize()], then [sqlite3_close()] |
| 238 | ** returns [SQLITE_BUSY] and leaves the connection open. |
drh | e30f442 | 2007-08-21 16:15:55 +0000 | [diff] [blame] | 239 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 240 | ** {F12014} Giving sqlite3_close() a NULL pointer is a harmless no-op. |
| 241 | ** |
| 242 | ** LIMITATIONS: |
| 243 | ** |
| 244 | ** {U12015} The parameter to [sqlite3_close()] must be an [sqlite3] object |
| 245 | ** pointer previously obtained from [sqlite3_open()] or the |
| 246 | ** equivalent, or NULL. |
| 247 | ** |
| 248 | ** {U12016} The parameter to [sqlite3_close()] must not have been previously |
| 249 | ** closed. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 250 | */ |
danielk1977 | f9d64d2 | 2004-06-19 08:18:07 +0000 | [diff] [blame] | 251 | int sqlite3_close(sqlite3 *); |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 252 | |
| 253 | /* |
| 254 | ** The type for a callback function. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 255 | ** This is legacy and deprecated. It is included for historical |
| 256 | ** compatibility and is not documented. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 257 | */ |
drh | 12057d5 | 2004-09-06 17:34:12 +0000 | [diff] [blame] | 258 | typedef int (*sqlite3_callback)(void*,int,char**, char**); |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 259 | |
| 260 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 261 | ** CAPI3REF: One-Step Query Execution Interface {F12100} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 262 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 263 | ** The sqlite3_exec() interface is a convenient way of running |
| 264 | ** one or more SQL statements without a lot of C code. The |
| 265 | ** SQL statements are passed in as the second parameter to |
| 266 | ** sqlite3_exec(). The statements are evaluated one by one |
| 267 | ** until either an error or an interrupt is encountered or |
| 268 | ** until they are all done. The 3rd parameter is an optional |
| 269 | ** callback that is invoked once for each row of any query results |
| 270 | ** produced by the SQL statements. The 5th parameter tells where |
| 271 | ** to write any error messages. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 272 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 273 | ** The sqlite3_exec() interface is implemented in terms of |
| 274 | ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()]. |
| 275 | ** The sqlite3_exec() routine does nothing that cannot be done |
| 276 | ** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()]. |
| 277 | ** The sqlite3_exec() is just a convenient wrapper. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 278 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 279 | ** INVARIANTS: |
| 280 | ** |
| 281 | ** {F12101} The [sqlite3_exec()] interface evaluates zero or more UTF-8 |
| 282 | ** encoded, semicolon-separated, SQL statements in the |
| 283 | ** zero-terminated string of its 2nd parameter within the |
| 284 | ** context of the [sqlite3] object given in the 1st parameter. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 285 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 286 | ** {F12104} The return value of [sqlite3_exec()] is SQLITE_OK if all |
| 287 | ** SQL statements run successfully. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 288 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 289 | ** {F12105} The return value of [sqlite3_exec()] is an appropriate |
| 290 | ** non-zero error code if any SQL statement fails. |
drh | 4dd022a | 2007-12-01 19:23:19 +0000 | [diff] [blame] | 291 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 292 | ** {F12107} If one or more of the SQL statements handed to [sqlite3_exec()] |
| 293 | ** return results and the 3rd parameter is not NULL, then |
| 294 | ** the callback function specified by the 3rd parameter is |
| 295 | ** invoked once for each row of result. |
drh | b19a2bc | 2001-09-16 00:13:26 +0000 | [diff] [blame] | 296 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 297 | ** {F12110} If the callback returns a non-zero value then [sqlite3_exec()] |
| 298 | ** will aborted the SQL statement it is currently evaluating, |
| 299 | ** skip all subsequent SQL statements, and return [SQLITE_ABORT]. |
| 300 | ** <todo>What happens to *errmsg here? Does the result code for |
| 301 | ** sqlite3_errcode() get set?</todo> |
| 302 | ** |
| 303 | ** {F12113} The [sqlite3_exec()] routine will pass its 4th parameter through |
| 304 | ** as the 1st parameter of the callback. |
| 305 | ** |
| 306 | ** {F12116} The [sqlite3_exec()] routine sets the 2nd parameter of its |
| 307 | ** callback to be the number of columns in the current row of |
| 308 | ** result. |
| 309 | ** |
| 310 | ** {F12119} The [sqlite3_exec()] routine sets the 3rd parameter of its |
| 311 | ** callback to be an array of pointers to strings holding the |
| 312 | ** values for each column in the current result set row as |
| 313 | ** obtained from [sqlite3_column_text()]. |
| 314 | ** |
| 315 | ** {F12122} The [sqlite3_exec()] routine sets the 4th parameter of its |
| 316 | ** callback to be an array of pointers to strings holding the |
| 317 | ** names of result columns as obtained from [sqlite3_column_name()]. |
| 318 | ** |
| 319 | ** {F12125} If the 3rd parameter to [sqlite3_exec()] is NULL then |
| 320 | ** [sqlite3_exec()] never invokes a callback. All query |
| 321 | ** results are silently discarded. |
| 322 | ** |
| 323 | ** {F12128} If an error occurs while parsing or evaluating any of the SQL |
| 324 | ** statements handed to [sqlite3_exec()] then [sqlite3_exec()] will |
| 325 | ** return an [error code] other than [SQLITE_OK]. |
| 326 | ** |
| 327 | ** {F12131} If an error occurs while parsing or evaluating any of the SQL |
| 328 | ** handed to [sqlite3_exec()] and if the 5th parameter (errmsg) |
| 329 | ** to [sqlite3_exec()] is not NULL, then an error message is |
| 330 | ** allocated using the equivalent of [sqlite3_mprintf()] and |
| 331 | ** *errmsg is made to point to that message. |
| 332 | ** |
| 333 | ** {F12134} The [sqlite3_exec()] routine does not change the value of |
| 334 | ** *errmsg if errmsg is NULL or if there are no errors. |
| 335 | ** |
| 336 | ** {F12137} The [sqlite3_exec()] function sets the error code and message |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 337 | ** accessible via [sqlite3_errcode()], [sqlite3_errmsg()], and |
| 338 | ** [sqlite3_errmsg16()]. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 339 | ** |
| 340 | ** LIMITATIONS: |
| 341 | ** |
| 342 | ** {U12141} The first parameter to [sqlite3_exec()] must be an valid and open |
| 343 | ** [database connection]. |
| 344 | ** |
| 345 | ** {U12142} The database connection must not be closed while |
| 346 | ** [sqlite3_exec()] is running. |
| 347 | ** |
| 348 | ** {U12143} The calling function is should use [sqlite3_free()] to free |
| 349 | ** the memory that *errmsg is left pointing at once the error |
| 350 | ** message is no longer needed. |
| 351 | ** |
| 352 | ** {U12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()] |
| 353 | ** must remain unchanged while [sqlite3_exec()] is running. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 354 | */ |
danielk1977 | 6f8a503 | 2004-05-10 10:34:51 +0000 | [diff] [blame] | 355 | int sqlite3_exec( |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 356 | sqlite3*, /* An open database */ |
| 357 | const char *sql, /* SQL to be evaluted */ |
| 358 | int (*callback)(void*,int,char**,char**), /* Callback function */ |
| 359 | void *, /* 1st argument to callback */ |
| 360 | char **errmsg /* Error msg written here */ |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 361 | ); |
| 362 | |
drh | 58b9576 | 2000-06-02 01:17:37 +0000 | [diff] [blame] | 363 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 364 | ** CAPI3REF: Result Codes {F10210} |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 365 | ** KEYWORDS: SQLITE_OK {error code} {error codes} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 366 | ** |
| 367 | ** Many SQLite functions return an integer result code from the set shown |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 368 | ** here in order to indicates success or failure. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 369 | ** |
| 370 | ** See also: [SQLITE_IOERR_READ | extended result codes] |
drh | 58b9576 | 2000-06-02 01:17:37 +0000 | [diff] [blame] | 371 | */ |
drh | 717e640 | 2001-09-27 03:22:32 +0000 | [diff] [blame] | 372 | #define SQLITE_OK 0 /* Successful result */ |
drh | 15b9a15 | 2006-01-31 20:49:13 +0000 | [diff] [blame] | 373 | /* beginning-of-error-codes */ |
drh | 717e640 | 2001-09-27 03:22:32 +0000 | [diff] [blame] | 374 | #define SQLITE_ERROR 1 /* SQL error or missing database */ |
drh | 89e0dde | 2007-12-12 12:25:21 +0000 | [diff] [blame] | 375 | #define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */ |
drh | 717e640 | 2001-09-27 03:22:32 +0000 | [diff] [blame] | 376 | #define SQLITE_PERM 3 /* Access permission denied */ |
| 377 | #define SQLITE_ABORT 4 /* Callback routine requested an abort */ |
| 378 | #define SQLITE_BUSY 5 /* The database file is locked */ |
| 379 | #define SQLITE_LOCKED 6 /* A table in the database is locked */ |
| 380 | #define SQLITE_NOMEM 7 /* A malloc() failed */ |
| 381 | #define SQLITE_READONLY 8 /* Attempt to write a readonly database */ |
drh | 24cd67e | 2004-05-10 16:18:47 +0000 | [diff] [blame] | 382 | #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/ |
drh | 717e640 | 2001-09-27 03:22:32 +0000 | [diff] [blame] | 383 | #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ |
| 384 | #define SQLITE_CORRUPT 11 /* The database disk image is malformed */ |
drh | 2db0bbc | 2005-08-11 02:10:18 +0000 | [diff] [blame] | 385 | #define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */ |
drh | 717e640 | 2001-09-27 03:22:32 +0000 | [diff] [blame] | 386 | #define SQLITE_FULL 13 /* Insertion failed because database is full */ |
| 387 | #define SQLITE_CANTOPEN 14 /* Unable to open the database file */ |
drh | 4f0ee68 | 2007-03-30 20:43:40 +0000 | [diff] [blame] | 388 | #define SQLITE_PROTOCOL 15 /* NOT USED. Database lock protocol error */ |
drh | 24cd67e | 2004-05-10 16:18:47 +0000 | [diff] [blame] | 389 | #define SQLITE_EMPTY 16 /* Database is empty */ |
drh | 717e640 | 2001-09-27 03:22:32 +0000 | [diff] [blame] | 390 | #define SQLITE_SCHEMA 17 /* The database schema changed */ |
drh | c797d4d | 2007-05-08 01:08:49 +0000 | [diff] [blame] | 391 | #define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */ |
danielk1977 | 6eb91d2 | 2007-09-21 04:27:02 +0000 | [diff] [blame] | 392 | #define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */ |
drh | 8aff101 | 2001-12-22 14:49:24 +0000 | [diff] [blame] | 393 | #define SQLITE_MISMATCH 20 /* Data type mismatch */ |
drh | 247be43 | 2002-05-10 05:44:55 +0000 | [diff] [blame] | 394 | #define SQLITE_MISUSE 21 /* Library used incorrectly */ |
drh | 8766c34 | 2002-11-09 00:33:15 +0000 | [diff] [blame] | 395 | #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ |
drh | ed6c867 | 2003-01-12 18:02:16 +0000 | [diff] [blame] | 396 | #define SQLITE_AUTH 23 /* Authorization denied */ |
drh | 1c2d841 | 2003-03-31 00:30:47 +0000 | [diff] [blame] | 397 | #define SQLITE_FORMAT 24 /* Auxiliary database format error */ |
danielk1977 | 6f8a503 | 2004-05-10 10:34:51 +0000 | [diff] [blame] | 398 | #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */ |
drh | c602f9a | 2004-02-12 19:01:04 +0000 | [diff] [blame] | 399 | #define SQLITE_NOTADB 26 /* File opened that is not a database file */ |
danielk1977 | 6f8a503 | 2004-05-10 10:34:51 +0000 | [diff] [blame] | 400 | #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ |
| 401 | #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ |
drh | 15b9a15 | 2006-01-31 20:49:13 +0000 | [diff] [blame] | 402 | /* end-of-error-codes */ |
drh | 717e640 | 2001-09-27 03:22:32 +0000 | [diff] [blame] | 403 | |
drh | af9ff33 | 2002-01-16 21:00:27 +0000 | [diff] [blame] | 404 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 405 | ** CAPI3REF: Extended Result Codes {F10220} |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 406 | ** KEYWORDS: {extended error code} {extended error codes} |
| 407 | ** KEYWORDS: {extended result codes} |
drh | 4ac285a | 2006-09-15 07:28:50 +0000 | [diff] [blame] | 408 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 409 | ** In its default configuration, SQLite API routines return one of 26 integer |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 410 | ** [SQLITE_OK | result codes]. However, experience has shown that |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 411 | ** many of these result codes are too course-grained. They do not provide as |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 412 | ** much information about problems as programmers might like. In an effort to |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 413 | ** address this, newer versions of SQLite (version 3.3.8 and later) include |
| 414 | ** support for additional result codes that provide more detailed information |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 415 | ** about errors. The extended result codes are enabled or disabled |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 416 | ** for each database connection using the [sqlite3_extended_result_codes()] |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 417 | ** API. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 418 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 419 | ** Some of the available extended result codes are listed here. |
| 420 | ** One may expect the number of extended result codes will be expand |
| 421 | ** over time. Software that uses extended result codes should expect |
| 422 | ** to see new result codes in future releases of SQLite. |
drh | 4ac285a | 2006-09-15 07:28:50 +0000 | [diff] [blame] | 423 | ** |
| 424 | ** The SQLITE_OK result code will never be extended. It will always |
| 425 | ** be exactly zero. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 426 | ** |
| 427 | ** INVARIANTS: |
| 428 | ** |
| 429 | ** {F10223} The symbolic name for an extended result code always contains |
| 430 | ** a related primary result code as a prefix. |
| 431 | ** |
| 432 | ** {F10224} Primary result code names contain a single "_" character. |
| 433 | ** |
| 434 | ** {F10225} Extended result code names contain two or more "_" characters. |
| 435 | ** |
| 436 | ** {F10226} The numeric value of an extended result code contains the |
| 437 | ** numeric value of its corresponding primary result code it |
| 438 | ** its least significant 8 bits. |
drh | 4ac285a | 2006-09-15 07:28:50 +0000 | [diff] [blame] | 439 | */ |
| 440 | #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) |
| 441 | #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) |
| 442 | #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) |
| 443 | #define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) |
| 444 | #define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) |
| 445 | #define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) |
| 446 | #define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) |
| 447 | #define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) |
| 448 | #define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) |
danielk1977 | 979f38e | 2007-03-27 16:19:51 +0000 | [diff] [blame] | 449 | #define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) |
danielk1977 | e965ac7 | 2007-06-13 15:22:28 +0000 | [diff] [blame] | 450 | #define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8)) |
danielk1977 | ae72d98 | 2007-10-03 08:46:44 +0000 | [diff] [blame] | 451 | #define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8)) |
drh | 4ac285a | 2006-09-15 07:28:50 +0000 | [diff] [blame] | 452 | |
| 453 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 454 | ** CAPI3REF: Flags For File Open Operations {F10230} |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 455 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 456 | ** These bit values are intended for use in then |
| 457 | ** 3rd parameter to the [sqlite3_open_v2()] interface and |
| 458 | ** in the 4th parameter to the xOpen method of the |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 459 | ** [sqlite3_vfs] object. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 460 | */ |
| 461 | #define SQLITE_OPEN_READONLY 0x00000001 |
| 462 | #define SQLITE_OPEN_READWRITE 0x00000002 |
| 463 | #define SQLITE_OPEN_CREATE 0x00000004 |
| 464 | #define SQLITE_OPEN_DELETEONCLOSE 0x00000008 |
| 465 | #define SQLITE_OPEN_EXCLUSIVE 0x00000010 |
| 466 | #define SQLITE_OPEN_MAIN_DB 0x00000100 |
| 467 | #define SQLITE_OPEN_TEMP_DB 0x00000200 |
drh | 33f4e02 | 2007-09-03 15:19:34 +0000 | [diff] [blame] | 468 | #define SQLITE_OPEN_TRANSIENT_DB 0x00000400 |
| 469 | #define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 |
| 470 | #define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 |
| 471 | #define SQLITE_OPEN_SUBJOURNAL 0x00002000 |
| 472 | #define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 473 | |
| 474 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 475 | ** CAPI3REF: Device Characteristics {F10240} |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 476 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 477 | ** The xDeviceCapabilities method of the [sqlite3_io_methods] |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 478 | ** object returns an integer which is a vector of the these |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 479 | ** bit values expressing I/O characteristics of the mass storage |
| 480 | ** device that holds the file that the [sqlite3_io_methods] |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 481 | ** refers to. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 482 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 483 | ** The SQLITE_IOCAP_ATOMIC property means that all writes of |
| 484 | ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 485 | ** mean that writes of blocks that are nnn bytes in size and |
| 486 | ** are aligned to an address which is an integer multiple of |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 487 | ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 488 | ** that when data is appended to a file, the data is appended |
| 489 | ** first then the size of the file is extended, never the other |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 490 | ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 491 | ** information is written to disk in the same order as calls |
| 492 | ** to xWrite(). |
| 493 | */ |
| 494 | #define SQLITE_IOCAP_ATOMIC 0x00000001 |
| 495 | #define SQLITE_IOCAP_ATOMIC512 0x00000002 |
| 496 | #define SQLITE_IOCAP_ATOMIC1K 0x00000004 |
| 497 | #define SQLITE_IOCAP_ATOMIC2K 0x00000008 |
| 498 | #define SQLITE_IOCAP_ATOMIC4K 0x00000010 |
| 499 | #define SQLITE_IOCAP_ATOMIC8K 0x00000020 |
| 500 | #define SQLITE_IOCAP_ATOMIC16K 0x00000040 |
| 501 | #define SQLITE_IOCAP_ATOMIC32K 0x00000080 |
| 502 | #define SQLITE_IOCAP_ATOMIC64K 0x00000100 |
| 503 | #define SQLITE_IOCAP_SAFE_APPEND 0x00000200 |
| 504 | #define SQLITE_IOCAP_SEQUENTIAL 0x00000400 |
| 505 | |
| 506 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 507 | ** CAPI3REF: File Locking Levels {F10250} |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 508 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 509 | ** SQLite uses one of these integer values as the second |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 510 | ** argument to calls it makes to the xLock() and xUnlock() methods |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 511 | ** of an [sqlite3_io_methods] object. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 512 | */ |
| 513 | #define SQLITE_LOCK_NONE 0 |
| 514 | #define SQLITE_LOCK_SHARED 1 |
| 515 | #define SQLITE_LOCK_RESERVED 2 |
| 516 | #define SQLITE_LOCK_PENDING 3 |
| 517 | #define SQLITE_LOCK_EXCLUSIVE 4 |
| 518 | |
| 519 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 520 | ** CAPI3REF: Synchronization Type Flags {F10260} |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 521 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 522 | ** When SQLite invokes the xSync() method of an |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 523 | ** [sqlite3_io_methods] object it uses a combination of the |
| 524 | ** these integer values as the second argument. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 525 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 526 | ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 527 | ** sync operation only needs to flush data to mass storage. Inode |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 528 | ** information need not be flushed. The SQLITE_SYNC_NORMAL means |
| 529 | ** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means |
danielk1977 | c16d463 | 2007-08-30 14:49:58 +0000 | [diff] [blame] | 530 | ** to use Mac OS-X style fullsync instead of fsync(). |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 531 | */ |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 532 | #define SQLITE_SYNC_NORMAL 0x00002 |
| 533 | #define SQLITE_SYNC_FULL 0x00003 |
| 534 | #define SQLITE_SYNC_DATAONLY 0x00010 |
| 535 | |
| 536 | |
| 537 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 538 | ** CAPI3REF: OS Interface Open File Handle {F11110} |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 539 | ** |
| 540 | ** An [sqlite3_file] object represents an open file in the OS |
| 541 | ** interface layer. Individual OS interface implementations will |
| 542 | ** want to subclass this object by appending additional fields |
drh | 4ff7fa0 | 2007-09-01 18:17:21 +0000 | [diff] [blame] | 543 | ** for their own use. The pMethods entry is a pointer to an |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 544 | ** [sqlite3_io_methods] object that defines methods for performing |
| 545 | ** I/O operations on the open file. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 546 | */ |
| 547 | typedef struct sqlite3_file sqlite3_file; |
| 548 | struct sqlite3_file { |
drh | 153c62c | 2007-08-24 03:51:33 +0000 | [diff] [blame] | 549 | const struct sqlite3_io_methods *pMethods; /* Methods for an open file */ |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 550 | }; |
| 551 | |
| 552 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 553 | ** CAPI3REF: OS Interface File Virtual Methods Object {F11120} |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 554 | ** |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 555 | ** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to |
| 556 | ** an instance of the this object. This object defines the |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 557 | ** methods used to perform various operations against the open file. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 558 | ** |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 559 | ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or |
| 560 | ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync(). |
| 561 | * The second choice is an |
| 562 | ** OS-X style fullsync. The SQLITE_SYNC_DATA flag may be ORed in to |
| 563 | ** indicate that only the data of the file and not its inode needs to be |
| 564 | ** synced. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 565 | ** |
| 566 | ** The integer values to xLock() and xUnlock() are one of |
drh | 4ff7fa0 | 2007-09-01 18:17:21 +0000 | [diff] [blame] | 567 | ** <ul> |
| 568 | ** <li> [SQLITE_LOCK_NONE], |
drh | 79491ab | 2007-09-04 12:00:00 +0000 | [diff] [blame] | 569 | ** <li> [SQLITE_LOCK_SHARED], |
drh | 4ff7fa0 | 2007-09-01 18:17:21 +0000 | [diff] [blame] | 570 | ** <li> [SQLITE_LOCK_RESERVED], |
| 571 | ** <li> [SQLITE_LOCK_PENDING], or |
| 572 | ** <li> [SQLITE_LOCK_EXCLUSIVE]. |
| 573 | ** </ul> |
| 574 | ** xLock() increases the lock. xUnlock() decreases the lock. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 575 | ** The xCheckReservedLock() method looks |
| 576 | ** to see if any database connection, either in this |
| 577 | ** process or in some other process, is holding an RESERVED, |
| 578 | ** PENDING, or EXCLUSIVE lock on the file. It returns true |
| 579 | ** if such a lock exists and false if not. |
| 580 | ** |
drh | cc6bb3e | 2007-08-31 16:11:35 +0000 | [diff] [blame] | 581 | ** The xFileControl() method is a generic interface that allows custom |
| 582 | ** VFS implementations to directly control an open file using the |
drh | 4ff7fa0 | 2007-09-01 18:17:21 +0000 | [diff] [blame] | 583 | ** [sqlite3_file_control()] interface. The second "op" argument |
| 584 | ** is an integer opcode. The third |
drh | cc6bb3e | 2007-08-31 16:11:35 +0000 | [diff] [blame] | 585 | ** argument is a generic pointer which is intended to be a pointer |
| 586 | ** to a structure that may contain arguments or space in which to |
| 587 | ** write return values. Potential uses for xFileControl() might be |
| 588 | ** functions to enable blocking locks with timeouts, to change the |
| 589 | ** locking strategy (for example to use dot-file locks), to inquire |
drh | 9e33c2c | 2007-08-31 18:34:59 +0000 | [diff] [blame] | 590 | ** about the status of a lock, or to break stale locks. The SQLite |
drh | 4ff7fa0 | 2007-09-01 18:17:21 +0000 | [diff] [blame] | 591 | ** core reserves opcodes less than 100 for its own use. |
| 592 | ** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available. |
| 593 | ** Applications that define a custom xFileControl method should use opcodes |
drh | 9e33c2c | 2007-08-31 18:34:59 +0000 | [diff] [blame] | 594 | ** greater than 100 to avoid conflicts. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 595 | ** |
| 596 | ** The xSectorSize() method returns the sector size of the |
| 597 | ** device that underlies the file. The sector size is the |
| 598 | ** minimum write that can be performed without disturbing |
| 599 | ** other bytes in the file. The xDeviceCharacteristics() |
| 600 | ** method returns a bit vector describing behaviors of the |
| 601 | ** underlying device: |
| 602 | ** |
| 603 | ** <ul> |
drh | 4ff7fa0 | 2007-09-01 18:17:21 +0000 | [diff] [blame] | 604 | ** <li> [SQLITE_IOCAP_ATOMIC] |
| 605 | ** <li> [SQLITE_IOCAP_ATOMIC512] |
| 606 | ** <li> [SQLITE_IOCAP_ATOMIC1K] |
| 607 | ** <li> [SQLITE_IOCAP_ATOMIC2K] |
| 608 | ** <li> [SQLITE_IOCAP_ATOMIC4K] |
| 609 | ** <li> [SQLITE_IOCAP_ATOMIC8K] |
| 610 | ** <li> [SQLITE_IOCAP_ATOMIC16K] |
| 611 | ** <li> [SQLITE_IOCAP_ATOMIC32K] |
| 612 | ** <li> [SQLITE_IOCAP_ATOMIC64K] |
| 613 | ** <li> [SQLITE_IOCAP_SAFE_APPEND] |
| 614 | ** <li> [SQLITE_IOCAP_SEQUENTIAL] |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 615 | ** </ul> |
| 616 | ** |
| 617 | ** The SQLITE_IOCAP_ATOMIC property means that all writes of |
| 618 | ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values |
| 619 | ** mean that writes of blocks that are nnn bytes in size and |
| 620 | ** are aligned to an address which is an integer multiple of |
| 621 | ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means |
| 622 | ** that when data is appended to a file, the data is appended |
| 623 | ** first then the size of the file is extended, never the other |
| 624 | ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that |
| 625 | ** information is written to disk in the same order as calls |
| 626 | ** to xWrite(). |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 627 | */ |
| 628 | typedef struct sqlite3_io_methods sqlite3_io_methods; |
| 629 | struct sqlite3_io_methods { |
| 630 | int iVersion; |
| 631 | int (*xClose)(sqlite3_file*); |
drh | 79491ab | 2007-09-04 12:00:00 +0000 | [diff] [blame] | 632 | int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst); |
| 633 | int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst); |
| 634 | int (*xTruncate)(sqlite3_file*, sqlite3_int64 size); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 635 | int (*xSync)(sqlite3_file*, int flags); |
drh | 79491ab | 2007-09-04 12:00:00 +0000 | [diff] [blame] | 636 | int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 637 | int (*xLock)(sqlite3_file*, int); |
| 638 | int (*xUnlock)(sqlite3_file*, int); |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 639 | int (*xCheckReservedLock)(sqlite3_file*); |
drh | cc6bb3e | 2007-08-31 16:11:35 +0000 | [diff] [blame] | 640 | int (*xFileControl)(sqlite3_file*, int op, void *pArg); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 641 | int (*xSectorSize)(sqlite3_file*); |
| 642 | int (*xDeviceCharacteristics)(sqlite3_file*); |
| 643 | /* Additional methods may be added in future releases */ |
| 644 | }; |
| 645 | |
| 646 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 647 | ** CAPI3REF: Standard File Control Opcodes {F11310} |
drh | 9e33c2c | 2007-08-31 18:34:59 +0000 | [diff] [blame] | 648 | ** |
| 649 | ** These integer constants are opcodes for the xFileControl method |
| 650 | ** of the [sqlite3_io_methods] object and to the [sqlite3_file_control()] |
| 651 | ** interface. |
| 652 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 653 | ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This |
drh | 9e33c2c | 2007-08-31 18:34:59 +0000 | [diff] [blame] | 654 | ** opcode cases the xFileControl method to write the current state of |
| 655 | ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED], |
| 656 | ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE]) |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 657 | ** into an integer that the pArg argument points to. This capability |
drh | 9e33c2c | 2007-08-31 18:34:59 +0000 | [diff] [blame] | 658 | ** is used during testing and only needs to be supported when SQLITE_TEST |
| 659 | ** is defined. |
| 660 | */ |
| 661 | #define SQLITE_FCNTL_LOCKSTATE 1 |
| 662 | |
| 663 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 664 | ** CAPI3REF: Mutex Handle {F17110} |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 665 | ** |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 666 | ** The mutex module within SQLite defines [sqlite3_mutex] to be an |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 667 | ** abstract type for a mutex object. The SQLite core never looks |
| 668 | ** at the internal representation of an [sqlite3_mutex]. It only |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 669 | ** deals with pointers to the [sqlite3_mutex] object. |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 670 | ** |
| 671 | ** Mutexes are created using [sqlite3_mutex_alloc()]. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 672 | */ |
| 673 | typedef struct sqlite3_mutex sqlite3_mutex; |
| 674 | |
| 675 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 676 | ** CAPI3REF: OS Interface Object {F11140} |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 677 | ** |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 678 | ** An instance of this object defines the interface between the |
| 679 | ** SQLite core and the underlying operating system. The "vfs" |
| 680 | ** in the name of the object stands for "virtual file system". |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 681 | ** |
| 682 | ** The iVersion field is initially 1 but may be larger for future |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 683 | ** versions of SQLite. Additional fields may be appended to this |
| 684 | ** object when the iVersion value is increased. |
| 685 | ** |
drh | 4ff7fa0 | 2007-09-01 18:17:21 +0000 | [diff] [blame] | 686 | ** The szOsFile field is the size of the subclassed [sqlite3_file] |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 687 | ** structure used by this VFS. mxPathname is the maximum length of |
| 688 | ** a pathname in this VFS. |
| 689 | ** |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 690 | ** Registered sqlite3_vfs objects are kept on a linked list formed by |
drh | 79491ab | 2007-09-04 12:00:00 +0000 | [diff] [blame] | 691 | ** the pNext pointer. The [sqlite3_vfs_register()] |
| 692 | ** and [sqlite3_vfs_unregister()] interfaces manage this list |
| 693 | ** in a thread-safe way. The [sqlite3_vfs_find()] interface |
drh | 153c62c | 2007-08-24 03:51:33 +0000 | [diff] [blame] | 694 | ** searches the list. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 695 | ** |
drh | 1cc8c44 | 2007-08-24 16:08:29 +0000 | [diff] [blame] | 696 | ** The pNext field is the only fields in the sqlite3_vfs |
| 697 | ** structure that SQLite will ever modify. SQLite will only access |
| 698 | ** or modify this field while holding a particular static mutex. |
| 699 | ** The application should never modify anything within the sqlite3_vfs |
| 700 | ** object once the object has been registered. |
| 701 | ** |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 702 | ** The zName field holds the name of the VFS module. The name must |
| 703 | ** be unique across all VFS modules. |
| 704 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 705 | ** {F11141} SQLite will guarantee that the zFilename string passed to |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 706 | ** xOpen() is a full pathname as generated by xFullPathname() and |
| 707 | ** that the string will be valid and unchanged until xClose() is |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 708 | ** called. {END} So the [sqlite3_file] can store a pointer to the |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 709 | ** filename if it needs to remember the filename for some reason. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 710 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 711 | ** {F11142} The flags argument to xOpen() includes all bits set in |
| 712 | ** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()] |
| 713 | ** or [sqlite3_open16()] is used, then flags includes at least |
| 714 | ** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. {END} |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 715 | ** If xOpen() opens a file read-only then it sets *pOutFlags to |
drh | 4ff7fa0 | 2007-09-01 18:17:21 +0000 | [diff] [blame] | 716 | ** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 717 | ** set. |
| 718 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 719 | ** {F11143} SQLite will also add one of the following flags to the xOpen() |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 720 | ** call, depending on the object being opened: |
| 721 | ** |
| 722 | ** <ul> |
| 723 | ** <li> [SQLITE_OPEN_MAIN_DB] |
| 724 | ** <li> [SQLITE_OPEN_MAIN_JOURNAL] |
| 725 | ** <li> [SQLITE_OPEN_TEMP_DB] |
| 726 | ** <li> [SQLITE_OPEN_TEMP_JOURNAL] |
drh | 33f4e02 | 2007-09-03 15:19:34 +0000 | [diff] [blame] | 727 | ** <li> [SQLITE_OPEN_TRANSIENT_DB] |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 728 | ** <li> [SQLITE_OPEN_SUBJOURNAL] |
| 729 | ** <li> [SQLITE_OPEN_MASTER_JOURNAL] |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 730 | ** </ul> {END} |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 731 | ** |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 732 | ** The file I/O implementation can use the object type flags to |
| 733 | ** changes the way it deals with files. For example, an application |
| 734 | ** that does not care about crash recovery or rollback, might make |
| 735 | ** 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] | 736 | ** also a no-op. Any attempt to read the journal return SQLITE_IOERR. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 737 | ** Or the implementation might recognize the a database file will |
| 738 | ** be doing page-aligned sector reads and writes in a random order |
| 739 | ** and set up its I/O subsystem accordingly. |
| 740 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 741 | ** SQLite might also add one of the following flags to the xOpen |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 742 | ** method: |
| 743 | ** |
| 744 | ** <ul> |
| 745 | ** <li> [SQLITE_OPEN_DELETEONCLOSE] |
| 746 | ** <li> [SQLITE_OPEN_EXCLUSIVE] |
| 747 | ** </ul> |
| 748 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 749 | ** {F11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be |
| 750 | ** deleted when it is closed. {F11146} The [SQLITE_OPEN_DELETEONCLOSE] |
| 751 | ** will be set for TEMP databases, journals and for subjournals. |
| 752 | ** {F11147} The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 753 | ** for exclusive access. This flag is set for all files except |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 754 | ** for the main database file. {END} |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 755 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 756 | ** {F11148} At least szOsFile bytes of memory is allocated by SQLite |
| 757 | ** to hold the [sqlite3_file] structure passed as the third |
| 758 | ** argument to xOpen. {END} The xOpen method does not have to |
| 759 | ** allocate the structure; it should just fill it in. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 760 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 761 | ** {F11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] |
drh | 4ff7fa0 | 2007-09-01 18:17:21 +0000 | [diff] [blame] | 762 | ** to test for the existance of a file, |
| 763 | ** or [SQLITE_ACCESS_READWRITE] to test to see |
| 764 | ** if a file is readable and writable, or [SQLITE_ACCESS_READ] |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 765 | ** to test to see if a file is at least readable. {END} The file can be a |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 766 | ** directory. |
| 767 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 768 | ** {F11150} SQLite will always allocate at least mxPathname+1 byte for |
| 769 | ** the output buffers for xGetTempname and xFullPathname. {F11151} The exact |
danielk1977 | adfb9b0 | 2007-09-17 07:02:56 +0000 | [diff] [blame] | 770 | ** size of the output buffer is also passed as a parameter to both |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 771 | ** methods. {END} If the output buffer is not large enough, SQLITE_CANTOPEN |
danielk1977 | adfb9b0 | 2007-09-17 07:02:56 +0000 | [diff] [blame] | 772 | ** should be returned. As this is handled as a fatal error by SQLite, |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 773 | ** vfs implementations should endeavor to prevent this by setting |
danielk1977 | adfb9b0 | 2007-09-17 07:02:56 +0000 | [diff] [blame] | 774 | ** mxPathname to a sufficiently large value. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 775 | ** |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 776 | ** The xRandomness(), xSleep(), and xCurrentTime() interfaces |
| 777 | ** are not strictly a part of the filesystem, but they are |
| 778 | ** included in the VFS structure for completeness. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 779 | ** The xRandomness() function attempts to return nBytes bytes |
| 780 | ** of good-quality randomness into zOut. The return value is |
drh | 4ff7fa0 | 2007-09-01 18:17:21 +0000 | [diff] [blame] | 781 | ** the actual number of bytes of randomness obtained. The |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 782 | ** xSleep() method cause the calling thread to sleep for at |
| 783 | ** least the number of microseconds given. The xCurrentTime() |
| 784 | ** method returns a Julian Day Number for the current date and |
| 785 | ** time. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 786 | */ |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 787 | typedef struct sqlite3_vfs sqlite3_vfs; |
| 788 | struct sqlite3_vfs { |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 789 | int iVersion; /* Structure version number */ |
| 790 | int szOsFile; /* Size of subclassed sqlite3_file */ |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 791 | int mxPathname; /* Maximum file pathname length */ |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 792 | sqlite3_vfs *pNext; /* Next registered VFS */ |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 793 | const char *zName; /* Name of this virtual file system */ |
drh | 1cc8c44 | 2007-08-24 16:08:29 +0000 | [diff] [blame] | 794 | void *pAppData; /* Pointer to application-specific data */ |
drh | 153c62c | 2007-08-24 03:51:33 +0000 | [diff] [blame] | 795 | int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*, |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 796 | int flags, int *pOutFlags); |
drh | 153c62c | 2007-08-24 03:51:33 +0000 | [diff] [blame] | 797 | int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir); |
| 798 | int (*xAccess)(sqlite3_vfs*, const char *zName, int flags); |
danielk1977 | adfb9b0 | 2007-09-17 07:02:56 +0000 | [diff] [blame] | 799 | int (*xGetTempname)(sqlite3_vfs*, int nOut, char *zOut); |
| 800 | int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut); |
drh | 153c62c | 2007-08-24 03:51:33 +0000 | [diff] [blame] | 801 | void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename); |
| 802 | void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg); |
| 803 | void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol); |
| 804 | void (*xDlClose)(sqlite3_vfs*, void*); |
| 805 | int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut); |
| 806 | int (*xSleep)(sqlite3_vfs*, int microseconds); |
| 807 | int (*xCurrentTime)(sqlite3_vfs*, double*); |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 808 | /* New fields may be appended in figure versions. The iVersion |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 809 | ** value will increment whenever this happens. */ |
| 810 | }; |
| 811 | |
drh | 50d3f90 | 2007-08-27 21:10:36 +0000 | [diff] [blame] | 812 | /* |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 813 | ** CAPI3REF: Flags for the xAccess VFS method {F11190} |
drh | 50d3f90 | 2007-08-27 21:10:36 +0000 | [diff] [blame] | 814 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 815 | ** {F11191} These integer constants can be used as the third parameter to |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 816 | ** the xAccess method of an [sqlite3_vfs] object. {END} They determine |
drh | 50d3f90 | 2007-08-27 21:10:36 +0000 | [diff] [blame] | 817 | ** the kind of what kind of permissions the xAccess method is |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 818 | ** looking for. {F11192} With SQLITE_ACCESS_EXISTS, the xAccess method |
| 819 | ** simply checks to see if the file exists. {F11193} With |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 820 | ** SQLITE_ACCESS_READWRITE, the xAccess method checks to see |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 821 | ** if the file is both readable and writable. {F11194} With |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 822 | ** SQLITE_ACCESS_READ the xAccess method |
drh | 50d3f90 | 2007-08-27 21:10:36 +0000 | [diff] [blame] | 823 | ** checks to see if the file is readable. |
| 824 | */ |
danielk1977 | b4b4741 | 2007-08-17 15:53:36 +0000 | [diff] [blame] | 825 | #define SQLITE_ACCESS_EXISTS 0 |
| 826 | #define SQLITE_ACCESS_READWRITE 1 |
drh | 50d3f90 | 2007-08-27 21:10:36 +0000 | [diff] [blame] | 827 | #define SQLITE_ACCESS_READ 2 |
danielk1977 | b4b4741 | 2007-08-17 15:53:36 +0000 | [diff] [blame] | 828 | |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 829 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 830 | ** CAPI3REF: Enable Or Disable Extended Result Codes {F12200} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 831 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 832 | ** The sqlite3_extended_result_codes() routine enables or disables the |
| 833 | ** [SQLITE_IOERR_READ | extended result codes] feature of SQLite. |
| 834 | ** The extended result codes are disabled by default for historical |
| 835 | ** compatibility. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 836 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 837 | ** INVARIANTS: |
| 838 | ** |
| 839 | ** {F12201} Each new [database connection] has the |
| 840 | ** [extended result codes] feature |
| 841 | ** disabled by default. |
| 842 | ** |
| 843 | ** {F12202} The [sqlite3_extended_result_codes(D,F)] interface will enable |
| 844 | ** [extended result codes] for the |
| 845 | ** [database connection] D if the F parameter |
| 846 | ** is true, or disable them if F is false. |
drh | 4ac285a | 2006-09-15 07:28:50 +0000 | [diff] [blame] | 847 | */ |
| 848 | int sqlite3_extended_result_codes(sqlite3*, int onoff); |
| 849 | |
| 850 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 851 | ** CAPI3REF: Last Insert Rowid {F12220} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 852 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 853 | ** Each entry in an SQLite table has a unique 64-bit signed |
| 854 | ** integer key called the "rowid". The rowid is always available |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 855 | ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 856 | ** names are not also used by explicitly declared columns. If |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 857 | ** the table has a column of type INTEGER PRIMARY KEY then that column |
| 858 | ** is another an alias for the rowid. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 859 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 860 | ** This routine returns the rowid of the most recent |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 861 | ** successful INSERT into the database from the database connection |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 862 | ** shown in the first argument. If no successful inserts |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 863 | ** have ever occurred on this database connection, zero is returned. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 864 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 865 | ** If an INSERT occurs within a trigger, then the rowid of the |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 866 | ** inserted row is returned by this routine as long as the trigger |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 867 | ** is running. But once the trigger terminates, the value returned |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 868 | ** by this routine reverts to the last value inserted before the |
| 869 | ** trigger fired. |
drh | e30f442 | 2007-08-21 16:15:55 +0000 | [diff] [blame] | 870 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 871 | ** An INSERT that fails due to a constraint violation is not a |
drh | dc1d9f1 | 2007-10-27 16:25:16 +0000 | [diff] [blame] | 872 | ** successful insert and does not change the value returned by this |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 873 | ** routine. Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK, |
drh | dc1d9f1 | 2007-10-27 16:25:16 +0000 | [diff] [blame] | 874 | ** and INSERT OR ABORT make no changes to the return value of this |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 875 | ** routine when their insertion fails. When INSERT OR REPLACE |
drh | dc1d9f1 | 2007-10-27 16:25:16 +0000 | [diff] [blame] | 876 | ** encounters a constraint violation, it does not fail. The |
| 877 | ** INSERT continues to completion after deleting rows that caused |
| 878 | ** the constraint problem so INSERT OR REPLACE will always change |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 879 | ** the return value of this interface. |
drh | dc1d9f1 | 2007-10-27 16:25:16 +0000 | [diff] [blame] | 880 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 881 | ** For the purposes of this routine, an insert is considered to |
| 882 | ** be successful even if it is subsequently rolled back. |
| 883 | ** |
| 884 | ** INVARIANTS: |
| 885 | ** |
| 886 | ** {F12221} The [sqlite3_last_insert_rowid()] function returns the |
| 887 | ** rowid of the most recent successful insert done |
| 888 | ** on the same database connection and within the same |
| 889 | ** trigger context, or zero if there have |
| 890 | ** been no qualifying inserts on that connection. |
| 891 | ** |
| 892 | ** {F12223} The [sqlite3_last_insert_rowid()] function returns |
| 893 | ** same value when called from the same trigger context |
| 894 | ** immediately before and after a ROLLBACK. |
| 895 | ** |
| 896 | ** LIMITATIONS: |
| 897 | ** |
| 898 | ** {U12232} If separate thread does a new insert on the same |
| 899 | ** database connection while the [sqlite3_last_insert_rowid()] |
| 900 | ** function is running and thus changes the last insert rowid, |
| 901 | ** then the value returned by [sqlite3_last_insert_rowid()] is |
| 902 | ** unpredictable and might not equal either the old or the new |
| 903 | ** last insert rowid. |
drh | af9ff33 | 2002-01-16 21:00:27 +0000 | [diff] [blame] | 904 | */ |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 905 | sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); |
drh | af9ff33 | 2002-01-16 21:00:27 +0000 | [diff] [blame] | 906 | |
drh | c8d30ac | 2002-04-12 10:08:59 +0000 | [diff] [blame] | 907 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 908 | ** CAPI3REF: Count The Number Of Rows Modified {F12240} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 909 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 910 | ** This function returns the number of database rows that were changed |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 911 | ** or inserted or deleted by the most recently completed SQL statement |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 912 | ** on the connection specified by the first parameter. Only |
drh | 930cc58 | 2007-03-28 13:07:40 +0000 | [diff] [blame] | 913 | ** changes that are directly specified by the INSERT, UPDATE, or |
| 914 | ** DELETE statement are counted. Auxiliary changes caused by |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 915 | ** triggers are not counted. Use the [sqlite3_total_changes()] function |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 916 | ** to find the total number of changes including changes caused by triggers. |
| 917 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 918 | ** A "row changes" is a change to a single row of a single table |
| 919 | ** caused by an INSERT, DELETE, or UPDATE statement. Rows that |
| 920 | ** are changed as side effects of REPLACE constraint resolution, |
| 921 | ** rollback, ABORT processing, DROP TABLE, or by any other |
| 922 | ** mechanisms do not count as direct row changes. |
| 923 | ** |
| 924 | ** A "trigger context" is a scope of execution that begins and |
| 925 | ** ends with the script of a trigger. Most SQL statements are |
| 926 | ** evaluated outside of any trigger. This is the "top level" |
| 927 | ** trigger context. If a trigger fires from the top level, a |
| 928 | ** new trigger context is entered for the duration of that one |
| 929 | ** trigger. Subtriggers create subcontexts for their duration. |
| 930 | ** |
| 931 | ** Calling [sqlite3_exec()] or [sqlite3_step()] recursively does |
| 932 | ** not create a new trigger context. |
| 933 | ** |
| 934 | ** This function returns the number of direct row changes in the |
| 935 | ** most recent INSERT, UPDATE, or DELETE statement within the same |
| 936 | ** trigger context. |
| 937 | ** |
| 938 | ** So when called from the top level, this function returns the |
| 939 | ** number of changes in the most recent INSERT, UPDATE, or DELETE |
| 940 | ** that also occurred at the top level. |
| 941 | ** Within the body of a trigger, the sqlite3_changes() interface |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 942 | ** can be called to find the number of |
drh | 930cc58 | 2007-03-28 13:07:40 +0000 | [diff] [blame] | 943 | ** changes in the most recently completed INSERT, UPDATE, or DELETE |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 944 | ** statement within the body of the same trigger. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 945 | ** However, the number returned does not include in changes |
| 946 | ** caused by subtriggers since they have their own context. |
drh | c8d30ac | 2002-04-12 10:08:59 +0000 | [diff] [blame] | 947 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 948 | ** SQLite implements the command "DELETE FROM table" without |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 949 | ** a WHERE clause by dropping and recreating the table. (This is much |
| 950 | ** faster than going through and deleting individual elements from the |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 951 | ** table.) Because of this optimization, the deletions in |
| 952 | ** "DELETE FROM table" are not row changes and will not be counted |
| 953 | ** by the sqlite3_changes() or [sqlite3_total_changes()] functions. |
| 954 | ** To get an accurate count of the number of rows deleted, use |
drh | c8d30ac | 2002-04-12 10:08:59 +0000 | [diff] [blame] | 955 | ** "DELETE FROM table WHERE 1" instead. |
drh | e30f442 | 2007-08-21 16:15:55 +0000 | [diff] [blame] | 956 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 957 | ** INVARIANTS: |
| 958 | ** |
| 959 | ** {F12241} The [sqlite3_changes()] function returns the number of |
| 960 | ** row changes caused by the most recent INSERT, UPDATE, |
| 961 | ** or DELETE statement on the same database connection and |
| 962 | ** within the same trigger context, or zero if there have |
| 963 | ** not been any qualifying row changes. |
| 964 | ** |
| 965 | ** LIMITATIONS: |
| 966 | ** |
| 967 | ** {U12252} If a separate thread makes changes on the same database connection |
| 968 | ** while [sqlite3_changes()] is running then the value returned |
| 969 | ** is unpredictable and unmeaningful. |
drh | c8d30ac | 2002-04-12 10:08:59 +0000 | [diff] [blame] | 970 | */ |
danielk1977 | f9d64d2 | 2004-06-19 08:18:07 +0000 | [diff] [blame] | 971 | int sqlite3_changes(sqlite3*); |
drh | c8d30ac | 2002-04-12 10:08:59 +0000 | [diff] [blame] | 972 | |
rdc | f146a77 | 2004-02-25 22:51:06 +0000 | [diff] [blame] | 973 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 974 | ** CAPI3REF: Total Number Of Rows Modified {F12260} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 975 | *** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 976 | ** This function returns the number of row changes caused |
| 977 | ** by INSERT, UPDATE or DELETE statements since the database handle |
| 978 | ** was opened. The count includes all changes from all trigger |
| 979 | ** contexts. But the count does not include changes used to |
| 980 | ** implement REPLACE constraints, do rollbacks or ABORT processing, |
| 981 | ** or DROP table processing. |
| 982 | ** The changes |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 983 | ** are counted as soon as the statement that makes them is completed |
| 984 | ** (when the statement handle is passed to [sqlite3_reset()] or |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 985 | ** [sqlite3_finalize()]). |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 986 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 987 | ** SQLite implements the command "DELETE FROM table" without |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 988 | ** a WHERE clause by dropping and recreating the table. (This is much |
| 989 | ** faster than going |
rdc | f146a77 | 2004-02-25 22:51:06 +0000 | [diff] [blame] | 990 | ** through and deleting individual elements form the table.) Because of |
| 991 | ** this optimization, the change count for "DELETE FROM table" will be |
| 992 | ** zero regardless of the number of elements that were originally in the |
| 993 | ** table. To get an accurate count of the number of rows deleted, use |
| 994 | ** "DELETE FROM table WHERE 1" instead. |
drh | e30f442 | 2007-08-21 16:15:55 +0000 | [diff] [blame] | 995 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 996 | ** See also the [sqlite3_changes()] interface. |
| 997 | ** |
| 998 | ** INVARIANTS: |
| 999 | ** |
| 1000 | ** {F12261} The [sqlite3_total_changes()] returns the total number |
| 1001 | ** of row changes caused by INSERT, UPDATE, and/or DELETE |
| 1002 | ** statements on the same [database connection], in any |
| 1003 | ** trigger context, since the database connection was |
| 1004 | ** created. |
| 1005 | ** |
| 1006 | ** LIMITATIONS: |
| 1007 | ** |
| 1008 | ** {U12264} If a separate thread makes changes on the same database connection |
| 1009 | ** while [sqlite3_total_changes()] is running then the value |
| 1010 | ** returned is unpredictable and unmeaningful. |
rdc | f146a77 | 2004-02-25 22:51:06 +0000 | [diff] [blame] | 1011 | */ |
danielk1977 | b28af71 | 2004-06-21 06:50:26 +0000 | [diff] [blame] | 1012 | int sqlite3_total_changes(sqlite3*); |
| 1013 | |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1014 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1015 | ** CAPI3REF: Interrupt A Long-Running Query {F12270} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1016 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1017 | ** This function causes any pending database operation to abort and |
| 1018 | ** return at its earliest opportunity. This routine is typically |
drh | 66b89c8 | 2000-11-28 20:47:17 +0000 | [diff] [blame] | 1019 | ** called in response to a user action such as pressing "Cancel" |
drh | 4c50439 | 2000-10-16 22:06:40 +0000 | [diff] [blame] | 1020 | ** or Ctrl-C where the user wants a long query operation to halt |
| 1021 | ** immediately. |
drh | 930cc58 | 2007-03-28 13:07:40 +0000 | [diff] [blame] | 1022 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1023 | ** It is safe to call this routine from a thread different from the |
| 1024 | ** thread that is currently running the database operation. But it |
drh | 871f6ca | 2007-08-14 18:03:14 +0000 | [diff] [blame] | 1025 | ** is not safe to call this routine with a database connection that |
| 1026 | ** is closed or might close before sqlite3_interrupt() returns. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1027 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1028 | ** If an SQL is very nearly finished at the time when sqlite3_interrupt() |
| 1029 | ** is called, then it might not have an opportunity to be interrupted. |
| 1030 | ** It might continue to completion. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1031 | ** An SQL operation that is interrupted will return |
| 1032 | ** [SQLITE_INTERRUPT]. If the interrupted SQL operation is an |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1033 | ** INSERT, UPDATE, or DELETE that is inside an explicit transaction, |
| 1034 | ** then the entire transaction will be rolled back automatically. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1035 | ** A call to sqlite3_interrupt() has no effect on SQL statements |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1036 | ** that are started after sqlite3_interrupt() returns. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1037 | ** |
| 1038 | ** INVARIANTS: |
| 1039 | ** |
| 1040 | ** {F12271} The [sqlite3_interrupt()] interface will force all running |
| 1041 | ** SQL statements associated with the same database connection |
| 1042 | ** to halt after processing at most one additional row of |
| 1043 | ** data. |
| 1044 | ** |
| 1045 | ** {F12272} Any SQL statement that is interrupted by [sqlite3_interrupt()] |
| 1046 | ** will return [SQLITE_INTERRUPT]. |
| 1047 | ** |
| 1048 | ** LIMITATIONS: |
| 1049 | ** |
| 1050 | ** {U12279} If the database connection closes while [sqlite3_interrupt()] |
| 1051 | ** is running then bad things will likely happen. |
drh | 4c50439 | 2000-10-16 22:06:40 +0000 | [diff] [blame] | 1052 | */ |
danielk1977 | f9d64d2 | 2004-06-19 08:18:07 +0000 | [diff] [blame] | 1053 | void sqlite3_interrupt(sqlite3*); |
drh | 4c50439 | 2000-10-16 22:06:40 +0000 | [diff] [blame] | 1054 | |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1055 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1056 | ** CAPI3REF: Determine If An SQL Statement Is Complete {F10510} |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 1057 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1058 | ** These routines are useful for command-line input to determine if the |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1059 | ** currently entered text seems to form complete a SQL statement or |
| 1060 | ** if additional input is needed before sending the text into |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1061 | ** SQLite for parsing. These routines return true if the input string |
| 1062 | ** appears to be a complete SQL statement. A statement is judged to be |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1063 | ** complete if it ends with a semicolon token and is not a fragment of a |
| 1064 | ** CREATE TRIGGER statement. Semicolons that are embedded within |
| 1065 | ** string literals or quoted identifier names or comments are not |
| 1066 | ** independent tokens (they are part of the token in which they are |
| 1067 | ** embedded) and thus do not count as a statement terminator. |
| 1068 | ** |
| 1069 | ** These routines do not parse the SQL and |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1070 | ** so will not detect syntactically incorrect SQL. |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1071 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1072 | ** INVARIANTS: |
| 1073 | ** |
| 1074 | ** {F10511} The sqlite3_complete() and sqlite3_complete16() functions |
| 1075 | ** return true (non-zero) if and only if the last |
| 1076 | ** non-whitespace token in their input is a semicolon that |
| 1077 | ** is not in between the BEGIN and END of a CREATE TRIGGER |
| 1078 | ** statement. |
| 1079 | ** |
| 1080 | ** LIMITATIONS: |
| 1081 | ** |
| 1082 | ** {U10512} The input to sqlite3_complete() must be a zero-terminated |
| 1083 | ** UTF-8 string. |
| 1084 | ** |
| 1085 | ** {U10513} The input to sqlite3_complete16() must be a zero-terminated |
| 1086 | ** UTF-16 string in native byte order. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 1087 | */ |
danielk1977 | 6f8a503 | 2004-05-10 10:34:51 +0000 | [diff] [blame] | 1088 | int sqlite3_complete(const char *sql); |
danielk1977 | 61de0d1 | 2004-05-27 23:56:16 +0000 | [diff] [blame] | 1089 | int sqlite3_complete16(const void *sql); |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 1090 | |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 1091 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1092 | ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {F12310} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1093 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1094 | ** This routine identifies a callback function that might be |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1095 | ** invoked whenever an attempt is made to open a database table |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1096 | ** that another thread or process has locked. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1097 | ** If the busy callback is NULL, then [SQLITE_BUSY] |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1098 | ** or [SQLITE_IOERR_BLOCKED] |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1099 | ** is returned immediately upon encountering the lock. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1100 | ** If the busy callback is not NULL, then the |
| 1101 | ** callback will be invoked with two arguments. The |
drh | 86939b5 | 2007-01-10 12:54:51 +0000 | [diff] [blame] | 1102 | ** first argument to the handler is a copy of the void* pointer which |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1103 | ** is the third argument to this routine. The second argument to |
drh | 86939b5 | 2007-01-10 12:54:51 +0000 | [diff] [blame] | 1104 | ** the handler is the number of times that the busy handler has |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1105 | ** been invoked for this locking event. If the |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1106 | ** busy callback returns 0, then no additional attempts are made to |
| 1107 | ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1108 | ** If the callback returns non-zero, then another attempt |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1109 | ** is made to open the database for reading and the cycle repeats. |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 1110 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1111 | ** The presence of a busy handler does not guarantee that |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1112 | ** it will be invoked when there is lock contention. |
drh | 86939b5 | 2007-01-10 12:54:51 +0000 | [diff] [blame] | 1113 | ** If SQLite determines that invoking the busy handler could result in |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1114 | ** a deadlock, it will go ahead and return [SQLITE_BUSY] or |
| 1115 | ** [SQLITE_IOERR_BLOCKED] instead of invoking the |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1116 | ** busy handler. |
drh | 86939b5 | 2007-01-10 12:54:51 +0000 | [diff] [blame] | 1117 | ** Consider a scenario where one process is holding a read lock that |
| 1118 | ** it is trying to promote to a reserved lock and |
| 1119 | ** a second process is holding a reserved lock that it is trying |
| 1120 | ** to promote to an exclusive lock. The first process cannot proceed |
| 1121 | ** because it is blocked by the second and the second process cannot |
| 1122 | ** proceed because it is blocked by the first. If both processes |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1123 | ** invoke the busy handlers, neither will make any progress. Therefore, |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1124 | ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this |
drh | 86939b5 | 2007-01-10 12:54:51 +0000 | [diff] [blame] | 1125 | ** will induce the first process to release its read lock and allow |
| 1126 | ** the second process to proceed. |
| 1127 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1128 | ** The default busy callback is NULL. |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 1129 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1130 | ** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED] |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1131 | ** when SQLite is in the middle of a large transaction where all the |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1132 | ** changes will not fit into the in-memory cache. SQLite will |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1133 | ** already hold a RESERVED lock on the database file, but it needs |
| 1134 | ** to promote this lock to EXCLUSIVE so that it can spill cache |
| 1135 | ** pages into the database file without harm to concurrent |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1136 | ** readers. If it is unable to promote the lock, then the in-memory |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1137 | ** cache will be left in an inconsistent state and so the error |
| 1138 | ** code is promoted from the relatively benign [SQLITE_BUSY] to |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1139 | ** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion |
| 1140 | ** forces an automatic rollback of the changes. See the |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1141 | ** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError"> |
| 1142 | ** CorruptionFollowingBusyError</a> wiki page for a discussion of why |
| 1143 | ** this is important. |
| 1144 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1145 | ** There can only be a single busy handler defined for each database |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1146 | ** connection. Setting a new busy handler clears any previous one. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1147 | ** Note that calling [sqlite3_busy_timeout()] will also set or clear |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1148 | ** the busy handler. |
drh | d677b3d | 2007-08-20 22:48:41 +0000 | [diff] [blame] | 1149 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1150 | ** INVARIANTS: |
| 1151 | ** |
| 1152 | ** {F12311} The [sqlite3_busy_handler()] function replaces the busy handler |
| 1153 | ** callback in the database connection identified by the 1st |
| 1154 | ** parameter with a new busy handler identified by the 2nd and 3rd |
| 1155 | ** parameters. |
| 1156 | ** |
| 1157 | ** {F12312} The default busy handler for new database connections is NULL. |
| 1158 | ** |
| 1159 | ** {F12314} When two or more database connection share a common cache, |
| 1160 | ** the busy handler for the database connection currently using |
| 1161 | ** the cache is invoked when the cache encounters a lock. |
| 1162 | ** |
| 1163 | ** {F12316} If a busy handler callback returns zero, then the SQLite |
| 1164 | ** interface that provoked the locking event will return |
| 1165 | ** [SQLITE_BUSY]. |
| 1166 | ** |
| 1167 | ** {F12318} SQLite will invokes the busy handler with two argument which |
| 1168 | ** are a copy of the pointer supplied by the 3rd parameter to |
| 1169 | ** [sqlite3_busy_handler()] and a count of the number of prior |
| 1170 | ** invocations of the busy handler for the same locking event. |
| 1171 | ** |
| 1172 | ** LIMITATIONS: |
| 1173 | ** |
| 1174 | ** {U12319} A busy handler should not call close the database connection |
| 1175 | ** or prepared statement that invoked the busy handler. |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 1176 | */ |
danielk1977 | f9d64d2 | 2004-06-19 08:18:07 +0000 | [diff] [blame] | 1177 | int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 1178 | |
| 1179 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1180 | ** CAPI3REF: Set A Busy Timeout {F12340} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1181 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1182 | ** This routine sets a [sqlite3_busy_handler | busy handler] |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1183 | ** that sleeps for a while when a |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1184 | ** table is locked. The handler will sleep multiple times until |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1185 | ** at least "ms" milliseconds of sleeping have been done. {F12343} After |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1186 | ** "ms" milliseconds of sleeping, the handler returns 0 which |
| 1187 | ** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]. |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 1188 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1189 | ** Calling this routine with an argument less than or equal to zero |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 1190 | ** turns off all busy handlers. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1191 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1192 | ** There can only be a single busy handler for a particular database |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1193 | ** connection. If another busy handler was defined |
| 1194 | ** (using [sqlite3_busy_handler()]) prior to calling |
| 1195 | ** this routine, that other busy handler is cleared. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1196 | ** |
| 1197 | ** INVARIANTS: |
| 1198 | ** |
| 1199 | ** {F12341} The [sqlite3_busy_timeout()] function overrides any prior |
| 1200 | ** [sqlite3_busy_timeout()] or [sqlite3_busy_handler()] setting |
| 1201 | ** on the same database connection. |
| 1202 | ** |
| 1203 | ** {F12343} If the 2nd parameter to [sqlite3_busy_timeout()] is less than |
| 1204 | ** or equal to zero, then the busy handler is cleared so that |
| 1205 | ** all subsequent locking events immediately return [SQLITE_BUSY]. |
| 1206 | ** |
| 1207 | ** {F12344} If the 2nd parameter to [sqlite3_busy_timeout()] is a positive |
| 1208 | ** number N, then a busy handler is set that repeatedly calls |
| 1209 | ** the xSleep() method in the VFS interface until either the |
| 1210 | ** lock clears or until the cumulative sleep time reported back |
| 1211 | ** by xSleep() exceeds N milliseconds. |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 1212 | */ |
danielk1977 | f9d64d2 | 2004-06-19 08:18:07 +0000 | [diff] [blame] | 1213 | int sqlite3_busy_timeout(sqlite3*, int ms); |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 1214 | |
drh | e371033 | 2000-09-29 13:30:53 +0000 | [diff] [blame] | 1215 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1216 | ** CAPI3REF: Convenience Routines For Running Queries {F12370} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1217 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1218 | ** Definition: A <b>result table</b> is memory data structure created by the |
| 1219 | ** [sqlite3_get_table()] interface. A result table records the |
| 1220 | ** complete query results from one or more queries. |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1221 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1222 | ** The table conceptually has a number of rows and columns. But |
| 1223 | ** these numbers are not part of the result table itself. These |
| 1224 | ** numbers are obtained separately. Let N be the number of rows |
| 1225 | ** and M be the number of columns. |
| 1226 | ** |
| 1227 | ** A result table is an array of pointers to zero-terminated |
| 1228 | ** UTF-8 strings. There are (N+1)*M elements in the array. |
| 1229 | ** The first M pointers point to zero-terminated strings that |
| 1230 | ** contain the names of the columns. |
| 1231 | ** The remaining entries all point to query results. NULL |
| 1232 | ** values are give a NULL pointer. All other values are in |
| 1233 | ** their UTF-8 zero-terminated string representation as returned by |
| 1234 | ** [sqlite3_column_text()]. |
| 1235 | ** |
| 1236 | ** A result table might consists of one or more memory allocations. |
| 1237 | ** It is not safe to pass a result table directly to [sqlite3_free()]. |
| 1238 | ** A result table should be deallocated using [sqlite3_free_table()]. |
| 1239 | ** |
| 1240 | ** As an example of the result table format, suppose a query result |
| 1241 | ** is as follows: |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1242 | ** |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 1243 | ** <blockquote><pre> |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1244 | ** Name | Age |
| 1245 | ** ----------------------- |
| 1246 | ** Alice | 43 |
| 1247 | ** Bob | 28 |
| 1248 | ** Cindy | 21 |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 1249 | ** </pre></blockquote> |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1250 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1251 | ** There are two column (M==2) and three rows (N==3). Thus the |
| 1252 | ** result table has 8 entries. Suppose the result table is stored |
| 1253 | ** in an array names azResult. Then azResult holds this content: |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1254 | ** |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 1255 | ** <blockquote><pre> |
| 1256 | ** azResult[0] = "Name"; |
| 1257 | ** azResult[1] = "Age"; |
| 1258 | ** azResult[2] = "Alice"; |
| 1259 | ** azResult[3] = "43"; |
| 1260 | ** azResult[4] = "Bob"; |
| 1261 | ** azResult[5] = "28"; |
| 1262 | ** azResult[6] = "Cindy"; |
| 1263 | ** azResult[7] = "21"; |
| 1264 | ** </pre></blockquote> |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1265 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1266 | ** The sqlite3_get_table() function evaluates one or more |
| 1267 | ** semicolon-separated SQL statements in the zero-terminated UTF-8 |
| 1268 | ** string of its 2nd parameter. It returns a result table to the |
| 1269 | ** pointer given in its 3rd parameter. |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1270 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1271 | ** After the calling function has finished using the result, it should |
| 1272 | ** pass the pointer to the result table to sqlite3_free_table() in order to |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1273 | ** release the memory that was malloc-ed. Because of the way the |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1274 | ** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling |
| 1275 | ** function must not try to call [sqlite3_free()] directly. Only |
| 1276 | ** [sqlite3_free_table()] is able to release the memory properly and safely. |
drh | e371033 | 2000-09-29 13:30:53 +0000 | [diff] [blame] | 1277 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1278 | ** The sqlite3_get_table() interface is implemented as a wrapper around |
| 1279 | ** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access |
| 1280 | ** to any internal data structures of SQLite. It uses only the public |
| 1281 | ** interface defined here. As a consequence, errors that occur in the |
| 1282 | ** wrapper layer outside of the internal [sqlite3_exec()] call are not |
| 1283 | ** reflected in subsequent calls to [sqlite3_errcode()] or |
| 1284 | ** [sqlite3_errmsg()]. |
| 1285 | ** |
| 1286 | ** INVARIANTS: |
| 1287 | ** |
| 1288 | ** {F12371} If a [sqlite3_get_table()] fails a memory allocation, then |
| 1289 | ** it frees the result table under construction, aborts the |
| 1290 | ** query in process, skips any subsequent queries, sets the |
| 1291 | ** *resultp output pointer to NULL and returns [SQLITE_NOMEM]. |
| 1292 | ** |
| 1293 | ** {F12373} If the ncolumn parameter to [sqlite3_get_table()] is not NULL |
| 1294 | ** then [sqlite3_get_table()] write the number of columns in the |
| 1295 | ** result set of the query into *ncolumn if the query is |
| 1296 | ** successful (if the function returns SQLITE_OK). |
| 1297 | ** |
| 1298 | ** {F12374} If the nrow parameter to [sqlite3_get_table()] is not NULL |
| 1299 | ** then [sqlite3_get_table()] write the number of rows in the |
| 1300 | ** result set of the query into *nrow if the query is |
| 1301 | ** successful (if the function returns SQLITE_OK). |
| 1302 | ** |
drh | 21ac7f9 | 2008-01-31 12:26:49 +0000 | [diff] [blame] | 1303 | ** {F12376} The [sqlite3_get_table()] function sets its *ncolumn value |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1304 | ** to the number of columns in the result set of the query in the |
| 1305 | ** sql parameter, or to zero if the query in sql has an empty |
| 1306 | ** result set. |
drh | e371033 | 2000-09-29 13:30:53 +0000 | [diff] [blame] | 1307 | */ |
danielk1977 | 6f8a503 | 2004-05-10 10:34:51 +0000 | [diff] [blame] | 1308 | int sqlite3_get_table( |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1309 | sqlite3*, /* An open database */ |
| 1310 | const char *sql, /* SQL to be evaluated */ |
| 1311 | char ***pResult, /* Results of the query */ |
| 1312 | int *nrow, /* Number of result rows written here */ |
| 1313 | int *ncolumn, /* Number of result columns written here */ |
| 1314 | char **errmsg /* Error msg written here */ |
drh | e371033 | 2000-09-29 13:30:53 +0000 | [diff] [blame] | 1315 | ); |
danielk1977 | 6f8a503 | 2004-05-10 10:34:51 +0000 | [diff] [blame] | 1316 | void sqlite3_free_table(char **result); |
drh | e371033 | 2000-09-29 13:30:53 +0000 | [diff] [blame] | 1317 | |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1318 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1319 | ** CAPI3REF: Formatted String Printing Functions {F17400} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1320 | ** |
| 1321 | ** These routines are workalikes of the "printf()" family of functions |
| 1322 | ** from the standard C library. |
| 1323 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1324 | ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1325 | ** results into memory obtained from [sqlite3_malloc()]. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1326 | ** The strings returned by these two routines should be |
| 1327 | ** released by [sqlite3_free()]. Both routines return a |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1328 | ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough |
| 1329 | ** memory to hold the resulting string. |
| 1330 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1331 | ** In sqlite3_snprintf() routine is similar to "snprintf()" from |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1332 | ** the standard C library. The result is written into the |
| 1333 | ** buffer supplied as the second parameter whose size is given by |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1334 | ** the first parameter. Note that the order of the |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1335 | ** first two parameters is reversed from snprintf(). This is an |
| 1336 | ** historical accident that cannot be fixed without breaking |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1337 | ** backwards compatibility. Note also that sqlite3_snprintf() |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1338 | ** returns a pointer to its buffer instead of the number of |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1339 | ** characters actually written into the buffer. We admit that |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1340 | ** the number of characters written would be a more useful return |
| 1341 | ** value but we cannot change the implementation of sqlite3_snprintf() |
| 1342 | ** now without breaking compatibility. |
| 1343 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1344 | ** As long as the buffer size is greater than zero, sqlite3_snprintf() |
| 1345 | ** guarantees that the buffer is always zero-terminated. The first |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1346 | ** parameter "n" is the total size of the buffer, including space for |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1347 | ** the zero terminator. So the longest string that can be completely |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1348 | ** written will be n-1 characters. |
| 1349 | ** |
| 1350 | ** These routines all implement some additional formatting |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1351 | ** options that are useful for constructing SQL statements. |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1352 | ** All of the usual printf formatting options apply. In addition, there |
drh | 153c62c | 2007-08-24 03:51:33 +0000 | [diff] [blame] | 1353 | ** is are "%q", "%Q", and "%z" options. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1354 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1355 | ** The %q option works like %s in that it substitutes a null-terminated |
drh | 66b89c8 | 2000-11-28 20:47:17 +0000 | [diff] [blame] | 1356 | ** string from the argument list. But %q also doubles every '\'' character. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1357 | ** %q is designed for use inside a string literal. By doubling each '\'' |
drh | 66b89c8 | 2000-11-28 20:47:17 +0000 | [diff] [blame] | 1358 | ** character it escapes that character and allows it to be inserted into |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1359 | ** the string. |
| 1360 | ** |
| 1361 | ** For example, so some string variable contains text as follows: |
| 1362 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1363 | ** <blockquote><pre> |
| 1364 | ** char *zText = "It's a happy day!"; |
| 1365 | ** </pre></blockquote> |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1366 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1367 | ** One can use this text in an SQL statement as follows: |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1368 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1369 | ** <blockquote><pre> |
| 1370 | ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText); |
| 1371 | ** sqlite3_exec(db, zSQL, 0, 0, 0); |
| 1372 | ** sqlite3_free(zSQL); |
| 1373 | ** </pre></blockquote> |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1374 | ** |
| 1375 | ** Because the %q format string is used, the '\'' character in zText |
| 1376 | ** is escaped and the SQL generated is as follows: |
| 1377 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1378 | ** <blockquote><pre> |
| 1379 | ** INSERT INTO table1 VALUES('It''s a happy day!') |
| 1380 | ** </pre></blockquote> |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1381 | ** |
| 1382 | ** This is correct. Had we used %s instead of %q, the generated SQL |
| 1383 | ** would have looked like this: |
| 1384 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1385 | ** <blockquote><pre> |
| 1386 | ** INSERT INTO table1 VALUES('It's a happy day!'); |
| 1387 | ** </pre></blockquote> |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1388 | ** |
| 1389 | ** This second example is an SQL syntax error. As a general rule you |
| 1390 | ** should always use %q instead of %s when inserting text into a string |
| 1391 | ** literal. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1392 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1393 | ** The %Q option works like %q except it also adds single quotes around |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1394 | ** the outside of the total string. Or if the parameter in the argument |
| 1395 | ** list is a NULL pointer, %Q substitutes the text "NULL" (without single |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1396 | ** quotes) in place of the %Q option. {END} So, for example, one could say: |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1397 | ** |
| 1398 | ** <blockquote><pre> |
| 1399 | ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText); |
| 1400 | ** sqlite3_exec(db, zSQL, 0, 0, 0); |
| 1401 | ** sqlite3_free(zSQL); |
| 1402 | ** </pre></blockquote> |
| 1403 | ** |
| 1404 | ** The code above will render a correct SQL statement in the zSQL |
| 1405 | ** variable even if the zText variable is a NULL pointer. |
drh | 153c62c | 2007-08-24 03:51:33 +0000 | [diff] [blame] | 1406 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1407 | ** The "%z" formatting option works exactly like "%s" with the |
drh | 153c62c | 2007-08-24 03:51:33 +0000 | [diff] [blame] | 1408 | ** addition that after the string has been read and copied into |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1409 | ** the result, [sqlite3_free()] is called on the input string. {END} |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1410 | ** |
| 1411 | ** INVARIANTS: |
| 1412 | ** |
| 1413 | ** {F17403} The [sqlite3_mprintf()] and [sqlite3_vmprintf()] interfaces |
| 1414 | ** return either pointers to zero-terminated UTF-8 strings held in |
| 1415 | ** memory obtained from [sqlite3_malloc()] or NULL pointers if |
| 1416 | ** a call to [sqlite3_malloc()] fails. |
| 1417 | ** |
| 1418 | ** {F17406} The [sqlite3_snprintf()] interface writes a zero-terminated |
| 1419 | ** UTF-8 string into the buffer pointed to by the second parameter |
| 1420 | ** provided that the first parameter is greater than zero. |
| 1421 | ** |
| 1422 | ** {F17407} The [sqlite3_snprintf()] interface does not writes slots of |
| 1423 | ** its output buffer (the second parameter) outside the range |
| 1424 | ** of 0 through N-1 (where N is the first parameter) |
| 1425 | ** regardless of the length of the string |
| 1426 | ** requested by the format specification. |
| 1427 | ** |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 1428 | */ |
danielk1977 | 6f8a503 | 2004-05-10 10:34:51 +0000 | [diff] [blame] | 1429 | char *sqlite3_mprintf(const char*,...); |
| 1430 | char *sqlite3_vmprintf(const char*, va_list); |
drh | feac5f8 | 2004-08-01 00:10:45 +0000 | [diff] [blame] | 1431 | char *sqlite3_snprintf(int,char*,const char*, ...); |
drh | 5191b7e | 2002-03-08 02:12:00 +0000 | [diff] [blame] | 1432 | |
drh | 28dd479 | 2006-06-26 21:35:44 +0000 | [diff] [blame] | 1433 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1434 | ** CAPI3REF: Memory Allocation Subsystem {F17300} |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 1435 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1436 | ** The SQLite core uses these three routines for all of its own |
| 1437 | ** internal memory allocation needs. "Core" in the previous sentence |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1438 | ** does not include operating-system specific VFS implementation. The |
| 1439 | ** windows VFS uses native malloc and free for some operations. |
drh | d64621d | 2007-11-05 17:54:17 +0000 | [diff] [blame] | 1440 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1441 | ** The sqlite3_malloc() routine returns a pointer to a block |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1442 | ** of memory at least N bytes in length, where N is the parameter. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1443 | ** If sqlite3_malloc() is unable to obtain sufficient free |
| 1444 | ** memory, it returns a NULL pointer. If the parameter N to |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1445 | ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns |
| 1446 | ** a NULL pointer. |
| 1447 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1448 | ** Calling sqlite3_free() with a pointer previously returned |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1449 | ** by sqlite3_malloc() or sqlite3_realloc() releases that memory so |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1450 | ** that it might be reused. The sqlite3_free() routine is |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1451 | ** a no-op if is called with a NULL pointer. Passing a NULL pointer |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1452 | ** to sqlite3_free() is harmless. After being freed, memory |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1453 | ** should neither be read nor written. Even reading previously freed |
| 1454 | ** memory might result in a segmentation fault or other severe error. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1455 | ** Memory corruption, a segmentation fault, or other severe error |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1456 | ** might result if sqlite3_free() is called with a non-NULL pointer that |
| 1457 | ** was not obtained from sqlite3_malloc() or sqlite3_free(). |
| 1458 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1459 | ** The sqlite3_realloc() interface attempts to resize a |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1460 | ** prior memory allocation to be at least N bytes, where N is the |
| 1461 | ** second parameter. The memory allocation to be resized is the first |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1462 | ** parameter. If the first parameter to sqlite3_realloc() |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1463 | ** is a NULL pointer then its behavior is identical to calling |
| 1464 | ** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc(). |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1465 | ** If the second parameter to sqlite3_realloc() is zero or |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1466 | ** negative then the behavior is exactly the same as calling |
| 1467 | ** sqlite3_free(P) where P is the first parameter to sqlite3_realloc(). |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1468 | ** Sqlite3_realloc() returns a pointer to a memory allocation |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1469 | ** of at least N bytes in size or NULL if sufficient memory is unavailable. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1470 | ** If M is the size of the prior allocation, then min(N,M) bytes |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1471 | ** of the prior allocation are copied into the beginning of buffer returned |
| 1472 | ** by sqlite3_realloc() and the prior allocation is freed. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1473 | ** If sqlite3_realloc() returns NULL, then the prior allocation |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1474 | ** is not freed. |
| 1475 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1476 | ** The memory returned by sqlite3_malloc() and sqlite3_realloc() |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1477 | ** is always aligned to at least an 8 byte boundary. {END} |
| 1478 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1479 | ** The default implementation |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 1480 | ** of the memory allocation subsystem uses the malloc(), realloc() |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1481 | ** and free() provided by the standard C library. {F17382} However, if |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 1482 | ** SQLite is compiled with the following C preprocessor macro |
| 1483 | ** |
drh | d64621d | 2007-11-05 17:54:17 +0000 | [diff] [blame] | 1484 | ** <blockquote> SQLITE_MEMORY_SIZE=<i>NNN</i> </blockquote> |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 1485 | ** |
drh | d64621d | 2007-11-05 17:54:17 +0000 | [diff] [blame] | 1486 | ** where <i>NNN</i> is an integer, then SQLite create a static |
| 1487 | ** array of at least <i>NNN</i> bytes in size and use that array |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1488 | ** for all of its dynamic memory allocation needs. {END} Additional |
| 1489 | ** memory allocator options may be added in future releases. |
drh | d64621d | 2007-11-05 17:54:17 +0000 | [diff] [blame] | 1490 | ** |
| 1491 | ** In SQLite version 3.5.0 and 3.5.1, it was possible to define |
| 1492 | ** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in |
| 1493 | ** implementation of these routines to be omitted. That capability |
| 1494 | ** is no longer provided. Only built-in memory allocators can be |
| 1495 | ** used. |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 1496 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1497 | ** The windows OS interface layer calls |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 1498 | ** the system malloc() and free() directly when converting |
| 1499 | ** filenames between the UTF-8 encoding used by SQLite |
| 1500 | ** and whatever filename encoding is used by the particular windows |
| 1501 | ** installation. Memory allocation errors are detected, but |
| 1502 | ** they are reported back as [SQLITE_CANTOPEN] or |
| 1503 | ** [SQLITE_IOERR] rather than [SQLITE_NOMEM]. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1504 | ** |
| 1505 | ** INVARIANTS: |
| 1506 | ** |
| 1507 | ** {F17303} The [sqlite3_malloc(N)] interface returns either a pointer to |
| 1508 | ** newly checked-out block of at least N bytes of memory |
| 1509 | ** that is 8-byte aligned, |
| 1510 | ** or it returns NULL if it is unable to fulfill the request. |
| 1511 | ** |
| 1512 | ** {F17304} The [sqlite3_malloc(N)] interface returns a NULL pointer if |
| 1513 | ** N is less than or equal to zero. |
| 1514 | ** |
| 1515 | ** {F17305} The [sqlite3_free(P)] interface releases memory previously |
| 1516 | ** returned from [sqlite3_malloc()] or [sqlite3_realloc()], |
| 1517 | ** making it available for reuse. |
| 1518 | ** |
| 1519 | ** {F17306} A call to [sqlite3_free(NULL)] is a harmless no-op. |
| 1520 | ** |
| 1521 | ** {F17310} A call to [sqlite3_realloc(0,N)] is equivalent to a call |
| 1522 | ** to [sqlite3_malloc(N)]. |
| 1523 | ** |
| 1524 | ** {F17312} A call to [sqlite3_realloc(P,0)] is equivalent to a call |
| 1525 | ** to [sqlite3_free(P)]. |
| 1526 | ** |
| 1527 | ** {F17315} The SQLite core uses [sqlite3_malloc()], [sqlite3_realloc()], |
| 1528 | ** and [sqlite3_free()] for all of its memory allocation and |
| 1529 | ** deallocation needs. |
| 1530 | ** |
| 1531 | ** {F17318} The [sqlite3_realloc(P,N)] interface returns either a pointer |
| 1532 | ** to a block of checked-out memory of at least N bytes in size |
| 1533 | ** that is 8-byte aligned, or a NULL pointer. |
| 1534 | ** |
| 1535 | ** {F17321} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first |
| 1536 | ** copies the first K bytes of content from P into the newly allocated |
| 1537 | ** where K is the lessor of N and the size of the buffer P. |
| 1538 | ** |
| 1539 | ** {F17322} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first |
| 1540 | ** releases the buffer P. |
| 1541 | ** |
| 1542 | ** {F17323} When [sqlite3_realloc(P,N)] returns NULL, the buffer P is |
| 1543 | ** not modified or released. |
| 1544 | ** |
| 1545 | ** LIMITATIONS: |
| 1546 | ** |
| 1547 | ** {U17350} The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()] |
| 1548 | ** must be either NULL or else a pointer obtained from a prior |
| 1549 | ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that has |
| 1550 | ** not been released. |
| 1551 | ** |
| 1552 | ** {U17351} The application must not read or write any part of |
| 1553 | ** a block of memory after it has been released using |
| 1554 | ** [sqlite3_free()] or [sqlite3_realloc()]. |
| 1555 | ** |
drh | 28dd479 | 2006-06-26 21:35:44 +0000 | [diff] [blame] | 1556 | */ |
drh | f3a65f7 | 2007-08-22 20:18:21 +0000 | [diff] [blame] | 1557 | void *sqlite3_malloc(int); |
| 1558 | void *sqlite3_realloc(void*, int); |
drh | 28dd479 | 2006-06-26 21:35:44 +0000 | [diff] [blame] | 1559 | void sqlite3_free(void*); |
| 1560 | |
drh | 5191b7e | 2002-03-08 02:12:00 +0000 | [diff] [blame] | 1561 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1562 | ** CAPI3REF: Memory Allocator Statistics {F17370} |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 1563 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1564 | ** SQLite provides these two interfaces for reporting on the status |
| 1565 | ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()] |
| 1566 | ** the memory allocation subsystem included within the SQLite. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 1567 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1568 | ** INVARIANTS: |
| 1569 | ** |
| 1570 | ** {F17371} The [sqlite3_memory_used()] routine returns the |
| 1571 | ** number of bytes of memory currently outstanding |
| 1572 | ** (malloced but not freed). |
| 1573 | ** |
| 1574 | ** {F17373} The [sqlite3_memory_highwater()] routine returns the maximum |
| 1575 | ** value of [sqlite3_memory_used()] |
| 1576 | ** since the highwater mark was last reset. |
| 1577 | ** |
| 1578 | ** {F17374} The values returned by [sqlite3_memory_used()] and |
| 1579 | ** [sqlite3_memory_highwater()] include any overhead |
| 1580 | ** added by SQLite in its implementation of [sqlite3_malloc()], |
| 1581 | ** but not overhead added by the any underlying system library |
| 1582 | ** routines that [sqlite3_malloc()] may call. |
| 1583 | ** |
| 1584 | ** {F17375} The memory highwater mark is reset to the current value of |
| 1585 | ** [sqlite3_memory_used()] if and only if the parameter to |
| 1586 | ** [sqlite3_memory_highwater()] is true. The value returned |
| 1587 | ** by [sqlite3_memory_highwater(1)] is the highwater mark |
| 1588 | ** prior to the reset. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 1589 | */ |
drh | 153c62c | 2007-08-24 03:51:33 +0000 | [diff] [blame] | 1590 | sqlite3_int64 sqlite3_memory_used(void); |
| 1591 | sqlite3_int64 sqlite3_memory_highwater(int resetFlag); |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 1592 | |
| 1593 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1594 | ** CAPI3REF: Compile-Time Authorization Callbacks {F12500} |
| 1595 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1596 | ** This routine registers a authorizer callback with a particular |
| 1597 | ** database connection, supplied in the first argument. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1598 | ** The authorizer callback is invoked as SQL statements are being compiled |
| 1599 | ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()], |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1600 | ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1601 | ** points during the compilation process, as logic is being created |
| 1602 | ** to perform various actions, the authorizer callback is invoked to |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1603 | ** see if those actions are allowed. The authorizer callback should |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1604 | ** return SQLITE_OK to allow the action, [SQLITE_IGNORE] to disallow the |
| 1605 | ** specific action but allow the SQL statement to continue to be |
| 1606 | ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1607 | ** rejected with an error. If the authorizer callback returns |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1608 | ** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] |
| 1609 | ** then [sqlite3_prepare_v2()] or equivalent call that triggered |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1610 | ** the authorizer will fail with an error message. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1611 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1612 | ** When the callback returns [SQLITE_OK], that means the operation |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1613 | ** requested is ok. When the callback returns [SQLITE_DENY], the |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1614 | ** [sqlite3_prepare_v2()] or equivalent call that triggered the |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1615 | ** authorizer will fail with an error message explaining that |
| 1616 | ** access is denied. If the authorizer code is [SQLITE_READ] |
| 1617 | ** and the callback returns [SQLITE_IGNORE] then the prepared |
| 1618 | ** statement is constructed to insert a NULL value in place of |
| 1619 | ** the table column that would have |
| 1620 | ** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE] |
| 1621 | ** return can be used to deny an untrusted user access to individual |
| 1622 | ** columns of a table. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1623 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1624 | ** The first parameter to the authorizer callback is a copy of |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1625 | ** the third parameter to the sqlite3_set_authorizer() interface. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1626 | ** The second parameter to the callback is an integer |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1627 | ** [SQLITE_COPY | action code] that specifies the particular action |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1628 | ** to be authorized. The third through sixth |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1629 | ** parameters to the callback are zero-terminated strings that contain |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1630 | ** additional details about the action to be authorized. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1631 | ** |
| 1632 | ** An authorizer is used when preparing SQL statements from an untrusted |
| 1633 | ** source, to ensure that the SQL statements do not try to access data |
| 1634 | ** that they are not allowed to see, or that they do not try to |
| 1635 | ** execute malicious statements that damage the database. For |
| 1636 | ** example, an application may allow a user to enter arbitrary |
| 1637 | ** SQL queries for evaluation by a database. But the application does |
| 1638 | ** not want the user to be able to make arbitrary changes to the |
| 1639 | ** database. An authorizer could then be put in place while the |
| 1640 | ** user-entered SQL is being prepared that disallows everything |
| 1641 | ** except SELECT statements. |
| 1642 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1643 | ** Only a single authorizer can be in place on a database connection |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1644 | ** at a time. Each call to sqlite3_set_authorizer overrides the |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1645 | ** previous call. Disable the authorizer by installing a NULL callback. |
| 1646 | ** The authorizer is disabled by default. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1647 | ** |
| 1648 | ** Note that the authorizer callback is invoked only during |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1649 | ** [sqlite3_prepare()] or its variants. Authorization is not |
| 1650 | ** performed during statement evaluation in [sqlite3_step()]. |
| 1651 | ** |
| 1652 | ** INVARIANTS: |
| 1653 | ** |
| 1654 | ** {F12501} The [sqlite3_set_authorizer(D,...)] interface registers a |
| 1655 | ** authorizer callback with database connection D. |
| 1656 | ** |
| 1657 | ** {F12502} The authorizer callback is invoked as SQL statements are |
| 1658 | ** being compiled |
| 1659 | ** |
| 1660 | ** {F12503} If the authorizer callback returns any value other than |
| 1661 | ** [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] then |
| 1662 | ** the [sqlite3_prepare_v2()] or equivalent call that caused |
| 1663 | ** the authorizer callback to run shall fail with an |
| 1664 | ** [SQLITE_ERROR] error code and an appropriate error message. |
| 1665 | ** |
| 1666 | ** {F12504} When the authorizer callback returns [SQLITE_OK], the operation |
| 1667 | ** described is coded normally. |
| 1668 | ** |
| 1669 | ** {F12505} When the authorizer callback returns [SQLITE_DENY], the |
| 1670 | ** [sqlite3_prepare_v2()] or equivalent call that caused the |
| 1671 | ** authorizer callback to run shall fail |
| 1672 | ** with an [SQLITE_ERROR] error code and an error message |
| 1673 | ** explaining that access is denied. |
| 1674 | ** |
| 1675 | ** {F12506} If the authorizer code (the 2nd parameter to the authorizer |
| 1676 | ** callback) is [SQLITE_READ] and the authorizer callback returns |
| 1677 | ** [SQLITE_IGNORE] then the prepared statement is constructed to |
| 1678 | ** insert a NULL value in place of the table column that would have |
| 1679 | ** been read if [SQLITE_OK] had been returned. |
| 1680 | ** |
| 1681 | ** {F12507} If the authorizer code (the 2nd parameter to the authorizer |
| 1682 | ** callback) is anything other than [SQLITE_READ], then |
| 1683 | ** a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY]. |
| 1684 | ** |
| 1685 | ** {F12510} The first parameter to the authorizer callback is a copy of |
| 1686 | ** the third parameter to the [sqlite3_set_authorizer()] interface. |
| 1687 | ** |
| 1688 | ** {F12511} The second parameter to the callback is an integer |
| 1689 | ** [SQLITE_COPY | action code] that specifies the particular action |
| 1690 | ** to be authorized. |
| 1691 | ** |
| 1692 | ** {F12512} The third through sixth parameters to the callback are |
| 1693 | ** zero-terminated strings that contain |
| 1694 | ** additional details about the action to be authorized. |
| 1695 | ** |
| 1696 | ** {F12520} Each call to [sqlite3_set_authorizer()] overrides the |
| 1697 | ** any previously installed authorizer. |
| 1698 | ** |
| 1699 | ** {F12521} A NULL authorizer means that no authorization |
| 1700 | ** callback is invoked. |
| 1701 | ** |
| 1702 | ** {F12522} The default authorizer is NULL. |
drh | ed6c867 | 2003-01-12 18:02:16 +0000 | [diff] [blame] | 1703 | */ |
danielk1977 | 6f8a503 | 2004-05-10 10:34:51 +0000 | [diff] [blame] | 1704 | int sqlite3_set_authorizer( |
danielk1977 | f9d64d2 | 2004-06-19 08:18:07 +0000 | [diff] [blame] | 1705 | sqlite3*, |
drh | e22a334 | 2003-04-22 20:30:37 +0000 | [diff] [blame] | 1706 | int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), |
drh | e5f9c64 | 2003-01-13 23:27:31 +0000 | [diff] [blame] | 1707 | void *pUserData |
drh | ed6c867 | 2003-01-12 18:02:16 +0000 | [diff] [blame] | 1708 | ); |
| 1709 | |
| 1710 | /* |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1711 | ** CAPI3REF: Authorizer Return Codes {F12590} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1712 | ** |
| 1713 | ** The [sqlite3_set_authorizer | authorizer callback function] must |
| 1714 | ** return either [SQLITE_OK] or one of these two constants in order |
| 1715 | ** to signal SQLite whether or not the action is permitted. See the |
| 1716 | ** [sqlite3_set_authorizer | authorizer documentation] for additional |
| 1717 | ** information. |
| 1718 | */ |
| 1719 | #define SQLITE_DENY 1 /* Abort the SQL statement with an error */ |
| 1720 | #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ |
| 1721 | |
| 1722 | /* |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1723 | ** CAPI3REF: Authorizer Action Codes {F12550} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1724 | ** |
| 1725 | ** The [sqlite3_set_authorizer()] interface registers a callback function |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1726 | ** that is invoked to authorizer certain SQL statement actions. The |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1727 | ** second parameter to the callback is an integer code that specifies |
| 1728 | ** what action is being authorized. These are the integer action codes that |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1729 | ** the authorizer callback may be passed. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1730 | ** |
| 1731 | ** These action code values signify what kind of operation is to be |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1732 | ** authorized. The 3rd and 4th parameters to the authorization |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1733 | ** callback function will be parameters or NULL depending on which of these |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1734 | ** codes is used as the second parameter. The 5th parameter to the |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1735 | ** authorizer callback is the name of the database ("main", "temp", |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1736 | ** etc.) if applicable. The 6th parameter to the authorizer callback |
drh | 5cf590c | 2003-04-24 01:45:04 +0000 | [diff] [blame] | 1737 | ** is the name of the inner-most trigger or view that is responsible for |
| 1738 | ** the access attempt or NULL if this access attempt is directly from |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1739 | ** top-level SQL code. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1740 | ** |
| 1741 | ** INVARIANTS: |
| 1742 | ** |
| 1743 | ** {F12551} The second parameter to an |
| 1744 | ** [sqlite3_set_authorizer | authorizer callback is always an integer |
| 1745 | ** [SQLITE_COPY | authorizer code] that specifies what action |
| 1746 | ** is being authorized. |
| 1747 | ** |
| 1748 | ** {F12552} The 3rd and 4th parameters to the |
| 1749 | ** [sqlite3_set_authorizer | authorization callback function] |
| 1750 | ** will be parameters or NULL depending on which |
| 1751 | ** [SQLITE_COPY | authorizer code] is used as the second parameter. |
| 1752 | ** |
| 1753 | ** {F12553} The 5th parameter to the |
| 1754 | ** [sqlite3_set_authorizer | authorizer callback] is the name |
| 1755 | ** of the database (example: "main", "temp", etc.) if applicable. |
| 1756 | ** |
| 1757 | ** {F12554} The 6th parameter to the |
| 1758 | ** [sqlite3_set_authorizer | authorizer callback] is the name |
| 1759 | ** of the inner-most trigger or view that is responsible for |
| 1760 | ** the access attempt or NULL if this access attempt is directly from |
| 1761 | ** top-level SQL code. |
drh | ed6c867 | 2003-01-12 18:02:16 +0000 | [diff] [blame] | 1762 | */ |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1763 | /******************************************* 3rd ************ 4th ***********/ |
drh | e5f9c64 | 2003-01-13 23:27:31 +0000 | [diff] [blame] | 1764 | #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ |
| 1765 | #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */ |
| 1766 | #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */ |
| 1767 | #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */ |
drh | 77ad4e4 | 2003-01-14 02:49:27 +0000 | [diff] [blame] | 1768 | #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */ |
drh | e5f9c64 | 2003-01-13 23:27:31 +0000 | [diff] [blame] | 1769 | #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */ |
drh | 77ad4e4 | 2003-01-14 02:49:27 +0000 | [diff] [blame] | 1770 | #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */ |
drh | e5f9c64 | 2003-01-13 23:27:31 +0000 | [diff] [blame] | 1771 | #define SQLITE_CREATE_VIEW 8 /* View Name NULL */ |
| 1772 | #define SQLITE_DELETE 9 /* Table Name NULL */ |
drh | 77ad4e4 | 2003-01-14 02:49:27 +0000 | [diff] [blame] | 1773 | #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */ |
drh | e5f9c64 | 2003-01-13 23:27:31 +0000 | [diff] [blame] | 1774 | #define SQLITE_DROP_TABLE 11 /* Table Name NULL */ |
drh | 77ad4e4 | 2003-01-14 02:49:27 +0000 | [diff] [blame] | 1775 | #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */ |
drh | e5f9c64 | 2003-01-13 23:27:31 +0000 | [diff] [blame] | 1776 | #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */ |
drh | 77ad4e4 | 2003-01-14 02:49:27 +0000 | [diff] [blame] | 1777 | #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */ |
drh | e5f9c64 | 2003-01-13 23:27:31 +0000 | [diff] [blame] | 1778 | #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */ |
drh | 77ad4e4 | 2003-01-14 02:49:27 +0000 | [diff] [blame] | 1779 | #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */ |
drh | e5f9c64 | 2003-01-13 23:27:31 +0000 | [diff] [blame] | 1780 | #define SQLITE_DROP_VIEW 17 /* View Name NULL */ |
| 1781 | #define SQLITE_INSERT 18 /* Table Name NULL */ |
| 1782 | #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */ |
| 1783 | #define SQLITE_READ 20 /* Table Name Column Name */ |
| 1784 | #define SQLITE_SELECT 21 /* NULL NULL */ |
| 1785 | #define SQLITE_TRANSACTION 22 /* NULL NULL */ |
| 1786 | #define SQLITE_UPDATE 23 /* Table Name Column Name */ |
drh | 81e293b | 2003-06-06 19:00:42 +0000 | [diff] [blame] | 1787 | #define SQLITE_ATTACH 24 /* Filename NULL */ |
| 1788 | #define SQLITE_DETACH 25 /* Database Name NULL */ |
danielk1977 | 1c8c23c | 2004-11-12 15:53:37 +0000 | [diff] [blame] | 1789 | #define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */ |
danielk1977 | 1d54df8 | 2004-11-23 15:41:16 +0000 | [diff] [blame] | 1790 | #define SQLITE_REINDEX 27 /* Index Name NULL */ |
drh | e6e0496 | 2005-07-23 02:17:03 +0000 | [diff] [blame] | 1791 | #define SQLITE_ANALYZE 28 /* Table Name NULL */ |
danielk1977 | f1a381e | 2006-06-16 08:01:02 +0000 | [diff] [blame] | 1792 | #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ |
| 1793 | #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ |
drh | 5169bbc | 2006-08-24 14:59:45 +0000 | [diff] [blame] | 1794 | #define SQLITE_FUNCTION 31 /* Function Name NULL */ |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1795 | #define SQLITE_COPY 0 /* No longer used */ |
drh | ed6c867 | 2003-01-12 18:02:16 +0000 | [diff] [blame] | 1796 | |
| 1797 | /* |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1798 | ** CAPI3REF: Tracing And Profiling Functions {F12280} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1799 | ** |
| 1800 | ** These routines register callback functions that can be used for |
| 1801 | ** tracing and profiling the execution of SQL statements. |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1802 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1803 | ** The callback function registered by sqlite3_trace() is invoked at |
| 1804 | ** various times when an SQL statement is being run by [sqlite3_step()]. |
| 1805 | ** The callback returns a UTF-8 rendering of the SQL statement text |
| 1806 | ** as the statement first begins executing. Additional callbacks occur |
| 1807 | ** as each triggersubprogram is entered. The callbacks for triggers |
| 1808 | ** contain a UTF-8 SQL comment that identifies the trigger. |
| 1809 | ** |
| 1810 | ** The callback function registered by sqlite3_profile() is invoked |
| 1811 | ** as each SQL statement finishes. The profile callback contains |
| 1812 | ** the original statement text and an estimate of wall-clock time |
| 1813 | ** of how long that statement took to run. |
drh | 19e2d37 | 2005-08-29 23:00:03 +0000 | [diff] [blame] | 1814 | ** |
| 1815 | ** The sqlite3_profile() API is currently considered experimental and |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1816 | ** is subject to change or removal in a future release. |
| 1817 | ** |
| 1818 | ** The trigger reporting feature of the trace callback is considered |
| 1819 | ** experimental and is subject to change or removal in future releases. |
| 1820 | ** Future versions of SQLite might also add new trace callback |
| 1821 | ** invocations. |
| 1822 | ** |
| 1823 | ** INVARIANTS: |
| 1824 | ** |
| 1825 | ** {F12281} The callback function registered by [sqlite3_trace()] is |
| 1826 | ** whenever an SQL statement first begins to execute and |
| 1827 | ** whenever a trigger subprogram first begins to run. |
| 1828 | ** |
| 1829 | ** {F12282} Each call to [sqlite3_trace()] overrides the previously |
| 1830 | ** registered trace callback. |
| 1831 | ** |
| 1832 | ** {F12283} A NULL trace callback disables tracing. |
| 1833 | ** |
| 1834 | ** {F12284} The first argument to the trace callback is a copy of |
| 1835 | ** the pointer which was the 3rd argument to [sqlite3_trace()]. |
| 1836 | ** |
| 1837 | ** {F12285} The second argument to the trace callback is a |
| 1838 | ** zero-terminated UTF8 string containing the original text |
| 1839 | ** of the SQL statement as it was passed into [sqlite3_prepare_v2()] |
| 1840 | ** or the equivalent, or an SQL comment indicating the beginning |
| 1841 | ** of a trigger subprogram. |
| 1842 | ** |
| 1843 | ** {F12287} The callback function registered by [sqlite3_profile()] is invoked |
| 1844 | ** as each SQL statement finishes. |
| 1845 | ** |
| 1846 | ** {F12288} The first parameter to the profile callback is a copy of |
| 1847 | ** the 3rd parameter to [sqlite3_profile()]. |
| 1848 | ** |
| 1849 | ** {F12289} The second parameter to the profile callback is a |
| 1850 | ** zero-terminated UTF-8 string that contains the complete text of |
| 1851 | ** the SQL statement as it was processed by [sqlite3_prepare_v2()] |
| 1852 | ** or the equivalent. |
| 1853 | ** |
| 1854 | ** {F12290} The third parameter to the profile callback is an estimate |
| 1855 | ** of the number of nanoseconds of wall-clock time required to |
| 1856 | ** run the SQL statement from start to finish. |
drh | 18de482 | 2003-01-16 16:28:53 +0000 | [diff] [blame] | 1857 | */ |
danielk1977 | f9d64d2 | 2004-06-19 08:18:07 +0000 | [diff] [blame] | 1858 | void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); |
drh | 19e2d37 | 2005-08-29 23:00:03 +0000 | [diff] [blame] | 1859 | void *sqlite3_profile(sqlite3*, |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1860 | void(*xProfile)(void*,const char*,sqlite3_uint64), void*); |
drh | 18de482 | 2003-01-16 16:28:53 +0000 | [diff] [blame] | 1861 | |
danielk1977 | 348bb5d | 2003-10-18 09:37:26 +0000 | [diff] [blame] | 1862 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1863 | ** CAPI3REF: Query Progress Callbacks {F12910} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1864 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1865 | ** This routine configures a callback function - the |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1866 | ** progress callback - that is invoked periodically during long |
| 1867 | ** running calls to [sqlite3_exec()], [sqlite3_step()] and |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1868 | ** [sqlite3_get_table()]. An example use for this |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1869 | ** interface is to keep a GUI updated during a large query. |
danielk1977 | 348bb5d | 2003-10-18 09:37:26 +0000 | [diff] [blame] | 1870 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1871 | ** If the progress callback returns non-zero, the opertion is |
| 1872 | ** interrupted. This feature can be used to implement a |
| 1873 | ** "Cancel" button on a GUI dialog box. |
danielk1977 | 348bb5d | 2003-10-18 09:37:26 +0000 | [diff] [blame] | 1874 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1875 | ** INVARIANTS: |
| 1876 | ** |
| 1877 | ** {F12911} The callback function registered by [sqlite3_progress_handler()] |
| 1878 | ** is invoked periodically during long running calls to |
| 1879 | ** [sqlite3_step()]. |
| 1880 | ** |
| 1881 | ** {F12912} The progress callback is invoked once for every N virtual |
| 1882 | ** machine opcodes, where N is the second argument to |
| 1883 | ** the [sqlite3_progress_handler()] call that registered |
| 1884 | ** the callback. <todo>What if N is less than 1?</todo> |
| 1885 | ** |
| 1886 | ** {F12913} The progress callback itself is identified by the third |
| 1887 | ** argument to [sqlite3_progress_handler()]. |
| 1888 | ** |
| 1889 | ** {F12914} The fourth argument [sqlite3_progress_handler()] is a |
| 1890 | *** void pointer passed to the progress callback |
| 1891 | ** function each time it is invoked. |
| 1892 | ** |
| 1893 | ** {F12915} If a call to [sqlite3_step()] results in fewer than |
| 1894 | ** N opcodes being executed, |
| 1895 | ** then the progress callback is never invoked. {END} |
danielk1977 | 348bb5d | 2003-10-18 09:37:26 +0000 | [diff] [blame] | 1896 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1897 | ** {F12916} Every call to [sqlite3_progress_handler()] |
| 1898 | ** overwrites any previously registere progress handler. |
| 1899 | ** |
| 1900 | ** {F12917} If the progress handler callback is NULL then no progress |
| 1901 | ** handler is invoked. |
danielk1977 | 348bb5d | 2003-10-18 09:37:26 +0000 | [diff] [blame] | 1902 | ** |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1903 | ** {F12918} If the progress callback returns a result other than 0, then |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1904 | ** the behavior is a if [sqlite3_interrupt()] had been called. |
danielk1977 | 348bb5d | 2003-10-18 09:37:26 +0000 | [diff] [blame] | 1905 | */ |
danielk1977 | f9d64d2 | 2004-06-19 08:18:07 +0000 | [diff] [blame] | 1906 | void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); |
danielk1977 | 348bb5d | 2003-10-18 09:37:26 +0000 | [diff] [blame] | 1907 | |
drh | aa940ea | 2004-01-15 02:44:03 +0000 | [diff] [blame] | 1908 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1909 | ** CAPI3REF: Opening A New Database Connection {F12700} |
drh | aa940ea | 2004-01-15 02:44:03 +0000 | [diff] [blame] | 1910 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1911 | ** These routines open an SQLite database file whose name |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1912 | ** is given by the filename argument. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1913 | ** The filename argument is interpreted as UTF-8 |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1914 | ** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16 |
drh | 9da9d96 | 2007-08-28 15:47:44 +0000 | [diff] [blame] | 1915 | ** in the native byte order for [sqlite3_open16()]. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1916 | ** An [sqlite3*] handle is usually returned in *ppDb, even |
| 1917 | ** if an error occurs. The only exception is if SQLite is unable |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1918 | ** to allocate memory to hold the [sqlite3] object, a NULL will |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1919 | ** be written into *ppDb instead of a pointer to the [sqlite3] object. |
| 1920 | ** If the database is opened (and/or created) |
| 1921 | ** successfully, then [SQLITE_OK] is returned. Otherwise an |
| 1922 | ** error code is returned. The |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1923 | ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 1924 | ** an English language description of the error. |
drh | 22fbcb8 | 2004-02-01 01:22:50 +0000 | [diff] [blame] | 1925 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1926 | ** The default encoding for the database will be UTF-8 if |
drh | 9da9d96 | 2007-08-28 15:47:44 +0000 | [diff] [blame] | 1927 | ** [sqlite3_open()] or [sqlite3_open_v2()] is called and |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1928 | ** UTF-16 in the native byte order if [sqlite3_open16()] is used. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 1929 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1930 | ** Whether or not an error occurs when it is opened, resources |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1931 | ** associated with the [sqlite3*] handle should be released by passing it |
| 1932 | ** to [sqlite3_close()] when it is no longer required. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1933 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1934 | ** The [sqlite3_open_v2()] interface works like [sqlite3_open()] |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 1935 | ** except that it acccepts two additional parameters for additional control |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1936 | ** over the new database connection. The flags parameter can be |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1937 | ** one of: |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1938 | ** |
| 1939 | ** <ol> |
| 1940 | ** <li> [SQLITE_OPEN_READONLY] |
| 1941 | ** <li> [SQLITE_OPEN_READWRITE] |
| 1942 | ** <li> [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE] |
| 1943 | ** </ol> |
| 1944 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1945 | ** The first value opens the database read-only. |
| 1946 | ** If the database does not previously exist, an error is returned. |
| 1947 | ** The second option opens |
drh | 9da9d96 | 2007-08-28 15:47:44 +0000 | [diff] [blame] | 1948 | ** the database for reading and writing if possible, or reading only if |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1949 | ** if the file is write protected. In either case the database |
| 1950 | ** must already exist or an error is returned. The third option |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 1951 | ** opens the database for reading and writing and creates it if it does |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1952 | ** not already exist. |
drh | 9da9d96 | 2007-08-28 15:47:44 +0000 | [diff] [blame] | 1953 | ** The third options is behavior that is always used for [sqlite3_open()] |
| 1954 | ** and [sqlite3_open16()]. |
| 1955 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1956 | ** If the filename is ":memory:", then an private |
| 1957 | ** in-memory database is created for the connection. This in-memory |
| 1958 | ** database will vanish when the database connection is closed. Future |
drh | 9da9d96 | 2007-08-28 15:47:44 +0000 | [diff] [blame] | 1959 | ** version of SQLite might make use of additional special filenames |
| 1960 | ** that begin with the ":" character. It is recommended that |
| 1961 | ** when a database filename really does begin with |
| 1962 | ** ":" that you prefix the filename with a pathname like "./" to |
| 1963 | ** avoid ambiguity. |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 1964 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1965 | ** If the filename is an empty string, then a private temporary |
| 1966 | ** on-disk database will be created. This private database will be |
drh | 3f3b635 | 2007-09-03 20:32:45 +0000 | [diff] [blame] | 1967 | ** automatically deleted as soon as the database connection is closed. |
| 1968 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1969 | ** The fourth parameter to sqlite3_open_v2() is the name of the |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 1970 | ** [sqlite3_vfs] object that defines the operating system |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1971 | ** interface that the new database connection should use. If the |
drh | 9da9d96 | 2007-08-28 15:47:44 +0000 | [diff] [blame] | 1972 | ** fourth parameter is a NULL pointer then the default [sqlite3_vfs] |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1973 | ** object is used. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 1974 | ** |
drh | 9da9d96 | 2007-08-28 15:47:44 +0000 | [diff] [blame] | 1975 | ** <b>Note to windows users:</b> The encoding used for the filename argument |
| 1976 | ** of [sqlite3_open()] and [sqlite3_open_v2()] must be UTF-8, not whatever |
| 1977 | ** codepage is currently defined. Filenames containing international |
| 1978 | ** characters must be converted to UTF-8 prior to passing them into |
| 1979 | ** [sqlite3_open()] or [sqlite3_open_v2()]. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 1980 | ** |
| 1981 | ** INVARIANTS: |
| 1982 | ** |
| 1983 | ** {F12701} The [sqlite3_open()], [sqlite3_open16()], and |
| 1984 | ** [sqlite3_open_v2()] interfaces create a new |
| 1985 | ** [database connection] associated with |
| 1986 | ** the database file given in their first parameter. |
| 1987 | ** |
| 1988 | ** {F12702} The filename argument is interpreted as UTF-8 |
| 1989 | ** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16 |
| 1990 | ** in the native byte order for [sqlite3_open16()]. |
| 1991 | ** |
| 1992 | ** {F12703} A successful invocation of [sqlite3_open()], [sqlite3_open16()], |
| 1993 | ** or [sqlite3_open_v2()] writes a pointer to a new |
| 1994 | ** [database connection] into *ppDb. |
| 1995 | ** |
| 1996 | ** {F12704} The [sqlite3_open()], [sqlite3_open16()], and |
| 1997 | ** [sqlite3_open_v2()] interfaces return [SQLITE_OK] upon success, |
| 1998 | ** or an appropriate [error code] on failure. |
| 1999 | ** |
| 2000 | ** {F12706} The default text encoding for a new database created using |
| 2001 | ** [sqlite3_open()] or [sqlite3_open_v2()] will be UTF-8. |
| 2002 | ** |
| 2003 | ** {F12707} The default text encoding for a new database created using |
| 2004 | ** [sqlite3_open16()] will be UTF-16. |
| 2005 | ** |
| 2006 | ** {F12709} The [sqlite3_open(F,D)] interface is equivalent to |
| 2007 | ** [sqlite3_open_v2(F,D,G,0)] where the G parameter is |
| 2008 | ** [SQLITE_OPEN_READWRITE]|[SQLITE_OPEN_CREATE]. |
| 2009 | ** |
| 2010 | ** {F12711} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the |
| 2011 | ** bit value [SQLITE_OPEN_READONLY] then the database is opened |
| 2012 | ** for reading only. |
| 2013 | ** |
| 2014 | ** {F12712} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the |
| 2015 | ** bit value [SQLITE_OPEN_READWRITE] then the database is opened |
| 2016 | ** reading and writing if possible, or for reading only if the |
| 2017 | ** file is write protected by the operating system. |
| 2018 | ** |
| 2019 | ** {F12713} If the G parameter to [sqlite3_open(v2(F,D,G,V)] omits the |
| 2020 | ** bit value [SQLITE_OPEN_CREATE] and the database does not |
| 2021 | ** previously exist, an error is returned. |
| 2022 | ** |
| 2023 | ** {F12714} If the G parameter to [sqlite3_open(v2(F,D,G,V)] contains the |
| 2024 | ** bit value [SQLITE_OPEN_CREATE] and the database does not |
| 2025 | ** previously exist, then an attempt is made to create and |
| 2026 | ** initialize the database. |
| 2027 | ** |
| 2028 | ** {F12717} If the filename argument to [sqlite3_open()], [sqlite3_open16()], |
| 2029 | ** or [sqlite3_open_v2()] is ":memory:", then an private, |
| 2030 | ** ephemeral, in-memory database is created for the connection. |
| 2031 | ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required |
| 2032 | ** in sqlite3_open_v2()?</todo> |
| 2033 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 2034 | ** {F12719} If the filename is NULL or an empty string, then a private, |
| 2035 | ** ephermeral on-disk database will be created. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2036 | ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required |
| 2037 | ** in sqlite3_open_v2()?</todo> |
| 2038 | ** |
| 2039 | ** {F12721} The [database connection] created by |
| 2040 | ** [sqlite3_open_v2(F,D,G,V)] will use the |
| 2041 | ** [sqlite3_vfs] object identified by the V parameter, or |
| 2042 | ** the default [sqlite3_vfs] object is V is a NULL pointer. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2043 | */ |
| 2044 | int sqlite3_open( |
| 2045 | const char *filename, /* Database filename (UTF-8) */ |
danielk1977 | 4f057f9 | 2004-06-08 00:02:33 +0000 | [diff] [blame] | 2046 | sqlite3 **ppDb /* OUT: SQLite db handle */ |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2047 | ); |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2048 | int sqlite3_open16( |
| 2049 | const void *filename, /* Database filename (UTF-16) */ |
danielk1977 | 4f057f9 | 2004-06-08 00:02:33 +0000 | [diff] [blame] | 2050 | sqlite3 **ppDb /* OUT: SQLite db handle */ |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2051 | ); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 2052 | int sqlite3_open_v2( |
drh | 428e282 | 2007-08-30 16:23:19 +0000 | [diff] [blame] | 2053 | const char *filename, /* Database filename (UTF-8) */ |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 2054 | sqlite3 **ppDb, /* OUT: SQLite db handle */ |
| 2055 | int flags, /* Flags */ |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 2056 | const char *zVfs /* Name of VFS module to use */ |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 2057 | ); |
danielk1977 | 295ba55 | 2004-05-19 10:34:51 +0000 | [diff] [blame] | 2058 | |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2059 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2060 | ** CAPI3REF: Error Codes And Messages {F12800} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2061 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2062 | ** The sqlite3_errcode() interface returns the numeric |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2063 | ** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code] |
| 2064 | ** for the most recent failed sqlite3_* API call associated |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2065 | ** with [sqlite3] handle 'db'. If a prior API call failed but the |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2066 | ** most recent API call succeeded, the return value from sqlite3_errcode() |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2067 | ** is undefined. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2068 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2069 | ** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2070 | ** text that describes the error, as either UTF8 or UTF16 respectively. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2071 | ** Memory to hold the error message string is managed internally. |
| 2072 | ** The application does not need to worry with freeing the result. |
mlcreech | 2735886 | 2008-03-01 23:34:46 +0000 | [diff] [blame] | 2073 | ** However, the error string might be overwritten or deallocated by |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2074 | ** subsequent calls to other SQLite interface functions. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2075 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2076 | ** INVARIANTS: |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2077 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2078 | ** {F12801} The [sqlite3_errcode(D)] interface returns the numeric |
| 2079 | ** [SQLITE_OK | result code] or |
| 2080 | ** [SQLITE_IOERR_READ | extended result code] |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 2081 | ** for the most recently failed interface call associated |
| 2082 | ** with [database connection] D. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2083 | ** |
| 2084 | ** {F12803} The [sqlite3_errmsg(D)] and [sqlite3_errmsg16(D)] |
| 2085 | ** interfaces return English-language text that describes |
| 2086 | ** the error in the mostly recently failed interface call, |
| 2087 | ** encoded as either UTF8 or UTF16 respectively. |
| 2088 | ** |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 2089 | ** {F12807} The strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()] |
| 2090 | ** are valid until the next SQLite interface call. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2091 | ** |
| 2092 | ** {F12808} Calls to API routines that do not return an error code |
| 2093 | ** (example: [sqlite3_data_count()]) do not |
| 2094 | ** change the error code or message returned by |
| 2095 | ** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()]. |
| 2096 | ** |
| 2097 | ** {F12809} Interfaces that are not associated with a specific |
| 2098 | ** [database connection] (examples: |
| 2099 | ** [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()] |
| 2100 | ** do not change the values returned by |
| 2101 | ** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()]. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2102 | */ |
| 2103 | int sqlite3_errcode(sqlite3 *db); |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2104 | const char *sqlite3_errmsg(sqlite3*); |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2105 | const void *sqlite3_errmsg16(sqlite3*); |
| 2106 | |
| 2107 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2108 | ** CAPI3REF: SQL Statement Object {F13000} |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2109 | ** KEYWORDS: {prepared statement} {prepared statements} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2110 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 2111 | ** An instance of this object represent single SQL statements. This |
| 2112 | ** object is variously known as a "prepared statement" or a |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2113 | ** "compiled SQL statement" or simply as a "statement". |
| 2114 | ** |
| 2115 | ** The life of a statement object goes something like this: |
| 2116 | ** |
| 2117 | ** <ol> |
| 2118 | ** <li> Create the object using [sqlite3_prepare_v2()] or a related |
| 2119 | ** function. |
| 2120 | ** <li> Bind values to host parameters using |
| 2121 | ** [sqlite3_bind_blob | sqlite3_bind_* interfaces]. |
| 2122 | ** <li> Run the SQL by calling [sqlite3_step()] one or more times. |
| 2123 | ** <li> Reset the statement using [sqlite3_reset()] then go back |
| 2124 | ** to step 2. Do this zero or more times. |
| 2125 | ** <li> Destroy the object using [sqlite3_finalize()]. |
| 2126 | ** </ol> |
| 2127 | ** |
| 2128 | ** Refer to documentation on individual methods above for additional |
| 2129 | ** information. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2130 | */ |
danielk1977 | fc57d7b | 2004-05-26 02:04:57 +0000 | [diff] [blame] | 2131 | typedef struct sqlite3_stmt sqlite3_stmt; |
| 2132 | |
danielk1977 | e3209e4 | 2004-05-20 01:40:18 +0000 | [diff] [blame] | 2133 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2134 | ** CAPI3REF: Compiling An SQL Statement {F13010} |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2135 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2136 | ** To execute an SQL query, it must first be compiled into a byte-code |
| 2137 | ** program using one of these routines. |
| 2138 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2139 | ** The first argument "db" is an [database connection] |
drh | 4ff7fa0 | 2007-09-01 18:17:21 +0000 | [diff] [blame] | 2140 | ** obtained from a prior call to [sqlite3_open()], [sqlite3_open_v2()] |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2141 | ** or [sqlite3_open16()]. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2142 | ** The second argument "zSql" is the statement to be compiled, encoded |
| 2143 | ** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() |
| 2144 | ** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2() |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2145 | ** use UTF-16. {END} |
drh | 21f0672 | 2007-07-19 12:41:39 +0000 | [diff] [blame] | 2146 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2147 | ** If the nByte argument is less |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2148 | ** than zero, then zSql is read up to the first zero terminator. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2149 | ** If nByte is non-negative, then it is the maximum number of |
drh | 21f0672 | 2007-07-19 12:41:39 +0000 | [diff] [blame] | 2150 | ** bytes read from zSql. When nByte is non-negative, the |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 2151 | ** zSql string ends at either the first '\000' or '\u0000' character or |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2152 | ** until the nByte-th byte, whichever comes first. {END} |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2153 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2154 | ** *pzTail is made to point to the first byte past the end of the |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 2155 | ** first SQL statement in zSql. These routines only compiles the first |
| 2156 | ** statement in zSql, so *pzTail is left pointing to what remains |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2157 | ** uncompiled. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2158 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2159 | ** *ppStmt is left pointing to a compiled [prepared statement] that can be |
drh | 17eaae7 | 2008-03-03 18:47:28 +0000 | [diff] [blame] | 2160 | ** executed using [sqlite3_step()]. Or if there is an error, *ppStmt is |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2161 | ** set to NULL. If the input text contains no SQL (if the input |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2162 | ** is and empty string or a comment) then *ppStmt is set to NULL. |
| 2163 | ** {U13018} The calling procedure is responsible for deleting the |
| 2164 | ** compiled SQL statement |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2165 | ** using [sqlite3_finalize()] after it has finished with it. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2166 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2167 | ** On success, [SQLITE_OK] is returned. Otherwise an |
| 2168 | ** [error code] is returned. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2169 | ** |
| 2170 | ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are |
| 2171 | ** recommended for all new programs. The two older interfaces are retained |
| 2172 | ** for backwards compatibility, but their use is discouraged. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2173 | ** In the "v2" interfaces, the prepared statement |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2174 | ** that is returned (the [sqlite3_stmt] object) contains a copy of the |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2175 | ** original SQL text. {END} This causes the [sqlite3_step()] interface to |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2176 | ** behave a differently in two ways: |
| 2177 | ** |
| 2178 | ** <ol> |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2179 | ** <li> |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2180 | ** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it |
| 2181 | ** always used to do, [sqlite3_step()] will automatically recompile the SQL |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2182 | ** statement and try to run it again. If the schema has changed in |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2183 | ** a way that makes the statement no longer valid, [sqlite3_step()] will still |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2184 | ** return [SQLITE_SCHEMA]. But unlike the legacy behavior, |
| 2185 | ** [SQLITE_SCHEMA] is now a fatal error. Calling |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2186 | ** [sqlite3_prepare_v2()] again will not make the |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2187 | ** error go away. Note: use [sqlite3_errmsg()] to find the text |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2188 | ** of the parsing error that results in an [SQLITE_SCHEMA] return. {END} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2189 | ** </li> |
| 2190 | ** |
| 2191 | ** <li> |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2192 | ** When an error occurs, |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2193 | ** [sqlite3_step()] will return one of the detailed |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2194 | ** [error codes] or [extended error codes]. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2195 | ** The legacy behavior was that [sqlite3_step()] would only return a generic |
| 2196 | ** [SQLITE_ERROR] result code and you would have to make a second call to |
| 2197 | ** [sqlite3_reset()] in order to find the underlying cause of the problem. |
| 2198 | ** With the "v2" prepare interfaces, the underlying reason for the error is |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2199 | ** returned immediately. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2200 | ** </li> |
| 2201 | ** </ol> |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2202 | ** |
| 2203 | ** INVARIANTS: |
| 2204 | ** |
| 2205 | ** {F13011} The [sqlite3_prepare(db,zSql,...)] and |
| 2206 | ** [sqlite3_prepare_v2(db,zSql,...)] interfaces interpret the |
| 2207 | ** text in their zSql parameter as UTF-8. |
| 2208 | ** |
| 2209 | ** {F13012} The [sqlite3_prepare16(db,zSql,...)] and |
| 2210 | ** [sqlite3_prepare16_v2(db,zSql,...)] interfaces interpret the |
| 2211 | ** text in their zSql parameter as UTF-16 in the native byte order. |
| 2212 | ** |
| 2213 | ** {F13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] |
| 2214 | ** and its variants is less than zero, then SQL text is |
| 2215 | ** read from zSql is read up to the first zero terminator. |
| 2216 | ** |
| 2217 | ** {F13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] |
| 2218 | ** and its variants is non-negative, then nBytes bytes |
| 2219 | ** SQL text is read from zSql. |
| 2220 | ** |
| 2221 | ** {F13015} In [sqlite3_prepare_v2(db,zSql,N,P,pzTail)] and its variants |
| 2222 | ** if the zSql input text contains more than one SQL statement |
| 2223 | ** and pzTail is not NULL, then *pzTail is made to point to the |
| 2224 | ** first byte past the end of the first SQL statement in zSql. |
| 2225 | ** <todo>What does *pzTail point to if there is one statement?</todo> |
| 2226 | ** |
| 2227 | ** {F13016} A successful call to [sqlite3_prepare_v2(db,zSql,N,ppStmt,...)] |
| 2228 | ** or one of its variants writes into *ppStmt a pointer to a new |
| 2229 | ** [prepared statement] or a pointer to NULL |
| 2230 | ** if zSql contains nothing other than whitespace or comments. |
| 2231 | ** |
| 2232 | ** {F13019} The [sqlite3_prepare_v2()] interface and its variants return |
| 2233 | ** [SQLITE_OK] or an appropriate [error code] upon failure. |
drh | 17eaae7 | 2008-03-03 18:47:28 +0000 | [diff] [blame] | 2234 | ** |
| 2235 | ** {F13021} Before [sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail)] or its |
| 2236 | ** variants returns an error (any value other than [SQLITE_OK]) |
| 2237 | ** it first sets *ppStmt to NULL. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2238 | */ |
| 2239 | int sqlite3_prepare( |
| 2240 | sqlite3 *db, /* Database handle */ |
| 2241 | const char *zSql, /* SQL statement, UTF-8 encoded */ |
drh | 21f0672 | 2007-07-19 12:41:39 +0000 | [diff] [blame] | 2242 | int nByte, /* Maximum length of zSql in bytes. */ |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2243 | sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
| 2244 | const char **pzTail /* OUT: Pointer to unused portion of zSql */ |
| 2245 | ); |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2246 | int sqlite3_prepare_v2( |
| 2247 | sqlite3 *db, /* Database handle */ |
| 2248 | const char *zSql, /* SQL statement, UTF-8 encoded */ |
drh | 21f0672 | 2007-07-19 12:41:39 +0000 | [diff] [blame] | 2249 | int nByte, /* Maximum length of zSql in bytes. */ |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2250 | sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
| 2251 | const char **pzTail /* OUT: Pointer to unused portion of zSql */ |
| 2252 | ); |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2253 | int sqlite3_prepare16( |
| 2254 | sqlite3 *db, /* Database handle */ |
| 2255 | const void *zSql, /* SQL statement, UTF-16 encoded */ |
drh | 21f0672 | 2007-07-19 12:41:39 +0000 | [diff] [blame] | 2256 | int nByte, /* Maximum length of zSql in bytes. */ |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2257 | sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
| 2258 | const void **pzTail /* OUT: Pointer to unused portion of zSql */ |
| 2259 | ); |
drh | b900aaf | 2006-11-09 00:24:53 +0000 | [diff] [blame] | 2260 | int sqlite3_prepare16_v2( |
| 2261 | sqlite3 *db, /* Database handle */ |
| 2262 | const void *zSql, /* SQL statement, UTF-16 encoded */ |
drh | 21f0672 | 2007-07-19 12:41:39 +0000 | [diff] [blame] | 2263 | int nByte, /* Maximum length of zSql in bytes. */ |
drh | b900aaf | 2006-11-09 00:24:53 +0000 | [diff] [blame] | 2264 | sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
| 2265 | const void **pzTail /* OUT: Pointer to unused portion of zSql */ |
| 2266 | ); |
| 2267 | |
| 2268 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2269 | ** CAPIREF: Retrieving Statement SQL {F13100} |
danielk1977 | d0e2a85 | 2007-11-14 06:48:48 +0000 | [diff] [blame] | 2270 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2271 | ** This intereface can be used to retrieve a saved copy of the original |
| 2272 | ** SQL text used to create a [prepared statement]. |
danielk1977 | d0e2a85 | 2007-11-14 06:48:48 +0000 | [diff] [blame] | 2273 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2274 | ** INVARIANTS: |
| 2275 | ** |
| 2276 | ** {F13101} If the [prepared statement] passed as |
| 2277 | ** the an argument to [sqlite3_sql()] was compiled |
| 2278 | ** compiled using either [sqlite3_prepare_v2()] or |
| 2279 | ** [sqlite3_prepare16_v2()], |
| 2280 | ** then [sqlite3_sql()] function returns a pointer to a |
| 2281 | ** zero-terminated string containing a UTF-8 rendering |
| 2282 | ** of the original SQL statement. |
| 2283 | ** |
| 2284 | ** {F13102} If the [prepared statement] passed as |
| 2285 | ** the an argument to [sqlite3_sql()] was compiled |
| 2286 | ** compiled using either [sqlite3_prepare()] or |
| 2287 | ** [sqlite3_prepare16()], |
| 2288 | ** then [sqlite3_sql()] function returns a NULL pointer. |
| 2289 | ** |
| 2290 | ** {F13103} The string returned by [sqlite3_sql(S)] is valid until the |
| 2291 | ** [prepared statement] S is deleted using [sqlite3_finalize(S)]. |
danielk1977 | d0e2a85 | 2007-11-14 06:48:48 +0000 | [diff] [blame] | 2292 | */ |
| 2293 | const char *sqlite3_sql(sqlite3_stmt *pStmt); |
| 2294 | |
| 2295 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2296 | ** CAPI3REF: Dynamically Typed Value Object {F15000} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2297 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2298 | ** SQLite uses the sqlite3_value object to represent all values |
| 2299 | ** that are or can be stored in a database table. |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 2300 | ** SQLite uses dynamic typing for the values it stores. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2301 | ** Values stored in sqlite3_value objects can be |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 2302 | ** be integers, floating point values, strings, BLOBs, or NULL. |
drh | f447950 | 2004-05-27 03:12:53 +0000 | [diff] [blame] | 2303 | */ |
drh | f447950 | 2004-05-27 03:12:53 +0000 | [diff] [blame] | 2304 | typedef struct Mem sqlite3_value; |
| 2305 | |
| 2306 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2307 | ** CAPI3REF: SQL Function Context Object {F16001} |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 2308 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2309 | ** The context in which an SQL function executes is stored in an |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2310 | ** sqlite3_context object. A pointer to an sqlite3_context |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 2311 | ** object is always first parameter to application-defined SQL functions. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2312 | */ |
| 2313 | typedef struct sqlite3_context sqlite3_context; |
| 2314 | |
| 2315 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2316 | ** CAPI3REF: Binding Values To Prepared Statements {F13500} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2317 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2318 | ** In the SQL strings input to [sqlite3_prepare_v2()] and its |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 2319 | ** variants, literals may be replace by a parameter in one |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2320 | ** of these forms: |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2321 | ** |
| 2322 | ** <ul> |
| 2323 | ** <li> ? |
| 2324 | ** <li> ?NNN |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2325 | ** <li> :VVV |
| 2326 | ** <li> @VVV |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2327 | ** <li> $VVV |
| 2328 | ** </ul> |
| 2329 | ** |
| 2330 | ** In the parameter forms shown above NNN is an integer literal, |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2331 | ** VVV alpha-numeric parameter name. |
| 2332 | ** The values of these parameters (also called "host parameter names" |
| 2333 | ** or "SQL parameters") |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2334 | ** can be set using the sqlite3_bind_*() routines defined here. |
| 2335 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2336 | ** The first argument to the sqlite3_bind_*() routines always |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2337 | ** is a pointer to the [sqlite3_stmt] object returned from |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2338 | ** [sqlite3_prepare_v2()] or its variants. The second |
| 2339 | ** argument is the index of the parameter to be set. The |
| 2340 | ** first parameter has an index of 1. When the same named |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2341 | ** parameter is used more than once, second and subsequent |
| 2342 | ** occurrences have the same index as the first occurrence. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2343 | ** The index for named parameters can be looked up using the |
| 2344 | ** [sqlite3_bind_parameter_name()] API if desired. The index |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 2345 | ** for "?NNN" parameters is the value of NNN. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2346 | ** The NNN value must be between 1 and the compile-time |
| 2347 | ** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999). |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2348 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2349 | ** The third argument is the value to bind to the parameter. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2350 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2351 | ** In those |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2352 | ** routines that have a fourth argument, its value is the number of bytes |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2353 | ** in the parameter. To be clear: the value is the number of <u>bytes</u> |
| 2354 | ** in the value, not the number of characters. The number |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2355 | ** of bytes does not include the zero-terminator at the end of strings. |
| 2356 | ** If the fourth parameter is negative, the length of the string is |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2357 | ** number of bytes up to the first zero terminator. |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 2358 | ** |
drh | 930cc58 | 2007-03-28 13:07:40 +0000 | [diff] [blame] | 2359 | ** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and |
drh | 900dfba | 2004-07-21 15:21:36 +0000 | [diff] [blame] | 2360 | ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2361 | ** string after SQLite has finished with it. If the fifth argument is |
| 2362 | ** the special value [SQLITE_STATIC], then SQLite assumes that the |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2363 | ** information is in static, unmanaged space and does not need to be freed. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2364 | ** If the fifth argument has the value [SQLITE_TRANSIENT], then |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2365 | ** SQLite makes its own private copy of the data immediately, before |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2366 | ** the sqlite3_bind_*() routine returns. |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 2367 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2368 | ** The sqlite3_bind_zeroblob() routine binds a BLOB of length N that |
| 2369 | ** is filled with zeros. A zeroblob uses a fixed amount of memory |
| 2370 | ** (just an integer to hold it size) while it is being processed. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2371 | ** Zeroblobs are intended to serve as place-holders for BLOBs whose |
| 2372 | ** content is later written using |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2373 | ** [sqlite3_blob_open | increment BLOB I/O] routines. A negative |
| 2374 | ** value for the zeroblob results in a zero-length BLOB. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2375 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2376 | ** The sqlite3_bind_*() routines must be called after |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2377 | ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2378 | ** before [sqlite3_step()]. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2379 | ** Bindings are not cleared by the [sqlite3_reset()] routine. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2380 | ** Unbound parameters are interpreted as NULL. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2381 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2382 | ** These routines return [SQLITE_OK] on success or an error code if |
| 2383 | ** anything goes wrong. [SQLITE_RANGE] is returned if the parameter |
| 2384 | ** index is out of range. [SQLITE_NOMEM] is returned if malloc fails. |
| 2385 | ** [SQLITE_MISUSE] might be returned if these routines are called on a |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2386 | ** virtual machine that is the wrong state or which has already been finalized. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2387 | ** Detection of misuse is unreliable. Applications should not depend |
| 2388 | ** on SQLITE_MISUSE returns. SQLITE_MISUSE is intended to indicate a |
| 2389 | ** a logic error in the application. Future versions of SQLite might |
| 2390 | ** panic rather than return SQLITE_MISUSE. |
| 2391 | ** |
| 2392 | ** See also: [sqlite3_bind_parameter_count()], |
| 2393 | ** [sqlite3_bind_parameter_name()], and |
| 2394 | ** [sqlite3_bind_parameter_index()]. |
| 2395 | ** |
| 2396 | ** INVARIANTS: |
| 2397 | ** |
| 2398 | ** {F13506} The [sqlite3_prepare | SQL statement compiler] recognizes |
| 2399 | ** tokens of the forms "?", "?NNN", "$VVV", ":VVV", and "@VVV" |
| 2400 | ** as SQL parameters, where NNN is any sequence of one or more |
| 2401 | ** digits and where VVV is any sequence of one or more |
| 2402 | ** alphanumeric characters or "::" optionally followed by |
| 2403 | ** a string containing no spaces and contained within parentheses. |
| 2404 | ** |
| 2405 | ** {F13509} The initial value of an SQL parameter is NULL. |
| 2406 | ** |
| 2407 | ** {F13512} The index of an "?" SQL parameter is one larger than the |
| 2408 | ** largest index of SQL parameter to the left, or 1 if |
| 2409 | ** the "?" is the leftmost SQL parameter. |
| 2410 | ** |
| 2411 | ** {F13515} The index of an "?NNN" SQL parameter is the integer NNN. |
| 2412 | ** |
| 2413 | ** {F13518} The index of an ":VVV", "$VVV", or "@VVV" SQL parameter is |
| 2414 | ** the same as the index of leftmost occurances of the same |
| 2415 | ** parameter, or one more than the largest index over all |
| 2416 | ** parameters to the left if this is the first occurrance |
| 2417 | ** of this parameter, or 1 if this is the leftmost parameter. |
| 2418 | ** |
| 2419 | ** {F13521} The [sqlite3_prepare | SQL statement compiler] fail with |
| 2420 | ** an [SQLITE_RANGE] error if the index of an SQL parameter |
| 2421 | ** is less than 1 or greater than SQLITE_MAX_VARIABLE_NUMBER. |
| 2422 | ** |
| 2423 | ** {F13524} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,V,...)] |
| 2424 | ** associate the value V with all SQL parameters having an |
| 2425 | ** index of N in the [prepared statement] S. |
| 2426 | ** |
| 2427 | ** {F13527} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,...)] |
| 2428 | ** override prior calls with the same values of S and N. |
| 2429 | ** |
| 2430 | ** {F13530} Bindings established by [sqlite3_bind_text | sqlite3_bind(S,...)] |
| 2431 | ** persist across calls to [sqlite3_reset(S)]. |
| 2432 | ** |
| 2433 | ** {F13533} In calls to [sqlite3_bind_blob(S,N,V,L,D)], |
| 2434 | ** [sqlite3_bind_text(S,N,V,L,D)], or |
| 2435 | ** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds the first L |
| 2436 | ** bytes of the blob or string pointed to by V, when L |
| 2437 | ** is non-negative. |
| 2438 | ** |
| 2439 | ** {F13536} In calls to [sqlite3_bind_text(S,N,V,L,D)] or |
| 2440 | ** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds characters |
| 2441 | ** from V through the first zero character when L is negative. |
| 2442 | ** |
| 2443 | ** {F13539} In calls to [sqlite3_bind_blob(S,N,V,L,D)], |
| 2444 | ** [sqlite3_bind_text(S,N,V,L,D)], or |
| 2445 | ** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special |
| 2446 | ** constant [SQLITE_STATIC], SQLite assumes that the value V |
| 2447 | ** is held in static unmanaged space that will not change |
| 2448 | ** during the lifetime of the binding. |
| 2449 | ** |
| 2450 | ** {F13542} In calls to [sqlite3_bind_blob(S,N,V,L,D)], |
| 2451 | ** [sqlite3_bind_text(S,N,V,L,D)], or |
| 2452 | ** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special |
| 2453 | ** constant [SQLITE_TRANSIENT], the routine makes a |
| 2454 | ** private copy of V value before it returns. |
| 2455 | ** |
| 2456 | ** {F13545} In calls to [sqlite3_bind_blob(S,N,V,L,D)], |
| 2457 | ** [sqlite3_bind_text(S,N,V,L,D)], or |
| 2458 | ** [sqlite3_bind_text16(S,N,V,L,D)] when D is a pointer to |
| 2459 | ** a function, SQLite invokes that function to destroy the |
| 2460 | ** V value after it has finished using the V value. |
| 2461 | ** |
| 2462 | ** {F13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound |
| 2463 | ** is a blob of L bytes, or a zero-length blob if L is negative. |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 2464 | */ |
danielk1977 | d812336 | 2004-06-12 09:25:12 +0000 | [diff] [blame] | 2465 | int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); |
drh | f447950 | 2004-05-27 03:12:53 +0000 | [diff] [blame] | 2466 | int sqlite3_bind_double(sqlite3_stmt*, int, double); |
| 2467 | int sqlite3_bind_int(sqlite3_stmt*, int, int); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 2468 | int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); |
drh | f447950 | 2004-05-27 03:12:53 +0000 | [diff] [blame] | 2469 | int sqlite3_bind_null(sqlite3_stmt*, int); |
danielk1977 | d812336 | 2004-06-12 09:25:12 +0000 | [diff] [blame] | 2470 | int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); |
| 2471 | int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); |
drh | f447950 | 2004-05-27 03:12:53 +0000 | [diff] [blame] | 2472 | int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); |
drh | b026e05 | 2007-05-02 01:34:31 +0000 | [diff] [blame] | 2473 | int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 2474 | |
| 2475 | /* |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2476 | ** CAPI3REF: Number Of SQL Parameters {F13600} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2477 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2478 | ** This routine can be used to find the number of SQL parameters |
| 2479 | ** in a prepared statement. SQL parameters are tokens of the |
| 2480 | ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as |
| 2481 | ** place-holders for values that are [sqlite3_bind_blob | bound] |
| 2482 | ** to the parameters at a later time. |
drh | 605264d | 2007-08-21 15:13:19 +0000 | [diff] [blame] | 2483 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2484 | ** This routine actually returns the index of the largest parameter. |
| 2485 | ** For all forms except ?NNN, this will correspond to the number of |
| 2486 | ** unique parameters. If parameters of the ?NNN are used, there may |
| 2487 | ** be gaps in the list. |
| 2488 | ** |
| 2489 | ** See also: [sqlite3_bind_blob|sqlite3_bind()], |
| 2490 | ** [sqlite3_bind_parameter_name()], and |
| 2491 | ** [sqlite3_bind_parameter_index()]. |
| 2492 | ** |
| 2493 | ** INVARIANTS: |
| 2494 | ** |
| 2495 | ** {F13601} The [sqlite3_bind_parameter_count(S)] interface returns |
| 2496 | ** the largest index of all SQL parameters in the |
| 2497 | ** [prepared statement] S, or 0 if S |
| 2498 | ** contains no SQL parameters. |
drh | 75f6a03 | 2004-07-15 14:15:00 +0000 | [diff] [blame] | 2499 | */ |
| 2500 | int sqlite3_bind_parameter_count(sqlite3_stmt*); |
| 2501 | |
| 2502 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2503 | ** CAPI3REF: Name Of A Host Parameter {F13620} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2504 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2505 | ** This routine returns a pointer to the name of the n-th |
| 2506 | ** SQL parameter in a [prepared statement]. |
| 2507 | ** SQL parameters of the form ":AAA" or "@AAA" or "$AAA" have a name |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2508 | ** which is the string ":AAA" or "@AAA" or "$VVV". |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2509 | ** In other words, the initial ":" or "$" or "@" |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2510 | ** is included as part of the name. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2511 | ** Parameters of the form "?" or "?NNN" have no name. |
| 2512 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2513 | ** The first host parameter has an index of 1, not 0. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2514 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2515 | ** If the value n is out of range or if the n-th parameter is |
| 2516 | ** nameless, then NULL is returned. The returned string is |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2517 | ** always in the UTF-8 encoding even if the named parameter was |
| 2518 | ** originally specified as UTF-16 in [sqlite3_prepare16()] or |
| 2519 | ** [sqlite3_prepare16_v2()]. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2520 | ** |
| 2521 | ** See also: [sqlite3_bind_blob|sqlite3_bind()], |
| 2522 | ** [sqlite3_bind_parameter_count()], and |
| 2523 | ** [sqlite3_bind_parameter_index()]. |
| 2524 | ** |
| 2525 | ** INVARIANTS: |
| 2526 | ** |
| 2527 | ** {F13621} The [sqlite3_bind_parameter_name(S,N)] interface returns |
| 2528 | ** a UTF-8 rendering of the name of the SQL parameter in |
| 2529 | ** [prepared statement] S having index N, or |
| 2530 | ** NULL if there is no SQL parameter with index N or if the |
| 2531 | ** parameter with index N is an anonymous parameter "?" or |
| 2532 | ** a numbered parameter "?NNN". |
drh | 895d747 | 2004-08-20 16:02:39 +0000 | [diff] [blame] | 2533 | */ |
| 2534 | const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); |
| 2535 | |
| 2536 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2537 | ** CAPI3REF: Index Of A Parameter With A Given Name {F13640} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2538 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2539 | ** Return the index of an SQL parameter given its name. The |
| 2540 | ** index value returned is suitable for use as the second |
| 2541 | ** parameter to [sqlite3_bind_blob|sqlite3_bind()]. A zero |
| 2542 | ** is returned if no matching parameter is found. The parameter |
| 2543 | ** name must be given in UTF-8 even if the original statement |
| 2544 | ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()]. |
| 2545 | ** |
| 2546 | ** See also: [sqlite3_bind_blob|sqlite3_bind()], |
| 2547 | ** [sqlite3_bind_parameter_count()], and |
| 2548 | ** [sqlite3_bind_parameter_index()]. |
| 2549 | ** |
| 2550 | ** INVARIANTS: |
| 2551 | ** |
| 2552 | ** {F13641} The [sqlite3_bind_parameter_index(S,N)] interface returns |
| 2553 | ** the index of SQL parameter in [prepared statement] |
| 2554 | ** S whose name matches the UTF-8 string N, or 0 if there is |
| 2555 | ** no match. |
drh | fa6bc00 | 2004-09-07 16:19:52 +0000 | [diff] [blame] | 2556 | */ |
| 2557 | int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); |
| 2558 | |
| 2559 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2560 | ** CAPI3REF: Reset All Bindings On A Prepared Statement {F13660} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2561 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2562 | ** Contrary to the intuition of many, [sqlite3_reset()] does not |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2563 | ** reset the [sqlite3_bind_blob | bindings] on a |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2564 | ** [prepared statement]. Use this routine to |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2565 | ** reset all host parameters to NULL. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2566 | ** |
| 2567 | ** INVARIANTS: |
| 2568 | ** |
| 2569 | ** {F13661} The [sqlite3_clear_bindings(S)] interface resets all |
| 2570 | ** SQL parameter bindings in [prepared statement] S |
| 2571 | ** back to NULL. |
danielk1977 | 600dd0b | 2005-01-20 01:14:23 +0000 | [diff] [blame] | 2572 | */ |
| 2573 | int sqlite3_clear_bindings(sqlite3_stmt*); |
| 2574 | |
| 2575 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2576 | ** CAPI3REF: Number Of Columns In A Result Set {F13710} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2577 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2578 | ** Return the number of columns in the result set returned by the |
| 2579 | ** [prepared statement]. This routine returns 0 |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2580 | ** if pStmt is an SQL statement that does not return data (for |
| 2581 | ** example an UPDATE). |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2582 | ** |
| 2583 | ** INVARIANTS: |
| 2584 | ** |
| 2585 | ** {F13711} The [sqlite3_column_count(S)] interface returns the number of |
| 2586 | ** columns in the result set generated by the |
| 2587 | ** [prepared statement] S, or 0 if S does not generate |
| 2588 | ** a result set. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2589 | */ |
| 2590 | int sqlite3_column_count(sqlite3_stmt *pStmt); |
| 2591 | |
| 2592 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2593 | ** CAPI3REF: Column Names In A Result Set {F13720} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2594 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2595 | ** These routines return the name assigned to a particular column |
| 2596 | ** in the result set of a SELECT statement. The sqlite3_column_name() |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 2597 | ** interface returns a pointer to a zero-terminated UTF8 string |
| 2598 | ** and sqlite3_column_name16() returns a pointer to a zero-terminated |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2599 | ** UTF16 string. The first parameter is the |
| 2600 | ** [prepared statement] that implements the SELECT statement. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2601 | ** The second parameter is the column number. The left-most column is |
| 2602 | ** number 0. |
| 2603 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2604 | ** The returned string pointer is valid until either the |
| 2605 | ** [prepared statement] is destroyed by [sqlite3_finalize()] |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2606 | ** or until the next call sqlite3_column_name() or sqlite3_column_name16() |
| 2607 | ** on the same column. |
drh | 4a50aac | 2007-08-23 02:47:53 +0000 | [diff] [blame] | 2608 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2609 | ** If sqlite3_malloc() fails during the processing of either routine |
drh | 4a50aac | 2007-08-23 02:47:53 +0000 | [diff] [blame] | 2610 | ** (for example during a conversion from UTF-8 to UTF-16) then a |
| 2611 | ** NULL pointer is returned. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2612 | ** |
| 2613 | ** The name of a result column is the value of the "AS" clause for |
| 2614 | ** that column, if there is an AS clause. If there is no AS clause |
| 2615 | ** then the name of the column is unspecified and may change from |
| 2616 | ** one release of SQLite to the next. |
| 2617 | ** |
| 2618 | ** INVARIANTS: |
| 2619 | ** |
| 2620 | ** {F13721} A successful invocation of the [sqlite3_column_name(S,N)] |
| 2621 | ** interface returns the name |
| 2622 | ** of the Nth column (where 0 is the left-most column) for the |
| 2623 | ** result set of [prepared statement] S as a |
| 2624 | ** zero-terminated UTF-8 string. |
| 2625 | ** |
| 2626 | ** {F13723} A successful invocation of the [sqlite3_column_name16(S,N)] |
| 2627 | ** interface returns the name |
| 2628 | ** of the Nth column (where 0 is the left-most column) for the |
| 2629 | ** result set of [prepared statement] S as a |
| 2630 | ** zero-terminated UTF-16 string in the native byte order. |
| 2631 | ** |
| 2632 | ** {F13724} The [sqlite3_column_name()] and [sqlite3_column_name16()] |
| 2633 | ** interfaces return a NULL pointer if they are unable to |
| 2634 | ** allocate memory memory to hold there normal return strings. |
| 2635 | ** |
| 2636 | ** {F13725} If the N parameter to [sqlite3_column_name(S,N)] or |
| 2637 | ** [sqlite3_column_name16(S,N)] is out of range, then the |
| 2638 | ** interfaces returns a NULL pointer. |
| 2639 | ** |
| 2640 | ** {F13726} The strings returned by [sqlite3_column_name(S,N)] and |
| 2641 | ** [sqlite3_column_name16(S,N)] are valid until the next |
| 2642 | ** call to either routine with the same S and N parameters |
| 2643 | ** or until [sqlite3_finalize(S)] is called. |
| 2644 | ** |
| 2645 | ** {F13727} When a result column of a [SELECT] statement contains |
| 2646 | ** an AS clause, the name of that column is the indentifier |
| 2647 | ** to the right of the AS keyword. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2648 | */ |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2649 | const char *sqlite3_column_name(sqlite3_stmt*, int N); |
| 2650 | const void *sqlite3_column_name16(sqlite3_stmt*, int N); |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2651 | |
| 2652 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2653 | ** CAPI3REF: Source Of Data In A Query Result {F13740} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2654 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2655 | ** These routines provide a means to determine what column of what |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2656 | ** table in which database a result of a SELECT statement comes from. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2657 | ** The name of the database or table or column can be returned as |
| 2658 | ** either a UTF8 or UTF16 string. The _database_ routines return |
drh | bf2564f | 2007-06-21 15:25:05 +0000 | [diff] [blame] | 2659 | ** the database name, the _table_ routines return the table name, and |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2660 | ** the origin_ routines return the column name. |
drh | bf2564f | 2007-06-21 15:25:05 +0000 | [diff] [blame] | 2661 | ** The returned string is valid until |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2662 | ** the [prepared statement] is destroyed using |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2663 | ** [sqlite3_finalize()] or until the same information is requested |
drh | bf2564f | 2007-06-21 15:25:05 +0000 | [diff] [blame] | 2664 | ** again in a different encoding. |
| 2665 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2666 | ** The names returned are the original un-aliased names of the |
drh | bf2564f | 2007-06-21 15:25:05 +0000 | [diff] [blame] | 2667 | ** database, table, and column. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2668 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2669 | ** The first argument to the following calls is a [prepared statement]. |
| 2670 | ** These functions return information about the Nth column returned by |
danielk1977 | 955de52 | 2006-02-10 02:27:42 +0000 | [diff] [blame] | 2671 | ** the statement, where N is the second function argument. |
| 2672 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2673 | ** If the Nth column returned by the statement is an expression |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2674 | ** or subquery and is not a column value, then all of these functions |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2675 | ** return NULL. These routine might also return NULL if a memory |
| 2676 | ** allocation error occurs. Otherwise, they return the |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2677 | ** name of the attached database, table and column that query result |
| 2678 | ** column was extracted from. |
danielk1977 | 955de52 | 2006-02-10 02:27:42 +0000 | [diff] [blame] | 2679 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2680 | ** As with all other SQLite APIs, those postfixed with "16" return |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2681 | ** UTF-16 encoded strings, the other functions return UTF-8. {END} |
danielk1977 | 4b1ae99 | 2006-02-10 03:06:10 +0000 | [diff] [blame] | 2682 | ** |
| 2683 | ** These APIs are only available if the library was compiled with the |
| 2684 | ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. |
drh | 32bc3f6 | 2007-08-21 20:25:39 +0000 | [diff] [blame] | 2685 | ** |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2686 | ** {U13751} |
drh | 32bc3f6 | 2007-08-21 20:25:39 +0000 | [diff] [blame] | 2687 | ** If two or more threads call one or more of these routines against the same |
| 2688 | ** prepared statement and column at the same time then the results are |
| 2689 | ** undefined. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2690 | ** |
| 2691 | ** INVARIANTS: |
| 2692 | ** |
| 2693 | ** {F13741} The [sqlite3_column_database_name(S,N)] interface returns either |
| 2694 | ** the UTF-8 zero-terminated name of the database from which the |
| 2695 | ** Nth result column of [prepared statement] S |
| 2696 | ** is extracted, or NULL if the the Nth column of S is a |
| 2697 | ** general expression or if unable to allocate memory |
| 2698 | ** to store the name. |
| 2699 | ** |
| 2700 | ** {F13742} The [sqlite3_column_database_name16(S,N)] interface returns either |
| 2701 | ** the UTF-16 native byte order |
| 2702 | ** zero-terminated name of the database from which the |
| 2703 | ** Nth result column of [prepared statement] S |
| 2704 | ** is extracted, or NULL if the the Nth column of S is a |
| 2705 | ** general expression or if unable to allocate memory |
| 2706 | ** to store the name. |
| 2707 | ** |
| 2708 | ** {F13743} The [sqlite3_column_table_name(S,N)] interface returns either |
| 2709 | ** the UTF-8 zero-terminated name of the table from which the |
| 2710 | ** Nth result column of [prepared statement] S |
| 2711 | ** is extracted, or NULL if the the Nth column of S is a |
| 2712 | ** general expression or if unable to allocate memory |
| 2713 | ** to store the name. |
| 2714 | ** |
| 2715 | ** {F13744} The [sqlite3_column_table_name16(S,N)] interface returns either |
| 2716 | ** the UTF-16 native byte order |
| 2717 | ** zero-terminated name of the table from which the |
| 2718 | ** Nth result column of [prepared statement] S |
| 2719 | ** is extracted, or NULL if the the Nth column of S is a |
| 2720 | ** general expression or if unable to allocate memory |
| 2721 | ** to store the name. |
| 2722 | ** |
| 2723 | ** {F13745} The [sqlite3_column_origin_name(S,N)] interface returns either |
| 2724 | ** the UTF-8 zero-terminated name of the table column from which the |
| 2725 | ** Nth result column of [prepared statement] S |
| 2726 | ** is extracted, or NULL if the the Nth column of S is a |
| 2727 | ** general expression or if unable to allocate memory |
| 2728 | ** to store the name. |
| 2729 | ** |
| 2730 | ** {F13746} The [sqlite3_column_origin_name16(S,N)] interface returns either |
| 2731 | ** the UTF-16 native byte order |
| 2732 | ** zero-terminated name of the table column from which the |
| 2733 | ** Nth result column of [prepared statement] S |
| 2734 | ** is extracted, or NULL if the the Nth column of S is a |
| 2735 | ** general expression or if unable to allocate memory |
| 2736 | ** to store the name. |
| 2737 | ** |
| 2738 | ** {F13748} The return values from |
| 2739 | ** [sqlite3_column_database_name|column metadata interfaces] |
| 2740 | ** are valid |
| 2741 | ** for the lifetime of the [prepared statement] |
| 2742 | ** or until the encoding is changed by another metadata |
| 2743 | ** interface call for the same prepared statement and column. |
| 2744 | ** |
| 2745 | ** LIMITATIONS: |
| 2746 | ** |
| 2747 | ** {U13751} If two or more threads call one or more |
| 2748 | ** [sqlite3_column_database_name|column metadata interfaces] |
| 2749 | ** the same [prepared statement] and result column |
| 2750 | ** at the same time then the results are undefined. |
danielk1977 | 955de52 | 2006-02-10 02:27:42 +0000 | [diff] [blame] | 2751 | */ |
| 2752 | const char *sqlite3_column_database_name(sqlite3_stmt*,int); |
| 2753 | const void *sqlite3_column_database_name16(sqlite3_stmt*,int); |
| 2754 | const char *sqlite3_column_table_name(sqlite3_stmt*,int); |
| 2755 | const void *sqlite3_column_table_name16(sqlite3_stmt*,int); |
| 2756 | const char *sqlite3_column_origin_name(sqlite3_stmt*,int); |
| 2757 | const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); |
| 2758 | |
| 2759 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2760 | ** CAPI3REF: Declared Datatype Of A Query Result {F13760} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2761 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2762 | ** The first parameter is a [prepared statement]. |
| 2763 | ** If this statement is a SELECT statement and the Nth column of the |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 2764 | ** returned result set of that SELECT is a table column (not an |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2765 | ** expression or subquery) then the declared type of the table |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2766 | ** column is returned. If the Nth column of the result set is an |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2767 | ** expression or subquery, then a NULL pointer is returned. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2768 | ** The returned string is always UTF-8 encoded. {END} |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2769 | ** For example, in the database schema: |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2770 | ** |
| 2771 | ** CREATE TABLE t1(c1 VARIANT); |
| 2772 | ** |
| 2773 | ** And the following statement compiled: |
| 2774 | ** |
danielk1977 | 955de52 | 2006-02-10 02:27:42 +0000 | [diff] [blame] | 2775 | ** SELECT c1 + 1, c1 FROM t1; |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2776 | ** |
| 2777 | ** Then this routine would return the string "VARIANT" for the second |
| 2778 | ** result column (i==1), and a NULL pointer for the first result column |
| 2779 | ** (i==0). |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2780 | ** |
| 2781 | ** SQLite uses dynamic run-time typing. So just because a column |
| 2782 | ** is declared to contain a particular type does not mean that the |
| 2783 | ** data stored in that column is of the declared type. SQLite is |
| 2784 | ** strongly typed, but the typing is dynamic not static. Type |
| 2785 | ** is associated with individual values, not with the containers |
| 2786 | ** used to hold those values. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2787 | ** |
| 2788 | ** INVARIANTS: |
| 2789 | ** |
| 2790 | ** {F13761} A successful call to [sqlite3_column_decltype(S,N)] |
| 2791 | ** returns a zero-terminated UTF-8 string containing the |
| 2792 | ** the declared datatype of the table column that appears |
| 2793 | ** as the Nth column (numbered from 0) of the result set to the |
| 2794 | ** [prepared statement] S. |
| 2795 | ** |
| 2796 | ** {F13762} A successful call to [sqlite3_column_decltype16(S,N)] |
| 2797 | ** returns a zero-terminated UTF-16 native byte order string |
| 2798 | ** containing the declared datatype of the table column that appears |
| 2799 | ** as the Nth column (numbered from 0) of the result set to the |
| 2800 | ** [prepared statement] S. |
| 2801 | ** |
| 2802 | ** {F13763} If N is less than 0 or N is greater than or equal to |
| 2803 | ** the number of columns in [prepared statement] S |
| 2804 | ** or if the Nth column of S is an expression or subquery rather |
| 2805 | ** than a table column or if a memory allocation failure |
| 2806 | ** occurs during encoding conversions, then |
| 2807 | ** calls to [sqlite3_column_decltype(S,N)] or |
| 2808 | ** [sqlite3_column_decltype16(S,N)] return NULL. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2809 | */ |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2810 | const char *sqlite3_column_decltype(sqlite3_stmt*,int); |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 2811 | const void *sqlite3_column_decltype16(sqlite3_stmt*,int); |
| 2812 | |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 2813 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2814 | ** CAPI3REF: Evaluate An SQL Statement {F13200} |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 2815 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2816 | ** After an [prepared statement] has been prepared with a call |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2817 | ** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of |
| 2818 | ** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], |
| 2819 | ** then this function must be called one or more times to evaluate the |
| 2820 | ** statement. |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 2821 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2822 | ** The details of the behavior of this sqlite3_step() interface depend |
| 2823 | ** on whether the statement was prepared using the newer "v2" interface |
| 2824 | ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy |
| 2825 | ** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the |
| 2826 | ** new "v2" interface is recommended for new applications but the legacy |
| 2827 | ** interface will continue to be supported. |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 2828 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2829 | ** In the lagacy interface, the return value will be either [SQLITE_BUSY], |
| 2830 | ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE]. |
| 2831 | ** With the "v2" interface, any of the other [SQLITE_OK | result code] |
| 2832 | ** or [SQLITE_IOERR_READ | extended result code] might be returned as |
| 2833 | ** well. |
| 2834 | ** |
| 2835 | ** [SQLITE_BUSY] means that the database engine was unable to acquire the |
| 2836 | ** database locks it needs to do its job. If the statement is a COMMIT |
| 2837 | ** or occurs outside of an explicit transaction, then you can retry the |
| 2838 | ** statement. If the statement is not a COMMIT and occurs within a |
| 2839 | ** explicit transaction then you should rollback the transaction before |
| 2840 | ** continuing. |
| 2841 | ** |
| 2842 | ** [SQLITE_DONE] means that the statement has finished executing |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 2843 | ** successfully. sqlite3_step() should not be called again on this virtual |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2844 | ** machine without first calling [sqlite3_reset()] to reset the virtual |
| 2845 | ** machine back to its initial state. |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 2846 | ** |
| 2847 | ** If the SQL statement being executed returns any data, then |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2848 | ** [SQLITE_ROW] is returned each time a new row of data is ready |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 2849 | ** for processing by the caller. The values may be accessed using |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2850 | ** the [sqlite3_column_int | column access functions]. |
| 2851 | ** sqlite3_step() is called again to retrieve the next row of data. |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 2852 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2853 | ** [SQLITE_ERROR] means that a run-time error (such as a constraint |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 2854 | ** violation) has occurred. sqlite3_step() should not be called again on |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2855 | ** the VM. More information may be found by calling [sqlite3_errmsg()]. |
| 2856 | ** With the legacy interface, a more specific error code (example: |
| 2857 | ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth) |
| 2858 | ** can be obtained by calling [sqlite3_reset()] on the |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2859 | ** [prepared statement]. In the "v2" interface, |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2860 | ** the more specific error code is returned directly by sqlite3_step(). |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 2861 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2862 | ** [SQLITE_MISUSE] means that the this routine was called inappropriately. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2863 | ** Perhaps it was called on a [prepared statement] that has |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2864 | ** already been [sqlite3_finalize | finalized] or on one that had |
| 2865 | ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could |
| 2866 | ** be the case that the same database connection is being used by two or |
| 2867 | ** more threads at the same moment in time. |
| 2868 | ** |
| 2869 | ** <b>Goofy Interface Alert:</b> |
| 2870 | ** In the legacy interface, |
| 2871 | ** the sqlite3_step() API always returns a generic error code, |
| 2872 | ** [SQLITE_ERROR], following any error other than [SQLITE_BUSY] |
| 2873 | ** and [SQLITE_MISUSE]. You must call [sqlite3_reset()] or |
| 2874 | ** [sqlite3_finalize()] in order to find one of the specific |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2875 | ** [error codes] that better describes the error. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2876 | ** We admit that this is a goofy design. The problem has been fixed |
| 2877 | ** with the "v2" interface. If you prepare all of your SQL statements |
| 2878 | ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead |
| 2879 | ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2880 | ** more specific [error codes] are returned directly |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2881 | ** by sqlite3_step(). The use of the "v2" interface is recommended. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2882 | ** |
| 2883 | ** INVARIANTS: |
| 2884 | ** |
| 2885 | ** {F13202} If [prepared statement] S is ready to be |
| 2886 | ** run, then [sqlite3_step(S)] advances that prepared statement |
| 2887 | ** until to completion or until it is ready to return another |
| 2888 | ** row of the result set or an interrupt or run-time error occurs. |
| 2889 | ** |
| 2890 | ** {F15304} When a call to [sqlite3_step(S)] causes the |
| 2891 | ** [prepared statement] S to run to completion, |
| 2892 | ** the function returns [SQLITE_DONE]. |
| 2893 | ** |
| 2894 | ** {F15306} When a call to [sqlite3_step(S)] stops because it is ready |
| 2895 | ** to return another row of the result set, it returns |
| 2896 | ** [SQLITE_ROW]. |
| 2897 | ** |
| 2898 | ** {F15308} If a call to [sqlite3_step(S)] encounters an |
| 2899 | ** [sqlite3_interrupt|interrupt] or a run-time error, |
| 2900 | ** it returns an appropraite error code that is not one of |
| 2901 | ** [SQLITE_OK], [SQLITE_ROW], or [SQLITE_DONE]. |
| 2902 | ** |
| 2903 | ** {F15310} If an [sqlite3_interrupt|interrupt] or run-time error |
| 2904 | ** occurs during a call to [sqlite3_step(S)] |
| 2905 | ** for a [prepared statement] S created using |
| 2906 | ** legacy interfaces [sqlite3_prepare()] or |
| 2907 | ** [sqlite3_prepare16()] then the function returns either |
| 2908 | ** [SQLITE_ERROR], [SQLITE_BUSY], or [SQLITE_MISUSE]. |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 2909 | */ |
danielk1977 | 17240fd | 2004-05-26 00:07:25 +0000 | [diff] [blame] | 2910 | int sqlite3_step(sqlite3_stmt*); |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 2911 | |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 2912 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2913 | ** CAPI3REF: Number of columns in a result set {F13770} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2914 | ** |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 2915 | ** Return the number of values in the current row of the result set. |
| 2916 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2917 | ** INVARIANTS: |
| 2918 | ** |
| 2919 | ** {F13771} After a call to [sqlite3_step(S)] that returns |
| 2920 | ** [SQLITE_ROW], the [sqlite3_data_count(S)] routine |
| 2921 | ** will return the same value as the |
| 2922 | ** [sqlite3_column_count(S)] function. |
| 2923 | ** |
| 2924 | ** {F13772} After [sqlite3_step(S)] has returned any value other than |
| 2925 | ** [SQLITE_ROW] or before [sqlite3_step(S)] has been |
| 2926 | ** called on the [prepared statement] for |
| 2927 | ** the first time since it was [sqlite3_prepare|prepared] |
| 2928 | ** or [sqlite3_reset|reset], the [sqlite3_data_count(S)] |
| 2929 | ** routine returns zero. |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 2930 | */ |
danielk1977 | 93d4675 | 2004-05-23 13:30:58 +0000 | [diff] [blame] | 2931 | int sqlite3_data_count(sqlite3_stmt *pStmt); |
danielk1977 | 4adee20 | 2004-05-08 08:23:19 +0000 | [diff] [blame] | 2932 | |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 2933 | /* |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 2934 | ** CAPI3REF: Fundamental Datatypes {F10265} |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2935 | ** KEYWORDS: SQLITE_TEXT |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2936 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 2937 | ** {F10266}Every value in SQLite has one of five fundamental datatypes: |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2938 | ** |
| 2939 | ** <ul> |
| 2940 | ** <li> 64-bit signed integer |
| 2941 | ** <li> 64-bit IEEE floating point number |
| 2942 | ** <li> string |
| 2943 | ** <li> BLOB |
| 2944 | ** <li> NULL |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2945 | ** </ul> {END} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2946 | ** |
| 2947 | ** These constants are codes for each of those types. |
| 2948 | ** |
| 2949 | ** Note that the SQLITE_TEXT constant was also used in SQLite version 2 |
| 2950 | ** for a completely different meaning. Software that links against both |
| 2951 | ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT not |
| 2952 | ** SQLITE_TEXT. |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 2953 | */ |
drh | 9c05483 | 2004-05-31 18:51:57 +0000 | [diff] [blame] | 2954 | #define SQLITE_INTEGER 1 |
| 2955 | #define SQLITE_FLOAT 2 |
drh | 9c05483 | 2004-05-31 18:51:57 +0000 | [diff] [blame] | 2956 | #define SQLITE_BLOB 4 |
| 2957 | #define SQLITE_NULL 5 |
drh | 1e284f4 | 2004-10-06 15:52:01 +0000 | [diff] [blame] | 2958 | #ifdef SQLITE_TEXT |
| 2959 | # undef SQLITE_TEXT |
| 2960 | #else |
| 2961 | # define SQLITE_TEXT 3 |
| 2962 | #endif |
| 2963 | #define SQLITE3_TEXT 3 |
| 2964 | |
| 2965 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 2966 | ** CAPI3REF: Results Values From A Query {F13800} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2967 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2968 | ** These routines form the "result set query" interface. |
| 2969 | ** |
drh | 32bc3f6 | 2007-08-21 20:25:39 +0000 | [diff] [blame] | 2970 | ** These routines return information about |
| 2971 | ** a single column of the current result row of a query. In every |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2972 | ** case the first argument is a pointer to the |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 2973 | ** [prepared statement] that is being |
drh | 32bc3f6 | 2007-08-21 20:25:39 +0000 | [diff] [blame] | 2974 | ** evaluated (the [sqlite3_stmt*] that was returned from |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2975 | ** [sqlite3_prepare_v2()] or one of its variants) and |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 2976 | ** the second argument is the index of the column for which information |
drh | 32bc3f6 | 2007-08-21 20:25:39 +0000 | [diff] [blame] | 2977 | ** should be returned. The left-most column of the result set |
| 2978 | ** has an index of 0. |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 2979 | ** |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 2980 | ** If the SQL statement is not currently point to a valid row, or if the |
drh | 32bc3f6 | 2007-08-21 20:25:39 +0000 | [diff] [blame] | 2981 | ** the column index is out of range, the result is undefined. |
| 2982 | ** These routines may only be called when the most recent call to |
| 2983 | ** [sqlite3_step()] has returned [SQLITE_ROW] and neither |
| 2984 | ** [sqlite3_reset()] nor [sqlite3_finalize()] has been call subsequently. |
| 2985 | ** If any of these routines are called after [sqlite3_reset()] or |
| 2986 | ** [sqlite3_finalize()] or after [sqlite3_step()] has returned |
| 2987 | ** something other than [SQLITE_ROW], the results are undefined. |
| 2988 | ** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()] |
| 2989 | ** are called from a different thread while any of these routines |
| 2990 | ** are pending, then the results are undefined. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 2991 | ** |
| 2992 | ** The sqlite3_column_type() routine returns |
| 2993 | ** [SQLITE_INTEGER | datatype code] for the initial data type |
| 2994 | ** of the result column. The returned value is one of [SQLITE_INTEGER], |
| 2995 | ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value |
| 2996 | ** returned by sqlite3_column_type() is only meaningful if no type |
| 2997 | ** conversions have occurred as described below. After a type conversion, |
| 2998 | ** the value returned by sqlite3_column_type() is undefined. Future |
| 2999 | ** versions of SQLite may change the behavior of sqlite3_column_type() |
| 3000 | ** following a type conversion. |
| 3001 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3002 | ** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() |
| 3003 | ** routine returns the number of bytes in that BLOB or string. |
| 3004 | ** If the result is a UTF-16 string, then sqlite3_column_bytes() converts |
| 3005 | ** the string to UTF-8 and then returns the number of bytes. |
| 3006 | ** If the result is a numeric value then sqlite3_column_bytes() uses |
| 3007 | ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns |
| 3008 | ** the number of bytes in that string. |
| 3009 | ** The value returned does not include the zero terminator at the end |
| 3010 | ** of the string. For clarity: the value returned is the number of |
| 3011 | ** bytes in the string, not the number of characters. |
| 3012 | ** |
drh | c0b3abb | 2007-09-04 12:18:41 +0000 | [diff] [blame] | 3013 | ** Strings returned by sqlite3_column_text() and sqlite3_column_text16(), |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 3014 | ** even empty strings, are always zero terminated. The return |
drh | c0b3abb | 2007-09-04 12:18:41 +0000 | [diff] [blame] | 3015 | ** value from sqlite3_column_blob() for a zero-length blob is an arbitrary |
| 3016 | ** pointer, possibly even a NULL pointer. |
| 3017 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3018 | ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes() |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 3019 | ** but leaves the result in UTF-16 in native byte order instead of UTF-8. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3020 | ** The zero terminator is not included in this count. |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 3021 | ** |
| 3022 | ** These routines attempt to convert the value where appropriate. For |
| 3023 | ** example, if the internal representation is FLOAT and a text result |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3024 | ** is requested, [sqlite3_snprintf()] is used internally to do the conversion |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 3025 | ** automatically. The following table details the conversions that |
| 3026 | ** are applied: |
| 3027 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3028 | ** <blockquote> |
| 3029 | ** <table border="1"> |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 3030 | ** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 3031 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3032 | ** <tr><td> NULL <td> INTEGER <td> Result is 0 |
| 3033 | ** <tr><td> NULL <td> FLOAT <td> Result is 0.0 |
| 3034 | ** <tr><td> NULL <td> TEXT <td> Result is NULL pointer |
| 3035 | ** <tr><td> NULL <td> BLOB <td> Result is NULL pointer |
| 3036 | ** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float |
| 3037 | ** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer |
| 3038 | ** <tr><td> INTEGER <td> BLOB <td> Same as for INTEGER->TEXT |
| 3039 | ** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer |
| 3040 | ** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float |
| 3041 | ** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT |
| 3042 | ** <tr><td> TEXT <td> INTEGER <td> Use atoi() |
| 3043 | ** <tr><td> TEXT <td> FLOAT <td> Use atof() |
| 3044 | ** <tr><td> TEXT <td> BLOB <td> No change |
| 3045 | ** <tr><td> BLOB <td> INTEGER <td> Convert to TEXT then use atoi() |
| 3046 | ** <tr><td> BLOB <td> FLOAT <td> Convert to TEXT then use atof() |
| 3047 | ** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed |
| 3048 | ** </table> |
| 3049 | ** </blockquote> |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 3050 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3051 | ** The table above makes reference to standard C library functions atoi() |
| 3052 | ** and atof(). SQLite does not really use these functions. It has its |
| 3053 | ** on equavalent internal routines. The atoi() and atof() names are |
| 3054 | ** used in the table for brevity and because they are familiar to most |
| 3055 | ** C programmers. |
| 3056 | ** |
| 3057 | ** Note that when type conversions occur, pointers returned by prior |
| 3058 | ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or |
| 3059 | ** sqlite3_column_text16() may be invalidated. |
| 3060 | ** Type conversions and pointer invalidations might occur |
| 3061 | ** in the following cases: |
| 3062 | ** |
| 3063 | ** <ul> |
| 3064 | ** <li><p> The initial content is a BLOB and sqlite3_column_text() |
| 3065 | ** or sqlite3_column_text16() is called. A zero-terminator might |
| 3066 | ** need to be added to the string.</p></li> |
| 3067 | ** |
| 3068 | ** <li><p> The initial content is UTF-8 text and sqlite3_column_bytes16() or |
| 3069 | ** sqlite3_column_text16() is called. The content must be converted |
| 3070 | ** to UTF-16.</p></li> |
| 3071 | ** |
| 3072 | ** <li><p> The initial content is UTF-16 text and sqlite3_column_bytes() or |
| 3073 | ** sqlite3_column_text() is called. The content must be converted |
| 3074 | ** to UTF-8.</p></li> |
| 3075 | ** </ul> |
| 3076 | ** |
| 3077 | ** Conversions between UTF-16be and UTF-16le are always done in place and do |
| 3078 | ** not invalidate a prior pointer, though of course the content of the buffer |
| 3079 | ** that the prior pointer points to will have been modified. Other kinds |
| 3080 | ** of conversion are done in place when it is possible, but sometime it is |
| 3081 | ** not possible and in those cases prior pointers are invalidated. |
| 3082 | ** |
| 3083 | ** The safest and easiest to remember policy is to invoke these routines |
| 3084 | ** in one of the following ways: |
| 3085 | ** |
| 3086 | ** <ul> |
| 3087 | ** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li> |
| 3088 | ** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li> |
| 3089 | ** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li> |
| 3090 | ** </ul> |
| 3091 | ** |
| 3092 | ** In other words, you should call sqlite3_column_text(), sqlite3_column_blob(), |
| 3093 | ** or sqlite3_column_text16() first to force the result into the desired |
| 3094 | ** format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to |
| 3095 | ** find the size of the result. Do not mix call to sqlite3_column_text() or |
| 3096 | ** sqlite3_column_blob() with calls to sqlite3_column_bytes16(). And do not |
| 3097 | ** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes(). |
drh | 32bc3f6 | 2007-08-21 20:25:39 +0000 | [diff] [blame] | 3098 | ** |
| 3099 | ** The pointers returned are valid until a type conversion occurs as |
| 3100 | ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or |
| 3101 | ** [sqlite3_finalize()] is called. The memory space used to hold strings |
| 3102 | ** and blobs is freed automatically. Do <b>not</b> pass the pointers returned |
drh | 79491ab | 2007-09-04 12:00:00 +0000 | [diff] [blame] | 3103 | ** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into |
drh | 32bc3f6 | 2007-08-21 20:25:39 +0000 | [diff] [blame] | 3104 | ** [sqlite3_free()]. |
drh | 4a50aac | 2007-08-23 02:47:53 +0000 | [diff] [blame] | 3105 | ** |
| 3106 | ** If a memory allocation error occurs during the evaluation of any |
| 3107 | ** of these routines, a default value is returned. The default value |
| 3108 | ** is either the integer 0, the floating point number 0.0, or a NULL |
| 3109 | ** pointer. Subsequent calls to [sqlite3_errcode()] will return |
| 3110 | ** [SQLITE_NOMEM]. |
drh | 21ac7f9 | 2008-01-31 12:26:49 +0000 | [diff] [blame] | 3111 | ** |
| 3112 | ** INVARIANTS: |
| 3113 | ** |
| 3114 | ** {F13803} The [sqlite3_column_blob(S,N)] interface converts the |
| 3115 | ** Nth column in the current row of the result set for |
drh | 414025d | 2008-01-31 16:36:40 +0000 | [diff] [blame] | 3116 | ** [prepared statement] S into a blob and then returns a |
drh | 21ac7f9 | 2008-01-31 12:26:49 +0000 | [diff] [blame] | 3117 | ** pointer to the converted value. |
| 3118 | ** |
| 3119 | ** {F13806} The [sqlite3_column_bytes(S,N)] interface returns the |
| 3120 | ** number of bytes in the blob or string (exclusive of the |
| 3121 | ** zero terminator on the string) that was returned by the |
| 3122 | ** most recent call to [sqlite3_column_blob(S,N)] or |
| 3123 | ** [sqlite3_column_text(S,N)]. |
| 3124 | ** |
| 3125 | ** {F13809} The [sqlite3_column_bytes16(S,N)] interface returns the |
| 3126 | ** number of bytes in the string (exclusive of the |
| 3127 | ** zero terminator on the string) that was returned by the |
| 3128 | ** most recent call to [sqlite3_column_text16(S,N)]. |
| 3129 | ** |
| 3130 | ** {F13812} The [sqlite3_column_double(S,N)] interface converts the |
| 3131 | ** Nth column in the current row of the result set for |
drh | 414025d | 2008-01-31 16:36:40 +0000 | [diff] [blame] | 3132 | ** [prepared statement] S into a floating point value and |
drh | 21ac7f9 | 2008-01-31 12:26:49 +0000 | [diff] [blame] | 3133 | ** returns a copy of that value. |
| 3134 | ** |
| 3135 | ** {F13815} The [sqlite3_column_int(S,N)] interface converts the |
| 3136 | ** Nth column in the current row of the result set for |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3137 | ** [prepared statement] S into a 64-bit signed integer and |
| 3138 | ** returns the lower 32 bits of that integer. |
drh | 21ac7f9 | 2008-01-31 12:26:49 +0000 | [diff] [blame] | 3139 | ** |
| 3140 | ** {F13818} The [sqlite3_column_int64(S,N)] interface converts the |
| 3141 | ** Nth column in the current row of the result set for |
drh | 414025d | 2008-01-31 16:36:40 +0000 | [diff] [blame] | 3142 | ** [prepared statement] S into a 64-bit signed integer and |
drh | 21ac7f9 | 2008-01-31 12:26:49 +0000 | [diff] [blame] | 3143 | ** returns a copy of that integer. |
| 3144 | ** |
| 3145 | ** {F13821} The [sqlite3_column_text(S,N)] interface converts the |
| 3146 | ** Nth column in the current row of the result set for |
drh | 414025d | 2008-01-31 16:36:40 +0000 | [diff] [blame] | 3147 | ** [prepared statement] S into a zero-terminated UTF-8 |
drh | 21ac7f9 | 2008-01-31 12:26:49 +0000 | [diff] [blame] | 3148 | ** string and returns a pointer to that string. |
| 3149 | ** |
| 3150 | ** {F13824} The [sqlite3_column_text16(S,N)] interface converts the |
| 3151 | ** Nth column in the current row of the result set for |
drh | 414025d | 2008-01-31 16:36:40 +0000 | [diff] [blame] | 3152 | ** [prepared statement] S into a zero-terminated 2-byte |
drh | 21ac7f9 | 2008-01-31 12:26:49 +0000 | [diff] [blame] | 3153 | ** aligned UTF-16 native byte order |
| 3154 | ** string and returns a pointer to that string. |
| 3155 | ** |
| 3156 | ** {F13827} The [sqlite3_column_type(S,N)] interface returns |
drh | 414025d | 2008-01-31 16:36:40 +0000 | [diff] [blame] | 3157 | ** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT], |
drh | 21ac7f9 | 2008-01-31 12:26:49 +0000 | [diff] [blame] | 3158 | ** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for |
| 3159 | ** the Nth column in the current row of the result set for |
drh | 414025d | 2008-01-31 16:36:40 +0000 | [diff] [blame] | 3160 | ** [prepared statement] S. |
drh | 21ac7f9 | 2008-01-31 12:26:49 +0000 | [diff] [blame] | 3161 | ** |
| 3162 | ** {F13830} The [sqlite3_column_value(S,N)] interface returns a |
| 3163 | ** pointer to the [sqlite3_value] object that for the |
| 3164 | ** Nth column in the current row of the result set for |
drh | 414025d | 2008-01-31 16:36:40 +0000 | [diff] [blame] | 3165 | ** [prepared statement] S. |
danielk1977 | 106bb23 | 2004-05-21 10:08:53 +0000 | [diff] [blame] | 3166 | */ |
drh | f447950 | 2004-05-27 03:12:53 +0000 | [diff] [blame] | 3167 | const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); |
| 3168 | int sqlite3_column_bytes(sqlite3_stmt*, int iCol); |
| 3169 | int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); |
| 3170 | double sqlite3_column_double(sqlite3_stmt*, int iCol); |
| 3171 | int sqlite3_column_int(sqlite3_stmt*, int iCol); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 3172 | sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); |
drh | f447950 | 2004-05-27 03:12:53 +0000 | [diff] [blame] | 3173 | const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); |
| 3174 | const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 3175 | int sqlite3_column_type(sqlite3_stmt*, int iCol); |
drh | 4be8b51 | 2006-06-13 23:51:34 +0000 | [diff] [blame] | 3176 | sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); |
danielk1977 | 4adee20 | 2004-05-08 08:23:19 +0000 | [diff] [blame] | 3177 | |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 3178 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 3179 | ** CAPI3REF: Destroy A Prepared Statement Object {F13300} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3180 | ** |
| 3181 | ** The sqlite3_finalize() function is called to delete a |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 3182 | ** [prepared statement]. If the statement was |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3183 | ** executed successfully, or not executed at all, then SQLITE_OK is returned. |
| 3184 | ** If execution of the statement failed then an |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 3185 | ** [error code] or [extended error code] |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3186 | ** is returned. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 3187 | ** |
| 3188 | ** This routine can be called at any point during the execution of the |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 3189 | ** [prepared statement]. If the virtual machine has not |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3190 | ** completed execution when this routine is called, that is like |
| 3191 | ** encountering an error or an interrupt. (See [sqlite3_interrupt()].) |
| 3192 | ** Incomplete updates may be rolled back and transactions cancelled, |
| 3193 | ** depending on the circumstances, and the |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 3194 | ** [error code] returned will be [SQLITE_ABORT]. |
| 3195 | ** |
| 3196 | ** INVARIANTS: |
| 3197 | ** |
| 3198 | ** {F11302} The [sqlite3_finalize(S)] interface destroys the |
| 3199 | ** [prepared statement] S and releases all |
| 3200 | ** memory and file resources held by that object. |
| 3201 | ** |
| 3202 | ** {F11304} If the most recent call to [sqlite3_step(S)] for the |
| 3203 | ** [prepared statement] S returned an error, |
| 3204 | ** then [sqlite3_finalize(S)] returns that same error. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 3205 | */ |
| 3206 | int sqlite3_finalize(sqlite3_stmt *pStmt); |
| 3207 | |
| 3208 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 3209 | ** CAPI3REF: Reset A Prepared Statement Object {F13330} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3210 | ** |
| 3211 | ** The sqlite3_reset() function is called to reset a |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 3212 | ** [prepared statement] object. |
drh | 85b623f | 2007-12-13 21:54:09 +0000 | [diff] [blame] | 3213 | ** back to its initial state, ready to be re-executed. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 3214 | ** Any SQL statement variables that had values bound to them using |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3215 | ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values. |
| 3216 | ** Use [sqlite3_clear_bindings()] to reset the bindings. |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 3217 | ** |
| 3218 | ** {F11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S |
| 3219 | ** back to the beginning of its program. |
| 3220 | ** |
| 3221 | ** {F11334} If the most recent call to [sqlite3_step(S)] for |
| 3222 | ** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE], |
| 3223 | ** or if [sqlite3_step(S)] has never before been called on S, |
| 3224 | ** then [sqlite3_reset(S)] returns [SQLITE_OK]. |
| 3225 | ** |
| 3226 | ** {F11336} If the most recent call to [sqlite3_step(S)] for |
| 3227 | ** [prepared statement] S indicated an error, then |
| 3228 | ** [sqlite3_reset(S)] returns an appropriate [error code]. |
| 3229 | ** |
| 3230 | ** {F11338} The [sqlite3_reset(S)] interface does not change the values |
| 3231 | ** of any [sqlite3_bind_blob|bindings] on [prepared statement] S. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 3232 | */ |
| 3233 | int sqlite3_reset(sqlite3_stmt *pStmt); |
| 3234 | |
| 3235 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 3236 | ** CAPI3REF: Create Or Redefine SQL Functions {F16100} |
drh | 21ac7f9 | 2008-01-31 12:26:49 +0000 | [diff] [blame] | 3237 | ** KEYWORDS: {function creation routines} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3238 | ** |
drh | 21ac7f9 | 2008-01-31 12:26:49 +0000 | [diff] [blame] | 3239 | ** These two functions (collectively known as |
| 3240 | ** "function creation routines") are used to add SQL functions or aggregates |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3241 | ** or to redefine the behavior of existing SQL functions or aggregates. The |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 3242 | ** difference only between the two is that the second parameter, the |
| 3243 | ** name of the (scalar) function or aggregate, is encoded in UTF-8 for |
| 3244 | ** sqlite3_create_function() and UTF-16 for sqlite3_create_function16(). |
| 3245 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 3246 | ** The first argument is the [database connection] that holds the |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3247 | ** SQL function or aggregate is to be added or redefined. If a single |
| 3248 | ** program uses more than one database handle internally, then SQL |
| 3249 | ** functions or aggregates must be added individually to each database |
| 3250 | ** handle with which they will be used. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 3251 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3252 | ** The second parameter is the name of the SQL function to be created |
| 3253 | ** or redefined. |
| 3254 | ** The length of the name is limited to 255 bytes, exclusive of the |
| 3255 | ** zero-terminator. Note that the name length limit is in bytes, not |
| 3256 | ** characters. Any attempt to create a function with a longer name |
| 3257 | ** will result in an SQLITE_ERROR error. |
| 3258 | ** |
| 3259 | ** The third parameter is the number of arguments that the SQL function or |
| 3260 | ** aggregate takes. If this parameter is negative, then the SQL function or |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 3261 | ** aggregate may take any number of arguments. |
| 3262 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3263 | ** The fourth parameter, eTextRep, specifies what |
| 3264 | ** [SQLITE_UTF8 | text encoding] this SQL function prefers for |
| 3265 | ** its parameters. Any SQL function implementation should be able to work |
| 3266 | ** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be |
| 3267 | ** more efficient with one encoding than another. It is allowed to |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 3268 | ** invoke sqlite3_create_function() or sqlite3_create_function16() multiple |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3269 | ** times with the same function but with different values of eTextRep. |
| 3270 | ** When multiple implementations of the same function are available, SQLite |
| 3271 | ** will pick the one that involves the least amount of data conversion. |
| 3272 | ** If there is only a single implementation which does not care what |
| 3273 | ** text encoding is used, then the fourth argument should be |
| 3274 | ** [SQLITE_ANY]. |
| 3275 | ** |
| 3276 | ** The fifth parameter is an arbitrary pointer. The implementation |
| 3277 | ** of the function can gain access to this pointer using |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 3278 | ** [sqlite3_user_data()]. |
danielk1977 | d02eb1f | 2004-06-06 09:44:03 +0000 | [diff] [blame] | 3279 | ** |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 3280 | ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3281 | ** pointers to C-language functions that implement the SQL |
| 3282 | ** function or aggregate. A scalar SQL function requires an implementation of |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 3283 | ** the xFunc callback only, NULL pointers should be passed as the xStep |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3284 | ** and xFinal parameters. An aggregate SQL function requires an implementation |
| 3285 | ** of xStep and xFinal and NULL should be passed for xFunc. To delete an |
| 3286 | ** existing SQL function or aggregate, pass NULL for all three function |
| 3287 | ** callback. |
| 3288 | ** |
| 3289 | ** It is permitted to register multiple implementations of the same |
| 3290 | ** functions with the same name but with either differing numbers of |
| 3291 | ** arguments or differing perferred text encodings. SQLite will use |
| 3292 | ** the implementation most closely matches the way in which the |
| 3293 | ** SQL function is used. |
drh | 21ac7f9 | 2008-01-31 12:26:49 +0000 | [diff] [blame] | 3294 | ** |
| 3295 | ** INVARIANTS: |
| 3296 | ** |
| 3297 | ** {F16103} The [sqlite3_create_function16()] interface behaves exactly |
| 3298 | ** like [sqlite3_create_function()] in every way except that it |
| 3299 | ** interprets the zFunctionName argument as |
| 3300 | ** zero-terminated UTF-16 native byte order instead of as a |
| 3301 | ** zero-terminated UTF-8. |
| 3302 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3303 | ** {F16106} A successful invocation of |
| 3304 | ** the [sqlite3_create_function(D,X,N,E,...)] interface registers |
| 3305 | ** or replaces callback functions in [database connection] D |
| 3306 | ** used to implement the SQL function named X with N parameters |
| 3307 | ** and having a perferred text encoding of E. |
| 3308 | ** |
| 3309 | ** {F16109} A successful call to [sqlite3_create_function(D,X,N,E,P,F,S,L)] |
| 3310 | ** replaces the P, F, S, and L values from any prior calls with |
| 3311 | ** the same D, X, N, and E values. |
| 3312 | ** |
| 3313 | ** {F16112} The [sqlite3_create_function(D,X,...)] interface fails with |
| 3314 | ** a return code of [SQLITE_ERROR] if the SQL function name X is |
| 3315 | ** longer than 255 bytes exclusive of the zero terminator. |
| 3316 | ** |
| 3317 | ** {F16118} Either F must be NULL and S and L are non-NULL or else F |
| 3318 | ** is non-NULL and S and L are NULL, otherwise |
| 3319 | ** [sqlite3_create_function(D,X,N,E,P,F,S,L)] returns [SQLITE_ERROR]. |
| 3320 | ** |
| 3321 | ** {F16121} The [sqlite3_create_function(D,...)] interface fails with an |
| 3322 | ** error code of [SQLITE_BUSY] if there exist [prepared statements] |
| 3323 | ** associated with the [database connection] D. |
| 3324 | ** |
| 3325 | ** {F16124} The [sqlite3_create_function(D,X,N,...)] interface fails with an |
| 3326 | ** error code of [SQLITE_ERROR] if parameter N (specifying the number |
| 3327 | ** of arguments to the SQL function being registered) is less |
| 3328 | ** than -1 or greater than 127. |
| 3329 | ** |
| 3330 | ** {F16127} When N is non-negative, the [sqlite3_create_function(D,X,N,...)] |
| 3331 | ** interface causes callbacks to be invoked for the SQL function |
| 3332 | ** named X when the number of arguments to the SQL function is |
| 3333 | ** exactly N. |
| 3334 | ** |
| 3335 | ** {F16130} When N is -1, the [sqlite3_create_function(D,X,N,...)] |
| 3336 | ** interface causes callbacks to be invoked for the SQL function |
| 3337 | ** named X with any number of arguments. |
| 3338 | ** |
| 3339 | ** {F16133} When calls to [sqlite3_create_function(D,X,N,...)] |
| 3340 | ** specify multiple implementations of the same function X |
| 3341 | ** and when one implementation has N>=0 and the other has N=(-1) |
| 3342 | ** the implementation with a non-zero N is preferred. |
| 3343 | ** |
| 3344 | ** {F16136} When calls to [sqlite3_create_function(D,X,N,E,...)] |
| 3345 | ** specify multiple implementations of the same function X with |
| 3346 | ** the same number of arguments N but with different |
| 3347 | ** encodings E, then the implementation where E matches the |
| 3348 | ** database encoding is preferred. |
| 3349 | ** |
| 3350 | ** {F16139} For an aggregate SQL function created using |
| 3351 | ** [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finializer |
| 3352 | ** function L will always be invoked exactly once if the |
| 3353 | ** step function S is called one or more times. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 3354 | */ |
| 3355 | int sqlite3_create_function( |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 3356 | sqlite3 *db, |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 3357 | const char *zFunctionName, |
| 3358 | int nArg, |
| 3359 | int eTextRep, |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 3360 | void *pApp, |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 3361 | void (*xFunc)(sqlite3_context*,int,sqlite3_value**), |
| 3362 | void (*xStep)(sqlite3_context*,int,sqlite3_value**), |
| 3363 | void (*xFinal)(sqlite3_context*) |
| 3364 | ); |
| 3365 | int sqlite3_create_function16( |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 3366 | sqlite3 *db, |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 3367 | const void *zFunctionName, |
| 3368 | int nArg, |
| 3369 | int eTextRep, |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 3370 | void *pApp, |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 3371 | void (*xFunc)(sqlite3_context*,int,sqlite3_value**), |
| 3372 | void (*xStep)(sqlite3_context*,int,sqlite3_value**), |
| 3373 | void (*xFinal)(sqlite3_context*) |
| 3374 | ); |
| 3375 | |
| 3376 | /* |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3377 | ** CAPI3REF: Text Encodings {F10267} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3378 | ** |
| 3379 | ** These constant define integer codes that represent the various |
| 3380 | ** text encodings supported by SQLite. |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 3381 | */ |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3382 | #define SQLITE_UTF8 1 |
| 3383 | #define SQLITE_UTF16LE 2 |
| 3384 | #define SQLITE_UTF16BE 3 |
| 3385 | #define SQLITE_UTF16 4 /* Use native byte order */ |
| 3386 | #define SQLITE_ANY 5 /* sqlite3_create_function only */ |
| 3387 | #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ |
danielk1977 | 6590493 | 2004-05-26 06:18:37 +0000 | [diff] [blame] | 3388 | |
danielk1977 | 0ffba6b | 2004-05-24 09:10:10 +0000 | [diff] [blame] | 3389 | /* |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3390 | ** CAPI3REF: Obsolete Functions |
| 3391 | ** |
| 3392 | ** These functions are all now obsolete. In order to maintain |
| 3393 | ** backwards compatibility with older code, we continue to support |
| 3394 | ** these functions. However, new development projects should avoid |
| 3395 | ** the use of these functions. To help encourage people to avoid |
| 3396 | ** using these functions, we are not going to tell you want they do. |
| 3397 | */ |
| 3398 | int sqlite3_aggregate_count(sqlite3_context*); |
| 3399 | int sqlite3_expired(sqlite3_stmt*); |
| 3400 | int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); |
| 3401 | int sqlite3_global_recover(void); |
drh | e30f442 | 2007-08-21 16:15:55 +0000 | [diff] [blame] | 3402 | void sqlite3_thread_cleanup(void); |
drh | d64621d | 2007-11-05 17:54:17 +0000 | [diff] [blame] | 3403 | int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64); |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3404 | |
| 3405 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 3406 | ** CAPI3REF: Obtaining SQL Function Parameter Values {F15100} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3407 | ** |
| 3408 | ** The C-language implementation of SQL functions and aggregates uses |
| 3409 | ** this set of interface routines to access the parameter values on |
| 3410 | ** the function or aggregate. |
| 3411 | ** |
| 3412 | ** The xFunc (for scalar functions) or xStep (for aggregates) parameters |
| 3413 | ** to [sqlite3_create_function()] and [sqlite3_create_function16()] |
| 3414 | ** define callbacks that implement the SQL functions and aggregates. |
| 3415 | ** The 4th parameter to these callbacks is an array of pointers to |
| 3416 | ** [sqlite3_value] objects. There is one [sqlite3_value] object for |
| 3417 | ** each parameter to the SQL function. These routines are used to |
| 3418 | ** extract values from the [sqlite3_value] objects. |
| 3419 | ** |
| 3420 | ** These routines work just like the corresponding |
| 3421 | ** [sqlite3_column_blob | sqlite3_column_* routines] except that |
| 3422 | ** these routines take a single [sqlite3_value*] pointer instead |
| 3423 | ** of an [sqlite3_stmt*] pointer and an integer column number. |
| 3424 | ** |
| 3425 | ** The sqlite3_value_text16() interface extracts a UTF16 string |
| 3426 | ** in the native byte-order of the host machine. The |
| 3427 | ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces |
| 3428 | ** extract UTF16 strings as big-endian and little-endian respectively. |
| 3429 | ** |
| 3430 | ** The sqlite3_value_numeric_type() interface attempts to apply |
| 3431 | ** numeric affinity to the value. This means that an attempt is |
| 3432 | ** made to convert the value to an integer or floating point. If |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3433 | ** such a conversion is possible without loss of information (in other |
| 3434 | ** words if the value is a string that looks like a number) |
| 3435 | ** then the conversion is done. Otherwise no conversion occurs. The |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3436 | ** [SQLITE_INTEGER | datatype] after conversion is returned. |
| 3437 | ** |
| 3438 | ** Please pay particular attention to the fact that the pointer that |
| 3439 | ** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or |
| 3440 | ** [sqlite3_value_text16()] can be invalidated by a subsequent call to |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 3441 | ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()], |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3442 | ** or [sqlite3_value_text16()]. |
drh | e53831d | 2007-08-17 01:14:38 +0000 | [diff] [blame] | 3443 | ** |
| 3444 | ** These routines must be called from the same thread as |
| 3445 | ** the SQL function that supplied the sqlite3_value* parameters. |
drh | 32bc3f6 | 2007-08-21 20:25:39 +0000 | [diff] [blame] | 3446 | ** Or, if the sqlite3_value* argument comes from the [sqlite3_column_value()] |
| 3447 | ** interface, then these routines should be called from the same thread |
| 3448 | ** that ran [sqlite3_column_value()]. |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3449 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3450 | ** |
| 3451 | ** INVARIANTS: |
| 3452 | ** |
| 3453 | ** {F15103} The [sqlite3_value_blob(V)] interface converts the |
| 3454 | ** [sqlite3_value] object V into a blob and then returns a |
| 3455 | ** pointer to the converted value. |
| 3456 | ** |
| 3457 | ** {F15106} The [sqlite3_value_bytes(V)] interface returns the |
| 3458 | ** number of bytes in the blob or string (exclusive of the |
| 3459 | ** zero terminator on the string) that was returned by the |
| 3460 | ** most recent call to [sqlite3_value_blob(V)] or |
| 3461 | ** [sqlite3_value_text(V)]. |
| 3462 | ** |
| 3463 | ** {F15109} The [sqlite3_value_bytes16(V)] interface returns the |
| 3464 | ** number of bytes in the string (exclusive of the |
| 3465 | ** zero terminator on the string) that was returned by the |
| 3466 | ** most recent call to [sqlite3_value_text16(V)], |
| 3467 | ** [sqlite3_value_text16be(V)], or [sqlite3_value_text16le(V)]. |
| 3468 | ** |
| 3469 | ** {F15112} The [sqlite3_value_double(V)] interface converts the |
| 3470 | ** [sqlite3_value] object V into a floating point value and |
| 3471 | ** returns a copy of that value. |
| 3472 | ** |
| 3473 | ** {F15115} The [sqlite3_value_int(V)] interface converts the |
| 3474 | ** [sqlite3_value] object V into a 64-bit signed integer and |
| 3475 | ** returns the lower 32 bits of that integer. |
| 3476 | ** |
| 3477 | ** {F15118} The [sqlite3_value_int64(V)] interface converts the |
| 3478 | ** [sqlite3_value] object V into a 64-bit signed integer and |
| 3479 | ** returns a copy of that integer. |
| 3480 | ** |
| 3481 | ** {F15121} The [sqlite3_value_text(V)] interface converts the |
| 3482 | ** [sqlite3_value] object V into a zero-terminated UTF-8 |
| 3483 | ** string and returns a pointer to that string. |
| 3484 | ** |
| 3485 | ** {F15124} The [sqlite3_value_text16(V)] interface converts the |
| 3486 | ** [sqlite3_value] object V into a zero-terminated 2-byte |
| 3487 | ** aligned UTF-16 native byte order |
| 3488 | ** string and returns a pointer to that string. |
| 3489 | ** |
| 3490 | ** {F15127} The [sqlite3_value_text16be(V)] interface converts the |
| 3491 | ** [sqlite3_value] object V into a zero-terminated 2-byte |
| 3492 | ** aligned UTF-16 big-endian |
| 3493 | ** string and returns a pointer to that string. |
| 3494 | ** |
| 3495 | ** {F15130} The [sqlite3_value_text16le(V)] interface converts the |
| 3496 | ** [sqlite3_value] object V into a zero-terminated 2-byte |
| 3497 | ** aligned UTF-16 little-endian |
| 3498 | ** string and returns a pointer to that string. |
| 3499 | ** |
| 3500 | ** {F15133} The [sqlite3_value_type(V)] interface returns |
| 3501 | ** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT], |
| 3502 | ** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for |
| 3503 | ** the [sqlite3_value] object V. |
| 3504 | ** |
| 3505 | ** {F15136} The [sqlite3_value_numeric_type(V)] interface converts |
| 3506 | ** the [sqlite3_value] object V into either an integer or |
| 3507 | ** a floating point value if it can do so without loss of |
| 3508 | ** information, and returns one of [SQLITE_NULL], |
| 3509 | ** [SQLITE_INTEGER], [SQLITE_FLOAT], [SQLITE_TEXT], or |
| 3510 | ** [SQLITE_BLOB] as appropriate for |
| 3511 | ** the [sqlite3_value] object V after the conversion attempt. |
danielk1977 | 0ffba6b | 2004-05-24 09:10:10 +0000 | [diff] [blame] | 3512 | */ |
drh | f447950 | 2004-05-27 03:12:53 +0000 | [diff] [blame] | 3513 | const void *sqlite3_value_blob(sqlite3_value*); |
| 3514 | int sqlite3_value_bytes(sqlite3_value*); |
| 3515 | int sqlite3_value_bytes16(sqlite3_value*); |
| 3516 | double sqlite3_value_double(sqlite3_value*); |
| 3517 | int sqlite3_value_int(sqlite3_value*); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 3518 | sqlite3_int64 sqlite3_value_int64(sqlite3_value*); |
drh | f447950 | 2004-05-27 03:12:53 +0000 | [diff] [blame] | 3519 | const unsigned char *sqlite3_value_text(sqlite3_value*); |
| 3520 | const void *sqlite3_value_text16(sqlite3_value*); |
danielk1977 | d812336 | 2004-06-12 09:25:12 +0000 | [diff] [blame] | 3521 | const void *sqlite3_value_text16le(sqlite3_value*); |
| 3522 | const void *sqlite3_value_text16be(sqlite3_value*); |
danielk1977 | 93d4675 | 2004-05-23 13:30:58 +0000 | [diff] [blame] | 3523 | int sqlite3_value_type(sqlite3_value*); |
drh | 29d7210 | 2006-02-09 22:13:41 +0000 | [diff] [blame] | 3524 | int sqlite3_value_numeric_type(sqlite3_value*); |
danielk1977 | 0ffba6b | 2004-05-24 09:10:10 +0000 | [diff] [blame] | 3525 | |
| 3526 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 3527 | ** CAPI3REF: Obtain Aggregate Function Context {F16210} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3528 | ** |
| 3529 | ** The implementation of aggregate SQL functions use this routine to allocate |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3530 | ** a structure for storing their state. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3531 | ** The first time the sqlite3_aggregate_context() routine is |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3532 | ** is called for a particular aggregate, SQLite allocates nBytes of memory |
| 3533 | ** zeros that memory, and returns a pointer to it. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3534 | ** On second and subsequent calls to sqlite3_aggregate_context() |
| 3535 | ** for the same aggregate function index, the same buffer is returned. |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3536 | ** The implementation |
danielk1977 | 0ae8b83 | 2004-05-25 12:05:56 +0000 | [diff] [blame] | 3537 | ** of the aggregate can use the returned buffer to accumulate data. |
| 3538 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3539 | ** SQLite automatically frees the allocated buffer when the aggregate |
| 3540 | ** query concludes. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3541 | ** |
| 3542 | ** The first parameter should be a copy of the |
| 3543 | ** [sqlite3_context | SQL function context] that is the first |
| 3544 | ** parameter to the callback routine that implements the aggregate |
| 3545 | ** function. |
drh | e53831d | 2007-08-17 01:14:38 +0000 | [diff] [blame] | 3546 | ** |
| 3547 | ** This routine must be called from the same thread in which |
drh | 605264d | 2007-08-21 15:13:19 +0000 | [diff] [blame] | 3548 | ** the aggregate SQL function is running. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3549 | ** |
| 3550 | ** INVARIANTS: |
| 3551 | ** |
| 3552 | ** {F16211} The first invocation of [sqlite3_aggregate_context(C,N)] for |
| 3553 | ** a particular instance of an aggregate function (for a particular |
| 3554 | ** context C) causes SQLite to allocation N bytes of memory, |
| 3555 | ** zero that memory, and return a pointer to the allocationed |
| 3556 | ** memory. |
| 3557 | ** |
| 3558 | ** {F16213} If a memory allocation error occurs during |
| 3559 | ** [sqlite3_aggregate_context(C,N)] then the function returns 0. |
| 3560 | ** |
| 3561 | ** {F16215} Second and subsequent invocations of |
| 3562 | ** [sqlite3_aggregate_context(C,N)] for the same context pointer C |
| 3563 | ** ignore the N parameter and return a pointer to the same |
| 3564 | ** block of memory returned by the first invocation. |
| 3565 | ** |
| 3566 | ** {F16217} The memory allocated by [sqlite3_aggregate_context(C,N)] is |
| 3567 | ** automatically freed on the next call to [sqlite3_reset()] |
| 3568 | ** or [sqlite3_finalize()] for the [prepared statement] containing |
| 3569 | ** the aggregate function associated with context C. |
danielk1977 | 0ae8b83 | 2004-05-25 12:05:56 +0000 | [diff] [blame] | 3570 | */ |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 3571 | void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); |
danielk1977 | 7e18c25 | 2004-05-25 11:47:24 +0000 | [diff] [blame] | 3572 | |
| 3573 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 3574 | ** CAPI3REF: User Data For Functions {F16240} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3575 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3576 | ** The sqlite3_user_data() interface returns a copy of |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3577 | ** the pointer that was the pUserData parameter (the 5th parameter) |
| 3578 | ** of the the [sqlite3_create_function()] |
| 3579 | ** and [sqlite3_create_function16()] routines that originally |
| 3580 | ** registered the application defined function. {END} |
drh | e53831d | 2007-08-17 01:14:38 +0000 | [diff] [blame] | 3581 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3582 | ** This routine must be called from the same thread in which |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3583 | ** the application-defined function is running. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3584 | ** |
| 3585 | ** INVARIANTS: |
| 3586 | ** |
| 3587 | ** {F16243} The [sqlite3_user_data(C)] interface returns a copy of the |
| 3588 | ** P pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)] |
| 3589 | ** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that |
| 3590 | ** registered the SQL function associated with |
| 3591 | ** [sqlite3_context] C. |
danielk1977 | 7e18c25 | 2004-05-25 11:47:24 +0000 | [diff] [blame] | 3592 | */ |
| 3593 | void *sqlite3_user_data(sqlite3_context*); |
| 3594 | |
| 3595 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 3596 | ** CAPI3REF: Function Auxiliary Data {F16270} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3597 | ** |
| 3598 | ** The following two functions may be used by scalar SQL functions to |
danielk1977 | 682f68b | 2004-06-05 10:22:17 +0000 | [diff] [blame] | 3599 | ** associate meta-data with argument values. If the same value is passed to |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3600 | ** multiple invocations of the same SQL function during query execution, under |
danielk1977 | 682f68b | 2004-06-05 10:22:17 +0000 | [diff] [blame] | 3601 | ** some circumstances the associated meta-data may be preserved. This may |
| 3602 | ** be used, for example, to add a regular-expression matching scalar |
| 3603 | ** function. The compiled version of the regular expression is stored as |
| 3604 | ** meta-data associated with the SQL value passed as the regular expression |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3605 | ** pattern. The compiled regular expression can be reused on multiple |
| 3606 | ** invocations of the same function so that the original pattern string |
| 3607 | ** does not need to be recompiled on each invocation. |
danielk1977 | 682f68b | 2004-06-05 10:22:17 +0000 | [diff] [blame] | 3608 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3609 | ** The sqlite3_get_auxdata() interface returns a pointer to the meta-data |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3610 | ** associated by the sqlite3_set_auxdata() function with the Nth argument |
| 3611 | ** value to the application-defined function. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3612 | ** If no meta-data has been ever been set for the Nth |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3613 | ** argument of the function, or if the cooresponding function parameter |
| 3614 | ** has changed since the meta-data was set, then sqlite3_get_auxdata() |
| 3615 | ** returns a NULL pointer. |
danielk1977 | 682f68b | 2004-06-05 10:22:17 +0000 | [diff] [blame] | 3616 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3617 | ** The sqlite3_set_auxdata() interface saves the meta-data |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3618 | ** pointed to by its 3rd parameter as the meta-data for the N-th |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3619 | ** argument of the application-defined function. Subsequent |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3620 | ** calls to sqlite3_get_auxdata() might return this data, if it has |
| 3621 | ** not been destroyed. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3622 | ** If it is not NULL, SQLite will invoke the destructor |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3623 | ** function given by the 4th parameter to sqlite3_set_auxdata() on |
| 3624 | ** the meta-data when the corresponding function parameter changes |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3625 | ** or when the SQL statement completes, whichever comes first. |
| 3626 | ** |
| 3627 | ** SQLite is free to call the destructor and drop meta-data on |
| 3628 | ** any parameter of any function at any time. The only guarantee |
| 3629 | ** is that the destructor will be called before the metadata is |
| 3630 | ** dropped. |
danielk1977 | 682f68b | 2004-06-05 10:22:17 +0000 | [diff] [blame] | 3631 | ** |
| 3632 | ** In practice, meta-data is preserved between function calls for |
| 3633 | ** expressions that are constant at compile time. This includes literal |
| 3634 | ** values and SQL variables. |
drh | e53831d | 2007-08-17 01:14:38 +0000 | [diff] [blame] | 3635 | ** |
drh | b21c8cd | 2007-08-21 19:33:56 +0000 | [diff] [blame] | 3636 | ** These routines must be called from the same thread in which |
| 3637 | ** the SQL function is running. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3638 | ** |
| 3639 | ** INVARIANTS: |
| 3640 | ** |
| 3641 | ** {F16272} The [sqlite3_get_auxdata(C,N)] interface returns a pointer |
| 3642 | ** to metadata associated with the Nth parameter of the SQL function |
| 3643 | ** whose context is C, or NULL if there is no metadata associated |
| 3644 | ** with that parameter. |
| 3645 | ** |
| 3646 | ** {F16274} The [sqlite3_set_auxdata(C,N,P,D)] interface assigns a metadata |
| 3647 | ** pointer P to the Nth parameter of the SQL function with context |
| 3648 | ** C. |
| 3649 | ** |
| 3650 | ** {F16276} SQLite will invoke the destructor D with a single argument |
| 3651 | ** which is the metadata pointer P following a call to |
| 3652 | ** [sqlite3_set_auxdata(C,N,P,D)] when SQLite ceases to hold |
| 3653 | ** the metadata. |
| 3654 | ** |
| 3655 | ** {F16277} SQLite ceases to hold metadata for an SQL function parameter |
| 3656 | ** when the value of that parameter changes. |
| 3657 | ** |
| 3658 | ** {F16278} When [sqlite3_set_auxdata(C,N,P,D)] is invoked, the destructor |
| 3659 | ** is called for any prior metadata associated with the same function |
| 3660 | ** context C and parameter N. |
| 3661 | ** |
| 3662 | ** {F16279} SQLite will call destructors for any metadata it is holding |
| 3663 | ** in a particular [prepared statement] S when either |
| 3664 | ** [sqlite3_reset(S)] or [sqlite3_finalize(S)] is called. |
danielk1977 | 682f68b | 2004-06-05 10:22:17 +0000 | [diff] [blame] | 3665 | */ |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3666 | void *sqlite3_get_auxdata(sqlite3_context*, int N); |
| 3667 | void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*)); |
danielk1977 | 682f68b | 2004-06-05 10:22:17 +0000 | [diff] [blame] | 3668 | |
drh | a285422 | 2004-06-17 19:04:17 +0000 | [diff] [blame] | 3669 | |
| 3670 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 3671 | ** CAPI3REF: Constants Defining Special Destructor Behavior {F10280} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3672 | ** |
drh | a285422 | 2004-06-17 19:04:17 +0000 | [diff] [blame] | 3673 | ** These are special value for the destructor that is passed in as the |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3674 | ** final argument to routines like [sqlite3_result_blob()]. If the destructor |
drh | a285422 | 2004-06-17 19:04:17 +0000 | [diff] [blame] | 3675 | ** argument is SQLITE_STATIC, it means that the content pointer is constant |
| 3676 | ** and will never change. It does not need to be destroyed. The |
| 3677 | ** SQLITE_TRANSIENT value means that the content will likely change in |
| 3678 | ** the near future and that SQLite should make its own private copy of |
| 3679 | ** the content before returning. |
drh | 6c9121a | 2007-01-26 00:51:43 +0000 | [diff] [blame] | 3680 | ** |
| 3681 | ** The typedef is necessary to work around problems in certain |
| 3682 | ** C++ compilers. See ticket #2191. |
drh | a285422 | 2004-06-17 19:04:17 +0000 | [diff] [blame] | 3683 | */ |
drh | 6c9121a | 2007-01-26 00:51:43 +0000 | [diff] [blame] | 3684 | typedef void (*sqlite3_destructor_type)(void*); |
| 3685 | #define SQLITE_STATIC ((sqlite3_destructor_type)0) |
| 3686 | #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) |
danielk1977 | d812336 | 2004-06-12 09:25:12 +0000 | [diff] [blame] | 3687 | |
danielk1977 | 682f68b | 2004-06-05 10:22:17 +0000 | [diff] [blame] | 3688 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 3689 | ** CAPI3REF: Setting The Result Of An SQL Function {F16400} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3690 | ** |
| 3691 | ** These routines are used by the xFunc or xFinal callbacks that |
| 3692 | ** implement SQL functions and aggregates. See |
| 3693 | ** [sqlite3_create_function()] and [sqlite3_create_function16()] |
| 3694 | ** for additional information. |
| 3695 | ** |
| 3696 | ** These functions work very much like the |
| 3697 | ** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used |
| 3698 | ** to bind values to host parameters in prepared statements. |
| 3699 | ** Refer to the |
| 3700 | ** [sqlite3_bind_blob | sqlite3_bind_* documentation] for |
| 3701 | ** additional information. |
| 3702 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3703 | ** The sqlite3_result_blob() interface sets the result from |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3704 | ** an application defined function to be the BLOB whose content is pointed |
| 3705 | ** to by the second parameter and which is N bytes long where N is the |
| 3706 | ** third parameter. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3707 | ** The sqlite3_result_zeroblob() inerfaces set the result of |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3708 | ** the application defined function to be a BLOB containing all zero |
| 3709 | ** bytes and N bytes in size, where N is the value of the 2nd parameter. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3710 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3711 | ** The sqlite3_result_double() interface sets the result from |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3712 | ** an application defined function to be a floating point value specified |
| 3713 | ** by its 2nd argument. |
drh | e53831d | 2007-08-17 01:14:38 +0000 | [diff] [blame] | 3714 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3715 | ** The sqlite3_result_error() and sqlite3_result_error16() functions |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3716 | ** cause the implemented SQL function to throw an exception. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3717 | ** SQLite uses the string pointed to by the |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3718 | ** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16() |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3719 | ** as the text of an error message. SQLite interprets the error |
| 3720 | ** message string from sqlite3_result_error() as UTF8. SQLite |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3721 | ** interprets the string from sqlite3_result_error16() as UTF16 in native |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3722 | ** byte order. If the third parameter to sqlite3_result_error() |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3723 | ** or sqlite3_result_error16() is negative then SQLite takes as the error |
| 3724 | ** message all text up through the first zero character. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3725 | ** If the third parameter to sqlite3_result_error() or |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3726 | ** sqlite3_result_error16() is non-negative then SQLite takes that many |
| 3727 | ** bytes (not characters) from the 2nd parameter as the error message. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3728 | ** The sqlite3_result_error() and sqlite3_result_error16() |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3729 | ** routines make a copy private copy of the error message text before |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3730 | ** they return. Hence, the calling function can deallocate or |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3731 | ** modify the text after they return without harm. |
drh | 69544ec | 2008-02-06 14:11:34 +0000 | [diff] [blame] | 3732 | ** The sqlite3_result_error_code() function changes the error code |
| 3733 | ** returned by SQLite as a result of an error in a function. By default, |
| 3734 | ** the error code is SQLITE_ERROR. |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3735 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3736 | ** The sqlite3_result_toobig() interface causes SQLite |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3737 | ** to throw an error indicating that a string or BLOB is to long |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3738 | ** to represent. The sqlite3_result_nomem() interface |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3739 | ** causes SQLite to throw an exception indicating that the a |
| 3740 | ** memory allocation failed. |
| 3741 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3742 | ** The sqlite3_result_int() interface sets the return value |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3743 | ** of the application-defined function to be the 32-bit signed integer |
| 3744 | ** value given in the 2nd argument. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3745 | ** The sqlite3_result_int64() interface sets the return value |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3746 | ** of the application-defined function to be the 64-bit signed integer |
| 3747 | ** value given in the 2nd argument. |
| 3748 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3749 | ** The sqlite3_result_null() interface sets the return value |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3750 | ** of the application-defined function to be NULL. |
| 3751 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3752 | ** The sqlite3_result_text(), sqlite3_result_text16(), |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3753 | ** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces |
| 3754 | ** set the return value of the application-defined function to be |
| 3755 | ** a text string which is represented as UTF-8, UTF-16 native byte order, |
| 3756 | ** UTF-16 little endian, or UTF-16 big endian, respectively. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3757 | ** SQLite takes the text result from the application from |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3758 | ** the 2nd parameter of the sqlite3_result_text* interfaces. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3759 | ** If the 3rd parameter to the sqlite3_result_text* interfaces |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3760 | ** is negative, then SQLite takes result text from the 2nd parameter |
| 3761 | ** through the first zero character. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3762 | ** If the 3rd parameter to the sqlite3_result_text* interfaces |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3763 | ** is non-negative, then as many bytes (not characters) of the text |
| 3764 | ** pointed to by the 2nd parameter are taken as the application-defined |
| 3765 | ** function result. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3766 | ** If the 4th parameter to the sqlite3_result_text* interfaces |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3767 | ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that |
| 3768 | ** function as the destructor on the text or blob result when it has |
| 3769 | ** finished using that result. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3770 | ** If the 4th parameter to the sqlite3_result_text* interfaces |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3771 | ** or sqlite3_result_blob is the special constant SQLITE_STATIC, then |
| 3772 | ** SQLite assumes that the text or blob result is constant space and |
| 3773 | ** does not copy the space or call a destructor when it has |
| 3774 | ** finished using that result. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3775 | ** If the 4th parameter to the sqlite3_result_text* interfaces |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3776 | ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT |
| 3777 | ** then SQLite makes a copy of the result into space obtained from |
| 3778 | ** from [sqlite3_malloc()] before it returns. |
| 3779 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3780 | ** The sqlite3_result_value() interface sets the result of |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3781 | ** the application-defined function to be a copy the [sqlite3_value] |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3782 | ** object specified by the 2nd parameter. The |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3783 | ** sqlite3_result_value() interface makes a copy of the [sqlite3_value] |
| 3784 | ** so that [sqlite3_value] specified in the parameter may change or |
| 3785 | ** be deallocated after sqlite3_result_value() returns without harm. |
| 3786 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3787 | ** If these routines are called from within the different thread |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3788 | ** than the one containing the application-defined function that recieved |
| 3789 | ** the [sqlite3_context] pointer, the results are undefined. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3790 | ** |
| 3791 | ** INVARIANTS: |
| 3792 | ** |
| 3793 | ** {F16403} The default return value from any SQL function is NULL. |
| 3794 | ** |
| 3795 | ** {F16406} The [sqlite3_result_blob(C,V,N,D)] interface changes the |
| 3796 | ** return value of function C to be a blob that is N bytes |
| 3797 | ** in length and with content pointed to by V. |
| 3798 | ** |
| 3799 | ** {F16409} The [sqlite3_result_double(C,V)] interface changes the |
| 3800 | ** return value of function C to be the floating point value V. |
| 3801 | ** |
| 3802 | ** {F16412} The [sqlite3_result_error(C,V,N)] interface changes the return |
| 3803 | ** value of function C to be an exception with error code |
| 3804 | ** [SQLITE_ERROR] and a UTF8 error message copied from V up to the |
| 3805 | ** first zero byte or until N bytes are read if N is positive. |
| 3806 | ** |
| 3807 | ** {F16415} The [sqlite3_result_error16(C,V,N)] interface changes the return |
| 3808 | ** value of function C to be an exception with error code |
| 3809 | ** [SQLITE_ERROR] and a UTF16 native byte order error message |
| 3810 | ** copied from V up to the first zero terminator or until N bytes |
| 3811 | ** are read if N is positive. |
| 3812 | ** |
| 3813 | ** {F16418} The [sqlite3_result_error_toobig(C)] interface changes the return |
| 3814 | ** value of the function C to be an exception with error code |
| 3815 | ** [SQLITE_TOOBIG] and an appropriate error message. |
| 3816 | ** |
| 3817 | ** {F16421} The [sqlite3_result_error_nomem(C)] interface changes the return |
| 3818 | ** value of the function C to be an exception with error code |
| 3819 | ** [SQLITE_NOMEM] and an appropriate error message. |
| 3820 | ** |
| 3821 | ** {F16424} The [sqlite3_result_error_code(C,E)] interface changes the return |
| 3822 | ** value of the function C to be an exception with error code E. |
| 3823 | ** The error message text is unchanged. |
| 3824 | ** |
| 3825 | ** {F16427} The [sqlite3_result_int(C,V)] interface changes the |
| 3826 | ** return value of function C to be the 32-bit integer value V. |
| 3827 | ** |
| 3828 | ** {F16430} The [sqlite3_result_int64(C,V)] interface changes the |
| 3829 | ** return value of function C to be the 64-bit integer value V. |
| 3830 | ** |
| 3831 | ** {F16433} The [sqlite3_result_null(C)] interface changes the |
| 3832 | ** return value of function C to be NULL. |
| 3833 | ** |
| 3834 | ** {F16436} The [sqlite3_result_text(C,V,N,D)] interface changes the |
| 3835 | ** return value of function C to be the UTF8 string |
| 3836 | ** V up through the first zero or until N bytes are read if N |
| 3837 | ** is positive. |
| 3838 | ** |
| 3839 | ** {F16439} The [sqlite3_result_text16(C,V,N,D)] interface changes the |
| 3840 | ** return value of function C to be the UTF16 native byte order |
| 3841 | ** string V up through the first zero or until N bytes are read if N |
| 3842 | ** is positive. |
| 3843 | ** |
| 3844 | ** {F16442} The [sqlite3_result_text16be(C,V,N,D)] interface changes the |
| 3845 | ** return value of function C to be the UTF16 big-endian |
| 3846 | ** string V up through the first zero or until N bytes are read if N |
| 3847 | ** is positive. |
| 3848 | ** |
| 3849 | ** {F16445} The [sqlite3_result_text16le(C,V,N,D)] interface changes the |
| 3850 | ** return value of function C to be the UTF16 little-endian |
| 3851 | ** string V up through the first zero or until N bytes are read if N |
| 3852 | ** is positive. |
| 3853 | ** |
| 3854 | ** {F16448} The [sqlite3_result_value(C,V)] interface changes the |
| 3855 | ** return value of function C to be [sqlite3_value] object V. |
| 3856 | ** |
| 3857 | ** {F16451} The [sqlite3_result_zeroblob(C,N)] interface changes the |
| 3858 | ** return value of function C to be an N-byte blob of all zeros. |
| 3859 | ** |
| 3860 | ** {F16454} The [sqlite3_result_error()] and [sqlite3_result_error16()] |
| 3861 | ** interfaces make a copy of their error message strings before |
| 3862 | ** returning. |
| 3863 | ** |
| 3864 | ** {F16457} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], |
| 3865 | ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)], |
| 3866 | ** [sqlite3_result_text16be(C,V,N,D)], or |
| 3867 | ** [sqlite3_result_text16le(C,V,N,D)] is the constant [SQLITE_STATIC] |
| 3868 | ** then no destructor is ever called on the pointer V and SQLite |
| 3869 | ** assumes that V is immutable. |
| 3870 | ** |
| 3871 | ** {F16460} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], |
| 3872 | ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)], |
| 3873 | ** [sqlite3_result_text16be(C,V,N,D)], or |
| 3874 | ** [sqlite3_result_text16le(C,V,N,D)] is the constant |
| 3875 | ** [SQLITE_TRANSIENT] then the interfaces makes a copy of the |
| 3876 | ** content of V and retains the copy. |
| 3877 | ** |
| 3878 | ** {F16463} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)], |
| 3879 | ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)], |
| 3880 | ** [sqlite3_result_text16be(C,V,N,D)], or |
| 3881 | ** [sqlite3_result_text16le(C,V,N,D)] is some value other than |
| 3882 | ** the constants [SQLITE_STATIC] and [SQLITE_TRANSIENT] then |
| 3883 | ** SQLite will invoke the destructor D with V as its only argument |
| 3884 | ** when it has finished with the V value. |
danielk1977 | 7e18c25 | 2004-05-25 11:47:24 +0000 | [diff] [blame] | 3885 | */ |
danielk1977 | d812336 | 2004-06-12 09:25:12 +0000 | [diff] [blame] | 3886 | void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 3887 | void sqlite3_result_double(sqlite3_context*, double); |
danielk1977 | 7e18c25 | 2004-05-25 11:47:24 +0000 | [diff] [blame] | 3888 | void sqlite3_result_error(sqlite3_context*, const char*, int); |
| 3889 | void sqlite3_result_error16(sqlite3_context*, const void*, int); |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3890 | void sqlite3_result_error_toobig(sqlite3_context*); |
danielk1977 | a1644fd | 2007-08-29 12:31:25 +0000 | [diff] [blame] | 3891 | void sqlite3_result_error_nomem(sqlite3_context*); |
drh | 69544ec | 2008-02-06 14:11:34 +0000 | [diff] [blame] | 3892 | void sqlite3_result_error_code(sqlite3_context*, int); |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 3893 | void sqlite3_result_int(sqlite3_context*, int); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 3894 | void sqlite3_result_int64(sqlite3_context*, sqlite3_int64); |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 3895 | void sqlite3_result_null(sqlite3_context*); |
danielk1977 | d812336 | 2004-06-12 09:25:12 +0000 | [diff] [blame] | 3896 | void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); |
| 3897 | void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); |
| 3898 | void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); |
| 3899 | void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); |
drh | 4f26d6c | 2004-05-26 23:25:30 +0000 | [diff] [blame] | 3900 | void sqlite3_result_value(sqlite3_context*, sqlite3_value*); |
drh | b026e05 | 2007-05-02 01:34:31 +0000 | [diff] [blame] | 3901 | void sqlite3_result_zeroblob(sqlite3_context*, int n); |
drh | f9b596e | 2004-05-26 16:54:42 +0000 | [diff] [blame] | 3902 | |
drh | 52619df | 2004-06-11 17:48:02 +0000 | [diff] [blame] | 3903 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 3904 | ** CAPI3REF: Define New Collating Sequences {F16600} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3905 | ** |
| 3906 | ** These functions are used to add new collation sequences to the |
| 3907 | ** [sqlite3*] handle specified as the first argument. |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 3908 | ** |
| 3909 | ** 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] | 3910 | ** for sqlite3_create_collation() and sqlite3_create_collation_v2() |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3911 | ** and a UTF-16 string for sqlite3_create_collation16(). In all cases |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3912 | ** the name is passed as the second function argument. |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 3913 | ** |
drh | 4145f83 | 2007-10-12 18:30:12 +0000 | [diff] [blame] | 3914 | ** The third argument may be one of the constants [SQLITE_UTF8], |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3915 | ** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 3916 | ** routine expects to be passed pointers to strings encoded using UTF-8, |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3917 | ** UTF-16 little-endian or UTF-16 big-endian respectively. The |
drh | 4145f83 | 2007-10-12 18:30:12 +0000 | [diff] [blame] | 3918 | ** third argument might also be [SQLITE_UTF16_ALIGNED] to indicate that |
| 3919 | ** the routine expects pointers to 16-bit word aligned strings |
| 3920 | ** of UTF16 in the native byte order of the host computer. |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 3921 | ** |
| 3922 | ** A pointer to the user supplied routine must be passed as the fifth |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3923 | ** argument. If it is NULL, this is the same as deleting the collation |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3924 | ** sequence (so that SQLite cannot call it anymore). |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3925 | ** Each time the application |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 3926 | ** supplied function is invoked, it is passed a copy of the void* passed as |
| 3927 | ** the fourth argument to sqlite3_create_collation() or |
| 3928 | ** sqlite3_create_collation16() as its first parameter. |
| 3929 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3930 | ** The remaining arguments to the application-supplied routine are two strings, |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 3931 | ** each represented by a (length, data) pair and encoded in the encoding |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 3932 | ** that was passed as the third argument when the collation sequence was |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3933 | ** registered. {END} The application defined collation routine should |
| 3934 | ** return negative, zero or positive if |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 3935 | ** the first string is less than, equal to, or greater than the second |
| 3936 | ** string. i.e. (STRING1 - STRING2). |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3937 | ** |
| 3938 | ** The sqlite3_create_collation_v2() works like sqlite3_create_collation() |
| 3939 | ** excapt that it takes an extra argument which is a destructor for |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3940 | ** the collation. The destructor is called when the collation is |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3941 | ** destroyed and is passed a copy of the fourth parameter void* pointer |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 3942 | ** of the sqlite3_create_collation_v2(). |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3943 | ** Collations are destroyed when |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 3944 | ** they are overridden by later calls to the collation creation functions |
| 3945 | ** or when the [sqlite3*] database handle is closed using [sqlite3_close()]. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 3946 | ** |
| 3947 | ** INVARIANTS: |
| 3948 | ** |
| 3949 | ** {F16603} A successful call to the |
| 3950 | ** [sqlite3_create_collation_v2(B,X,E,P,F,D)] interface |
| 3951 | ** registers function F as the comparison function used to |
| 3952 | ** implement collation X on [database connection] B for |
| 3953 | ** databases having encoding E. |
| 3954 | ** |
| 3955 | ** {F16604} SQLite understands the X parameter to |
| 3956 | ** [sqlite3_create_collation_v2(B,X,E,P,F,D)] as a zero-terminated |
| 3957 | ** UTF-8 string in which case is ignored for ASCII characters and |
| 3958 | ** is significant for non-ASCII characters. |
| 3959 | ** |
| 3960 | ** {F16606} Successive calls to [sqlite3_create_collation_v2(B,X,E,P,F,D)] |
| 3961 | ** with the same values for B, X, and E, override prior values |
| 3962 | ** of P, F, and D. |
| 3963 | ** |
| 3964 | ** {F16609} The destructor D in [sqlite3_create_collation_v2(B,X,E,P,F,D)] |
| 3965 | ** is not NULL then it is called with argument P when the |
| 3966 | ** collating function is dropped by SQLite. |
| 3967 | ** |
| 3968 | ** {F16612} A collating function is dropped when it is overloaded. |
| 3969 | ** |
| 3970 | ** {F16615} A collating function is dropped when the database connection |
| 3971 | ** is closed using [sqlite3_close()]. |
| 3972 | ** |
| 3973 | ** {F16618} The pointer P in [sqlite3_create_collation_v2(B,X,E,P,F,D)] |
| 3974 | ** is passed through as the first parameter to the comparison |
| 3975 | ** function F for all subsequent invocations of F. |
| 3976 | ** |
| 3977 | ** {F16621} A call to [sqlite3_create_collation(B,X,E,P,F)] is exactly |
| 3978 | ** the same as a call to [sqlite3_create_collation_v2()] with |
| 3979 | ** the same parameters and a NULL destructor. |
| 3980 | ** |
| 3981 | ** {F16624} Following a [sqlite3_create_collation_v2(B,X,E,P,F,D)], |
| 3982 | ** SQLite uses the comparison function F for all text comparison |
| 3983 | ** operations on [database connection] B on text values that |
| 3984 | ** use the collating sequence name X. |
| 3985 | ** |
| 3986 | ** {F16627} The [sqlite3_create_collation16(B,X,E,P,F)] works the same |
| 3987 | ** as [sqlite3_create_collation(B,X,E,P,F)] except that the |
| 3988 | ** collation name X is understood as UTF-16 in native byte order |
| 3989 | ** instead of UTF-8. |
| 3990 | ** |
| 3991 | ** {F16630} When multiple comparison functions are available for the same |
| 3992 | ** collating sequence, SQLite chooses the one whose text encoding |
| 3993 | ** requires the least amount of conversion from the default |
| 3994 | ** text encoding of the database. |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 3995 | */ |
danielk1977 | 0202b29 | 2004-06-09 09:55:16 +0000 | [diff] [blame] | 3996 | int sqlite3_create_collation( |
| 3997 | sqlite3*, |
| 3998 | const char *zName, |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 3999 | int eTextRep, |
danielk1977 | 0202b29 | 2004-06-09 09:55:16 +0000 | [diff] [blame] | 4000 | void*, |
| 4001 | int(*xCompare)(void*,int,const void*,int,const void*) |
| 4002 | ); |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4003 | int sqlite3_create_collation_v2( |
| 4004 | sqlite3*, |
| 4005 | const char *zName, |
| 4006 | int eTextRep, |
| 4007 | void*, |
| 4008 | int(*xCompare)(void*,int,const void*,int,const void*), |
| 4009 | void(*xDestroy)(void*) |
| 4010 | ); |
danielk1977 | 0202b29 | 2004-06-09 09:55:16 +0000 | [diff] [blame] | 4011 | int sqlite3_create_collation16( |
| 4012 | sqlite3*, |
| 4013 | const char *zName, |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 4014 | int eTextRep, |
danielk1977 | 0202b29 | 2004-06-09 09:55:16 +0000 | [diff] [blame] | 4015 | void*, |
| 4016 | int(*xCompare)(void*,int,const void*,int,const void*) |
| 4017 | ); |
| 4018 | |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 4019 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4020 | ** CAPI3REF: Collation Needed Callbacks {F16700} |
danielk1977 | a393c03 | 2007-05-07 14:58:53 +0000 | [diff] [blame] | 4021 | ** |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 4022 | ** To avoid having to register all collation sequences before a database |
| 4023 | ** can be used, a single callback function may be registered with the |
| 4024 | ** database handle to be called whenever an undefined collation sequence is |
| 4025 | ** required. |
| 4026 | ** |
| 4027 | ** If the function is registered using the sqlite3_collation_needed() API, |
| 4028 | ** then it is passed the names of undefined collation sequences as strings |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4029 | ** encoded in UTF-8. {F16703} If sqlite3_collation_needed16() is used, the names |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4030 | ** are passed as UTF-16 in machine native byte order. A call to either |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 4031 | ** function replaces any existing callback. |
| 4032 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4033 | ** When the callback is invoked, the first argument passed is a copy |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 4034 | ** of the second argument to sqlite3_collation_needed() or |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4035 | ** sqlite3_collation_needed16(). The second argument is the database |
| 4036 | ** handle. The third argument is one of [SQLITE_UTF8], |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4037 | ** [SQLITE_UTF16BE], or [SQLITE_UTF16LE], indicating the most |
| 4038 | ** desirable form of the collation sequence function required. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4039 | ** The fourth parameter is the name of the |
| 4040 | ** required collation sequence. |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 4041 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4042 | ** The callback function should register the desired collation using |
| 4043 | ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or |
| 4044 | ** [sqlite3_create_collation_v2()]. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4045 | ** |
| 4046 | ** INVARIANTS: |
| 4047 | ** |
| 4048 | ** {F16702} A successful call to [sqlite3_collation_needed(D,P,F)] |
| 4049 | ** or [sqlite3_collation_needed16(D,P,F)] causes |
| 4050 | ** the [database connection] D to invoke callback F with first |
| 4051 | ** parameter P whenever it needs a comparison function for a |
| 4052 | ** collating sequence that it does not know about. |
| 4053 | ** |
| 4054 | ** {F16704} Each successful call to [sqlite3_collation_needed()] or |
| 4055 | ** [sqlite3_collation_needed16()] overrides the callback registered |
| 4056 | ** on the same [database connection] by prior calls to either |
| 4057 | ** interface. |
| 4058 | ** |
| 4059 | ** {F16706} The name of the requested collating function passed in the |
| 4060 | ** 4th parameter to the callback is in UTF-8 if the callback |
| 4061 | ** was registered using [sqlite3_collation_needed()] and |
| 4062 | ** is in UTF-16 native byte order if the callback was |
| 4063 | ** registered using [sqlite3_collation_needed16()]. |
| 4064 | ** |
| 4065 | ** |
danielk1977 | 7cedc8d | 2004-06-10 10:50:08 +0000 | [diff] [blame] | 4066 | */ |
| 4067 | int sqlite3_collation_needed( |
| 4068 | sqlite3*, |
| 4069 | void*, |
| 4070 | void(*)(void*,sqlite3*,int eTextRep,const char*) |
| 4071 | ); |
| 4072 | int sqlite3_collation_needed16( |
| 4073 | sqlite3*, |
| 4074 | void*, |
| 4075 | void(*)(void*,sqlite3*,int eTextRep,const void*) |
| 4076 | ); |
| 4077 | |
drh | 2011d5f | 2004-07-22 02:40:37 +0000 | [diff] [blame] | 4078 | /* |
| 4079 | ** Specify the key for an encrypted database. This routine should be |
| 4080 | ** called right after sqlite3_open(). |
| 4081 | ** |
| 4082 | ** The code to implement this API is not available in the public release |
| 4083 | ** of SQLite. |
| 4084 | */ |
| 4085 | int sqlite3_key( |
| 4086 | sqlite3 *db, /* Database to be rekeyed */ |
| 4087 | const void *pKey, int nKey /* The key */ |
| 4088 | ); |
| 4089 | |
| 4090 | /* |
| 4091 | ** Change the key on an open database. If the current database is not |
| 4092 | ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the |
| 4093 | ** database is decrypted. |
| 4094 | ** |
| 4095 | ** The code to implement this API is not available in the public release |
| 4096 | ** of SQLite. |
| 4097 | */ |
| 4098 | int sqlite3_rekey( |
| 4099 | sqlite3 *db, /* Database to be rekeyed */ |
| 4100 | const void *pKey, int nKey /* The new key */ |
| 4101 | ); |
danielk1977 | 0202b29 | 2004-06-09 09:55:16 +0000 | [diff] [blame] | 4102 | |
drh | ab3f9fe | 2004-08-14 17:10:10 +0000 | [diff] [blame] | 4103 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4104 | ** CAPI3REF: Suspend Execution For A Short Time {F10530} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4105 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4106 | ** The sqlite3_sleep() function |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4107 | ** causes the current thread to suspend execution |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4108 | ** for at least a number of milliseconds specified in its parameter. |
danielk1977 | 600dd0b | 2005-01-20 01:14:23 +0000 | [diff] [blame] | 4109 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4110 | ** If the operating system does not support sleep requests with |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4111 | ** millisecond time resolution, then the time will be rounded up to |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4112 | ** the nearest second. The number of milliseconds of sleep actually |
danielk1977 | 600dd0b | 2005-01-20 01:14:23 +0000 | [diff] [blame] | 4113 | ** requested from the operating system is returned. |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 4114 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4115 | ** SQLite implements this interface by calling the xSleep() |
| 4116 | ** method of the default [sqlite3_vfs] object. |
| 4117 | ** |
| 4118 | ** INVARIANTS: |
| 4119 | ** |
| 4120 | ** {F10533} The [sqlite3_sleep(M)] interface invokes the xSleep |
| 4121 | ** method of the default [sqlite3_vfs|VFS] in order to |
| 4122 | ** suspend execution of the current thread for at least |
| 4123 | ** M milliseconds. |
| 4124 | ** |
| 4125 | ** {F10536} The [sqlite3_sleep(M)] interface returns the number of |
| 4126 | ** milliseconds of sleep actually requested of the operating |
| 4127 | ** system, which might be larger than the parameter M. |
danielk1977 | 600dd0b | 2005-01-20 01:14:23 +0000 | [diff] [blame] | 4128 | */ |
| 4129 | int sqlite3_sleep(int); |
| 4130 | |
| 4131 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4132 | ** CAPI3REF: Name Of The Folder Holding Temporary Files {F10310} |
drh | d89bd00 | 2005-01-22 03:03:54 +0000 | [diff] [blame] | 4133 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4134 | ** If this global variable is made to point to a string which is |
| 4135 | ** the name of a folder (a.ka. directory), then all temporary files |
drh | ab3f9fe | 2004-08-14 17:10:10 +0000 | [diff] [blame] | 4136 | ** created by SQLite will be placed in that directory. If this variable |
| 4137 | ** is NULL pointer, then SQLite does a search for an appropriate temporary |
| 4138 | ** file directory. |
| 4139 | ** |
drh | 4ff7fa0 | 2007-09-01 18:17:21 +0000 | [diff] [blame] | 4140 | ** It is not safe to modify this variable once a database connection |
| 4141 | ** has been opened. It is intended that this variable be set once |
| 4142 | ** as part of process initialization and before any SQLite interface |
| 4143 | ** routines have been call and remain unchanged thereafter. |
drh | ab3f9fe | 2004-08-14 17:10:10 +0000 | [diff] [blame] | 4144 | */ |
drh | 73be501 | 2007-08-08 12:11:21 +0000 | [diff] [blame] | 4145 | SQLITE_EXTERN char *sqlite3_temp_directory; |
drh | ab3f9fe | 2004-08-14 17:10:10 +0000 | [diff] [blame] | 4146 | |
danielk1977 | 6b456a2 | 2005-03-21 04:04:02 +0000 | [diff] [blame] | 4147 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4148 | ** CAPI3REF: Test To See If The Database Is In Auto-Commit Mode {F12930} |
danielk1977 | 6b456a2 | 2005-03-21 04:04:02 +0000 | [diff] [blame] | 4149 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 4150 | ** The sqlite3_get_autocommit() interfaces returns non-zero or |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4151 | ** zero if the given database connection is or is not in autocommit mode, |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 4152 | ** respectively. Autocommit mode is on |
| 4153 | ** by default. Autocommit mode is disabled by a [BEGIN] statement. |
| 4154 | ** Autocommit mode is reenabled by a [COMMIT] or [ROLLBACK]. |
drh | e30f442 | 2007-08-21 16:15:55 +0000 | [diff] [blame] | 4155 | ** |
drh | 7c3472a | 2007-10-03 20:15:28 +0000 | [diff] [blame] | 4156 | ** If certain kinds of errors occur on a statement within a multi-statement |
| 4157 | ** transactions (errors including [SQLITE_FULL], [SQLITE_IOERR], |
| 4158 | ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 4159 | ** transaction might be rolled back automatically. The only way to |
drh | 7c3472a | 2007-10-03 20:15:28 +0000 | [diff] [blame] | 4160 | ** find out if SQLite automatically rolled back the transaction after |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 4161 | ** an error is to use this function. |
drh | 7c3472a | 2007-10-03 20:15:28 +0000 | [diff] [blame] | 4162 | ** |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 4163 | ** INVARIANTS: |
| 4164 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4165 | ** {F12931} The [sqlite3_get_autocommit(D)] interface returns non-zero or |
| 4166 | ** zero if the [database connection] D is or is not in autocommit |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 4167 | ** mode, respectively. |
| 4168 | ** |
| 4169 | ** {F12932} Autocommit mode is on by default. |
| 4170 | ** |
| 4171 | ** {F12933} Autocommit mode is disabled by a successful [BEGIN] statement. |
| 4172 | ** |
| 4173 | ** {F12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK] |
| 4174 | ** statement. |
| 4175 | ** |
| 4176 | ** |
| 4177 | ** LIMITATIONS: |
| 4178 | *** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4179 | ** {U12936} If another thread changes the autocommit status of the database |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 4180 | ** connection while this routine is running, then the return value |
| 4181 | ** is undefined. |
drh | 3e1d8e6 | 2005-05-26 16:23:34 +0000 | [diff] [blame] | 4182 | */ |
| 4183 | int sqlite3_get_autocommit(sqlite3*); |
| 4184 | |
drh | 51942bc | 2005-06-12 22:01:42 +0000 | [diff] [blame] | 4185 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4186 | ** CAPI3REF: Find The Database Handle Of A Prepared Statement {F13120} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4187 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4188 | ** The sqlite3_db_handle interface |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4189 | ** returns the [sqlite3*] database handle to which a |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 4190 | ** [prepared statement] belongs. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4191 | ** The database handle returned by sqlite3_db_handle |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4192 | ** is the same database handle that was |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4193 | ** the first argument to the [sqlite3_prepare_v2()] or its variants |
| 4194 | ** that was used to create the statement in the first place. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4195 | ** |
| 4196 | ** INVARIANTS: |
| 4197 | ** |
| 4198 | ** {F13123} The [sqlite3_db_handle(S)] interface returns a pointer |
| 4199 | ** to the [database connection] associated with |
| 4200 | ** [prepared statement] S. |
drh | 51942bc | 2005-06-12 22:01:42 +0000 | [diff] [blame] | 4201 | */ |
| 4202 | sqlite3 *sqlite3_db_handle(sqlite3_stmt*); |
drh | 3e1d8e6 | 2005-05-26 16:23:34 +0000 | [diff] [blame] | 4203 | |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4204 | |
drh | b37df7b | 2005-10-13 02:09:49 +0000 | [diff] [blame] | 4205 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4206 | ** CAPI3REF: Commit And Rollback Notification Callbacks {F12950} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4207 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4208 | ** The sqlite3_commit_hook() interface registers a callback |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4209 | ** function to be invoked whenever a transaction is committed. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4210 | ** Any callback set by a previous call to sqlite3_commit_hook() |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4211 | ** for the same database connection is overridden. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4212 | ** The sqlite3_rollback_hook() interface registers a callback |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4213 | ** function to be invoked whenever a transaction is committed. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4214 | ** Any callback set by a previous call to sqlite3_commit_hook() |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4215 | ** for the same database connection is overridden. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4216 | ** The pArg argument is passed through |
| 4217 | ** to the callback. If the callback on a commit hook function |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4218 | ** returns non-zero, then the commit is converted into a rollback. |
| 4219 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4220 | ** If another function was previously registered, its |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4221 | ** pArg value is returned. Otherwise NULL is returned. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4222 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4223 | ** Registering a NULL function disables the callback. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4224 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4225 | ** For the purposes of this API, a transaction is said to have been |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4226 | ** rolled back if an explicit "ROLLBACK" statement is executed, or |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4227 | ** an error or constraint causes an implicit rollback to occur. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4228 | ** The rollback callback is not invoked if a transaction is |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4229 | ** automatically rolled back because the database connection is closed. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4230 | ** The rollback callback is not invoked if a transaction is |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4231 | ** rolled back because a commit callback returned non-zero. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4232 | ** <todo> Check on this </todo> |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4233 | ** |
| 4234 | ** These are experimental interfaces and are subject to change. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4235 | ** |
| 4236 | ** INVARIANTS: |
| 4237 | ** |
| 4238 | ** {F12951} The [sqlite3_commit_hook(D,F,P)] interface registers the |
| 4239 | ** callback function F to be invoked with argument P whenever |
| 4240 | ** a transaction commits on [database connection] D. |
| 4241 | ** |
| 4242 | ** {F12952} The [sqlite3_commit_hook(D,F,P)] interface returns the P |
| 4243 | ** argument from the previous call with the same |
| 4244 | ** [database connection ] D , or NULL on the first call |
| 4245 | ** for a particular [database connection] D. |
| 4246 | ** |
| 4247 | ** {F12953} Each call to [sqlite3_commit_hook()] overwrites the callback |
| 4248 | ** registered by prior calls. |
| 4249 | ** |
| 4250 | ** {F12954} If the F argument to [sqlite3_commit_hook(D,F,P)] is NULL |
| 4251 | ** then the commit hook callback is cancelled and no callback |
| 4252 | ** is invoked when a transaction commits. |
| 4253 | ** |
| 4254 | ** {F12955} If the commit callback returns non-zero then the commit is |
| 4255 | ** converted into a rollback. |
| 4256 | ** |
| 4257 | ** {F12961} The [sqlite3_rollback_hook(D,F,P)] interface registers the |
| 4258 | ** callback function F to be invoked with argument P whenever |
| 4259 | ** a transaction rolls back on [database connection] D. |
| 4260 | ** |
| 4261 | ** {F12962} The [sqlite3_rollback_hook(D,F,P)] interface returns the P |
| 4262 | ** argument from the previous call with the same |
| 4263 | ** [database connection ] D , or NULL on the first call |
| 4264 | ** for a particular [database connection] D. |
| 4265 | ** |
| 4266 | ** {F12963} Each call to [sqlite3_rollback_hook()] overwrites the callback |
| 4267 | ** registered by prior calls. |
| 4268 | ** |
| 4269 | ** {F12964} If the F argument to [sqlite3_rollback_hook(D,F,P)] is NULL |
| 4270 | ** then the rollback hook callback is cancelled and no callback |
| 4271 | ** is invoked when a transaction rolls back. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4272 | */ |
| 4273 | void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); |
| 4274 | void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); |
| 4275 | |
| 4276 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4277 | ** CAPI3REF: Data Change Notification Callbacks {F12970} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4278 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4279 | ** The sqlite3_update_hook() interface |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4280 | ** registers a callback function with the database connection identified by the |
danielk1977 | 94eb6a1 | 2005-12-15 15:22:08 +0000 | [diff] [blame] | 4281 | ** first argument to be invoked whenever a row is updated, inserted or deleted. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4282 | ** Any callback set by a previous call to this function for the same |
danielk1977 | 94eb6a1 | 2005-12-15 15:22:08 +0000 | [diff] [blame] | 4283 | ** database connection is overridden. |
| 4284 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4285 | ** The second argument is a pointer to the function to invoke when a |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4286 | ** row is updated, inserted or deleted. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4287 | ** The first argument to the callback is |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4288 | ** a copy of the third argument to sqlite3_update_hook(). |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4289 | ** The second callback |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4290 | ** argument is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], |
| 4291 | ** depending on the operation that caused the callback to be invoked. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4292 | ** The third and |
danielk1977 | 94eb6a1 | 2005-12-15 15:22:08 +0000 | [diff] [blame] | 4293 | ** fourth arguments to the callback contain pointers to the database and |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4294 | ** table name containing the affected row. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4295 | ** The final callback parameter is |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4296 | ** the rowid of the row. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4297 | ** In the case of an update, this is the rowid after |
danielk1977 | 94eb6a1 | 2005-12-15 15:22:08 +0000 | [diff] [blame] | 4298 | ** the update takes place. |
| 4299 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4300 | ** The update hook is not invoked when internal system tables are |
danielk1977 | 94eb6a1 | 2005-12-15 15:22:08 +0000 | [diff] [blame] | 4301 | ** modified (i.e. sqlite_master and sqlite_sequence). |
danielk1977 | 71fd80b | 2005-12-16 06:54:01 +0000 | [diff] [blame] | 4302 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4303 | ** If another function was previously registered, its pArg value |
| 4304 | ** is returned. Otherwise NULL is returned. |
| 4305 | ** |
| 4306 | ** INVARIANTS: |
| 4307 | ** |
| 4308 | ** {F12971} The [sqlite3_update_hook(D,F,P)] interface causes callback |
| 4309 | ** function F to be invoked with first parameter P whenever |
| 4310 | ** a table row is modified, inserted, or deleted on |
| 4311 | ** [database connection] D. |
| 4312 | ** |
| 4313 | ** {F12973} The [sqlite3_update_hook(D,F,P)] interface returns the value |
| 4314 | ** of P for the previous call on the same [database connection] D, |
| 4315 | ** or NULL for the first call. |
| 4316 | ** |
| 4317 | ** {F12975} If the update hook callback F in [sqlite3_update_hook(D,F,P)] |
| 4318 | ** is NULL then the no update callbacks are made. |
| 4319 | ** |
| 4320 | ** {F12977} Each call to [sqlite3_update_hook(D,F,P)] overrides prior calls |
| 4321 | ** to the same interface on the same [database connection] D. |
| 4322 | ** |
| 4323 | ** {F12979} The update hook callback is not invoked when internal system |
| 4324 | ** tables such as sqlite_master and sqlite_sequence are modified. |
| 4325 | ** |
| 4326 | ** {F12981} The second parameter to the update callback |
| 4327 | ** is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], |
| 4328 | ** depending on the operation that caused the callback to be invoked. |
| 4329 | ** |
| 4330 | ** {F12983} The third and fourth arguments to the callback contain pointers |
| 4331 | ** to zero-terminated UTF-8 strings which are the names of the |
| 4332 | ** database and table that is being updated. |
| 4333 | |
| 4334 | ** {F12985} The final callback parameter is the rowid of the row after |
| 4335 | ** the change occurs. |
danielk1977 | 94eb6a1 | 2005-12-15 15:22:08 +0000 | [diff] [blame] | 4336 | */ |
danielk1977 | 71fd80b | 2005-12-16 06:54:01 +0000 | [diff] [blame] | 4337 | void *sqlite3_update_hook( |
danielk1977 | 94eb6a1 | 2005-12-15 15:22:08 +0000 | [diff] [blame] | 4338 | sqlite3*, |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 4339 | void(*)(void *,int ,char const *,char const *,sqlite3_int64), |
danielk1977 | 94eb6a1 | 2005-12-15 15:22:08 +0000 | [diff] [blame] | 4340 | void* |
| 4341 | ); |
danielk1977 | 13a68c3 | 2005-12-15 10:11:30 +0000 | [diff] [blame] | 4342 | |
danielk1977 | f3f06bb | 2005-12-16 15:24:28 +0000 | [diff] [blame] | 4343 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4344 | ** CAPI3REF: Enable Or Disable Shared Pager Cache {F10330} |
danielk1977 | f3f06bb | 2005-12-16 15:24:28 +0000 | [diff] [blame] | 4345 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4346 | ** This routine enables or disables the sharing of the database cache |
| 4347 | ** and schema data structures between connections to the same database. |
| 4348 | ** Sharing is enabled if the argument is true and disabled if the argument |
| 4349 | ** is false. |
danielk1977 | f3f06bb | 2005-12-16 15:24:28 +0000 | [diff] [blame] | 4350 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4351 | ** Cache sharing is enabled and disabled |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4352 | ** for an entire process. {END} This is a change as of SQLite version 3.5.0. |
| 4353 | ** In prior versions of SQLite, sharing was |
drh | e30f442 | 2007-08-21 16:15:55 +0000 | [diff] [blame] | 4354 | ** enabled or disabled for each thread separately. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4355 | ** |
drh | e30f442 | 2007-08-21 16:15:55 +0000 | [diff] [blame] | 4356 | ** The cache sharing mode set by this interface effects all subsequent |
| 4357 | ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()]. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4358 | ** Existing database connections continue use the sharing mode |
| 4359 | ** that was in effect at the time they were opened. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4360 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4361 | ** Virtual tables cannot be used with a shared cache. When shared |
drh | 4ff7fa0 | 2007-09-01 18:17:21 +0000 | [diff] [blame] | 4362 | ** cache is enabled, the [sqlite3_create_module()] API used to register |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4363 | ** virtual tables will always return an error. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4364 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4365 | ** This routine returns [SQLITE_OK] if shared cache was |
| 4366 | ** enabled or disabled successfully. An [error code] |
| 4367 | ** is returned otherwise. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4368 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4369 | ** Shared cache is disabled by default. But this might change in |
drh | 4ff7fa0 | 2007-09-01 18:17:21 +0000 | [diff] [blame] | 4370 | ** future releases of SQLite. Applications that care about shared |
| 4371 | ** cache setting should set it explicitly. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4372 | ** |
| 4373 | ** INVARIANTS: |
| 4374 | ** |
| 4375 | ** {F10331} A successful invocation of [sqlite3_enable_shared_cache(B)] |
| 4376 | ** will enable or disable shared cache mode for any subsequently |
| 4377 | ** created [database connection] in the same process. |
| 4378 | ** |
| 4379 | ** {F10336} When shared cache is enabled, the [sqlite3_create_module()] |
| 4380 | ** interface will always return an error. |
| 4381 | ** |
| 4382 | ** {F10337} The [sqlite3_enable_shared_cache(B)] interface returns |
| 4383 | ** [SQLITE_OK] if shared cache was enabled or disabled successfully. |
| 4384 | ** |
| 4385 | ** {F10339} Shared cache is disabled by default. |
danielk1977 | aef0bf6 | 2005-12-30 16:28:01 +0000 | [diff] [blame] | 4386 | */ |
| 4387 | int sqlite3_enable_shared_cache(int); |
| 4388 | |
| 4389 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4390 | ** CAPI3REF: Attempt To Free Heap Memory {F17340} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4391 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4392 | ** The sqlite3_release_memory() interface attempts to |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4393 | ** free N bytes of heap memory by deallocating non-essential memory |
| 4394 | ** allocations held by the database labrary. {END} Memory used |
| 4395 | ** to cache database pages to improve performance is an example of |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4396 | ** non-essential memory. Sqlite3_release_memory() returns |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4397 | ** the number of bytes actually freed, which might be more or less |
| 4398 | ** than the amount requested. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4399 | ** |
| 4400 | ** INVARIANTS: |
| 4401 | ** |
| 4402 | ** {F17341} The [sqlite3_release_memory(N)] interface attempts to |
| 4403 | ** free N bytes of heap memory by deallocating non-essential |
| 4404 | ** memory allocations held by the database labrary. |
| 4405 | ** |
| 4406 | ** {F16342} The [sqlite3_release_memory(N)] returns the number |
| 4407 | ** of bytes actually freed, which might be more or less |
| 4408 | ** than the amount requested. |
danielk1977 | 5262282 | 2006-01-09 09:59:49 +0000 | [diff] [blame] | 4409 | */ |
| 4410 | int sqlite3_release_memory(int); |
| 4411 | |
| 4412 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4413 | ** CAPI3REF: Impose A Limit On Heap Size {F17350} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4414 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4415 | ** The sqlite3_soft_heap_limit() interface |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4416 | ** places a "soft" limit on the amount of heap memory that may be allocated |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4417 | ** by SQLite. If an internal allocation is requested |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4418 | ** that would exceed the soft heap limit, [sqlite3_release_memory()] is |
drh | e30f442 | 2007-08-21 16:15:55 +0000 | [diff] [blame] | 4419 | ** invoked one or more times to free up some space before the allocation |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4420 | ** is made. |
danielk1977 | 5262282 | 2006-01-09 09:59:49 +0000 | [diff] [blame] | 4421 | ** |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4422 | ** The limit is called "soft", because if |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4423 | ** [sqlite3_release_memory()] cannot |
drh | e30f442 | 2007-08-21 16:15:55 +0000 | [diff] [blame] | 4424 | ** free sufficient memory to prevent the limit from being exceeded, |
| 4425 | ** the memory is allocated anyway and the current operation proceeds. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4426 | ** |
| 4427 | ** A negative or zero value for N means that there is no soft heap limit and |
drh | e30f442 | 2007-08-21 16:15:55 +0000 | [diff] [blame] | 4428 | ** [sqlite3_release_memory()] will only be called when memory is exhausted. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4429 | ** The default value for the soft heap limit is zero. |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4430 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4431 | ** SQLite makes a best effort to honor the soft heap limit. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4432 | ** But if the soft heap limit cannot honored, execution will |
| 4433 | ** continue without error or notification. This is why the limit is |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4434 | ** called a "soft" limit. It is advisory only. |
| 4435 | ** |
drh | e30f442 | 2007-08-21 16:15:55 +0000 | [diff] [blame] | 4436 | ** Prior to SQLite version 3.5.0, this routine only constrained the memory |
| 4437 | ** allocated by a single thread - the same thread in which this routine |
| 4438 | ** runs. Beginning with SQLite version 3.5.0, the soft heap limit is |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4439 | ** applied to all threads. The value specified for the soft heap limit |
| 4440 | ** is an upper bound on the total memory allocation for all threads. In |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 4441 | ** version 3.5.0 there is no mechanism for limiting the heap usage for |
| 4442 | ** individual threads. |
drh | afc9104 | 2008-02-21 02:09:45 +0000 | [diff] [blame] | 4443 | ** |
| 4444 | ** INVARIANTS: |
| 4445 | ** |
| 4446 | ** {F16351} The [sqlite3_soft_heap_limit(N)] interface places a soft limit |
| 4447 | ** of N bytes on the amount of heap memory that may be allocated |
| 4448 | ** using [sqlite3_malloc()] or [sqlite3_realloc()] at any point |
| 4449 | ** in time. |
| 4450 | ** |
| 4451 | ** {F16352} If a call to [sqlite3_malloc()] or [sqlite3_realloc()] would |
| 4452 | ** cause the total amount of allocated memory to exceed the |
| 4453 | ** soft heap limit, then [sqlite3_release_memory()] is invoked |
| 4454 | ** in an attempt to reduce the memory usage prior to proceeding |
| 4455 | ** with the memory allocation attempt. |
| 4456 | ** |
| 4457 | ** {F16353} Calls to [sqlite3_malloc()] or [sqlite3_realloc()] that trigger |
| 4458 | ** attempts to reduce memory usage through the soft heap limit |
| 4459 | ** mechanism continue even if the attempt to reduce memory |
| 4460 | ** usage is unsuccessful. |
| 4461 | ** |
| 4462 | ** {F16354} A negative or zero value for N in a call to |
| 4463 | ** [sqlite3_soft_heap_limit(N)] means that there is no soft |
| 4464 | ** heap limit and [sqlite3_release_memory()] will only be |
| 4465 | ** called when memory is completely exhausted. |
| 4466 | ** |
| 4467 | ** {F16355} The default value for the soft heap limit is zero. |
| 4468 | ** |
| 4469 | ** {F16358} Each call to [sqlite3_soft_heap_limit(N)] overrides the |
| 4470 | ** values set by all prior calls. |
danielk1977 | 5262282 | 2006-01-09 09:59:49 +0000 | [diff] [blame] | 4471 | */ |
drh | d2d4a6b | 2006-01-10 15:18:27 +0000 | [diff] [blame] | 4472 | void sqlite3_soft_heap_limit(int); |
danielk1977 | 5262282 | 2006-01-09 09:59:49 +0000 | [diff] [blame] | 4473 | |
| 4474 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4475 | ** CAPI3REF: Extract Metadata About A Column Of A Table {F12850} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4476 | ** |
| 4477 | ** This routine |
| 4478 | ** returns meta-data about a specific column of a specific database |
danielk1977 | deb802c | 2006-02-09 13:43:28 +0000 | [diff] [blame] | 4479 | ** table accessible using the connection handle passed as the first function |
| 4480 | ** argument. |
| 4481 | ** |
| 4482 | ** The column is identified by the second, third and fourth parameters to |
| 4483 | ** this function. The second parameter is either the name of the database |
| 4484 | ** (i.e. "main", "temp" or an attached database) containing the specified |
| 4485 | ** table or NULL. If it is NULL, then all attached databases are searched |
| 4486 | ** for the table using the same algorithm as the database engine uses to |
| 4487 | ** resolve unqualified table references. |
| 4488 | ** |
| 4489 | ** The third and fourth parameters to this function are the table and column |
| 4490 | ** name of the desired column, respectively. Neither of these parameters |
| 4491 | ** may be NULL. |
| 4492 | ** |
| 4493 | ** Meta information is returned by writing to the memory locations passed as |
| 4494 | ** the 5th and subsequent parameters to this function. Any of these |
| 4495 | ** arguments may be NULL, in which case the corresponding element of meta |
| 4496 | ** information is ommitted. |
| 4497 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4498 | ** <pre> |
danielk1977 | deb802c | 2006-02-09 13:43:28 +0000 | [diff] [blame] | 4499 | ** Parameter Output Type Description |
| 4500 | ** ----------------------------------- |
| 4501 | ** |
| 4502 | ** 5th const char* Data type |
| 4503 | ** 6th const char* Name of the default collation sequence |
| 4504 | ** 7th int True if the column has a NOT NULL constraint |
| 4505 | ** 8th int True if the column is part of the PRIMARY KEY |
| 4506 | ** 9th int True if the column is AUTOINCREMENT |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4507 | ** </pre> |
danielk1977 | deb802c | 2006-02-09 13:43:28 +0000 | [diff] [blame] | 4508 | ** |
| 4509 | ** |
| 4510 | ** The memory pointed to by the character pointers returned for the |
| 4511 | ** declaration type and collation sequence is valid only until the next |
| 4512 | ** call to any sqlite API function. |
| 4513 | ** |
| 4514 | ** If the specified table is actually a view, then an error is returned. |
| 4515 | ** |
| 4516 | ** If the specified column is "rowid", "oid" or "_rowid_" and an |
| 4517 | ** INTEGER PRIMARY KEY column has been explicitly declared, then the output |
| 4518 | ** parameters are set for the explicitly declared column. If there is no |
| 4519 | ** explicitly declared IPK column, then the output parameters are set as |
| 4520 | ** follows: |
| 4521 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4522 | ** <pre> |
danielk1977 | deb802c | 2006-02-09 13:43:28 +0000 | [diff] [blame] | 4523 | ** data type: "INTEGER" |
| 4524 | ** collation sequence: "BINARY" |
| 4525 | ** not null: 0 |
| 4526 | ** primary key: 1 |
| 4527 | ** auto increment: 0 |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4528 | ** </pre> |
danielk1977 | deb802c | 2006-02-09 13:43:28 +0000 | [diff] [blame] | 4529 | ** |
| 4530 | ** This function may load one or more schemas from database files. If an |
| 4531 | ** error occurs during this process, or if the requested table or column |
| 4532 | ** cannot be found, an SQLITE error code is returned and an error message |
| 4533 | ** left in the database handle (to be retrieved using sqlite3_errmsg()). |
danielk1977 | 4b1ae99 | 2006-02-10 03:06:10 +0000 | [diff] [blame] | 4534 | ** |
| 4535 | ** This API is only available if the library was compiled with the |
| 4536 | ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. |
danielk1977 | deb802c | 2006-02-09 13:43:28 +0000 | [diff] [blame] | 4537 | */ |
| 4538 | int sqlite3_table_column_metadata( |
| 4539 | sqlite3 *db, /* Connection handle */ |
| 4540 | const char *zDbName, /* Database name or NULL */ |
| 4541 | const char *zTableName, /* Table name */ |
| 4542 | const char *zColumnName, /* Column name */ |
| 4543 | char const **pzDataType, /* OUTPUT: Declared data type */ |
| 4544 | char const **pzCollSeq, /* OUTPUT: Collation sequence name */ |
| 4545 | int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ |
| 4546 | int *pPrimaryKey, /* OUTPUT: True if column part of PK */ |
drh | 98c9480 | 2007-10-01 13:50:31 +0000 | [diff] [blame] | 4547 | int *pAutoinc /* OUTPUT: True if column is auto-increment */ |
danielk1977 | deb802c | 2006-02-09 13:43:28 +0000 | [diff] [blame] | 4548 | ); |
| 4549 | |
| 4550 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4551 | ** CAPI3REF: Load An Extension {F12600} |
drh | 1e397f8 | 2006-06-08 15:28:43 +0000 | [diff] [blame] | 4552 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4553 | ** {F12601} The sqlite3_load_extension() interface |
| 4554 | ** attempts to load an SQLite extension library contained in the file |
| 4555 | ** zFile. {F12602} The entry point is zProc. {F12603} zProc may be 0 |
| 4556 | ** in which case the name of the entry point defaults |
| 4557 | ** to "sqlite3_extension_init". |
drh | 1e397f8 | 2006-06-08 15:28:43 +0000 | [diff] [blame] | 4558 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4559 | ** {F12604} The sqlite3_load_extension() interface shall |
| 4560 | ** return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. |
drh | 1e397f8 | 2006-06-08 15:28:43 +0000 | [diff] [blame] | 4561 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4562 | ** {F12605} |
| 4563 | ** If an error occurs and pzErrMsg is not 0, then the |
| 4564 | ** sqlite3_load_extension() interface shall attempt to fill *pzErrMsg with |
| 4565 | ** error message text stored in memory obtained from [sqlite3_malloc()]. |
| 4566 | ** {END} The calling function should free this memory |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4567 | ** by calling [sqlite3_free()]. |
drh | 1e397f8 | 2006-06-08 15:28:43 +0000 | [diff] [blame] | 4568 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4569 | ** {F12606} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4570 | ** Extension loading must be enabled using [sqlite3_enable_load_extension()] |
drh | c2e87a3 | 2006-06-27 15:16:14 +0000 | [diff] [blame] | 4571 | ** prior to calling this API or an error will be returned. |
drh | 1e397f8 | 2006-06-08 15:28:43 +0000 | [diff] [blame] | 4572 | */ |
| 4573 | int sqlite3_load_extension( |
| 4574 | sqlite3 *db, /* Load the extension into this database connection */ |
| 4575 | const char *zFile, /* Name of the shared library containing extension */ |
| 4576 | const char *zProc, /* Entry point. Derived from zFile if 0 */ |
| 4577 | char **pzErrMsg /* Put error message here if not 0 */ |
| 4578 | ); |
| 4579 | |
| 4580 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4581 | ** CAPI3REF: Enable Or Disable Extension Loading {F12620} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4582 | ** |
drh | c2e87a3 | 2006-06-27 15:16:14 +0000 | [diff] [blame] | 4583 | ** So as not to open security holes in older applications that are |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4584 | ** unprepared to deal with extension loading, and as a means of disabling |
| 4585 | ** extension loading while evaluating user-entered SQL, the following |
| 4586 | ** API is provided to turn the [sqlite3_load_extension()] mechanism on and |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4587 | ** off. {F12622} It is off by default. {END} See ticket #1863. |
drh | c2e87a3 | 2006-06-27 15:16:14 +0000 | [diff] [blame] | 4588 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4589 | ** {F12621} Call the sqlite3_enable_load_extension() routine |
| 4590 | ** with onoff==1 to turn extension loading on |
| 4591 | ** and call it with onoff==0 to turn it back off again. {END} |
drh | c2e87a3 | 2006-06-27 15:16:14 +0000 | [diff] [blame] | 4592 | */ |
| 4593 | int sqlite3_enable_load_extension(sqlite3 *db, int onoff); |
| 4594 | |
| 4595 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4596 | ** CAPI3REF: Make Arrangements To Automatically Load An Extension {F12640} |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4597 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4598 | ** {F12641} This function |
| 4599 | ** registers an extension entry point that is automatically invoked |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4600 | ** whenever a new database connection is opened using |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4601 | ** [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()]. {END} |
drh | 1409be6 | 2006-08-23 20:07:20 +0000 | [diff] [blame] | 4602 | ** |
| 4603 | ** This API can be invoked at program startup in order to register |
| 4604 | ** one or more statically linked extensions that will be available |
| 4605 | ** to all new database connections. |
| 4606 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4607 | ** {F12642} Duplicate extensions are detected so calling this routine multiple |
drh | 1409be6 | 2006-08-23 20:07:20 +0000 | [diff] [blame] | 4608 | ** times with the same extension is harmless. |
| 4609 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4610 | ** {F12643} This routine stores a pointer to the extension in an array |
| 4611 | ** that is obtained from sqlite_malloc(). {END} If you run a memory leak |
drh | 1409be6 | 2006-08-23 20:07:20 +0000 | [diff] [blame] | 4612 | ** checker on your program and it reports a leak because of this |
drh | cfa063b | 2007-11-21 15:24:00 +0000 | [diff] [blame] | 4613 | ** array, then invoke [sqlite3_reset_auto_extension()] prior |
drh | 1409be6 | 2006-08-23 20:07:20 +0000 | [diff] [blame] | 4614 | ** to shutdown to free the memory. |
| 4615 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4616 | ** {F12644} Automatic extensions apply across all threads. {END} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4617 | ** |
| 4618 | ** This interface is experimental and is subject to change or |
| 4619 | ** removal in future releases of SQLite. |
drh | 1409be6 | 2006-08-23 20:07:20 +0000 | [diff] [blame] | 4620 | */ |
| 4621 | int sqlite3_auto_extension(void *xEntryPoint); |
| 4622 | |
| 4623 | |
| 4624 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4625 | ** CAPI3REF: Reset Automatic Extension Loading {F12660} |
drh | 1409be6 | 2006-08-23 20:07:20 +0000 | [diff] [blame] | 4626 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4627 | ** {F12661} This function disables all previously registered |
| 4628 | ** automatic extensions. {END} This |
drh | 21ac7f9 | 2008-01-31 12:26:49 +0000 | [diff] [blame] | 4629 | ** routine undoes the effect of all prior [sqlite3_auto_extension()] |
drh | 1409be6 | 2006-08-23 20:07:20 +0000 | [diff] [blame] | 4630 | ** calls. |
| 4631 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4632 | ** {F12662} This call disabled automatic extensions in all threads. {END} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4633 | ** |
| 4634 | ** This interface is experimental and is subject to change or |
| 4635 | ** removal in future releases of SQLite. |
drh | 1409be6 | 2006-08-23 20:07:20 +0000 | [diff] [blame] | 4636 | */ |
| 4637 | void sqlite3_reset_auto_extension(void); |
| 4638 | |
| 4639 | |
| 4640 | /* |
| 4641 | ****** EXPERIMENTAL - subject to change without notice ************** |
| 4642 | ** |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4643 | ** The interface to the virtual-table mechanism is currently considered |
| 4644 | ** to be experimental. The interface might change in incompatible ways. |
| 4645 | ** If this is a problem for you, do not use the interface at this time. |
| 4646 | ** |
| 4647 | ** When the virtual-table mechanism stablizes, we will declare the |
| 4648 | ** interface fixed, support it indefinitely, and remove this comment. |
| 4649 | */ |
| 4650 | |
| 4651 | /* |
| 4652 | ** Structures used by the virtual table interface |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 4653 | */ |
| 4654 | typedef struct sqlite3_vtab sqlite3_vtab; |
| 4655 | typedef struct sqlite3_index_info sqlite3_index_info; |
| 4656 | typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor; |
| 4657 | typedef struct sqlite3_module sqlite3_module; |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4658 | |
| 4659 | /* |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4660 | ** CAPI3REF: Virtual Table Object {F18000} |
| 4661 | ** KEYWORDS: sqlite3_module |
| 4662 | ** |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4663 | ** A module is a class of virtual tables. Each module is defined |
| 4664 | ** by an instance of the following structure. This structure consists |
| 4665 | ** mostly of methods for the module. |
| 4666 | */ |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 4667 | struct sqlite3_module { |
| 4668 | int iVersion; |
danielk1977 | 9da9d47 | 2006-06-14 06:58:15 +0000 | [diff] [blame] | 4669 | int (*xCreate)(sqlite3*, void *pAux, |
drh | e410296 | 2006-09-11 00:34:22 +0000 | [diff] [blame] | 4670 | int argc, const char *const*argv, |
drh | 4ca8aac | 2006-09-10 17:31:58 +0000 | [diff] [blame] | 4671 | sqlite3_vtab **ppVTab, char**); |
danielk1977 | 9da9d47 | 2006-06-14 06:58:15 +0000 | [diff] [blame] | 4672 | int (*xConnect)(sqlite3*, void *pAux, |
drh | e410296 | 2006-09-11 00:34:22 +0000 | [diff] [blame] | 4673 | int argc, const char *const*argv, |
drh | 4ca8aac | 2006-09-10 17:31:58 +0000 | [diff] [blame] | 4674 | sqlite3_vtab **ppVTab, char**); |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 4675 | int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*); |
| 4676 | int (*xDisconnect)(sqlite3_vtab *pVTab); |
| 4677 | int (*xDestroy)(sqlite3_vtab *pVTab); |
| 4678 | int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor); |
| 4679 | int (*xClose)(sqlite3_vtab_cursor*); |
drh | 4be8b51 | 2006-06-13 23:51:34 +0000 | [diff] [blame] | 4680 | int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr, |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 4681 | int argc, sqlite3_value **argv); |
| 4682 | int (*xNext)(sqlite3_vtab_cursor*); |
danielk1977 | a298e90 | 2006-06-22 09:53:48 +0000 | [diff] [blame] | 4683 | int (*xEof)(sqlite3_vtab_cursor*); |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 4684 | int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 4685 | int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid); |
| 4686 | int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *); |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 4687 | int (*xBegin)(sqlite3_vtab *pVTab); |
| 4688 | int (*xSync)(sqlite3_vtab *pVTab); |
| 4689 | int (*xCommit)(sqlite3_vtab *pVTab); |
| 4690 | int (*xRollback)(sqlite3_vtab *pVTab); |
drh | b7f6f68 | 2006-07-08 17:06:43 +0000 | [diff] [blame] | 4691 | int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, |
drh | e94b0c3 | 2006-07-08 18:09:15 +0000 | [diff] [blame] | 4692 | void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), |
| 4693 | void **ppArg); |
danielk1977 | 182c4ba | 2007-06-27 15:53:34 +0000 | [diff] [blame] | 4694 | |
| 4695 | int (*xRename)(sqlite3_vtab *pVtab, const char *zNew); |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 4696 | }; |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4697 | |
| 4698 | /* |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4699 | ** CAPI3REF: Virtual Table Indexing Information {F18100} |
| 4700 | ** KEYWORDS: sqlite3_index_info |
| 4701 | ** |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4702 | ** The sqlite3_index_info structure and its substructures is used to |
| 4703 | ** pass information into and receive the reply from the xBestIndex |
| 4704 | ** method of an sqlite3_module. The fields under **Inputs** are the |
| 4705 | ** inputs to xBestIndex and are read-only. xBestIndex inserts its |
| 4706 | ** results into the **Outputs** fields. |
| 4707 | ** |
| 4708 | ** The aConstraint[] array records WHERE clause constraints of the |
| 4709 | ** form: |
| 4710 | ** |
| 4711 | ** column OP expr |
| 4712 | ** |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4713 | ** Where OP is =, <, <=, >, or >=. |
| 4714 | ** The particular operator is stored |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4715 | ** in aConstraint[].op. The index of the column is stored in |
| 4716 | ** aConstraint[].iColumn. aConstraint[].usable is TRUE if the |
| 4717 | ** expr on the right-hand side can be evaluated (and thus the constraint |
| 4718 | ** is usable) and false if it cannot. |
| 4719 | ** |
| 4720 | ** The optimizer automatically inverts terms of the form "expr OP column" |
drh | 98c9480 | 2007-10-01 13:50:31 +0000 | [diff] [blame] | 4721 | ** and makes other simplifications to the WHERE clause in an attempt to |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4722 | ** get as many WHERE clause terms into the form shown above as possible. |
| 4723 | ** The aConstraint[] array only reports WHERE clause terms in the correct |
| 4724 | ** form that refer to the particular virtual table being queried. |
| 4725 | ** |
| 4726 | ** Information about the ORDER BY clause is stored in aOrderBy[]. |
| 4727 | ** Each term of aOrderBy records a column of the ORDER BY clause. |
| 4728 | ** |
| 4729 | ** The xBestIndex method must fill aConstraintUsage[] with information |
danielk1977 | 5fac9f8 | 2006-06-13 14:16:58 +0000 | [diff] [blame] | 4730 | ** about what parameters to pass to xFilter. If argvIndex>0 then |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4731 | ** the right-hand side of the corresponding aConstraint[] is evaluated |
| 4732 | ** and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit |
| 4733 | ** is true, then the constraint is assumed to be fully handled by the |
| 4734 | ** virtual table and is not checked again by SQLite. |
| 4735 | ** |
drh | 4be8b51 | 2006-06-13 23:51:34 +0000 | [diff] [blame] | 4736 | ** The idxNum and idxPtr values are recorded and passed into xFilter. |
| 4737 | ** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true. |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4738 | ** |
| 4739 | ** The orderByConsumed means that output from xFilter will occur in |
| 4740 | ** the correct order to satisfy the ORDER BY clause so that no separate |
| 4741 | ** sorting step is required. |
| 4742 | ** |
| 4743 | ** The estimatedCost value is an estimate of the cost of doing the |
| 4744 | ** particular lookup. A full scan of a table with N entries should have |
| 4745 | ** a cost of N. A binary search of a table of N entries should have a |
| 4746 | ** cost of approximately log(N). |
| 4747 | */ |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 4748 | struct sqlite3_index_info { |
| 4749 | /* Inputs */ |
drh | 6cca08c | 2007-09-21 12:43:16 +0000 | [diff] [blame] | 4750 | int nConstraint; /* Number of entries in aConstraint */ |
| 4751 | struct sqlite3_index_constraint { |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4752 | int iColumn; /* Column on left-hand side of constraint */ |
| 4753 | unsigned char op; /* Constraint operator */ |
| 4754 | unsigned char usable; /* True if this constraint is usable */ |
| 4755 | int iTermOffset; /* Used internally - xBestIndex should ignore */ |
drh | 6cca08c | 2007-09-21 12:43:16 +0000 | [diff] [blame] | 4756 | } *aConstraint; /* Table of WHERE clause constraints */ |
| 4757 | int nOrderBy; /* Number of terms in the ORDER BY clause */ |
| 4758 | struct sqlite3_index_orderby { |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4759 | int iColumn; /* Column number */ |
| 4760 | unsigned char desc; /* True for DESC. False for ASC. */ |
drh | 6cca08c | 2007-09-21 12:43:16 +0000 | [diff] [blame] | 4761 | } *aOrderBy; /* The ORDER BY clause */ |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 4762 | |
| 4763 | /* Outputs */ |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4764 | struct sqlite3_index_constraint_usage { |
| 4765 | int argvIndex; /* if >0, constraint is part of argv to xFilter */ |
| 4766 | unsigned char omit; /* Do not code a test for this constraint */ |
drh | 6cca08c | 2007-09-21 12:43:16 +0000 | [diff] [blame] | 4767 | } *aConstraintUsage; |
drh | 4be8b51 | 2006-06-13 23:51:34 +0000 | [diff] [blame] | 4768 | int idxNum; /* Number used to identify the index */ |
| 4769 | char *idxStr; /* String, possibly obtained from sqlite3_malloc */ |
| 4770 | int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */ |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4771 | int orderByConsumed; /* True if output is already ordered */ |
| 4772 | double estimatedCost; /* Estimated cost of using this index */ |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 4773 | }; |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4774 | #define SQLITE_INDEX_CONSTRAINT_EQ 2 |
| 4775 | #define SQLITE_INDEX_CONSTRAINT_GT 4 |
| 4776 | #define SQLITE_INDEX_CONSTRAINT_LE 8 |
| 4777 | #define SQLITE_INDEX_CONSTRAINT_LT 16 |
| 4778 | #define SQLITE_INDEX_CONSTRAINT_GE 32 |
| 4779 | #define SQLITE_INDEX_CONSTRAINT_MATCH 64 |
| 4780 | |
| 4781 | /* |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4782 | ** CAPI3REF: Register A Virtual Table Implementation {F18200} |
| 4783 | ** |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4784 | ** This routine is used to register a new module name with an SQLite |
| 4785 | ** connection. Module names must be registered before creating new |
| 4786 | ** virtual tables on the module, or before using preexisting virtual |
| 4787 | ** tables of the module. |
| 4788 | */ |
drh | b9bb7c1 | 2006-06-11 23:41:55 +0000 | [diff] [blame] | 4789 | int sqlite3_create_module( |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4790 | sqlite3 *db, /* SQLite connection to register module with */ |
| 4791 | const char *zName, /* Name of the module */ |
danielk1977 | d1ab1ba | 2006-06-15 04:28:13 +0000 | [diff] [blame] | 4792 | const sqlite3_module *, /* Methods for the module */ |
| 4793 | void * /* Client data for xCreate/xConnect */ |
drh | b9bb7c1 | 2006-06-11 23:41:55 +0000 | [diff] [blame] | 4794 | ); |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 4795 | |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4796 | /* |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4797 | ** CAPI3REF: Register A Virtual Table Implementation {F18210} |
| 4798 | ** |
danielk1977 | 832a58a | 2007-06-22 15:21:15 +0000 | [diff] [blame] | 4799 | ** This routine is identical to the sqlite3_create_module() method above, |
| 4800 | ** except that it allows a destructor function to be specified. It is |
| 4801 | ** even more experimental than the rest of the virtual tables API. |
| 4802 | */ |
| 4803 | int sqlite3_create_module_v2( |
| 4804 | sqlite3 *db, /* SQLite connection to register module with */ |
| 4805 | const char *zName, /* Name of the module */ |
| 4806 | const sqlite3_module *, /* Methods for the module */ |
| 4807 | void *, /* Client data for xCreate/xConnect */ |
| 4808 | void(*xDestroy)(void*) /* Module destructor function */ |
| 4809 | ); |
| 4810 | |
| 4811 | /* |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4812 | ** CAPI3REF: Virtual Table Instance Object {F18010} |
| 4813 | ** KEYWORDS: sqlite3_vtab |
| 4814 | ** |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4815 | ** Every module implementation uses a subclass of the following structure |
| 4816 | ** to describe a particular instance of the module. Each subclass will |
drh | 98c9480 | 2007-10-01 13:50:31 +0000 | [diff] [blame] | 4817 | ** be tailored to the specific needs of the module implementation. The |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4818 | ** purpose of this superclass is to define certain fields that are common |
| 4819 | ** to all module implementations. |
drh | fe1368e | 2006-09-10 17:08:29 +0000 | [diff] [blame] | 4820 | ** |
| 4821 | ** Virtual tables methods can set an error message by assigning a |
| 4822 | ** string obtained from sqlite3_mprintf() to zErrMsg. The method should |
| 4823 | ** take care that any prior string is freed by a call to sqlite3_free() |
| 4824 | ** prior to assigning a new string to zErrMsg. After the error message |
| 4825 | ** is delivered up to the client application, the string will be automatically |
| 4826 | ** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note |
| 4827 | ** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field |
| 4828 | ** since virtual tables are commonly implemented in loadable extensions which |
| 4829 | ** do not have access to sqlite3MPrintf() or sqlite3Free(). |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4830 | */ |
| 4831 | struct sqlite3_vtab { |
drh | a967e88 | 2006-06-13 01:04:52 +0000 | [diff] [blame] | 4832 | const sqlite3_module *pModule; /* The module for this virtual table */ |
danielk1977 | be71889 | 2006-06-23 08:05:19 +0000 | [diff] [blame] | 4833 | int nRef; /* Used internally */ |
drh | 4ca8aac | 2006-09-10 17:31:58 +0000 | [diff] [blame] | 4834 | char *zErrMsg; /* Error message from sqlite3_mprintf() */ |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4835 | /* Virtual table implementations will typically add additional fields */ |
| 4836 | }; |
| 4837 | |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4838 | /* |
| 4839 | ** CAPI3REF: Virtual Table Cursor Object {F18020} |
| 4840 | ** KEYWORDS: sqlite3_vtab_cursor |
| 4841 | ** |
| 4842 | ** Every module implementation uses a subclass of the following structure |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4843 | ** to describe cursors that point into the virtual table and are used |
| 4844 | ** to loop through the virtual table. Cursors are created using the |
| 4845 | ** xOpen method of the module. Each module implementation will define |
| 4846 | ** the content of a cursor structure to suit its own needs. |
| 4847 | ** |
| 4848 | ** This superclass exists in order to define fields of the cursor that |
| 4849 | ** are common to all implementations. |
| 4850 | */ |
| 4851 | struct sqlite3_vtab_cursor { |
| 4852 | sqlite3_vtab *pVtab; /* Virtual table of this cursor */ |
| 4853 | /* Virtual table implementations will typically add additional fields */ |
| 4854 | }; |
| 4855 | |
| 4856 | /* |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4857 | ** CAPI3REF: Declare The Schema Of A Virtual Table {F18280} |
| 4858 | ** |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4859 | ** The xCreate and xConnect methods of a module use the following API |
| 4860 | ** to declare the format (the names and datatypes of the columns) of |
| 4861 | ** the virtual tables they implement. |
| 4862 | */ |
danielk1977 | 7e6ebfb | 2006-06-12 11:24:37 +0000 | [diff] [blame] | 4863 | int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); |
drh | e09daa9 | 2006-06-10 13:29:31 +0000 | [diff] [blame] | 4864 | |
| 4865 | /* |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4866 | ** CAPI3REF: Overload A Function For A Virtual Table {F18300} |
| 4867 | ** |
drh | b7481e7 | 2006-09-16 21:45:14 +0000 | [diff] [blame] | 4868 | ** Virtual tables can provide alternative implementations of functions |
| 4869 | ** using the xFindFunction method. But global versions of those functions |
| 4870 | ** must exist in order to be overloaded. |
| 4871 | ** |
| 4872 | ** This API makes sure a global version of a function with a particular |
| 4873 | ** name and number of parameters exists. If no such function exists |
| 4874 | ** before this API is called, a new function is created. The implementation |
| 4875 | ** of the new function always causes an exception to be thrown. So |
| 4876 | ** the new function is not good for anything by itself. Its only |
| 4877 | ** purpose is to be a place-holder function that can be overloaded |
| 4878 | ** by virtual tables. |
| 4879 | ** |
| 4880 | ** This API should be considered part of the virtual table interface, |
| 4881 | ** which is experimental and subject to change. |
| 4882 | */ |
| 4883 | int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); |
| 4884 | |
| 4885 | /* |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4886 | ** The interface to the virtual-table mechanism defined above (back up |
| 4887 | ** to a comment remarkably similar to this one) is currently considered |
| 4888 | ** to be experimental. The interface might change in incompatible ways. |
| 4889 | ** If this is a problem for you, do not use the interface at this time. |
| 4890 | ** |
drh | 98c9480 | 2007-10-01 13:50:31 +0000 | [diff] [blame] | 4891 | ** When the virtual-table mechanism stabilizes, we will declare the |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 4892 | ** interface fixed, support it indefinitely, and remove this comment. |
| 4893 | ** |
| 4894 | ****** EXPERIMENTAL - subject to change without notice ************** |
| 4895 | */ |
| 4896 | |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 4897 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4898 | ** CAPI3REF: A Handle To An Open BLOB {F17800} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4899 | ** |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4900 | ** An instance of this object represents an open BLOB on which |
| 4901 | ** incremental I/O can be preformed. |
| 4902 | ** Objects of this type are created by |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4903 | ** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()]. |
| 4904 | ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces |
| 4905 | ** can be used to read or write small subsections of the blob. |
drh | 79491ab | 2007-09-04 12:00:00 +0000 | [diff] [blame] | 4906 | ** The [sqlite3_blob_bytes()] interface returns the size of the |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4907 | ** blob in bytes. |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 4908 | */ |
danielk1977 | b4e9af9 | 2007-05-01 17:49:49 +0000 | [diff] [blame] | 4909 | typedef struct sqlite3_blob sqlite3_blob; |
| 4910 | |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 4911 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4912 | ** CAPI3REF: Open A BLOB For Incremental I/O {F17810} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4913 | ** |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4914 | ** This interfaces opens a handle to the blob located |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4915 | ** in row iRow,, column zColumn, table zTable in database zDb; |
| 4916 | ** in other words, the same blob that would be selected by: |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 4917 | ** |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4918 | ** <pre> |
| 4919 | ** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow; |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4920 | ** </pre> {END} |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 4921 | ** |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4922 | ** If the flags parameter is non-zero, the blob is opened for |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 4923 | ** read and write access. If it is zero, the blob is opened for read |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4924 | ** access. |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 4925 | ** |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4926 | ** On success, [SQLITE_OK] is returned and the new |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4927 | ** [sqlite3_blob | blob handle] is written to *ppBlob. |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4928 | ** Otherwise an error code is returned and |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 4929 | ** any value written to *ppBlob should not be used by the caller. |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4930 | ** This function sets the database-handle error code and message |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4931 | ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()]. |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4932 | ** |
| 4933 | ** INVARIANTS: |
| 4934 | ** |
| 4935 | ** {F17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)] |
| 4936 | ** interface opens an [sqlite3_blob] object P on the blob |
| 4937 | ** in column C of table T in database B on [database connection] D. |
| 4938 | ** |
| 4939 | ** {F17814} A successful invocation of [sqlite3_blob_open(D,...)] starts |
| 4940 | ** a new transaction on [database connection] D if that connection |
| 4941 | ** is not already in a transaction. |
| 4942 | ** |
| 4943 | ** {F17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface opens the blob |
| 4944 | ** for read and write access if and only if the F parameter |
| 4945 | ** is non-zero. |
| 4946 | ** |
| 4947 | ** {F17819} The [sqlite3_blob_open()] interface returns [SQLITE_OK] on |
| 4948 | ** success and an appropriate [error code] on failure. |
| 4949 | ** |
| 4950 | ** {F17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)] |
| 4951 | ** then subsequent calls to [sqlite3_errcode(D)], |
| 4952 | ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return |
| 4953 | ** information approprate for that error. |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 4954 | */ |
danielk1977 | b4e9af9 | 2007-05-01 17:49:49 +0000 | [diff] [blame] | 4955 | int sqlite3_blob_open( |
| 4956 | sqlite3*, |
| 4957 | const char *zDb, |
| 4958 | const char *zTable, |
| 4959 | const char *zColumn, |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 4960 | sqlite3_int64 iRow, |
danielk1977 | b4e9af9 | 2007-05-01 17:49:49 +0000 | [diff] [blame] | 4961 | int flags, |
| 4962 | sqlite3_blob **ppBlob |
| 4963 | ); |
| 4964 | |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 4965 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 4966 | ** CAPI3REF: Close A BLOB Handle {F17830} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 4967 | ** |
| 4968 | ** Close an open [sqlite3_blob | blob handle]. |
drh | 2dd62be | 2007-12-04 13:22:43 +0000 | [diff] [blame] | 4969 | ** |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4970 | ** Closing a BLOB shall cause the current transaction to commit |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4971 | ** if there are no other BLOBs, no pending prepared statements, and the |
| 4972 | ** database connection is in autocommit mode. |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4973 | ** If any writes were made to the BLOB, they might be held in cache |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4974 | ** until the close operation if they will fit. {END} |
| 4975 | ** Closing the BLOB often forces the changes |
drh | 2dd62be | 2007-12-04 13:22:43 +0000 | [diff] [blame] | 4976 | ** out to disk and so if any I/O errors occur, they will likely occur |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 4977 | ** at the time when the BLOB is closed. {F17833} Any errors that occur during |
drh | 2dd62be | 2007-12-04 13:22:43 +0000 | [diff] [blame] | 4978 | ** closing are reported as a non-zero return value. |
| 4979 | ** |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4980 | ** The BLOB is closed unconditionally. Even if this routine returns |
drh | 2dd62be | 2007-12-04 13:22:43 +0000 | [diff] [blame] | 4981 | ** an error code, the BLOB is still closed. |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 4982 | ** |
| 4983 | ** INVARIANTS: |
| 4984 | ** |
| 4985 | ** {F17833} The [sqlite3_blob_close(P)] interface closes an |
| 4986 | ** [sqlite3_blob] object P previously opened using |
| 4987 | ** [sqlite3_blob_open()]. |
| 4988 | ** |
| 4989 | ** {F17836} Closing an [sqlite3_blob] object using |
| 4990 | ** [sqlite3_blob_close()] shall cause the current transaction to |
| 4991 | ** commit if there are no other open [sqlite3_blob] objects |
| 4992 | ** or [prepared statements] on the same [database connection] and |
| 4993 | ** the [database connection] is in |
| 4994 | ** [sqlite3_get_autocommit | autocommit mode]. |
| 4995 | ** |
| 4996 | ** {F17839} The [sqlite3_blob_close(P)] interfaces closes the |
| 4997 | ** [sqlite3_blob] object P unconditionally, even if |
| 4998 | ** [sqlite3_blob_close(P)] returns something other than [SQLITE_OK]. |
| 4999 | ** |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 5000 | */ |
danielk1977 | b4e9af9 | 2007-05-01 17:49:49 +0000 | [diff] [blame] | 5001 | int sqlite3_blob_close(sqlite3_blob *); |
| 5002 | |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 5003 | /* |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 5004 | ** CAPI3REF: Return The Size Of An Open BLOB {F17840} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 5005 | ** |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 5006 | ** Return the size in bytes of the blob accessible via the open |
| 5007 | ** [sqlite3_blob] object in its only argument. |
| 5008 | ** |
| 5009 | ** INVARIANTS: |
| 5010 | ** |
| 5011 | ** {F17843} The [sqlite3_blob_bytes(P)] interface returns the size |
| 5012 | ** in bytes of the BLOB that the [sqlite3_blob] object P |
| 5013 | ** refers to. |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 5014 | */ |
danielk1977 | b4e9af9 | 2007-05-01 17:49:49 +0000 | [diff] [blame] | 5015 | int sqlite3_blob_bytes(sqlite3_blob *); |
| 5016 | |
drh | 9eff616 | 2006-06-12 21:59:13 +0000 | [diff] [blame] | 5017 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5018 | ** CAPI3REF: Read Data From A BLOB Incrementally {F17850} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 5019 | ** |
| 5020 | ** This function is used to read data from an open |
| 5021 | ** [sqlite3_blob | blob-handle] into a caller supplied buffer. |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 5022 | ** N bytes of data are copied into buffer |
| 5023 | ** Z from the open blob, starting at offset iOffset. |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 5024 | ** |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 5025 | ** If offset iOffset is less than N bytes from the end of the blob, |
| 5026 | ** [SQLITE_ERROR] is returned and no data is read. If N or iOffset is |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5027 | ** less than zero [SQLITE_ERROR] is returned and no data is read. |
| 5028 | ** |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 5029 | ** On success, SQLITE_OK is returned. Otherwise, an |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 5030 | ** [error code] or an [extended error code] is returned. |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 5031 | ** |
| 5032 | ** INVARIANTS: |
| 5033 | ** |
| 5034 | ** {F17853} The [sqlite3_blob_read(P,Z,N,X)] interface reads N bytes |
| 5035 | ** beginning at offset X from |
| 5036 | ** the blob that [sqlite3_blob] object P refers to |
| 5037 | ** and writes those N bytes into buffer Z. |
| 5038 | ** |
| 5039 | ** {F17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the blob |
| 5040 | ** is less than N+X bytes, then the function returns [SQLITE_ERROR] |
| 5041 | ** and nothing is read from the blob. |
| 5042 | ** |
| 5043 | ** {F17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero |
| 5044 | ** then the function returns [SQLITE_ERROR] |
| 5045 | ** and nothing is read from the blob. |
| 5046 | ** |
| 5047 | ** {F17862} The [sqlite3_blob_read(P,Z,N,X)] interface returns [SQLITE_OK] |
| 5048 | ** if N bytes where successfully read into buffer Z. |
| 5049 | ** |
| 5050 | ** {F17865} If the requested read could not be completed, |
| 5051 | ** the [sqlite3_blob_read(P,Z,N,X)] interface returns an |
| 5052 | ** appropriate [error code] or [extended error code]. |
| 5053 | ** |
| 5054 | ** {F17868} If an error occurs during evaluation of [sqlite3_blob_read(D,...)] |
| 5055 | ** then subsequent calls to [sqlite3_errcode(D)], |
| 5056 | ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return |
| 5057 | ** information approprate for that error. |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 5058 | */ |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 5059 | int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset); |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 5060 | |
| 5061 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5062 | ** CAPI3REF: Write Data Into A BLOB Incrementally {F17870} |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 5063 | ** |
| 5064 | ** This function is used to write data into an open |
| 5065 | ** [sqlite3_blob | blob-handle] from a user supplied buffer. |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 5066 | ** n bytes of data are copied from the buffer |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 5067 | ** pointed to by z into the open blob, starting at offset iOffset. |
| 5068 | ** |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 5069 | ** If the [sqlite3_blob | blob-handle] passed as the first argument |
drh | 6ed48bf | 2007-06-14 20:57:18 +0000 | [diff] [blame] | 5070 | ** was not opened for writing (the flags parameter to [sqlite3_blob_open()] |
| 5071 | *** was zero), this function returns [SQLITE_READONLY]. |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 5072 | ** |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 5073 | ** This function may only modify the contents of the blob; it is |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5074 | ** not possible to increase the size of a blob using this API. |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 5075 | ** If offset iOffset is less than n bytes from the end of the blob, |
| 5076 | ** [SQLITE_ERROR] is returned and no data is written. If n is |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5077 | ** less than zero [SQLITE_ERROR] is returned and no data is written. |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 5078 | ** |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 5079 | ** On success, SQLITE_OK is returned. Otherwise, an |
drh | 33c1be3 | 2008-01-30 16:16:14 +0000 | [diff] [blame] | 5080 | ** [error code] or an [extended error code] is returned. |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 5081 | ** |
| 5082 | ** INVARIANTS: |
| 5083 | ** |
| 5084 | ** {F17873} The [sqlite3_blob_write(P,Z,N,X)] interface writes N bytes |
| 5085 | ** from buffer Z into |
| 5086 | ** the blob that [sqlite3_blob] object P refers to |
| 5087 | ** beginning at an offset of X into the blob. |
| 5088 | ** |
| 5089 | ** {F17875} The [sqlite3_blob_write(P,Z,N,X)] interface returns |
| 5090 | ** [SQLITE_READONLY] if the [sqlite3_blob] object P was |
| 5091 | ** [sqlite3_blob_open | opened] for reading only. |
| 5092 | ** |
| 5093 | ** {F17876} In [sqlite3_blob_write(P,Z,N,X)] if the size of the blob |
| 5094 | ** is less than N+X bytes, then the function returns [SQLITE_ERROR] |
| 5095 | ** and nothing is written into the blob. |
| 5096 | ** |
| 5097 | ** {F17879} In [sqlite3_blob_write(P,Z,N,X)] if X or N is less than zero |
| 5098 | ** then the function returns [SQLITE_ERROR] |
| 5099 | ** and nothing is written into the blob. |
| 5100 | ** |
| 5101 | ** {F17882} The [sqlite3_blob_write(P,Z,N,X)] interface returns [SQLITE_OK] |
| 5102 | ** if N bytes where successfully written into blob. |
| 5103 | ** |
| 5104 | ** {F17885} If the requested write could not be completed, |
| 5105 | ** the [sqlite3_blob_write(P,Z,N,X)] interface returns an |
| 5106 | ** appropriate [error code] or [extended error code]. |
| 5107 | ** |
| 5108 | ** {F17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)] |
| 5109 | ** then subsequent calls to [sqlite3_errcode(D)], |
| 5110 | ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return |
| 5111 | ** information approprate for that error. |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 5112 | */ |
| 5113 | int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); |
| 5114 | |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5115 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5116 | ** CAPI3REF: Virtual File System Objects {F11200} |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5117 | ** |
| 5118 | ** A virtual filesystem (VFS) is an [sqlite3_vfs] object |
| 5119 | ** that SQLite uses to interact |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 5120 | ** with the underlying operating system. Most SQLite builds come with a |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5121 | ** single default VFS that is appropriate for the host computer. |
| 5122 | ** New VFSes can be registered and existing VFSes can be unregistered. |
| 5123 | ** The following interfaces are provided. |
| 5124 | ** |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 5125 | ** The sqlite3_vfs_find() interface returns a pointer to |
| 5126 | ** a VFS given its name. Names are case sensitive. |
| 5127 | ** Names are zero-terminated UTF-8 strings. |
| 5128 | ** If there is no match, a NULL |
| 5129 | ** pointer is returned. If zVfsName is NULL then the default |
| 5130 | ** VFS is returned. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5131 | ** |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 5132 | ** New VFSes are registered with sqlite3_vfs_register(). |
| 5133 | ** Each new VFS becomes the default VFS if the makeDflt flag is set. |
| 5134 | ** The same VFS can be registered multiple times without injury. |
| 5135 | ** To make an existing VFS into the default VFS, register it again |
| 5136 | ** with the makeDflt flag set. If two different VFSes with the |
| 5137 | ** same name are registered, the behavior is undefined. If a |
drh | b6f5cf3 | 2007-08-28 15:21:45 +0000 | [diff] [blame] | 5138 | ** VFS is registered with a name that is NULL or an empty string, |
| 5139 | ** then the behavior is undefined. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5140 | ** |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 5141 | ** Unregister a VFS with the sqlite3_vfs_unregister() interface. |
| 5142 | ** If the default VFS is unregistered, another VFS is chosen as |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5143 | ** the default. The choice for the new VFS is arbitrary. |
drh | b4d58ae | 2008-02-21 20:17:06 +0000 | [diff] [blame] | 5144 | ** |
| 5145 | ** INVARIANTS: |
| 5146 | ** |
| 5147 | ** {F11203} The [sqlite3_vfs_find(N)] interface returns a pointer to the |
| 5148 | ** registered [sqlite3_vfs] object whose name exactly matches |
| 5149 | ** the zero-terminated UTF-8 string N, or it returns NULL if |
| 5150 | ** there is no match. |
| 5151 | ** |
| 5152 | ** {F11206} If the N parameter to [sqlite3_vfs_find(N)] is NULL then |
| 5153 | ** the function returns a pointer to the default [sqlite3_vfs] |
| 5154 | ** object if there is one, or NULL if there is no default |
| 5155 | ** [sqlite3_vfs] object. |
| 5156 | ** |
| 5157 | ** {F11209} The [sqlite3_vfs_register(P,F)] interface registers the |
| 5158 | ** well-formed [sqlite3_vfs] object P using the name given |
| 5159 | ** by the zName field of the object. |
| 5160 | ** |
| 5161 | ** {F11212} Using the [sqlite3_vfs_register(P,F)] interface to register |
| 5162 | ** the same [sqlite3_vfs] object multiple times is a harmless no-op. |
| 5163 | ** |
| 5164 | ** {F11215} The [sqlite3_vfs_register(P,F)] interface makes the |
| 5165 | ** the [sqlite3_vfs] object P the default [sqlite3_vfs] object |
| 5166 | ** if F is non-zero. |
| 5167 | ** |
| 5168 | ** {F11218} The [sqlite3_vfs_unregister(P)] interface unregisters the |
| 5169 | ** [sqlite3_vfs] object P so that it is no longer returned by |
| 5170 | ** subsequent calls to [sqlite3_vfs_find()]. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5171 | */ |
drh | d677b3d | 2007-08-20 22:48:41 +0000 | [diff] [blame] | 5172 | sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); |
drh | d677b3d | 2007-08-20 22:48:41 +0000 | [diff] [blame] | 5173 | int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); |
| 5174 | int sqlite3_vfs_unregister(sqlite3_vfs*); |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5175 | |
| 5176 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5177 | ** CAPI3REF: Mutexes {F17000} |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5178 | ** |
| 5179 | ** The SQLite core uses these routines for thread |
| 5180 | ** synchronization. Though they are intended for internal |
| 5181 | ** use by SQLite, code that links against SQLite is |
| 5182 | ** permitted to use any of these routines. |
| 5183 | ** |
| 5184 | ** The SQLite source code contains multiple implementations |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 5185 | ** of these mutex routines. An appropriate implementation |
| 5186 | ** is selected automatically at compile-time. The following |
| 5187 | ** implementations are available in the SQLite core: |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5188 | ** |
| 5189 | ** <ul> |
drh | c7ce76a | 2007-08-30 14:10:30 +0000 | [diff] [blame] | 5190 | ** <li> SQLITE_MUTEX_OS2 |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5191 | ** <li> SQLITE_MUTEX_PTHREAD |
drh | c7ce76a | 2007-08-30 14:10:30 +0000 | [diff] [blame] | 5192 | ** <li> SQLITE_MUTEX_W32 |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5193 | ** <li> SQLITE_MUTEX_NOOP |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5194 | ** </ul> |
| 5195 | ** |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5196 | ** The SQLITE_MUTEX_NOOP implementation is a set of routines |
| 5197 | ** that does no real locking and is appropriate for use in |
drh | c7ce76a | 2007-08-30 14:10:30 +0000 | [diff] [blame] | 5198 | ** a single-threaded application. The SQLITE_MUTEX_OS2, |
| 5199 | ** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations |
| 5200 | ** are appropriate for use on os/2, unix, and windows. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5201 | ** |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 5202 | ** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor |
| 5203 | ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5204 | ** implementation is included with the library. The |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 5205 | ** mutex interface routines defined here become external |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5206 | ** references in the SQLite library for which implementations |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 5207 | ** must be provided by the application. This facility allows an |
| 5208 | ** application that links against SQLite to provide its own mutex |
| 5209 | ** implementation without having to modify the SQLite core. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5210 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5211 | ** {F17011} The sqlite3_mutex_alloc() routine allocates a new |
| 5212 | ** mutex and returns a pointer to it. {F17012} If it returns NULL |
| 5213 | ** that means that a mutex could not be allocated. {F17013} SQLite |
| 5214 | ** will unwind its stack and return an error. {F17014} The argument |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 5215 | ** to sqlite3_mutex_alloc() is one of these integer constants: |
| 5216 | ** |
| 5217 | ** <ul> |
| 5218 | ** <li> SQLITE_MUTEX_FAST |
| 5219 | ** <li> SQLITE_MUTEX_RECURSIVE |
| 5220 | ** <li> SQLITE_MUTEX_STATIC_MASTER |
| 5221 | ** <li> SQLITE_MUTEX_STATIC_MEM |
drh | 86f8c19 | 2007-08-22 00:39:19 +0000 | [diff] [blame] | 5222 | ** <li> SQLITE_MUTEX_STATIC_MEM2 |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 5223 | ** <li> SQLITE_MUTEX_STATIC_PRNG |
danielk1977 | 9f61c2f | 2007-08-27 17:27:49 +0000 | [diff] [blame] | 5224 | ** <li> SQLITE_MUTEX_STATIC_LRU |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5225 | ** </ul> {END} |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 5226 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5227 | ** {F17015} The first two constants cause sqlite3_mutex_alloc() to create |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 5228 | ** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5229 | ** is used but not necessarily so when SQLITE_MUTEX_FAST is used. {END} |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 5230 | ** The mutex implementation does not need to make a distinction |
| 5231 | ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5232 | ** not want to. {F17016} But SQLite will only request a recursive mutex in |
| 5233 | ** cases where it really needs one. {END} If a faster non-recursive mutex |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 5234 | ** implementation is available on the host platform, the mutex subsystem |
| 5235 | ** might return such a mutex in response to SQLITE_MUTEX_FAST. |
| 5236 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5237 | ** {F17017} The other allowed parameters to sqlite3_mutex_alloc() each return |
| 5238 | ** a pointer to a static preexisting mutex. {END} Four static mutexes are |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 5239 | ** used by the current version of SQLite. Future versions of SQLite |
| 5240 | ** may add additional static mutexes. Static mutexes are for internal |
| 5241 | ** use by SQLite only. Applications that use SQLite mutexes should |
| 5242 | ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or |
| 5243 | ** SQLITE_MUTEX_RECURSIVE. |
| 5244 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5245 | ** {F17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 5246 | ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5247 | ** returns a different mutex on every call. {F17034} But for the static |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 5248 | ** mutex types, the same mutex is returned on every call that has |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5249 | ** the same type number. {END} |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5250 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5251 | ** {F17019} The sqlite3_mutex_free() routine deallocates a previously |
| 5252 | ** allocated dynamic mutex. {F17020} SQLite is careful to deallocate every |
| 5253 | ** dynamic mutex that it allocates. {U17021} The dynamic mutexes must not be in |
| 5254 | ** use when they are deallocated. {U17022} Attempting to deallocate a static |
| 5255 | ** mutex results in undefined behavior. {F17023} SQLite never deallocates |
| 5256 | ** a static mutex. {END} |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5257 | ** |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 5258 | ** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5259 | ** to enter a mutex. {F17024} If another thread is already within the mutex, |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 5260 | ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5261 | ** SQLITE_BUSY. {F17025} The sqlite3_mutex_try() interface returns SQLITE_OK |
| 5262 | ** upon successful entry. {F17026} Mutexes created using |
| 5263 | ** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread. |
| 5264 | ** {F17027} In such cases the, |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 5265 | ** mutex must be exited an equal number of times before another thread |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5266 | ** can enter. {U17028} If the same thread tries to enter any other |
| 5267 | ** kind of mutex more than once, the behavior is undefined. |
| 5268 | ** {F17029} SQLite will never exhibit |
| 5269 | ** such behavior in its own use of mutexes. {END} |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5270 | ** |
drh | ca49cba | 2007-09-04 22:31:36 +0000 | [diff] [blame] | 5271 | ** Some systems (ex: windows95) do not the operation implemented by |
| 5272 | ** sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() will |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5273 | ** always return SQLITE_BUSY. {F17030} The SQLite core only ever uses |
| 5274 | ** sqlite3_mutex_try() as an optimization so this is acceptable behavior. {END} |
drh | ca49cba | 2007-09-04 22:31:36 +0000 | [diff] [blame] | 5275 | ** |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5276 | ** {F17031} The sqlite3_mutex_leave() routine exits a mutex that was |
| 5277 | ** previously entered by the same thread. {U17032} The behavior |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 5278 | ** is undefined if the mutex is not currently entered by the |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5279 | ** calling thread or is not currently allocated. {F17033} SQLite will |
| 5280 | ** never do either. {END} |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 5281 | ** |
| 5282 | ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()]. |
| 5283 | */ |
| 5284 | sqlite3_mutex *sqlite3_mutex_alloc(int); |
| 5285 | void sqlite3_mutex_free(sqlite3_mutex*); |
| 5286 | void sqlite3_mutex_enter(sqlite3_mutex*); |
| 5287 | int sqlite3_mutex_try(sqlite3_mutex*); |
| 5288 | void sqlite3_mutex_leave(sqlite3_mutex*); |
| 5289 | |
| 5290 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5291 | ** CAPI3REF: Mutex Verifcation Routines {F17080} |
drh | d677b3d | 2007-08-20 22:48:41 +0000 | [diff] [blame] | 5292 | ** |
| 5293 | ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5294 | ** are intended for use inside assert() statements. {F17081} The SQLite core |
drh | f77a2ff | 2007-08-25 14:49:36 +0000 | [diff] [blame] | 5295 | ** never uses these routines except inside an assert() and applications |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5296 | ** are advised to follow the lead of the core. {F17082} The core only |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 5297 | ** provides implementations for these routines when it is compiled |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5298 | ** with the SQLITE_DEBUG flag. {U17087} External mutex implementations |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 5299 | ** are only required to provide these routines if SQLITE_DEBUG is |
| 5300 | ** defined and if NDEBUG is not defined. |
| 5301 | ** |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5302 | ** {F17083} These routines should return true if the mutex in their argument |
| 5303 | ** is held or not held, respectively, by the calling thread. {END} |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 5304 | ** |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5305 | ** {X17084} The implementation is not required to provided versions of these |
drh | 8bacf97 | 2007-08-25 16:21:29 +0000 | [diff] [blame] | 5306 | ** routines that actually work. |
| 5307 | ** If the implementation does not provide working |
| 5308 | ** versions of these routines, it should at least provide stubs |
| 5309 | ** that always return true so that one does not get spurious |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5310 | ** assertion failures. {END} |
drh | d677b3d | 2007-08-20 22:48:41 +0000 | [diff] [blame] | 5311 | ** |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5312 | ** {F17085} If the argument to sqlite3_mutex_held() is a NULL pointer then |
| 5313 | ** the routine should return 1. {END} This seems counter-intuitive since |
drh | d677b3d | 2007-08-20 22:48:41 +0000 | [diff] [blame] | 5314 | ** clearly the mutex cannot be held if it does not exist. But the |
| 5315 | ** the reason the mutex does not exist is because the build is not |
| 5316 | ** using mutexes. And we do not want the assert() containing the |
| 5317 | ** call to sqlite3_mutex_held() to fail, so a non-zero return is |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5318 | ** the appropriate thing to do. {F17086} The sqlite3_mutex_notheld() |
drh | d677b3d | 2007-08-20 22:48:41 +0000 | [diff] [blame] | 5319 | ** interface should also return 1 when given a NULL pointer. |
drh | d84f946 | 2007-08-15 11:28:56 +0000 | [diff] [blame] | 5320 | */ |
drh | d677b3d | 2007-08-20 22:48:41 +0000 | [diff] [blame] | 5321 | int sqlite3_mutex_held(sqlite3_mutex*); |
| 5322 | int sqlite3_mutex_notheld(sqlite3_mutex*); |
drh | 32bc3f6 | 2007-08-21 20:25:39 +0000 | [diff] [blame] | 5323 | |
| 5324 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5325 | ** CAPI3REF: Mutex Types {F17001} |
drh | 32bc3f6 | 2007-08-21 20:25:39 +0000 | [diff] [blame] | 5326 | ** |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5327 | ** {F17002} The [sqlite3_mutex_alloc()] interface takes a single argument |
| 5328 | ** which is one of these integer constants. {END} |
drh | 32bc3f6 | 2007-08-21 20:25:39 +0000 | [diff] [blame] | 5329 | */ |
drh | 6bdec4a | 2007-08-16 19:40:16 +0000 | [diff] [blame] | 5330 | #define SQLITE_MUTEX_FAST 0 |
| 5331 | #define SQLITE_MUTEX_RECURSIVE 1 |
| 5332 | #define SQLITE_MUTEX_STATIC_MASTER 2 |
drh | 86f8c19 | 2007-08-22 00:39:19 +0000 | [diff] [blame] | 5333 | #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ |
| 5334 | #define SQLITE_MUTEX_STATIC_MEM2 4 /* sqlite3_release_memory() */ |
| 5335 | #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */ |
danielk1977 | 9f61c2f | 2007-08-27 17:27:49 +0000 | [diff] [blame] | 5336 | #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 5337 | |
drh | cc6bb3e | 2007-08-31 16:11:35 +0000 | [diff] [blame] | 5338 | /* |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5339 | ** CAPI3REF: Low-Level Control Of Database Files {F11300} |
drh | cc6bb3e | 2007-08-31 16:11:35 +0000 | [diff] [blame] | 5340 | ** |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5341 | ** {F11301} The [sqlite3_file_control()] interface makes a direct call to the |
drh | cc6bb3e | 2007-08-31 16:11:35 +0000 | [diff] [blame] | 5342 | ** xFileControl method for the [sqlite3_io_methods] object associated |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5343 | ** with a particular database identified by the second argument. {F11302} The |
drh | cc6bb3e | 2007-08-31 16:11:35 +0000 | [diff] [blame] | 5344 | ** name of the database is the name assigned to the database by the |
| 5345 | ** <a href="lang_attach.html">ATTACH</a> SQL command that opened the |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5346 | ** database. {F11303} To control the main database file, use the name "main" |
| 5347 | ** or a NULL pointer. {F11304} The third and fourth parameters to this routine |
drh | cc6bb3e | 2007-08-31 16:11:35 +0000 | [diff] [blame] | 5348 | ** are passed directly through to the second and third parameters of |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5349 | ** the xFileControl method. {F11305} The return value of the xFileControl |
drh | cc6bb3e | 2007-08-31 16:11:35 +0000 | [diff] [blame] | 5350 | ** method becomes the return value of this routine. |
| 5351 | ** |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5352 | ** {F11306} If the second parameter (zDbName) does not match the name of any |
| 5353 | ** open database file, then SQLITE_ERROR is returned. {F11307} This error |
drh | cc6bb3e | 2007-08-31 16:11:35 +0000 | [diff] [blame] | 5354 | ** code is not remembered and will not be recalled by [sqlite3_errcode()] |
drh | f5befa0 | 2007-12-06 02:42:07 +0000 | [diff] [blame] | 5355 | ** or [sqlite3_errmsg()]. {U11308} The underlying xFileControl method might |
| 5356 | ** also return SQLITE_ERROR. {U11309} There is no way to distinguish between |
drh | cc6bb3e | 2007-08-31 16:11:35 +0000 | [diff] [blame] | 5357 | ** an incorrect zDbName and an SQLITE_ERROR return from the underlying |
drh | fddfa2d | 2007-12-05 18:05:16 +0000 | [diff] [blame] | 5358 | ** xFileControl method. {END} |
drh | 4ff7fa0 | 2007-09-01 18:17:21 +0000 | [diff] [blame] | 5359 | ** |
| 5360 | ** See also: [SQLITE_FCNTL_LOCKSTATE] |
drh | cc6bb3e | 2007-08-31 16:11:35 +0000 | [diff] [blame] | 5361 | */ |
| 5362 | int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); |
drh | 6d2069d | 2007-08-14 01:58:53 +0000 | [diff] [blame] | 5363 | |
danielk1977 | 8cbadb0 | 2007-05-03 16:31:26 +0000 | [diff] [blame] | 5364 | /* |
drh | ed13d98 | 2008-01-31 14:43:24 +0000 | [diff] [blame] | 5365 | ** CAPI3REF: Testing Interface {F11400} |
| 5366 | ** |
| 5367 | ** The sqlite3_test_control() interface is used to read out internal |
| 5368 | ** state of SQLite and to inject faults into SQLite for testing |
| 5369 | ** purposes. The first parameter a operation code that determines |
| 5370 | ** the number, meaning, and operation of all subsequent parameters. |
| 5371 | ** |
| 5372 | ** This interface is not for use by applications. It exists solely |
| 5373 | ** for verifying the correct operation of the SQLite library. Depending |
| 5374 | ** on how the SQLite library is compiled, this interface might not exist. |
| 5375 | ** |
| 5376 | ** The details of the operation codes, their meanings, the parameters |
| 5377 | ** they take, and what they do are all subject to change without notice. |
| 5378 | ** Unlike most of the SQLite API, this function is not guaranteed to |
| 5379 | ** operate consistently from one release to the next. |
| 5380 | */ |
| 5381 | int sqlite3_test_control(int op, ...); |
| 5382 | |
| 5383 | /* |
| 5384 | ** CAPI3REF: Testing Interface Operation Codes {F11410} |
| 5385 | ** |
| 5386 | ** These constants are the valid operation code parameters used |
| 5387 | ** as the first argument to [sqlite3_test_control()]. |
| 5388 | ** |
| 5389 | ** These parameters and their meansing are subject to change |
| 5390 | ** without notice. These values are for testing purposes only. |
| 5391 | ** Applications should not use any of these parameters or the |
| 5392 | ** [sqlite3_test_control()] interface. |
| 5393 | */ |
| 5394 | #define SQLITE_TESTCTRL_FAULT_CONFIG 1 |
| 5395 | #define SQLITE_TESTCTRL_FAULT_FAILURES 2 |
| 5396 | #define SQLITE_TESTCTRL_FAULT_BENIGN_FAILURES 3 |
| 5397 | #define SQLITE_TESTCTRL_FAULT_PENDING 4 |
| 5398 | |
| 5399 | |
| 5400 | |
| 5401 | |
| 5402 | |
| 5403 | /* |
drh | b37df7b | 2005-10-13 02:09:49 +0000 | [diff] [blame] | 5404 | ** Undo the hack that converts floating point types to integer for |
| 5405 | ** builds on processors without floating point support. |
| 5406 | */ |
| 5407 | #ifdef SQLITE_OMIT_FLOATING_POINT |
| 5408 | # undef double |
| 5409 | #endif |
| 5410 | |
drh | 382c024 | 2001-10-06 16:33:02 +0000 | [diff] [blame] | 5411 | #ifdef __cplusplus |
| 5412 | } /* End of the 'extern "C"' block */ |
| 5413 | #endif |
danielk1977 | 4adee20 | 2004-05-08 08:23:19 +0000 | [diff] [blame] | 5414 | #endif |