1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/stdapis/sqlite3.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,6362 @@
1.4 +/*
1.5 +** 2001 September 15
1.6 +**
1.7 +** The author disclaims copyright to this source code. In place of
1.8 +** a legal notice, here is a blessing:
1.9 +**
1.10 +** May you do good and not evil.
1.11 +** May you find forgiveness for yourself and forgive others.
1.12 +** May you share freely, never taking more than you give.
1.13 +**
1.14 +*************************************************************************
1.15 +** This header file defines the interface that the SQLite library
1.16 +** presents to client programs. If a C-function, structure, datatype,
1.17 +** or constant definition does not appear in this file, then it is
1.18 +** not a published API of SQLite, is subject to change without
1.19 +** notice, and should not be referenced by programs that use SQLite.
1.20 +**
1.21 +** Some of the definitions that are in this file are marked as
1.22 +** "experimental". Experimental interfaces are normally new
1.23 +** features recently added to SQLite. We do not anticipate changes
1.24 +** to experimental interfaces but reserve to make minor changes if
1.25 +** experience from use "in the wild" suggest such changes are prudent.
1.26 +**
1.27 +** The official C-language API documentation for SQLite is derived
1.28 +** from comments in this file. This file is the authoritative source
1.29 +** on how SQLite interfaces are suppose to operate.
1.30 +**
1.31 +** The name of this file under configuration management is "sqlite.h.in".
1.32 +** The makefile makes some minor changes to this file (such as inserting
1.33 +** the version number) and changes its name to "sqlite3.h" as
1.34 +** part of the build process.
1.35 +**
1.36 +** @(#) $Id: sqlite.h.in,v 1.400 2008/10/02 14:33:57 drh Exp $
1.37 +*/
1.38 +#ifndef _SQLITE3_H_
1.39 +#define _SQLITE3_H_
1.40 +#include <stdarg.h> /* Needed for the definition of va_list */
1.41 +#include <e32def.h>
1.42 +
1.43 +#ifdef SQLITE_DLL
1.44 +# define SQLITE_EXPORT EXPORT_C
1.45 +#else
1.46 +# define SQLITE_EXPORT
1.47 +#endif
1.48 +
1.49 +/*
1.50 +** Make sure we can call this stuff from C++.
1.51 +*/
1.52 +#ifdef __cplusplus
1.53 +extern "C" {
1.54 +#endif
1.55 +
1.56 +
1.57 +/*
1.58 +** Add the ability to override 'extern'
1.59 +*/
1.60 +#ifndef SQLITE_EXTERN
1.61 +# define SQLITE_EXTERN extern
1.62 +#endif
1.63 +
1.64 +/*
1.65 +** These no-op macros are used in front of interfaces to mark those
1.66 +** interfaces as either deprecated or experimental. New applications
1.67 +** should not use deprecated intrfaces - they are support for backwards
1.68 +** compatibility only. Application writers should be aware that
1.69 +** experimental interfaces are subject to change in point releases.
1.70 +**
1.71 +** These macros used to resolve to various kinds of compiler magic that
1.72 +** would generate warning messages when they were used. But that
1.73 +** compiler magic ended up generating such a flurry of bug reports
1.74 +** that we have taken it all out and gone back to using simple
1.75 +** noop macros.
1.76 +*/
1.77 +#define SQLITE_DEPRECATED
1.78 +#define SQLITE_EXPERIMENTAL
1.79 +
1.80 +/*
1.81 +** Ensure these symbols were not defined by some previous header file.
1.82 +*/
1.83 +#ifdef SQLITE_VERSION
1.84 +# undef SQLITE_VERSION
1.85 +#endif
1.86 +#ifdef SQLITE_VERSION_NUMBER
1.87 +# undef SQLITE_VERSION_NUMBER
1.88 +#endif
1.89 +
1.90 +/*
1.91 +** CAPI3REF: Compile-Time Library Version Numbers {H10010} <S60100>
1.92 +**
1.93 +** The SQLITE_VERSION and SQLITE_VERSION_NUMBER #defines in
1.94 +** the sqlite3.h file specify the version of SQLite with which
1.95 +** that header file is associated.
1.96 +**
1.97 +** The "version" of SQLite is a string of the form "X.Y.Z".
1.98 +** The phrase "alpha" or "beta" might be appended after the Z.
1.99 +** The X value is major version number always 3 in SQLite3.
1.100 +** The X value only changes when backwards compatibility is
1.101 +** broken and we intend to never break backwards compatibility.
1.102 +** The Y value is the minor version number and only changes when
1.103 +** there are major feature enhancements that are forwards compatible
1.104 +** but not backwards compatible.
1.105 +** The Z value is the release number and is incremented with
1.106 +** each release but resets back to 0 whenever Y is incremented.
1.107 +**
1.108 +** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
1.109 +**
1.110 +** INVARIANTS:
1.111 +**
1.112 +** {H10011} The SQLITE_VERSION #define in the sqlite3.h header file shall
1.113 +** evaluate to a string literal that is the SQLite version
1.114 +** with which the header file is associated.
1.115 +**
1.116 +** {H10014} The SQLITE_VERSION_NUMBER #define shall resolve to an integer
1.117 +** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z
1.118 +** are the major version, minor version, and release number.
1.119 +*/
1.120 +#define SQLITE_VERSION "3.6.3"
1.121 +#define SQLITE_VERSION_NUMBER 3006003
1.122 +
1.123 +/*
1.124 +** CAPI3REF: Run-Time Library Version Numbers {H10020} <S60100>
1.125 +** KEYWORDS: sqlite3_version
1.126 +**
1.127 +** These features provide the same information as the [SQLITE_VERSION]
1.128 +** and [SQLITE_VERSION_NUMBER] #defines in the header, but are associated
1.129 +** with the library instead of the header file. Cautious programmers might
1.130 +** include a check in their application to verify that
1.131 +** sqlite3_libversion_number() always returns the value
1.132 +** [SQLITE_VERSION_NUMBER].
1.133 +**
1.134 +** The sqlite3_libversion() function returns the same information as is
1.135 +** in the sqlite3_version[] string constant. The function is provided
1.136 +** for use in DLLs since DLL users usually do not have direct access to string
1.137 +** constants within the DLL.
1.138 +**
1.139 +** INVARIANTS:
1.140 +**
1.141 +** {H10021} The [sqlite3_libversion_number()] interface shall return
1.142 +** an integer equal to [SQLITE_VERSION_NUMBER].
1.143 +**
1.144 +** {H10022} The [sqlite3_version] string constant shall contain
1.145 +** the text of the [SQLITE_VERSION] string.
1.146 +**
1.147 +** {H10023} The [sqlite3_libversion()] function shall return
1.148 +** a pointer to the [sqlite3_version] string constant.
1.149 +*/
1.150 +SQLITE_EXTERN const char sqlite3_version[];
1.151 +IMPORT_C const char *sqlite3_libversion(void);
1.152 +IMPORT_C int sqlite3_libversion_number(void);
1.153 +
1.154 +/*
1.155 +** CAPI3REF: Test To See If The Library Is Threadsafe {H10100} <S60100>
1.156 +**
1.157 +** SQLite can be compiled with or without mutexes. When
1.158 +** the [SQLITE_THREADSAFE] C preprocessor macro 1 or 2, mutexes
1.159 +** are enabled and SQLite is threadsafe. When the
1.160 +** [SQLITE_THREADSAFE] macro is 0,
1.161 +** the mutexes are omitted. Without the mutexes, it is not safe
1.162 +** to use SQLite concurrently from more than one thread.
1.163 +**
1.164 +** Enabling mutexes incurs a measurable performance penalty.
1.165 +** So if speed is of utmost importance, it makes sense to disable
1.166 +** the mutexes. But for maximum safety, mutexes should be enabled.
1.167 +** The default behavior is for mutexes to be enabled.
1.168 +**
1.169 +** This interface can be used by a program to make sure that the
1.170 +** version of SQLite that it is linking against was compiled with
1.171 +** the desired setting of the [SQLITE_THREADSAFE] macro.
1.172 +**
1.173 +** This interface only reports on the compile-time mutex setting
1.174 +** of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with
1.175 +** SQLITE_THREADSAFE=1 then mutexes are enabled by default but
1.176 +** can be fully or partially disabled using a call to [sqlite3_config()]
1.177 +** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
1.178 +** or [SQLITE_CONFIG_MUTEX]. The return value of this function shows
1.179 +** only the default compile-time setting, not any run-time changes
1.180 +** to that setting.
1.181 +**
1.182 +** See the [threading mode] documentation for additional information.
1.183 +**
1.184 +** INVARIANTS:
1.185 +**
1.186 +** {H10101} The [sqlite3_threadsafe()] function shall return nonzero if
1.187 +** and only if
1.188 +** SQLite was compiled with the its mutexes enabled by default.
1.189 +**
1.190 +** {H10102} The value returned by the [sqlite3_threadsafe()] function
1.191 +** shall not change when mutex setting are modified at
1.192 +** runtime using the [sqlite3_config()] interface and
1.193 +** especially the [SQLITE_CONFIG_SINGLETHREAD],
1.194 +** [SQLITE_CONFIG_MULTITHREAD], [SQLITE_CONFIG_SERIALIZED],
1.195 +** and [SQLITE_CONFIG_MUTEX] verbs.
1.196 +*/
1.197 +IMPORT_C int sqlite3_threadsafe(void);
1.198 +
1.199 +/*
1.200 +** CAPI3REF: Database Connection Handle {H12000} <S40200>
1.201 +** KEYWORDS: {database connection} {database connections}
1.202 +**
1.203 +** Each open SQLite database is represented by a pointer to an instance of
1.204 +** the opaque structure named "sqlite3". It is useful to think of an sqlite3
1.205 +** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and
1.206 +** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
1.207 +** is its destructor. There are many other interfaces (such as
1.208 +** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
1.209 +** [sqlite3_busy_timeout()] to name but three) that are methods on an
1.210 +** sqlite3 object.
1.211 +*/
1.212 +typedef struct sqlite3 sqlite3;
1.213 +
1.214 +/*
1.215 +** CAPI3REF: 64-Bit Integer Types {H10200} <S10110>
1.216 +** KEYWORDS: sqlite_int64 sqlite_uint64
1.217 +**
1.218 +** Because there is no cross-platform way to specify 64-bit integer types
1.219 +** SQLite includes typedefs for 64-bit signed and unsigned integers.
1.220 +**
1.221 +** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
1.222 +** The sqlite_int64 and sqlite_uint64 types are supported for backwards
1.223 +** compatibility only.
1.224 +**
1.225 +** INVARIANTS:
1.226 +**
1.227 +** {H10201} The [sqlite_int64] and [sqlite3_int64] type shall specify
1.228 +** a 64-bit signed integer.
1.229 +**
1.230 +** {H10202} The [sqlite_uint64] and [sqlite3_uint64] type shall specify
1.231 +** a 64-bit unsigned integer.
1.232 +*/
1.233 +#ifdef SQLITE_INT64_TYPE
1.234 + typedef SQLITE_INT64_TYPE sqlite_int64;
1.235 + typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
1.236 +#elif defined(_MSC_VER) || defined(__BORLANDC__)
1.237 + typedef __int64 sqlite_int64;
1.238 + typedef unsigned __int64 sqlite_uint64;
1.239 +#else
1.240 + typedef long long int sqlite_int64;
1.241 + typedef unsigned long long int sqlite_uint64;
1.242 +#endif
1.243 +typedef sqlite_int64 sqlite3_int64;
1.244 +typedef sqlite_uint64 sqlite3_uint64;
1.245 +
1.246 +/*
1.247 +** If compiling for a processor that lacks floating point support,
1.248 +** substitute integer for floating-point.
1.249 +*/
1.250 +#ifdef SQLITE_OMIT_FLOATING_POINT
1.251 +# define double sqlite3_int64
1.252 +#endif
1.253 +
1.254 +/*
1.255 +** CAPI3REF: Closing A Database Connection {H12010} <S30100><S40200>
1.256 +**
1.257 +** This routine is the destructor for the [sqlite3] object.
1.258 +**
1.259 +** Applications should [sqlite3_finalize | finalize] all [prepared statements]
1.260 +** and [sqlite3_blob_close | close] all [BLOB handles] associated with
1.261 +** the [sqlite3] object prior to attempting to close the object.
1.262 +** The [sqlite3_next_stmt()] interface can be used to locate all
1.263 +** [prepared statements] associated with a [database connection] if desired.
1.264 +** Typical code might look like this:
1.265 +**
1.266 +** <blockquote><pre>
1.267 +** sqlite3_stmt *pStmt;
1.268 +** while( (pStmt = sqlite3_next_stmt(db, 0))!=0 ){
1.269 +** sqlite3_finalize(pStmt);
1.270 +** }
1.271 +** </pre></blockquote>
1.272 +**
1.273 +** If [sqlite3_close()] is invoked while a transaction is open,
1.274 +** the transaction is automatically rolled back.
1.275 +**
1.276 +** INVARIANTS:
1.277 +**
1.278 +** {H12011} A successful call to [sqlite3_close(C)] shall destroy the
1.279 +** [database connection] object C.
1.280 +**
1.281 +** {H12012} A successful call to [sqlite3_close(C)] shall return SQLITE_OK.
1.282 +**
1.283 +** {H12013} A successful call to [sqlite3_close(C)] shall release all
1.284 +** memory and system resources associated with [database connection]
1.285 +** C.
1.286 +**
1.287 +** {H12014} A call to [sqlite3_close(C)] on a [database connection] C that
1.288 +** has one or more open [prepared statements] shall fail with
1.289 +** an [SQLITE_BUSY] error code.
1.290 +**
1.291 +** {H12015} A call to [sqlite3_close(C)] where C is a NULL pointer shall
1.292 +** return SQLITE_OK.
1.293 +**
1.294 +** {H12019} When [sqlite3_close(C)] is invoked on a [database connection] C
1.295 +** that has a pending transaction, the transaction shall be
1.296 +** rolled back.
1.297 +**
1.298 +** ASSUMPTIONS:
1.299 +**
1.300 +** {A12016} The C parameter to [sqlite3_close(C)] must be either a NULL
1.301 +** pointer or an [sqlite3] object pointer obtained
1.302 +** from [sqlite3_open()], [sqlite3_open16()], or
1.303 +** [sqlite3_open_v2()], and not previously closed.
1.304 +*/
1.305 +IMPORT_C int sqlite3_close(sqlite3 *);
1.306 +
1.307 +/*
1.308 +** The type for a callback function.
1.309 +** This is legacy and deprecated. It is included for historical
1.310 +** compatibility and is not documented.
1.311 +*/
1.312 +typedef int (*sqlite3_callback)(void*,int,char**, char**);
1.313 +
1.314 +/*
1.315 +** CAPI3REF: One-Step Query Execution Interface {H12100} <S10000>
1.316 +**
1.317 +** The sqlite3_exec() interface is a convenient way of running one or more
1.318 +** SQL statements without having to write a lot of C code. The UTF-8 encoded
1.319 +** SQL statements are passed in as the second parameter to sqlite3_exec().
1.320 +** The statements are evaluated one by one until either an error or
1.321 +** an interrupt is encountered, or until they are all done. The 3rd parameter
1.322 +** is an optional callback that is invoked once for each row of any query
1.323 +** results produced by the SQL statements. The 5th parameter tells where
1.324 +** to write any error messages.
1.325 +**
1.326 +** The error message passed back through the 5th parameter is held
1.327 +** in memory obtained from [sqlite3_malloc()]. To avoid a memory leak,
1.328 +** the calling application should call [sqlite3_free()] on any error
1.329 +** message returned through the 5th parameter when it has finished using
1.330 +** the error message.
1.331 +**
1.332 +** If the SQL statement in the 2nd parameter is NULL or an empty string
1.333 +** or a string containing only whitespace and comments, then no SQL
1.334 +** statements are evaluated and the database is not changed.
1.335 +**
1.336 +** The sqlite3_exec() interface is implemented in terms of
1.337 +** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
1.338 +** The sqlite3_exec() routine does nothing to the database that cannot be done
1.339 +** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
1.340 +**
1.341 +** INVARIANTS:
1.342 +**
1.343 +** {H12101} A successful invocation of [sqlite3_exec(D,S,C,A,E)]
1.344 +** shall sequentially evaluate all of the UTF-8 encoded,
1.345 +** semicolon-separated SQL statements in the zero-terminated
1.346 +** string S within the context of the [database connection] D.
1.347 +**
1.348 +** {H12102} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is NULL then
1.349 +** the actions of the interface shall be the same as if the
1.350 +** S parameter were an empty string.
1.351 +**
1.352 +** {H12104} The return value of [sqlite3_exec()] shall be [SQLITE_OK] if all
1.353 +** SQL statements run successfully and to completion.
1.354 +**
1.355 +** {H12105} The return value of [sqlite3_exec()] shall be an appropriate
1.356 +** non-zero [error code] if any SQL statement fails.
1.357 +**
1.358 +** {H12107} If one or more of the SQL statements handed to [sqlite3_exec()]
1.359 +** return results and the 3rd parameter is not NULL, then
1.360 +** the callback function specified by the 3rd parameter shall be
1.361 +** invoked once for each row of result.
1.362 +**
1.363 +** {H12110} If the callback returns a non-zero value then [sqlite3_exec()]
1.364 +** shall abort the SQL statement it is currently evaluating,
1.365 +** skip all subsequent SQL statements, and return [SQLITE_ABORT].
1.366 +**
1.367 +** {H12113} The [sqlite3_exec()] routine shall pass its 4th parameter through
1.368 +** as the 1st parameter of the callback.
1.369 +**
1.370 +** {H12116} The [sqlite3_exec()] routine shall set the 2nd parameter of its
1.371 +** callback to be the number of columns in the current row of
1.372 +** result.
1.373 +**
1.374 +** {H12119} The [sqlite3_exec()] routine shall set the 3rd parameter of its
1.375 +** callback to be an array of pointers to strings holding the
1.376 +** values for each column in the current result set row as
1.377 +** obtained from [sqlite3_column_text()].
1.378 +**
1.379 +** {H12122} The [sqlite3_exec()] routine shall set the 4th parameter of its
1.380 +** callback to be an array of pointers to strings holding the
1.381 +** names of result columns as obtained from [sqlite3_column_name()].
1.382 +**
1.383 +** {H12125} If the 3rd parameter to [sqlite3_exec()] is NULL then
1.384 +** [sqlite3_exec()] shall silently discard query results.
1.385 +**
1.386 +** {H12131} If an error occurs while parsing or evaluating any of the SQL
1.387 +** statements in the S parameter of [sqlite3_exec(D,S,C,A,E)] and if
1.388 +** the E parameter is not NULL, then [sqlite3_exec()] shall store
1.389 +** in *E an appropriate error message written into memory obtained
1.390 +** from [sqlite3_malloc()].
1.391 +**
1.392 +** {H12134} The [sqlite3_exec(D,S,C,A,E)] routine shall set the value of
1.393 +** *E to NULL if E is not NULL and there are no errors.
1.394 +**
1.395 +** {H12137} The [sqlite3_exec(D,S,C,A,E)] function shall set the [error code]
1.396 +** and message accessible via [sqlite3_errcode()],
1.397 +** [sqlite3_errmsg()], and [sqlite3_errmsg16()].
1.398 +**
1.399 +** {H12138} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is NULL or an
1.400 +** empty string or contains nothing other than whitespace, comments,
1.401 +** and/or semicolons, then results of [sqlite3_errcode()],
1.402 +** [sqlite3_errmsg()], and [sqlite3_errmsg16()]
1.403 +** shall reset to indicate no errors.
1.404 +**
1.405 +** ASSUMPTIONS:
1.406 +**
1.407 +** {A12141} The first parameter to [sqlite3_exec()] must be an valid and open
1.408 +** [database connection].
1.409 +**
1.410 +** {A12142} The database connection must not be closed while
1.411 +** [sqlite3_exec()] is running.
1.412 +**
1.413 +** {A12143} The calling function should use [sqlite3_free()] to free
1.414 +** the memory that *errmsg is left pointing at once the error
1.415 +** message is no longer needed.
1.416 +**
1.417 +** {A12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()]
1.418 +** must remain unchanged while [sqlite3_exec()] is running.
1.419 +*/
1.420 +IMPORT_C int sqlite3_exec(
1.421 + sqlite3*, /* An open database */
1.422 + const char *sql, /* SQL to be evaluated */
1.423 + int (*callback)(void*,int,char**,char**), /* Callback function */
1.424 + void *, /* 1st argument to callback */
1.425 + char **errmsg /* Error msg written here */
1.426 +);
1.427 +
1.428 +/*
1.429 +** CAPI3REF: Result Codes {H10210} <S10700>
1.430 +** KEYWORDS: SQLITE_OK {error code} {error codes}
1.431 +** KEYWORDS: {result code} {result codes}
1.432 +**
1.433 +** Many SQLite functions return an integer result code from the set shown
1.434 +** here in order to indicates success or failure.
1.435 +**
1.436 +** New error codes may be added in future versions of SQLite.
1.437 +**
1.438 +** See also: [SQLITE_IOERR_READ | extended result codes]
1.439 +*/
1.440 +#define SQLITE_OK 0 /* Successful result */
1.441 +/* beginning-of-error-codes */
1.442 +#define SQLITE_ERROR 1 /* SQL error or missing database */
1.443 +#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */
1.444 +#define SQLITE_PERM 3 /* Access permission denied */
1.445 +#define SQLITE_ABORT 4 /* Callback routine requested an abort */
1.446 +#define SQLITE_BUSY 5 /* The database file is locked */
1.447 +#define SQLITE_LOCKED 6 /* A table in the database is locked */
1.448 +#define SQLITE_NOMEM 7 /* A malloc() failed */
1.449 +#define SQLITE_READONLY 8 /* Attempt to write a readonly database */
1.450 +#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
1.451 +#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
1.452 +#define SQLITE_CORRUPT 11 /* The database disk image is malformed */
1.453 +#define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */
1.454 +#define SQLITE_FULL 13 /* Insertion failed because database is full */
1.455 +#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
1.456 +#define SQLITE_PROTOCOL 15 /* NOT USED. Database lock protocol error */
1.457 +#define SQLITE_EMPTY 16 /* Database is empty */
1.458 +#define SQLITE_SCHEMA 17 /* The database schema changed */
1.459 +#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
1.460 +#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
1.461 +#define SQLITE_MISMATCH 20 /* Data type mismatch */
1.462 +#define SQLITE_MISUSE 21 /* Library used incorrectly */
1.463 +#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
1.464 +#define SQLITE_AUTH 23 /* Authorization denied */
1.465 +#define SQLITE_FORMAT 24 /* Auxiliary database format error */
1.466 +#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
1.467 +#define SQLITE_NOTADB 26 /* File opened that is not a database file */
1.468 +#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
1.469 +#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
1.470 +/* end-of-error-codes */
1.471 +
1.472 +/*
1.473 +** CAPI3REF: Extended Result Codes {H10220} <S10700>
1.474 +** KEYWORDS: {extended error code} {extended error codes}
1.475 +** KEYWORDS: {extended result code} {extended result codes}
1.476 +**
1.477 +** In its default configuration, SQLite API routines return one of 26 integer
1.478 +** [SQLITE_OK | result codes]. However, experience has shown that many of
1.479 +** these result codes are too coarse-grained. They do not provide as
1.480 +** much information about problems as programmers might like. In an effort to
1.481 +** address this, newer versions of SQLite (version 3.3.8 and later) include
1.482 +** support for additional result codes that provide more detailed information
1.483 +** about errors. The extended result codes are enabled or disabled
1.484 +** on a per database connection basis using the
1.485 +** [sqlite3_extended_result_codes()] API.
1.486 +**
1.487 +** Some of the available extended result codes are listed here.
1.488 +** One may expect the number of extended result codes will be expand
1.489 +** over time. Software that uses extended result codes should expect
1.490 +** to see new result codes in future releases of SQLite.
1.491 +**
1.492 +** The SQLITE_OK result code will never be extended. It will always
1.493 +** be exactly zero.
1.494 +**
1.495 +** INVARIANTS:
1.496 +**
1.497 +** {H10223} The symbolic name for an extended result code shall contains
1.498 +** a related primary result code as a prefix.
1.499 +**
1.500 +** {H10224} Primary result code names shall contain a single "_" character.
1.501 +**
1.502 +** {H10225} Extended result code names shall contain two or more "_" characters.
1.503 +**
1.504 +** {H10226} The numeric value of an extended result code shall contain the
1.505 +** numeric value of its corresponding primary result code in
1.506 +** its least significant 8 bits.
1.507 +*/
1.508 +#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))
1.509 +#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))
1.510 +#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8))
1.511 +#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8))
1.512 +#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8))
1.513 +#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8))
1.514 +#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8))
1.515 +#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8))
1.516 +#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8))
1.517 +#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8))
1.518 +#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8))
1.519 +#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8))
1.520 +#define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8))
1.521 +#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
1.522 +#define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8))
1.523 +
1.524 +/*
1.525 +** CAPI3REF: Flags For File Open Operations {H10230} <H11120> <H12700>
1.526 +**
1.527 +** These bit values are intended for use in the
1.528 +** 3rd parameter to the [sqlite3_open_v2()] interface and
1.529 +** in the 4th parameter to the xOpen method of the
1.530 +** [sqlite3_vfs] object.
1.531 +*/
1.532 +#define SQLITE_OPEN_READONLY 0x00000001
1.533 +#define SQLITE_OPEN_READWRITE 0x00000002
1.534 +#define SQLITE_OPEN_CREATE 0x00000004
1.535 +#define SQLITE_OPEN_DELETEONCLOSE 0x00000008
1.536 +#define SQLITE_OPEN_EXCLUSIVE 0x00000010
1.537 +#define SQLITE_OPEN_MAIN_DB 0x00000100
1.538 +#define SQLITE_OPEN_TEMP_DB 0x00000200
1.539 +#define SQLITE_OPEN_TRANSIENT_DB 0x00000400
1.540 +#define SQLITE_OPEN_MAIN_JOURNAL 0x00000800
1.541 +#define SQLITE_OPEN_TEMP_JOURNAL 0x00001000
1.542 +#define SQLITE_OPEN_SUBJOURNAL 0x00002000
1.543 +#define SQLITE_OPEN_MASTER_JOURNAL 0x00004000
1.544 +#define SQLITE_OPEN_NOMUTEX 0x00008000
1.545 +#define SQLITE_OPEN_FULLMUTEX 0x00010000
1.546 +
1.547 +/*
1.548 +** CAPI3REF: Device Characteristics {H10240} <H11120>
1.549 +**
1.550 +** The xDeviceCapabilities method of the [sqlite3_io_methods]
1.551 +** object returns an integer which is a vector of the these
1.552 +** bit values expressing I/O characteristics of the mass storage
1.553 +** device that holds the file that the [sqlite3_io_methods]
1.554 +** refers to.
1.555 +**
1.556 +** The SQLITE_IOCAP_ATOMIC property means that all writes of
1.557 +** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
1.558 +** mean that writes of blocks that are nnn bytes in size and
1.559 +** are aligned to an address which is an integer multiple of
1.560 +** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
1.561 +** that when data is appended to a file, the data is appended
1.562 +** first then the size of the file is extended, never the other
1.563 +** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
1.564 +** information is written to disk in the same order as calls
1.565 +** to xWrite().
1.566 +*/
1.567 +#define SQLITE_IOCAP_ATOMIC 0x00000001
1.568 +#define SQLITE_IOCAP_ATOMIC512 0x00000002
1.569 +#define SQLITE_IOCAP_ATOMIC1K 0x00000004
1.570 +#define SQLITE_IOCAP_ATOMIC2K 0x00000008
1.571 +#define SQLITE_IOCAP_ATOMIC4K 0x00000010
1.572 +#define SQLITE_IOCAP_ATOMIC8K 0x00000020
1.573 +#define SQLITE_IOCAP_ATOMIC16K 0x00000040
1.574 +#define SQLITE_IOCAP_ATOMIC32K 0x00000080
1.575 +#define SQLITE_IOCAP_ATOMIC64K 0x00000100
1.576 +#define SQLITE_IOCAP_SAFE_APPEND 0x00000200
1.577 +#define SQLITE_IOCAP_SEQUENTIAL 0x00000400
1.578 +
1.579 +/*
1.580 +** CAPI3REF: File Locking Levels {H10250} <H11120> <H11310>
1.581 +**
1.582 +** SQLite uses one of these integer values as the second
1.583 +** argument to calls it makes to the xLock() and xUnlock() methods
1.584 +** of an [sqlite3_io_methods] object.
1.585 +*/
1.586 +#define SQLITE_LOCK_NONE 0
1.587 +#define SQLITE_LOCK_SHARED 1
1.588 +#define SQLITE_LOCK_RESERVED 2
1.589 +#define SQLITE_LOCK_PENDING 3
1.590 +#define SQLITE_LOCK_EXCLUSIVE 4
1.591 +
1.592 +/*
1.593 +** CAPI3REF: Synchronization Type Flags {H10260} <H11120>
1.594 +**
1.595 +** When SQLite invokes the xSync() method of an
1.596 +** [sqlite3_io_methods] object it uses a combination of
1.597 +** these integer values as the second argument.
1.598 +**
1.599 +** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
1.600 +** sync operation only needs to flush data to mass storage. Inode
1.601 +** information need not be flushed. The SQLITE_SYNC_NORMAL flag means
1.602 +** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means
1.603 +** to use Mac OS-X style fullsync instead of fsync().
1.604 +*/
1.605 +#define SQLITE_SYNC_NORMAL 0x00002
1.606 +#define SQLITE_SYNC_FULL 0x00003
1.607 +#define SQLITE_SYNC_DATAONLY 0x00010
1.608 +
1.609 +/*
1.610 +** CAPI3REF: OS Interface Open File Handle {H11110} <S20110>
1.611 +**
1.612 +** An [sqlite3_file] object represents an open file in the OS
1.613 +** interface layer. Individual OS interface implementations will
1.614 +** want to subclass this object by appending additional fields
1.615 +** for their own use. The pMethods entry is a pointer to an
1.616 +** [sqlite3_io_methods] object that defines methods for performing
1.617 +** I/O operations on the open file.
1.618 +*/
1.619 +typedef struct sqlite3_file sqlite3_file;
1.620 +struct sqlite3_file {
1.621 + const struct sqlite3_io_methods *pMethods; /* Methods for an open file */
1.622 +};
1.623 +
1.624 +/*
1.625 +** CAPI3REF: OS Interface File Virtual Methods Object {H11120} <S20110>
1.626 +**
1.627 +** Every file opened by the [sqlite3_vfs] xOpen method populates an
1.628 +** [sqlite3_file] object (or, more commonly, a subclass of the
1.629 +** [sqlite3_file] object) with a pointer to an instance of this object.
1.630 +** This object defines the methods used to perform various operations
1.631 +** against the open file represented by the [sqlite3_file] object.
1.632 +**
1.633 +** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
1.634 +** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
1.635 +** The second choice is a Mac OS-X style fullsync. The [SQLITE_SYNC_DATAONLY]
1.636 +** flag may be ORed in to indicate that only the data of the file
1.637 +** and not its inode needs to be synced.
1.638 +**
1.639 +** The integer values to xLock() and xUnlock() are one of
1.640 +** <ul>
1.641 +** <li> [SQLITE_LOCK_NONE],
1.642 +** <li> [SQLITE_LOCK_SHARED],
1.643 +** <li> [SQLITE_LOCK_RESERVED],
1.644 +** <li> [SQLITE_LOCK_PENDING], or
1.645 +** <li> [SQLITE_LOCK_EXCLUSIVE].
1.646 +** </ul>
1.647 +** xLock() increases the lock. xUnlock() decreases the lock.
1.648 +** The xCheckReservedLock() method checks whether any database connection,
1.649 +** either in this process or in some other process, is holding a RESERVED,
1.650 +** PENDING, or EXCLUSIVE lock on the file. It returns true
1.651 +** if such a lock exists and false otherwise.
1.652 +**
1.653 +** The xFileControl() method is a generic interface that allows custom
1.654 +** VFS implementations to directly control an open file using the
1.655 +** [sqlite3_file_control()] interface. The second "op" argument is an
1.656 +** integer opcode. The third argument is a generic pointer intended to
1.657 +** point to a structure that may contain arguments or space in which to
1.658 +** write return values. Potential uses for xFileControl() might be
1.659 +** functions to enable blocking locks with timeouts, to change the
1.660 +** locking strategy (for example to use dot-file locks), to inquire
1.661 +** about the status of a lock, or to break stale locks. The SQLite
1.662 +** core reserves all opcodes less than 100 for its own use.
1.663 +** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
1.664 +** Applications that define a custom xFileControl method should use opcodes
1.665 +** greater than 100 to avoid conflicts.
1.666 +**
1.667 +** The xSectorSize() method returns the sector size of the
1.668 +** device that underlies the file. The sector size is the
1.669 +** minimum write that can be performed without disturbing
1.670 +** other bytes in the file. The xDeviceCharacteristics()
1.671 +** method returns a bit vector describing behaviors of the
1.672 +** underlying device:
1.673 +**
1.674 +** <ul>
1.675 +** <li> [SQLITE_IOCAP_ATOMIC]
1.676 +** <li> [SQLITE_IOCAP_ATOMIC512]
1.677 +** <li> [SQLITE_IOCAP_ATOMIC1K]
1.678 +** <li> [SQLITE_IOCAP_ATOMIC2K]
1.679 +** <li> [SQLITE_IOCAP_ATOMIC4K]
1.680 +** <li> [SQLITE_IOCAP_ATOMIC8K]
1.681 +** <li> [SQLITE_IOCAP_ATOMIC16K]
1.682 +** <li> [SQLITE_IOCAP_ATOMIC32K]
1.683 +** <li> [SQLITE_IOCAP_ATOMIC64K]
1.684 +** <li> [SQLITE_IOCAP_SAFE_APPEND]
1.685 +** <li> [SQLITE_IOCAP_SEQUENTIAL]
1.686 +** </ul>
1.687 +**
1.688 +** The SQLITE_IOCAP_ATOMIC property means that all writes of
1.689 +** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
1.690 +** mean that writes of blocks that are nnn bytes in size and
1.691 +** are aligned to an address which is an integer multiple of
1.692 +** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
1.693 +** that when data is appended to a file, the data is appended
1.694 +** first then the size of the file is extended, never the other
1.695 +** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
1.696 +** information is written to disk in the same order as calls
1.697 +** to xWrite().
1.698 +*/
1.699 +typedef struct sqlite3_io_methods sqlite3_io_methods;
1.700 +struct sqlite3_io_methods {
1.701 + int iVersion;
1.702 + int (*xClose)(sqlite3_file*);
1.703 + int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
1.704 + int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
1.705 + int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
1.706 + int (*xSync)(sqlite3_file*, int flags);
1.707 + int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
1.708 + int (*xLock)(sqlite3_file*, int);
1.709 + int (*xUnlock)(sqlite3_file*, int);
1.710 + int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
1.711 + int (*xFileControl)(sqlite3_file*, int op, void *pArg);
1.712 + int (*xSectorSize)(sqlite3_file*);
1.713 + int (*xDeviceCharacteristics)(sqlite3_file*);
1.714 + /* Additional methods may be added in future releases */
1.715 +};
1.716 +
1.717 +/*
1.718 +** CAPI3REF: Standard File Control Opcodes {H11310} <S30800>
1.719 +**
1.720 +** These integer constants are opcodes for the xFileControl method
1.721 +** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
1.722 +** interface.
1.723 +**
1.724 +** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
1.725 +** opcode causes the xFileControl method to write the current state of
1.726 +** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
1.727 +** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
1.728 +** into an integer that the pArg argument points to. This capability
1.729 +** is used during testing and only needs to be supported when SQLITE_TEST
1.730 +** is defined.
1.731 +*/
1.732 +#define SQLITE_FCNTL_LOCKSTATE 1
1.733 +
1.734 +/*
1.735 +** CAPI3REF: Mutex Handle {H17110} <S20130>
1.736 +**
1.737 +** The mutex module within SQLite defines [sqlite3_mutex] to be an
1.738 +** abstract type for a mutex object. The SQLite core never looks
1.739 +** at the internal representation of an [sqlite3_mutex]. It only
1.740 +** deals with pointers to the [sqlite3_mutex] object.
1.741 +**
1.742 +** Mutexes are created using [sqlite3_mutex_alloc()].
1.743 +*/
1.744 +typedef struct sqlite3_mutex sqlite3_mutex;
1.745 +
1.746 +/*
1.747 +** CAPI3REF: OS Interface Object {H11140} <S20100>
1.748 +**
1.749 +** An instance of the sqlite3_vfs object defines the interface between
1.750 +** the SQLite core and the underlying operating system. The "vfs"
1.751 +** in the name of the object stands for "virtual file system".
1.752 +**
1.753 +** The value of the iVersion field is initially 1 but may be larger in
1.754 +** future versions of SQLite. Additional fields may be appended to this
1.755 +** object when the iVersion value is increased. Note that the structure
1.756 +** of the sqlite3_vfs object changes in the transaction between
1.757 +** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not
1.758 +** modified.
1.759 +**
1.760 +** The szOsFile field is the size of the subclassed [sqlite3_file]
1.761 +** structure used by this VFS. mxPathname is the maximum length of
1.762 +** a pathname in this VFS.
1.763 +**
1.764 +** Registered sqlite3_vfs objects are kept on a linked list formed by
1.765 +** the pNext pointer. The [sqlite3_vfs_register()]
1.766 +** and [sqlite3_vfs_unregister()] interfaces manage this list
1.767 +** in a thread-safe way. The [sqlite3_vfs_find()] interface
1.768 +** searches the list. Neither the application code nor the VFS
1.769 +** implementation should use the pNext pointer.
1.770 +**
1.771 +** The pNext field is the only field in the sqlite3_vfs
1.772 +** structure that SQLite will ever modify. SQLite will only access
1.773 +** or modify this field while holding a particular static mutex.
1.774 +** The application should never modify anything within the sqlite3_vfs
1.775 +** object once the object has been registered.
1.776 +**
1.777 +** The zName field holds the name of the VFS module. The name must
1.778 +** be unique across all VFS modules.
1.779 +**
1.780 +** {H11141} SQLite will guarantee that the zFilename parameter to xOpen
1.781 +** is either a NULL pointer or string obtained
1.782 +** from xFullPathname(). SQLite further guarantees that
1.783 +** the string will be valid and unchanged until xClose() is
1.784 +** called. {END} Because of the previous sentense,
1.785 +** the [sqlite3_file] can safely store a pointer to the
1.786 +** filename if it needs to remember the filename for some reason.
1.787 +** If the zFilename parameter is xOpen is a NULL pointer then xOpen
1.788 +** must invite its own temporary name for the file. Whenever the
1.789 +** xFilename parameter is NULL it will also be the case that the
1.790 +** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
1.791 +**
1.792 +** {H11142} The flags argument to xOpen() includes all bits set in
1.793 +** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()]
1.794 +** or [sqlite3_open16()] is used, then flags includes at least
1.795 +** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. {END}
1.796 +** If xOpen() opens a file read-only then it sets *pOutFlags to
1.797 +** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set.
1.798 +**
1.799 +** {H11143} SQLite will also add one of the following flags to the xOpen()
1.800 +** call, depending on the object being opened:
1.801 +**
1.802 +** <ul>
1.803 +** <li> [SQLITE_OPEN_MAIN_DB]
1.804 +** <li> [SQLITE_OPEN_MAIN_JOURNAL]
1.805 +** <li> [SQLITE_OPEN_TEMP_DB]
1.806 +** <li> [SQLITE_OPEN_TEMP_JOURNAL]
1.807 +** <li> [SQLITE_OPEN_TRANSIENT_DB]
1.808 +** <li> [SQLITE_OPEN_SUBJOURNAL]
1.809 +** <li> [SQLITE_OPEN_MASTER_JOURNAL]
1.810 +** </ul> {END}
1.811 +**
1.812 +** The file I/O implementation can use the object type flags to
1.813 +** change the way it deals with files. For example, an application
1.814 +** that does not care about crash recovery or rollback might make
1.815 +** the open of a journal file a no-op. Writes to this journal would
1.816 +** also be no-ops, and any attempt to read the journal would return
1.817 +** SQLITE_IOERR. Or the implementation might recognize that a database
1.818 +** file will be doing page-aligned sector reads and writes in a random
1.819 +** order and set up its I/O subsystem accordingly.
1.820 +**
1.821 +** SQLite might also add one of the following flags to the xOpen method:
1.822 +**
1.823 +** <ul>
1.824 +** <li> [SQLITE_OPEN_DELETEONCLOSE]
1.825 +** <li> [SQLITE_OPEN_EXCLUSIVE]
1.826 +** </ul>
1.827 +**
1.828 +** {H11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
1.829 +** deleted when it is closed. {H11146} The [SQLITE_OPEN_DELETEONCLOSE]
1.830 +** will be set for TEMP databases, journals and for subjournals.
1.831 +**
1.832 +** {H11147} The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
1.833 +** for exclusive access. This flag is set for all files except
1.834 +** for the main database file.
1.835 +**
1.836 +** {H11148} At least szOsFile bytes of memory are allocated by SQLite
1.837 +** to hold the [sqlite3_file] structure passed as the third
1.838 +** argument to xOpen. {END} The xOpen method does not have to
1.839 +** allocate the structure; it should just fill it in.
1.840 +**
1.841 +** {H11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
1.842 +** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
1.843 +** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
1.844 +** to test whether a file is at least readable. {END} The file can be a
1.845 +** directory.
1.846 +**
1.847 +** {H11150} SQLite will always allocate at least mxPathname+1 bytes for the
1.848 +** output buffer xFullPathname. {H11151} The exact size of the output buffer
1.849 +** is also passed as a parameter to both methods. {END} If the output buffer
1.850 +** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
1.851 +** handled as a fatal error by SQLite, vfs implementations should endeavor
1.852 +** to prevent this by setting mxPathname to a sufficiently large value.
1.853 +**
1.854 +** The xRandomness(), xSleep(), and xCurrentTime() interfaces
1.855 +** are not strictly a part of the filesystem, but they are
1.856 +** included in the VFS structure for completeness.
1.857 +** The xRandomness() function attempts to return nBytes bytes
1.858 +** of good-quality randomness into zOut. The return value is
1.859 +** the actual number of bytes of randomness obtained.
1.860 +** The xSleep() method causes the calling thread to sleep for at
1.861 +** least the number of microseconds given. The xCurrentTime()
1.862 +** method returns a Julian Day Number for the current date and time.
1.863 +*/
1.864 +typedef struct sqlite3_vfs sqlite3_vfs;
1.865 +struct sqlite3_vfs {
1.866 + int iVersion; /* Structure version number */
1.867 + int szOsFile; /* Size of subclassed sqlite3_file */
1.868 + int mxPathname; /* Maximum file pathname length */
1.869 + sqlite3_vfs *pNext; /* Next registered VFS */
1.870 + const char *zName; /* Name of this virtual file system */
1.871 + void *pAppData; /* Pointer to application-specific data */
1.872 + int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
1.873 + int flags, int *pOutFlags);
1.874 + int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
1.875 + int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
1.876 + int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
1.877 + void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
1.878 + void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
1.879 + void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol);
1.880 + void (*xDlClose)(sqlite3_vfs*, void*);
1.881 + int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
1.882 + int (*xSleep)(sqlite3_vfs*, int microseconds);
1.883 + int (*xCurrentTime)(sqlite3_vfs*, double*);
1.884 + int (*xGetLastError)(sqlite3_vfs*, int, char *);
1.885 + /* New fields may be appended in figure versions. The iVersion
1.886 + ** value will increment whenever this happens. */
1.887 +};
1.888 +
1.889 +/*
1.890 +** CAPI3REF: Flags for the xAccess VFS method {H11190} <H11140>
1.891 +**
1.892 +** {H11191} These integer constants can be used as the third parameter to
1.893 +** the xAccess method of an [sqlite3_vfs] object. {END} They determine
1.894 +** what kind of permissions the xAccess method is looking for.
1.895 +** {H11192} With SQLITE_ACCESS_EXISTS, the xAccess method
1.896 +** simply checks whether the file exists.
1.897 +** {H11193} With SQLITE_ACCESS_READWRITE, the xAccess method
1.898 +** checks whether the file is both readable and writable.
1.899 +** {H11194} With SQLITE_ACCESS_READ, the xAccess method
1.900 +** checks whether the file is readable.
1.901 +*/
1.902 +#define SQLITE_ACCESS_EXISTS 0
1.903 +#define SQLITE_ACCESS_READWRITE 1
1.904 +#define SQLITE_ACCESS_READ 2
1.905 +
1.906 +/*
1.907 +** CAPI3REF: Initialize The SQLite Library {H10130} <S20000><S30100>
1.908 +**
1.909 +** The sqlite3_initialize() routine initializes the
1.910 +** SQLite library. The sqlite3_shutdown() routine
1.911 +** deallocates any resources that were allocated by sqlite3_initialize().
1.912 +**
1.913 +** A call to sqlite3_initialize() is an "effective" call if it is
1.914 +** the first time sqlite3_initialize() is invoked during the lifetime of
1.915 +** the process, or if it is the first time sqlite3_initialize() is invoked
1.916 +** following a call to sqlite3_shutdown(). Only an effective call
1.917 +** of sqlite3_initialize() does any initialization. All other calls
1.918 +** are harmless no-ops.
1.919 +**
1.920 +** Among other things, sqlite3_initialize() shall invoke
1.921 +** sqlite3_os_init(). Similarly, sqlite3_shutdown()
1.922 +** shall invoke sqlite3_os_end().
1.923 +**
1.924 +** The sqlite3_initialize() routine returns SQLITE_OK on success.
1.925 +** If for some reason, sqlite3_initialize() is unable to initialize
1.926 +** the library (perhaps it is unable to allocate a needed resource such
1.927 +** as a mutex) it returns an [error code] other than SQLITE_OK.
1.928 +**
1.929 +** The sqlite3_initialize() routine is called internally by many other
1.930 +** SQLite interfaces so that an application usually does not need to
1.931 +** invoke sqlite3_initialize() directly. For example, [sqlite3_open()]
1.932 +** calls sqlite3_initialize() so the SQLite library will be automatically
1.933 +** initialized when [sqlite3_open()] is called if it has not be initialized
1.934 +** already. However, if SQLite is compiled with the SQLITE_OMIT_AUTOINIT
1.935 +** compile-time option, then the automatic calls to sqlite3_initialize()
1.936 +** are omitted and the application must call sqlite3_initialize() directly
1.937 +** prior to using any other SQLite interface. For maximum portability,
1.938 +** it is recommended that applications always invoke sqlite3_initialize()
1.939 +** directly prior to using any other SQLite interface. Future releases
1.940 +** of SQLite may require this. In other words, the behavior exhibited
1.941 +** when SQLite is compiled with SQLITE_OMIT_AUTOINIT might become the
1.942 +** default behavior in some future release of SQLite.
1.943 +**
1.944 +** The sqlite3_os_init() routine does operating-system specific
1.945 +** initialization of the SQLite library. The sqlite3_os_end()
1.946 +** routine undoes the effect of sqlite3_os_init(). Typical tasks
1.947 +** performed by these routines include allocation or deallocation
1.948 +** of static resources, initialization of global variables,
1.949 +** setting up a default [sqlite3_vfs] module, or setting up
1.950 +** a default configuration using [sqlite3_config()].
1.951 +**
1.952 +** The application should never invoke either sqlite3_os_init()
1.953 +** or sqlite3_os_end() directly. The application should only invoke
1.954 +** sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init()
1.955 +** interface is called automatically by sqlite3_initialize() and
1.956 +** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate
1.957 +** implementations for sqlite3_os_init() and sqlite3_os_end()
1.958 +** are built into SQLite when it is compiled for unix, windows, or os/2.
1.959 +** When built for other platforms (using the SQLITE_OS_OTHER=1 compile-time
1.960 +** option) the application must supply a suitable implementation for
1.961 +** sqlite3_os_init() and sqlite3_os_end(). An application-supplied
1.962 +** implementation of sqlite3_os_init() or sqlite3_os_end()
1.963 +** must return SQLITE_OK on success and some other [error code] upon
1.964 +** failure.
1.965 +*/
1.966 +IMPORT_C int sqlite3_initialize(void);
1.967 +IMPORT_C int sqlite3_shutdown(void);
1.968 +IMPORT_C int sqlite3_os_init(void);
1.969 +IMPORT_C int sqlite3_os_end(void);
1.970 +
1.971 +/*
1.972 +** CAPI3REF: Configuring The SQLite Library {H10145} <S20000><S30200>
1.973 +** EXPERIMENTAL
1.974 +**
1.975 +** The sqlite3_config() interface is used to make global configuration
1.976 +** changes to SQLite in order to tune SQLite to the specific needs of
1.977 +** the application. The default configuration is recommended for most
1.978 +** applications and so this routine is usually not necessary. It is
1.979 +** provided to support rare applications with unusual needs.
1.980 +**
1.981 +** The sqlite3_config() interface is not threadsafe. The application
1.982 +** must insure that no other SQLite interfaces are invoked by other
1.983 +** threads while sqlite3_config() is running. Furthermore, sqlite3_config()
1.984 +** may only be invoked prior to library initialization using
1.985 +** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
1.986 +** Note, however, that sqlite3_config() can be called as part of the
1.987 +** implementation of an application-defined [sqlite3_os_init()].
1.988 +**
1.989 +** The first argument to sqlite3_config() is an integer
1.990 +** [SQLITE_CONFIG_SINGLETHREAD | configuration option] that determines
1.991 +** what property of SQLite is to be configured. Subsequent arguments
1.992 +** vary depending on the [SQLITE_CONFIG_SINGLETHREAD | configuration option]
1.993 +** in the first argument.
1.994 +**
1.995 +** When a configuration option is set, sqlite3_config() returns SQLITE_OK.
1.996 +** If the option is unknown or SQLite is unable to set the option
1.997 +** then this routine returns a non-zero [error code].
1.998 +*/
1.999 +IMPORT_C int sqlite3_config(int, ...);
1.1000 +
1.1001 +/*
1.1002 +** CAPI3REF: Configure database connections {H10180} <S20000>
1.1003 +** EXPERIMENTAL
1.1004 +**
1.1005 +** The sqlite3_db_config() interface is used to make configuration
1.1006 +** changes to a [database connection]. The interface is similar to
1.1007 +** [sqlite3_config()] except that the changes apply to a single
1.1008 +** [database connection] (specified in the first argument). The
1.1009 +** sqlite3_db_config() interface can only be used immediately after
1.1010 +** the database connection is created using [sqlite3_open()],
1.1011 +** [sqlite3_open16()], or [sqlite3_open_v2()].
1.1012 +**
1.1013 +** The second argument to sqlite3_db_config(D,V,...) is the
1.1014 +** configuration verb - an integer code that indicates what
1.1015 +** aspect of the [database connection] is being configured.
1.1016 +** The only choice for this value is [SQLITE_DBCONFIG_LOOKASIDE].
1.1017 +** New verbs are likely to be added in future releases of SQLite.
1.1018 +** Additional arguments depend on the verb.
1.1019 +*/
1.1020 +IMPORT_C int sqlite3_db_config(sqlite3*, int op, ...);
1.1021 +
1.1022 +/*
1.1023 +** CAPI3REF: Memory Allocation Routines {H10155} <S20120>
1.1024 +** EXPERIMENTAL
1.1025 +**
1.1026 +** An instance of this object defines the interface between SQLite
1.1027 +** and low-level memory allocation routines.
1.1028 +**
1.1029 +** This object is used in only one place in the SQLite interface.
1.1030 +** A pointer to an instance of this object is the argument to
1.1031 +** [sqlite3_config()] when the configuration option is
1.1032 +** [SQLITE_CONFIG_MALLOC]. By creating an instance of this object
1.1033 +** and passing it to [sqlite3_config()] during configuration, an
1.1034 +** application can specify an alternative memory allocation subsystem
1.1035 +** for SQLite to use for all of its dynamic memory needs.
1.1036 +**
1.1037 +** Note that SQLite comes with a built-in memory allocator that is
1.1038 +** perfectly adequate for the overwhelming majority of applications
1.1039 +** and that this object is only useful to a tiny minority of applications
1.1040 +** with specialized memory allocation requirements. This object is
1.1041 +** also used during testing of SQLite in order to specify an alternative
1.1042 +** memory allocator that simulates memory out-of-memory conditions in
1.1043 +** order to verify that SQLite recovers gracefully from such
1.1044 +** conditions.
1.1045 +**
1.1046 +** The xMalloc, xFree, and xRealloc methods must work like the
1.1047 +** malloc(), free(), and realloc() functions from the standard library.
1.1048 +**
1.1049 +** xSize should return the allocated size of a memory allocation
1.1050 +** previously obtained from xMalloc or xRealloc. The allocated size
1.1051 +** is always at least as big as the requested size but may be larger.
1.1052 +**
1.1053 +** The xRoundup method returns what would be the allocated size of
1.1054 +** a memory allocation given a particular requested size. Most memory
1.1055 +** allocators round up memory allocations at least to the next multiple
1.1056 +** of 8. Some allocators round up to a larger multiple or to a power of 2.
1.1057 +**
1.1058 +** The xInit method initializes the memory allocator. (For example,
1.1059 +** it might allocate any require mutexes or initialize internal data
1.1060 +** structures. The xShutdown method is invoked (indirectly) by
1.1061 +** [sqlite3_shutdown()] and should deallocate any resources acquired
1.1062 +** by xInit. The pAppData pointer is used as the only parameter to
1.1063 +** xInit and xShutdown.
1.1064 +*/
1.1065 +typedef struct sqlite3_mem_methods sqlite3_mem_methods;
1.1066 +struct sqlite3_mem_methods {
1.1067 + void *(*xMalloc)(int); /* Memory allocation function */
1.1068 + void (*xFree)(void*); /* Free a prior allocation */
1.1069 + void *(*xRealloc)(void*,int); /* Resize an allocation */
1.1070 + int (*xSize)(void*); /* Return the size of an allocation */
1.1071 + int (*xRoundup)(int); /* Round up request size to allocation size */
1.1072 + int (*xInit)(void*); /* Initialize the memory allocator */
1.1073 + void (*xShutdown)(void*); /* Deinitialize the memory allocator */
1.1074 + void *pAppData; /* Argument to xInit() and xShutdown() */
1.1075 +};
1.1076 +
1.1077 +/*
1.1078 +** CAPI3REF: Configuration Options {H10160} <S20000>
1.1079 +** EXPERIMENTAL
1.1080 +**
1.1081 +** These constants are the available integer configuration options that
1.1082 +** can be passed as the first argument to the [sqlite3_config()] interface.
1.1083 +**
1.1084 +** New configuration options may be added in future releases of SQLite.
1.1085 +** Existing configuration options might be discontinued. Applications
1.1086 +** should check the return code from [sqlite3_config()] to make sure that
1.1087 +** the call worked. The [sqlite3_config()] interface will return a
1.1088 +** non-zero [error code] if a discontinued or unsupported configuration option
1.1089 +** is invoked.
1.1090 +**
1.1091 +** <dl>
1.1092 +** <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
1.1093 +** <dd>There are no arguments to this option. This option disables
1.1094 +** all mutexing and puts SQLite into a mode where it can only be used
1.1095 +** by a single thread.</dd>
1.1096 +**
1.1097 +** <dt>SQLITE_CONFIG_MULTITHREAD</dt>
1.1098 +** <dd>There are no arguments to this option. This option disables
1.1099 +** mutexing on [database connection] and [prepared statement] objects.
1.1100 +** The application is responsible for serializing access to
1.1101 +** [database connections] and [prepared statements]. But other mutexes
1.1102 +** are enabled so that SQLite will be safe to use in a multi-threaded
1.1103 +** environment as long as no two threads attempt to use the same
1.1104 +** [database connection] at the same time. See the [threading mode]
1.1105 +** documentation for additional information.</dd>
1.1106 +**
1.1107 +** <dt>SQLITE_CONFIG_SERIALIZED</dt>
1.1108 +** <dd>There are no arguments to this option. This option enables
1.1109 +** all mutexes including the recursive
1.1110 +** mutexes on [database connection] and [prepared statement] objects.
1.1111 +** In this mode (which is the default when SQLite is compiled with
1.1112 +** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
1.1113 +** to [database connections] and [prepared statements] so that the
1.1114 +** application is free to use the same [database connection] or the
1.1115 +** same [prepared statement] in different threads at the same time.
1.1116 +** See the [threading mode] documentation for additional information.</dd>
1.1117 +**
1.1118 +** <dt>SQLITE_CONFIG_MALLOC</dt>
1.1119 +** <dd>This option takes a single argument which is a pointer to an
1.1120 +** instance of the [sqlite3_mem_methods] structure. The argument specifies
1.1121 +** alternative low-level memory allocation routines to be used in place of
1.1122 +** the memory allocation routines built into SQLite.</dd>
1.1123 +**
1.1124 +** <dt>SQLITE_CONFIG_GETMALLOC</dt>
1.1125 +** <dd>This option takes a single argument which is a pointer to an
1.1126 +** instance of the [sqlite3_mem_methods] structure. The [sqlite3_mem_methods]
1.1127 +** structure is filled with the currently defined memory allocation routines.
1.1128 +** This option can be used to overload the default memory allocation
1.1129 +** routines with a wrapper that simulations memory allocation failure or
1.1130 +** tracks memory usage, for example.</dd>
1.1131 +**
1.1132 +** <dt>SQLITE_CONFIG_MEMSTATUS</dt>
1.1133 +** <dd>This option takes single argument of type int, interpreted as a
1.1134 +** boolean, which enables or disables the collection of memory allocation
1.1135 +** statistics. When disabled, the following SQLite interfaces become
1.1136 +** non-operational:
1.1137 +** <ul>
1.1138 +** <li> [sqlite3_memory_used()]
1.1139 +** <li> [sqlite3_memory_highwater()]
1.1140 +** <li> [sqlite3_soft_heap_limit()]
1.1141 +** <li> [sqlite3_status()]
1.1142 +** </ul>
1.1143 +** </dd>
1.1144 +**
1.1145 +** <dt>SQLITE_CONFIG_SCRATCH</dt>
1.1146 +** <dd>This option specifies a static memory buffer that SQLite can use for
1.1147 +** scratch memory. There are three arguments: A pointer to the memory, the
1.1148 +** size of each scratch buffer (sz), and the number of buffers (N). The sz
1.1149 +** argument must be a multiple of 16. The sz parameter should be a few bytes
1.1150 +** larger than the actual scratch space required due internal overhead.
1.1151 +** The first
1.1152 +** argument should point to an allocation of at least sz*N bytes of memory.
1.1153 +** SQLite will use no more than one scratch buffer at once per thread, so
1.1154 +** N should be set to the expected maximum number of threads. The sz
1.1155 +** parameter should be 6 times the size of the largest database page size.
1.1156 +** Scratch buffers are used as part of the btree balance operation. If
1.1157 +** The btree balancer needs additional memory beyond what is provided by
1.1158 +** scratch buffers or if no scratch buffer space is specified, then SQLite
1.1159 +** goes to [sqlite3_malloc()] to obtain the memory it needs.</dd>
1.1160 +**
1.1161 +** <dt>SQLITE_CONFIG_PAGECACHE</dt>
1.1162 +** <dd>This option specifies a static memory buffer that SQLite can use for
1.1163 +** the database page cache. There are three arguments: A pointer to the
1.1164 +** memory, the size of each page buffer (sz), and the number of pages (N).
1.1165 +** The sz argument must be a power of two between 512 and 32768. The first
1.1166 +** argument should point to an allocation of at least sz*N bytes of memory.
1.1167 +** SQLite will use the memory provided by the first argument to satisfy its
1.1168 +** memory needs for the first N pages that it adds to cache. If additional
1.1169 +** page cache memory is needed beyond what is provided by this option, then
1.1170 +** SQLite goes to [sqlite3_malloc()] for the additional storage space.
1.1171 +** The implementation might use one or more of the N buffers to hold
1.1172 +** memory accounting information. </dd>
1.1173 +**
1.1174 +** <dt>SQLITE_CONFIG_HEAP</dt>
1.1175 +** <dd>This option specifies a static memory buffer that SQLite will use
1.1176 +** for all of its dynamic memory allocation needs beyond those provided
1.1177 +** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE].
1.1178 +** There are three arguments: A pointer to the memory, the number of
1.1179 +** bytes in the memory buffer, and the minimum allocation size. If
1.1180 +** the first pointer (the memory pointer) is NULL, then SQLite reverts
1.1181 +** to using its default memory allocator (the system malloc() implementation),
1.1182 +** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. If the
1.1183 +** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or
1.1184 +** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory
1.1185 +** allocator is engaged to handle all of SQLites memory allocation needs.</dd>
1.1186 +**
1.1187 +** <dt>SQLITE_CONFIG_MUTEX</dt>
1.1188 +** <dd>This option takes a single argument which is a pointer to an
1.1189 +** instance of the [sqlite3_mutex_methods] structure. The argument specifies
1.1190 +** alternative low-level mutex routines to be used in place
1.1191 +** the mutex routines built into SQLite.</dd>
1.1192 +**
1.1193 +** <dt>SQLITE_CONFIG_GETMUTEX</dt>
1.1194 +** <dd>This option takes a single argument which is a pointer to an
1.1195 +** instance of the [sqlite3_mutex_methods] structure. The
1.1196 +** [sqlite3_mutex_methods]
1.1197 +** structure is filled with the currently defined mutex routines.
1.1198 +** This option can be used to overload the default mutex allocation
1.1199 +** routines with a wrapper used to track mutex usage for performance
1.1200 +** profiling or testing, for example.</dd>
1.1201 +**
1.1202 +** <dt>SQLITE_CONFIG_LOOKASIDE</dt>
1.1203 +** <dd>This option takes two arguments that determine the default
1.1204 +** memory allcation lookaside optimization. The first argument is the
1.1205 +** size of each lookaside buffer slot and the second is the number of
1.1206 +** slots allocated to each database connection.</dd>
1.1207 +**
1.1208 +** </dl>
1.1209 +*/
1.1210 +#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
1.1211 +#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
1.1212 +#define SQLITE_CONFIG_SERIALIZED 3 /* nil */
1.1213 +#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
1.1214 +#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
1.1215 +#define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */
1.1216 +#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
1.1217 +#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
1.1218 +#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
1.1219 +#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
1.1220 +#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
1.1221 +#define SQLITE_CONFIG_CHUNKALLOC 12 /* int threshold */
1.1222 +#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
1.1223 +
1.1224 +/*
1.1225 +** CAPI3REF: Configuration Options {H10170} <S20000>
1.1226 +** EXPERIMENTAL
1.1227 +**
1.1228 +** These constants are the available integer configuration options that
1.1229 +** can be passed as the second argument to the [sqlite3_db_config()] interface.
1.1230 +**
1.1231 +** New configuration options may be added in future releases of SQLite.
1.1232 +** Existing configuration options might be discontinued. Applications
1.1233 +** should check the return code from [sqlite3_db_config()] to make sure that
1.1234 +** the call worked. The [sqlite3_db_config()] interface will return a
1.1235 +** non-zero [error code] if a discontinued or unsupported configuration option
1.1236 +** is invoked.
1.1237 +**
1.1238 +** <dl>
1.1239 +** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
1.1240 +** <dd>This option takes three additional arguments that determine the
1.1241 +** [lookaside memory allocator] configuration for the [database connection].
1.1242 +** The first argument (the third parameter to [sqlite3_db_config()] is a
1.1243 +** pointer to a memory buffer to use for lookaside memory. The first
1.1244 +** argument may be NULL in which case SQLite will allocate the lookaside
1.1245 +** buffer itself using [sqlite3_malloc()]. The second argument is the
1.1246 +** size of each lookaside buffer slot and the third argument is the number of
1.1247 +** slots. The size of the buffer in the first argument must be greater than
1.1248 +** or equal to the product of the second and third arguments.</dd>
1.1249 +**
1.1250 +** </dl>
1.1251 +*/
1.1252 +#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */
1.1253 +
1.1254 +
1.1255 +/*
1.1256 +** CAPI3REF: Enable Or Disable Extended Result Codes {H12200} <S10700>
1.1257 +**
1.1258 +** The sqlite3_extended_result_codes() routine enables or disables the
1.1259 +** [extended result codes] feature of SQLite. The extended result
1.1260 +** codes are disabled by default for historical compatibility considerations.
1.1261 +**
1.1262 +** INVARIANTS:
1.1263 +**
1.1264 +** {H12201} Each new [database connection] shall have the
1.1265 +** [extended result codes] feature disabled by default.
1.1266 +**
1.1267 +** {H12202} The [sqlite3_extended_result_codes(D,F)] interface shall enable
1.1268 +** [extended result codes] for the [database connection] D
1.1269 +** if the F parameter is true, or disable them if F is false.
1.1270 +*/
1.1271 +IMPORT_C int sqlite3_extended_result_codes(sqlite3*, int onoff);
1.1272 +
1.1273 +/*
1.1274 +** CAPI3REF: Last Insert Rowid {H12220} <S10700>
1.1275 +**
1.1276 +** Each entry in an SQLite table has a unique 64-bit signed
1.1277 +** integer key called the "rowid". The rowid is always available
1.1278 +** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
1.1279 +** names are not also used by explicitly declared columns. If
1.1280 +** the table has a column of type INTEGER PRIMARY KEY then that column
1.1281 +** is another alias for the rowid.
1.1282 +**
1.1283 +** This routine returns the rowid of the most recent
1.1284 +** successful INSERT into the database from the [database connection]
1.1285 +** in the first argument. If no successful INSERTs
1.1286 +** have ever occurred on that database connection, zero is returned.
1.1287 +**
1.1288 +** If an INSERT occurs within a trigger, then the rowid of the inserted
1.1289 +** row is returned by this routine as long as the trigger is running.
1.1290 +** But once the trigger terminates, the value returned by this routine
1.1291 +** reverts to the last value inserted before the trigger fired.
1.1292 +**
1.1293 +** An INSERT that fails due to a constraint violation is not a
1.1294 +** successful INSERT and does not change the value returned by this
1.1295 +** routine. Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
1.1296 +** and INSERT OR ABORT make no changes to the return value of this
1.1297 +** routine when their insertion fails. When INSERT OR REPLACE
1.1298 +** encounters a constraint violation, it does not fail. The
1.1299 +** INSERT continues to completion after deleting rows that caused
1.1300 +** the constraint problem so INSERT OR REPLACE will always change
1.1301 +** the return value of this interface.
1.1302 +**
1.1303 +** For the purposes of this routine, an INSERT is considered to
1.1304 +** be successful even if it is subsequently rolled back.
1.1305 +**
1.1306 +** INVARIANTS:
1.1307 +**
1.1308 +** {H12221} The [sqlite3_last_insert_rowid()] function returns the rowid
1.1309 +** of the most recent successful INSERT performed on the same
1.1310 +** [database connection] and within the same or higher level
1.1311 +** trigger context, or zero if there have been no qualifying inserts.
1.1312 +**
1.1313 +** {H12223} The [sqlite3_last_insert_rowid()] function returns the
1.1314 +** same value when called from the same trigger context
1.1315 +** immediately before and after a ROLLBACK.
1.1316 +**
1.1317 +** ASSUMPTIONS:
1.1318 +**
1.1319 +** {A12232} If a separate thread performs a new INSERT on the same
1.1320 +** database connection while the [sqlite3_last_insert_rowid()]
1.1321 +** function is running and thus changes the last insert rowid,
1.1322 +** then the value returned by [sqlite3_last_insert_rowid()] is
1.1323 +** unpredictable and might not equal either the old or the new
1.1324 +** last insert rowid.
1.1325 +*/
1.1326 +IMPORT_C sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
1.1327 +
1.1328 +/*
1.1329 +** CAPI3REF: Count The Number Of Rows Modified {H12240} <S10600>
1.1330 +**
1.1331 +** This function returns the number of database rows that were changed
1.1332 +** or inserted or deleted by the most recently completed SQL statement
1.1333 +** on the [database connection] specified by the first parameter.
1.1334 +** Only changes that are directly specified by the INSERT, UPDATE,
1.1335 +** or DELETE statement are counted. Auxiliary changes caused by
1.1336 +** triggers are not counted. Use the [sqlite3_total_changes()] function
1.1337 +** to find the total number of changes including changes caused by triggers.
1.1338 +**
1.1339 +** A "row change" is a change to a single row of a single table
1.1340 +** caused by an INSERT, DELETE, or UPDATE statement. Rows that
1.1341 +** are changed as side effects of REPLACE constraint resolution,
1.1342 +** rollback, ABORT processing, DROP TABLE, or by any other
1.1343 +** mechanisms do not count as direct row changes.
1.1344 +**
1.1345 +** A "trigger context" is a scope of execution that begins and
1.1346 +** ends with the script of a trigger. Most SQL statements are
1.1347 +** evaluated outside of any trigger. This is the "top level"
1.1348 +** trigger context. If a trigger fires from the top level, a
1.1349 +** new trigger context is entered for the duration of that one
1.1350 +** trigger. Subtriggers create subcontexts for their duration.
1.1351 +**
1.1352 +** Calling [sqlite3_exec()] or [sqlite3_step()] recursively does
1.1353 +** not create a new trigger context.
1.1354 +**
1.1355 +** This function returns the number of direct row changes in the
1.1356 +** most recent INSERT, UPDATE, or DELETE statement within the same
1.1357 +** trigger context.
1.1358 +**
1.1359 +** Thus, when called from the top level, this function returns the
1.1360 +** number of changes in the most recent INSERT, UPDATE, or DELETE
1.1361 +** that also occurred at the top level. Within the body of a trigger,
1.1362 +** the sqlite3_changes() interface can be called to find the number of
1.1363 +** changes in the most recently completed INSERT, UPDATE, or DELETE
1.1364 +** statement within the body of the same trigger.
1.1365 +** However, the number returned does not include changes
1.1366 +** caused by subtriggers since those have their own context.
1.1367 +**
1.1368 +** SQLite implements the command "DELETE FROM table" without a WHERE clause
1.1369 +** by dropping and recreating the table. (This is much faster than going
1.1370 +** through and deleting individual elements from the table.) Because of this
1.1371 +** optimization, the deletions in "DELETE FROM table" are not row changes and
1.1372 +** will not be counted by the sqlite3_changes() or [sqlite3_total_changes()]
1.1373 +** functions, regardless of the number of elements that were originally
1.1374 +** in the table. To get an accurate count of the number of rows deleted, use
1.1375 +** "DELETE FROM table WHERE 1" instead.
1.1376 +**
1.1377 +** INVARIANTS:
1.1378 +**
1.1379 +** {H12241} The [sqlite3_changes()] function shall return the number of
1.1380 +** row changes caused by the most recent INSERT, UPDATE,
1.1381 +** or DELETE statement on the same database connection and
1.1382 +** within the same or higher trigger context, or zero if there have
1.1383 +** not been any qualifying row changes.
1.1384 +**
1.1385 +** {H12243} Statements of the form "DELETE FROM tablename" with no
1.1386 +** WHERE clause shall cause subsequent calls to
1.1387 +** [sqlite3_changes()] to return zero, regardless of the
1.1388 +** number of rows originally in the table.
1.1389 +**
1.1390 +** ASSUMPTIONS:
1.1391 +**
1.1392 +** {A12252} If a separate thread makes changes on the same database connection
1.1393 +** while [sqlite3_changes()] is running then the value returned
1.1394 +** is unpredictable and not meaningful.
1.1395 +*/
1.1396 +IMPORT_C int sqlite3_changes(sqlite3*);
1.1397 +
1.1398 +/*
1.1399 +** CAPI3REF: Total Number Of Rows Modified {H12260} <S10600>
1.1400 +**
1.1401 +** This function returns the number of row changes caused by INSERT,
1.1402 +** UPDATE or DELETE statements since the [database connection] was opened.
1.1403 +** The count includes all changes from all trigger contexts. However,
1.1404 +** the count does not include changes used to implement REPLACE constraints,
1.1405 +** do rollbacks or ABORT processing, or DROP table processing.
1.1406 +** The changes are counted as soon as the statement that makes them is
1.1407 +** completed (when the statement handle is passed to [sqlite3_reset()] or
1.1408 +** [sqlite3_finalize()]).
1.1409 +**
1.1410 +** SQLite implements the command "DELETE FROM table" without a WHERE clause
1.1411 +** by dropping and recreating the table. (This is much faster than going
1.1412 +** through and deleting individual elements from the table.) Because of this
1.1413 +** optimization, the deletions in "DELETE FROM table" are not row changes and
1.1414 +** will not be counted by the sqlite3_changes() or [sqlite3_total_changes()]
1.1415 +** functions, regardless of the number of elements that were originally
1.1416 +** in the table. To get an accurate count of the number of rows deleted, use
1.1417 +** "DELETE FROM table WHERE 1" instead.
1.1418 +**
1.1419 +** See also the [sqlite3_changes()] interface.
1.1420 +**
1.1421 +** INVARIANTS:
1.1422 +**
1.1423 +** {H12261} The [sqlite3_total_changes()] returns the total number
1.1424 +** of row changes caused by INSERT, UPDATE, and/or DELETE
1.1425 +** statements on the same [database connection], in any
1.1426 +** trigger context, since the database connection was created.
1.1427 +**
1.1428 +** {H12263} Statements of the form "DELETE FROM tablename" with no
1.1429 +** WHERE clause shall not change the value returned
1.1430 +** by [sqlite3_total_changes()].
1.1431 +**
1.1432 +** ASSUMPTIONS:
1.1433 +**
1.1434 +** {A12264} If a separate thread makes changes on the same database connection
1.1435 +** while [sqlite3_total_changes()] is running then the value
1.1436 +** returned is unpredictable and not meaningful.
1.1437 +*/
1.1438 +IMPORT_C int sqlite3_total_changes(sqlite3*);
1.1439 +
1.1440 +/*
1.1441 +** CAPI3REF: Interrupt A Long-Running Query {H12270} <S30500>
1.1442 +**
1.1443 +** This function causes any pending database operation to abort and
1.1444 +** return at its earliest opportunity. This routine is typically
1.1445 +** called in response to a user action such as pressing "Cancel"
1.1446 +** or Ctrl-C where the user wants a long query operation to halt
1.1447 +** immediately.
1.1448 +**
1.1449 +** It is safe to call this routine from a thread different from the
1.1450 +** thread that is currently running the database operation. But it
1.1451 +** is not safe to call this routine with a [database connection] that
1.1452 +** is closed or might close before sqlite3_interrupt() returns.
1.1453 +**
1.1454 +** If an SQL operation is very nearly finished at the time when
1.1455 +** sqlite3_interrupt() is called, then it might not have an opportunity
1.1456 +** to be interrupted and might continue to completion.
1.1457 +**
1.1458 +** An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
1.1459 +** If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
1.1460 +** that is inside an explicit transaction, then the entire transaction
1.1461 +** will be rolled back automatically.
1.1462 +**
1.1463 +** A call to sqlite3_interrupt() has no effect on SQL statements
1.1464 +** that are started after sqlite3_interrupt() returns.
1.1465 +**
1.1466 +** INVARIANTS:
1.1467 +**
1.1468 +** {H12271} The [sqlite3_interrupt()] interface will force all running
1.1469 +** SQL statements associated with the same database connection
1.1470 +** to halt after processing at most one additional row of data.
1.1471 +**
1.1472 +** {H12272} Any SQL statement that is interrupted by [sqlite3_interrupt()]
1.1473 +** will return [SQLITE_INTERRUPT].
1.1474 +**
1.1475 +** ASSUMPTIONS:
1.1476 +**
1.1477 +** {A12279} If the database connection closes while [sqlite3_interrupt()]
1.1478 +** is running then bad things will likely happen.
1.1479 +*/
1.1480 +IMPORT_C void sqlite3_interrupt(sqlite3*);
1.1481 +
1.1482 +/*
1.1483 +** CAPI3REF: Determine If An SQL Statement Is Complete {H10510} <S70200>
1.1484 +**
1.1485 +** These routines are useful for command-line input to determine if the
1.1486 +** currently entered text seems to form complete a SQL statement or
1.1487 +** if additional input is needed before sending the text into
1.1488 +** SQLite for parsing. These routines return true if the input string
1.1489 +** appears to be a complete SQL statement. A statement is judged to be
1.1490 +** complete if it ends with a semicolon token and is not a fragment of a
1.1491 +** CREATE TRIGGER statement. Semicolons that are embedded within
1.1492 +** string literals or quoted identifier names or comments are not
1.1493 +** independent tokens (they are part of the token in which they are
1.1494 +** embedded) and thus do not count as a statement terminator.
1.1495 +**
1.1496 +** These routines do not parse the SQL statements thus
1.1497 +** will not detect syntactically incorrect SQL.
1.1498 +**
1.1499 +** INVARIANTS:
1.1500 +**
1.1501 +** {H10511} A successful evaluation of [sqlite3_complete()] or
1.1502 +** [sqlite3_complete16()] functions shall
1.1503 +** return a numeric 1 if and only if the last non-whitespace
1.1504 +** token in their input is a semicolon that is not in between
1.1505 +** the BEGIN and END of a CREATE TRIGGER statement.
1.1506 +**
1.1507 +** {H10512} If a memory allocation error occurs during an invocation
1.1508 +** of [sqlite3_complete()] or [sqlite3_complete16()] then the
1.1509 +** routine shall return [SQLITE_NOMEM].
1.1510 +**
1.1511 +** ASSUMPTIONS:
1.1512 +**
1.1513 +** {A10512} The input to [sqlite3_complete()] must be a zero-terminated
1.1514 +** UTF-8 string.
1.1515 +**
1.1516 +** {A10513} The input to [sqlite3_complete16()] must be a zero-terminated
1.1517 +** UTF-16 string in native byte order.
1.1518 +*/
1.1519 +IMPORT_C int sqlite3_complete(const char *sql);
1.1520 +IMPORT_C int sqlite3_complete16(const void *sql);
1.1521 +
1.1522 +/*
1.1523 +** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {H12310} <S40400>
1.1524 +**
1.1525 +** This routine sets a callback function that might be invoked whenever
1.1526 +** an attempt is made to open a database table that another thread
1.1527 +** or process has locked.
1.1528 +**
1.1529 +** If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]
1.1530 +** is returned immediately upon encountering the lock. If the busy callback
1.1531 +** is not NULL, then the callback will be invoked with two arguments.
1.1532 +**
1.1533 +** The first argument to the handler is a copy of the void* pointer which
1.1534 +** is the third argument to sqlite3_busy_handler(). The second argument to
1.1535 +** the handler callback is the number of times that the busy handler has
1.1536 +** been invoked for this locking event. If the
1.1537 +** busy callback returns 0, then no additional attempts are made to
1.1538 +** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
1.1539 +** If the callback returns non-zero, then another attempt
1.1540 +** is made to open the database for reading and the cycle repeats.
1.1541 +**
1.1542 +** The presence of a busy handler does not guarantee that it will be invoked
1.1543 +** when there is lock contention. If SQLite determines that invoking the busy
1.1544 +** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
1.1545 +** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler.
1.1546 +** Consider a scenario where one process is holding a read lock that
1.1547 +** it is trying to promote to a reserved lock and
1.1548 +** a second process is holding a reserved lock that it is trying
1.1549 +** to promote to an exclusive lock. The first process cannot proceed
1.1550 +** because it is blocked by the second and the second process cannot
1.1551 +** proceed because it is blocked by the first. If both processes
1.1552 +** invoke the busy handlers, neither will make any progress. Therefore,
1.1553 +** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
1.1554 +** will induce the first process to release its read lock and allow
1.1555 +** the second process to proceed.
1.1556 +**
1.1557 +** The default busy callback is NULL.
1.1558 +**
1.1559 +** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
1.1560 +** when SQLite is in the middle of a large transaction where all the
1.1561 +** changes will not fit into the in-memory cache. SQLite will
1.1562 +** already hold a RESERVED lock on the database file, but it needs
1.1563 +** to promote this lock to EXCLUSIVE so that it can spill cache
1.1564 +** pages into the database file without harm to concurrent
1.1565 +** readers. If it is unable to promote the lock, then the in-memory
1.1566 +** cache will be left in an inconsistent state and so the error
1.1567 +** code is promoted from the relatively benign [SQLITE_BUSY] to
1.1568 +** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion
1.1569 +** forces an automatic rollback of the changes. See the
1.1570 +** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError">
1.1571 +** CorruptionFollowingBusyError</a> wiki page for a discussion of why
1.1572 +** this is important.
1.1573 +**
1.1574 +** There can only be a single busy handler defined for each
1.1575 +** [database connection]. Setting a new busy handler clears any
1.1576 +** previously set handler. Note that calling [sqlite3_busy_timeout()]
1.1577 +** will also set or clear the busy handler.
1.1578 +**
1.1579 +** The busy callback should not take any actions which modify the
1.1580 +** database connection that invoked the busy handler. Any such actions
1.1581 +** result in undefined behavior.
1.1582 +**
1.1583 +** INVARIANTS:
1.1584 +**
1.1585 +** {H12311} The [sqlite3_busy_handler(D,C,A)] function shall replace
1.1586 +** busy callback in the [database connection] D with a new
1.1587 +** a new busy handler C and application data pointer A.
1.1588 +**
1.1589 +** {H12312} Newly created [database connections] shall have a busy
1.1590 +** handler of NULL.
1.1591 +**
1.1592 +** {H12314} When two or more [database connections] share a
1.1593 +** [sqlite3_enable_shared_cache | common cache],
1.1594 +** the busy handler for the database connection currently using
1.1595 +** the cache shall be invoked when the cache encounters a lock.
1.1596 +**
1.1597 +** {H12316} If a busy handler callback returns zero, then the SQLite interface
1.1598 +** that provoked the locking event shall return [SQLITE_BUSY].
1.1599 +**
1.1600 +** {H12318} SQLite shall invokes the busy handler with two arguments which
1.1601 +** are a copy of the pointer supplied by the 3rd parameter to
1.1602 +** [sqlite3_busy_handler()] and a count of the number of prior
1.1603 +** invocations of the busy handler for the same locking event.
1.1604 +**
1.1605 +** ASSUMPTIONS:
1.1606 +**
1.1607 +** {A12319} A busy handler must not close the database connection
1.1608 +** or [prepared statement] that invoked the busy handler.
1.1609 +*/
1.1610 +IMPORT_C int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
1.1611 +
1.1612 +/*
1.1613 +** CAPI3REF: Set A Busy Timeout {H12340} <S40410>
1.1614 +**
1.1615 +** This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
1.1616 +** for a specified amount of time when a table is locked. The handler
1.1617 +** will sleep multiple times until at least "ms" milliseconds of sleeping
1.1618 +** have accumulated. {H12343} After "ms" milliseconds of sleeping,
1.1619 +** the handler returns 0 which causes [sqlite3_step()] to return
1.1620 +** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
1.1621 +**
1.1622 +** Calling this routine with an argument less than or equal to zero
1.1623 +** turns off all busy handlers.
1.1624 +**
1.1625 +** There can only be a single busy handler for a particular
1.1626 +** [database connection] any any given moment. If another busy handler
1.1627 +** was defined (using [sqlite3_busy_handler()]) prior to calling
1.1628 +** this routine, that other busy handler is cleared.
1.1629 +**
1.1630 +** INVARIANTS:
1.1631 +**
1.1632 +** {H12341} The [sqlite3_busy_timeout()] function shall override any prior
1.1633 +** [sqlite3_busy_timeout()] or [sqlite3_busy_handler()] setting
1.1634 +** on the same [database connection].
1.1635 +**
1.1636 +** {H12343} If the 2nd parameter to [sqlite3_busy_timeout()] is less than
1.1637 +** or equal to zero, then the busy handler shall be cleared so that
1.1638 +** all subsequent locking events immediately return [SQLITE_BUSY].
1.1639 +**
1.1640 +** {H12344} If the 2nd parameter to [sqlite3_busy_timeout()] is a positive
1.1641 +** number N, then a busy handler shall be set that repeatedly calls
1.1642 +** the xSleep() method in the [sqlite3_vfs | VFS interface] until
1.1643 +** either the lock clears or until the cumulative sleep time
1.1644 +** reported back by xSleep() exceeds N milliseconds.
1.1645 +*/
1.1646 +IMPORT_C int sqlite3_busy_timeout(sqlite3*, int ms);
1.1647 +
1.1648 +/*
1.1649 +** CAPI3REF: Convenience Routines For Running Queries {H12370} <S10000>
1.1650 +**
1.1651 +** Definition: A <b>result table</b> is memory data structure created by the
1.1652 +** [sqlite3_get_table()] interface. A result table records the
1.1653 +** complete query results from one or more queries.
1.1654 +**
1.1655 +** The table conceptually has a number of rows and columns. But
1.1656 +** these numbers are not part of the result table itself. These
1.1657 +** numbers are obtained separately. Let N be the number of rows
1.1658 +** and M be the number of columns.
1.1659 +**
1.1660 +** A result table is an array of pointers to zero-terminated UTF-8 strings.
1.1661 +** There are (N+1)*M elements in the array. The first M pointers point
1.1662 +** to zero-terminated strings that contain the names of the columns.
1.1663 +** The remaining entries all point to query results. NULL values result
1.1664 +** in NULL pointers. All other values are in their UTF-8 zero-terminated
1.1665 +** string representation as returned by [sqlite3_column_text()].
1.1666 +**
1.1667 +** A result table might consist of one or more memory allocations.
1.1668 +** It is not safe to pass a result table directly to [sqlite3_free()].
1.1669 +** A result table should be deallocated using [sqlite3_free_table()].
1.1670 +**
1.1671 +** As an example of the result table format, suppose a query result
1.1672 +** is as follows:
1.1673 +**
1.1674 +** <blockquote><pre>
1.1675 +** Name | Age
1.1676 +** -----------------------
1.1677 +** Alice | 43
1.1678 +** Bob | 28
1.1679 +** Cindy | 21
1.1680 +** </pre></blockquote>
1.1681 +**
1.1682 +** There are two column (M==2) and three rows (N==3). Thus the
1.1683 +** result table has 8 entries. Suppose the result table is stored
1.1684 +** in an array names azResult. Then azResult holds this content:
1.1685 +**
1.1686 +** <blockquote><pre>
1.1687 +** azResult[0] = "Name";
1.1688 +** azResult[1] = "Age";
1.1689 +** azResult[2] = "Alice";
1.1690 +** azResult[3] = "43";
1.1691 +** azResult[4] = "Bob";
1.1692 +** azResult[5] = "28";
1.1693 +** azResult[6] = "Cindy";
1.1694 +** azResult[7] = "21";
1.1695 +** </pre></blockquote>
1.1696 +**
1.1697 +** The sqlite3_get_table() function evaluates one or more
1.1698 +** semicolon-separated SQL statements in the zero-terminated UTF-8
1.1699 +** string of its 2nd parameter. It returns a result table to the
1.1700 +** pointer given in its 3rd parameter.
1.1701 +**
1.1702 +** After the calling function has finished using the result, it should
1.1703 +** pass the pointer to the result table to sqlite3_free_table() in order to
1.1704 +** release the memory that was malloced. Because of the way the
1.1705 +** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
1.1706 +** function must not try to call [sqlite3_free()] directly. Only
1.1707 +** [sqlite3_free_table()] is able to release the memory properly and safely.
1.1708 +**
1.1709 +** The sqlite3_get_table() interface is implemented as a wrapper around
1.1710 +** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access
1.1711 +** to any internal data structures of SQLite. It uses only the public
1.1712 +** interface defined here. As a consequence, errors that occur in the
1.1713 +** wrapper layer outside of the internal [sqlite3_exec()] call are not
1.1714 +** reflected in subsequent calls to [sqlite3_errcode()] or [sqlite3_errmsg()].
1.1715 +**
1.1716 +** INVARIANTS:
1.1717 +**
1.1718 +** {H12371} If a [sqlite3_get_table()] fails a memory allocation, then
1.1719 +** it shall free the result table under construction, abort the
1.1720 +** query in process, skip any subsequent queries, set the
1.1721 +** *pazResult output pointer to NULL and return [SQLITE_NOMEM].
1.1722 +**
1.1723 +** {H12373} If the pnColumn parameter to [sqlite3_get_table()] is not NULL
1.1724 +** then a successful invocation of [sqlite3_get_table()] shall
1.1725 +** write the number of columns in the
1.1726 +** result set of the query into *pnColumn.
1.1727 +**
1.1728 +** {H12374} If the pnRow parameter to [sqlite3_get_table()] is not NULL
1.1729 +** then a successful invocation of [sqlite3_get_table()] shall
1.1730 +** writes the number of rows in the
1.1731 +** result set of the query into *pnRow.
1.1732 +**
1.1733 +** {H12376} A successful invocation of [sqlite3_get_table()] that computes
1.1734 +** N rows of result with C columns per row shall make *pazResult
1.1735 +** point to an array of pointers to (N+1)*C strings where the first
1.1736 +** C strings are column names as obtained from
1.1737 +** [sqlite3_column_name()] and the rest are column result values
1.1738 +** obtained from [sqlite3_column_text()].
1.1739 +**
1.1740 +** {H12379} The values in the pazResult array returned by [sqlite3_get_table()]
1.1741 +** shall remain valid until cleared by [sqlite3_free_table()].
1.1742 +**
1.1743 +** {H12382} When an error occurs during evaluation of [sqlite3_get_table()]
1.1744 +** the function shall set *pazResult to NULL, write an error message
1.1745 +** into memory obtained from [sqlite3_malloc()], make
1.1746 +** **pzErrmsg point to that error message, and return a
1.1747 +** appropriate [error code].
1.1748 +*/
1.1749 +IMPORT_C int sqlite3_get_table(
1.1750 + sqlite3 *db, /* An open database */
1.1751 + const char *zSql, /* SQL to be evaluated */
1.1752 + char ***pazResult, /* Results of the query */
1.1753 + int *pnRow, /* Number of result rows written here */
1.1754 + int *pnColumn, /* Number of result columns written here */
1.1755 + char **pzErrmsg /* Error msg written here */
1.1756 +);
1.1757 +IMPORT_C void sqlite3_free_table(char **result);
1.1758 +
1.1759 +/*
1.1760 +** CAPI3REF: Formatted String Printing Functions {H17400} <S70000><S20000>
1.1761 +**
1.1762 +** These routines are workalikes of the "printf()" family of functions
1.1763 +** from the standard C library.
1.1764 +**
1.1765 +** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
1.1766 +** results into memory obtained from [sqlite3_malloc()].
1.1767 +** The strings returned by these two routines should be
1.1768 +** released by [sqlite3_free()]. Both routines return a
1.1769 +** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
1.1770 +** memory to hold the resulting string.
1.1771 +**
1.1772 +** In sqlite3_snprintf() routine is similar to "snprintf()" from
1.1773 +** the standard C library. The result is written into the
1.1774 +** buffer supplied as the second parameter whose size is given by
1.1775 +** the first parameter. Note that the order of the
1.1776 +** first two parameters is reversed from snprintf(). This is an
1.1777 +** historical accident that cannot be fixed without breaking
1.1778 +** backwards compatibility. Note also that sqlite3_snprintf()
1.1779 +** returns a pointer to its buffer instead of the number of
1.1780 +** characters actually written into the buffer. We admit that
1.1781 +** the number of characters written would be a more useful return
1.1782 +** value but we cannot change the implementation of sqlite3_snprintf()
1.1783 +** now without breaking compatibility.
1.1784 +**
1.1785 +** As long as the buffer size is greater than zero, sqlite3_snprintf()
1.1786 +** guarantees that the buffer is always zero-terminated. The first
1.1787 +** parameter "n" is the total size of the buffer, including space for
1.1788 +** the zero terminator. So the longest string that can be completely
1.1789 +** written will be n-1 characters.
1.1790 +**
1.1791 +** These routines all implement some additional formatting
1.1792 +** options that are useful for constructing SQL statements.
1.1793 +** All of the usual printf() formatting options apply. In addition, there
1.1794 +** is are "%q", "%Q", and "%z" options.
1.1795 +**
1.1796 +** The %q option works like %s in that it substitutes a null-terminated
1.1797 +** string from the argument list. But %q also doubles every '\'' character.
1.1798 +** %q is designed for use inside a string literal. By doubling each '\''
1.1799 +** character it escapes that character and allows it to be inserted into
1.1800 +** the string.
1.1801 +**
1.1802 +** For example, assume the string variable zText contains text as follows:
1.1803 +**
1.1804 +** <blockquote><pre>
1.1805 +** char *zText = "It's a happy day!";
1.1806 +** </pre></blockquote>
1.1807 +**
1.1808 +** One can use this text in an SQL statement as follows:
1.1809 +**
1.1810 +** <blockquote><pre>
1.1811 +** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
1.1812 +** sqlite3_exec(db, zSQL, 0, 0, 0);
1.1813 +** sqlite3_free(zSQL);
1.1814 +** </pre></blockquote>
1.1815 +**
1.1816 +** Because the %q format string is used, the '\'' character in zText
1.1817 +** is escaped and the SQL generated is as follows:
1.1818 +**
1.1819 +** <blockquote><pre>
1.1820 +** INSERT INTO table1 VALUES('It''s a happy day!')
1.1821 +** </pre></blockquote>
1.1822 +**
1.1823 +** This is correct. Had we used %s instead of %q, the generated SQL
1.1824 +** would have looked like this:
1.1825 +**
1.1826 +** <blockquote><pre>
1.1827 +** INSERT INTO table1 VALUES('It's a happy day!');
1.1828 +** </pre></blockquote>
1.1829 +**
1.1830 +** This second example is an SQL syntax error. As a general rule you should
1.1831 +** always use %q instead of %s when inserting text into a string literal.
1.1832 +**
1.1833 +** The %Q option works like %q except it also adds single quotes around
1.1834 +** the outside of the total string. Additionally, if the parameter in the
1.1835 +** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
1.1836 +** single quotes) in place of the %Q option. So, for example, one could say:
1.1837 +**
1.1838 +** <blockquote><pre>
1.1839 +** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
1.1840 +** sqlite3_exec(db, zSQL, 0, 0, 0);
1.1841 +** sqlite3_free(zSQL);
1.1842 +** </pre></blockquote>
1.1843 +**
1.1844 +** The code above will render a correct SQL statement in the zSQL
1.1845 +** variable even if the zText variable is a NULL pointer.
1.1846 +**
1.1847 +** The "%z" formatting option works exactly like "%s" with the
1.1848 +** addition that after the string has been read and copied into
1.1849 +** the result, [sqlite3_free()] is called on the input string. {END}
1.1850 +**
1.1851 +** INVARIANTS:
1.1852 +**
1.1853 +** {H17403} The [sqlite3_mprintf()] and [sqlite3_vmprintf()] interfaces
1.1854 +** return either pointers to zero-terminated UTF-8 strings held in
1.1855 +** memory obtained from [sqlite3_malloc()] or NULL pointers if
1.1856 +** a call to [sqlite3_malloc()] fails.
1.1857 +**
1.1858 +** {H17406} The [sqlite3_snprintf()] interface writes a zero-terminated
1.1859 +** UTF-8 string into the buffer pointed to by the second parameter
1.1860 +** provided that the first parameter is greater than zero.
1.1861 +**
1.1862 +** {H17407} The [sqlite3_snprintf()] interface does not write slots of
1.1863 +** its output buffer (the second parameter) outside the range
1.1864 +** of 0 through N-1 (where N is the first parameter)
1.1865 +** regardless of the length of the string
1.1866 +** requested by the format specification.
1.1867 +*/
1.1868 +IMPORT_C char *sqlite3_mprintf(const char*,...);
1.1869 +IMPORT_C char *sqlite3_vmprintf(const char*, va_list);
1.1870 +IMPORT_C char *sqlite3_snprintf(int,char*,const char*, ...);
1.1871 +
1.1872 +/*
1.1873 +** CAPI3REF: Memory Allocation Subsystem {H17300} <S20000>
1.1874 +**
1.1875 +** The SQLite core uses these three routines for all of its own
1.1876 +** internal memory allocation needs. "Core" in the previous sentence
1.1877 +** does not include operating-system specific VFS implementation. The
1.1878 +** Windows VFS uses native malloc() and free() for some operations.
1.1879 +**
1.1880 +** The sqlite3_malloc() routine returns a pointer to a block
1.1881 +** of memory at least N bytes in length, where N is the parameter.
1.1882 +** If sqlite3_malloc() is unable to obtain sufficient free
1.1883 +** memory, it returns a NULL pointer. If the parameter N to
1.1884 +** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
1.1885 +** a NULL pointer.
1.1886 +**
1.1887 +** Calling sqlite3_free() with a pointer previously returned
1.1888 +** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
1.1889 +** that it might be reused. The sqlite3_free() routine is
1.1890 +** a no-op if is called with a NULL pointer. Passing a NULL pointer
1.1891 +** to sqlite3_free() is harmless. After being freed, memory
1.1892 +** should neither be read nor written. Even reading previously freed
1.1893 +** memory might result in a segmentation fault or other severe error.
1.1894 +** Memory corruption, a segmentation fault, or other severe error
1.1895 +** might result if sqlite3_free() is called with a non-NULL pointer that
1.1896 +** was not obtained from sqlite3_malloc() or sqlite3_free().
1.1897 +**
1.1898 +** The sqlite3_realloc() interface attempts to resize a
1.1899 +** prior memory allocation to be at least N bytes, where N is the
1.1900 +** second parameter. The memory allocation to be resized is the first
1.1901 +** parameter. If the first parameter to sqlite3_realloc()
1.1902 +** is a NULL pointer then its behavior is identical to calling
1.1903 +** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc().
1.1904 +** If the second parameter to sqlite3_realloc() is zero or
1.1905 +** negative then the behavior is exactly the same as calling
1.1906 +** sqlite3_free(P) where P is the first parameter to sqlite3_realloc().
1.1907 +** sqlite3_realloc() returns a pointer to a memory allocation
1.1908 +** of at least N bytes in size or NULL if sufficient memory is unavailable.
1.1909 +** If M is the size of the prior allocation, then min(N,M) bytes
1.1910 +** of the prior allocation are copied into the beginning of buffer returned
1.1911 +** by sqlite3_realloc() and the prior allocation is freed.
1.1912 +** If sqlite3_realloc() returns NULL, then the prior allocation
1.1913 +** is not freed.
1.1914 +**
1.1915 +** The memory returned by sqlite3_malloc() and sqlite3_realloc()
1.1916 +** is always aligned to at least an 8 byte boundary. {END}
1.1917 +**
1.1918 +** The default implementation of the memory allocation subsystem uses
1.1919 +** the malloc(), realloc() and free() provided by the standard C library.
1.1920 +** {H17382} However, if SQLite is compiled with the
1.1921 +** SQLITE_MEMORY_SIZE=<i>NNN</i> C preprocessor macro (where <i>NNN</i>
1.1922 +** is an integer), then SQLite create a static array of at least
1.1923 +** <i>NNN</i> bytes in size and uses that array for all of its dynamic
1.1924 +** memory allocation needs. {END} Additional memory allocator options
1.1925 +** may be added in future releases.
1.1926 +**
1.1927 +** In SQLite version 3.5.0 and 3.5.1, it was possible to define
1.1928 +** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
1.1929 +** implementation of these routines to be omitted. That capability
1.1930 +** is no longer provided. Only built-in memory allocators can be used.
1.1931 +**
1.1932 +** The Windows OS interface layer calls
1.1933 +** the system malloc() and free() directly when converting
1.1934 +** filenames between the UTF-8 encoding used by SQLite
1.1935 +** and whatever filename encoding is used by the particular Windows
1.1936 +** installation. Memory allocation errors are detected, but
1.1937 +** they are reported back as [SQLITE_CANTOPEN] or
1.1938 +** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
1.1939 +**
1.1940 +** INVARIANTS:
1.1941 +**
1.1942 +** {H17303} The [sqlite3_malloc(N)] interface returns either a pointer to
1.1943 +** a newly checked-out block of at least N bytes of memory
1.1944 +** that is 8-byte aligned, or it returns NULL if it is unable
1.1945 +** to fulfill the request.
1.1946 +**
1.1947 +** {H17304} The [sqlite3_malloc(N)] interface returns a NULL pointer if
1.1948 +** N is less than or equal to zero.
1.1949 +**
1.1950 +** {H17305} The [sqlite3_free(P)] interface releases memory previously
1.1951 +** returned from [sqlite3_malloc()] or [sqlite3_realloc()],
1.1952 +** making it available for reuse.
1.1953 +**
1.1954 +** {H17306} A call to [sqlite3_free(NULL)] is a harmless no-op.
1.1955 +**
1.1956 +** {H17310} A call to [sqlite3_realloc(0,N)] is equivalent to a call
1.1957 +** to [sqlite3_malloc(N)].
1.1958 +**
1.1959 +** {H17312} A call to [sqlite3_realloc(P,0)] is equivalent to a call
1.1960 +** to [sqlite3_free(P)].
1.1961 +**
1.1962 +** {H17315} The SQLite core uses [sqlite3_malloc()], [sqlite3_realloc()],
1.1963 +** and [sqlite3_free()] for all of its memory allocation and
1.1964 +** deallocation needs.
1.1965 +**
1.1966 +** {H17318} The [sqlite3_realloc(P,N)] interface returns either a pointer
1.1967 +** to a block of checked-out memory of at least N bytes in size
1.1968 +** that is 8-byte aligned, or a NULL pointer.
1.1969 +**
1.1970 +** {H17321} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first
1.1971 +** copies the first K bytes of content from P into the newly
1.1972 +** allocated block, where K is the lesser of N and the size of
1.1973 +** the buffer P.
1.1974 +**
1.1975 +** {H17322} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first
1.1976 +** releases the buffer P.
1.1977 +**
1.1978 +** {H17323} When [sqlite3_realloc(P,N)] returns NULL, the buffer P is
1.1979 +** not modified or released.
1.1980 +**
1.1981 +** ASSUMPTIONS:
1.1982 +**
1.1983 +** {A17350} The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
1.1984 +** must be either NULL or else pointers obtained from a prior
1.1985 +** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
1.1986 +** not yet been released.
1.1987 +**
1.1988 +** {A17351} The application must not read or write any part of
1.1989 +** a block of memory after it has been released using
1.1990 +** [sqlite3_free()] or [sqlite3_realloc()].
1.1991 +*/
1.1992 +IMPORT_C void *sqlite3_malloc(int);
1.1993 +IMPORT_C void *sqlite3_realloc(void*, int);
1.1994 +IMPORT_C void sqlite3_free(void*);
1.1995 +
1.1996 +/*
1.1997 +** CAPI3REF: Memory Allocator Statistics {H17370} <S30210>
1.1998 +**
1.1999 +** SQLite provides these two interfaces for reporting on the status
1.2000 +** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
1.2001 +** routines, which form the built-in memory allocation subsystem.
1.2002 +**
1.2003 +** INVARIANTS:
1.2004 +**
1.2005 +** {H17371} The [sqlite3_memory_used()] routine returns the number of bytes
1.2006 +** of memory currently outstanding (malloced but not freed).
1.2007 +**
1.2008 +** {H17373} The [sqlite3_memory_highwater()] routine returns the maximum
1.2009 +** value of [sqlite3_memory_used()] since the high-water mark
1.2010 +** was last reset.
1.2011 +**
1.2012 +** {H17374} The values returned by [sqlite3_memory_used()] and
1.2013 +** [sqlite3_memory_highwater()] include any overhead
1.2014 +** added by SQLite in its implementation of [sqlite3_malloc()],
1.2015 +** but not overhead added by the any underlying system library
1.2016 +** routines that [sqlite3_malloc()] may call.
1.2017 +**
1.2018 +** {H17375} The memory high-water mark is reset to the current value of
1.2019 +** [sqlite3_memory_used()] if and only if the parameter to
1.2020 +** [sqlite3_memory_highwater()] is true. The value returned
1.2021 +** by [sqlite3_memory_highwater(1)] is the high-water mark
1.2022 +** prior to the reset.
1.2023 +*/
1.2024 +IMPORT_C sqlite3_int64 sqlite3_memory_used(void);
1.2025 +IMPORT_C sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
1.2026 +
1.2027 +/*
1.2028 +** CAPI3REF: Pseudo-Random Number Generator {H17390} <S20000>
1.2029 +**
1.2030 +** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
1.2031 +** select random ROWIDs when inserting new records into a table that
1.2032 +** already uses the largest possible ROWID. The PRNG is also used for
1.2033 +** the build-in random() and randomblob() SQL functions. This interface allows
1.2034 +** applications to access the same PRNG for other purposes.
1.2035 +**
1.2036 +** A call to this routine stores N bytes of randomness into buffer P.
1.2037 +**
1.2038 +** The first time this routine is invoked (either internally or by
1.2039 +** the application) the PRNG is seeded using randomness obtained
1.2040 +** from the xRandomness method of the default [sqlite3_vfs] object.
1.2041 +** On all subsequent invocations, the pseudo-randomness is generated
1.2042 +** internally and without recourse to the [sqlite3_vfs] xRandomness
1.2043 +** method.
1.2044 +**
1.2045 +** INVARIANTS:
1.2046 +**
1.2047 +** {H17392} The [sqlite3_randomness(N,P)] interface writes N bytes of
1.2048 +** high-quality pseudo-randomness into buffer P.
1.2049 +*/
1.2050 +IMPORT_C void sqlite3_randomness(int N, void *P);
1.2051 +
1.2052 +/*
1.2053 +** CAPI3REF: Compile-Time Authorization Callbacks {H12500} <S70100>
1.2054 +**
1.2055 +** This routine registers a authorizer callback with a particular
1.2056 +** [database connection], supplied in the first argument.
1.2057 +** The authorizer callback is invoked as SQL statements are being compiled
1.2058 +** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
1.2059 +** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various
1.2060 +** points during the compilation process, as logic is being created
1.2061 +** to perform various actions, the authorizer callback is invoked to
1.2062 +** see if those actions are allowed. The authorizer callback should
1.2063 +** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
1.2064 +** specific action but allow the SQL statement to continue to be
1.2065 +** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
1.2066 +** rejected with an error. If the authorizer callback returns
1.2067 +** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
1.2068 +** then the [sqlite3_prepare_v2()] or equivalent call that triggered
1.2069 +** the authorizer will fail with an error message.
1.2070 +**
1.2071 +** When the callback returns [SQLITE_OK], that means the operation
1.2072 +** requested is ok. When the callback returns [SQLITE_DENY], the
1.2073 +** [sqlite3_prepare_v2()] or equivalent call that triggered the
1.2074 +** authorizer will fail with an error message explaining that
1.2075 +** access is denied. If the authorizer code is [SQLITE_READ]
1.2076 +** and the callback returns [SQLITE_IGNORE] then the
1.2077 +** [prepared statement] statement is constructed to substitute
1.2078 +** a NULL value in place of the table column that would have
1.2079 +** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE]
1.2080 +** return can be used to deny an untrusted user access to individual
1.2081 +** columns of a table.
1.2082 +**
1.2083 +** The first parameter to the authorizer callback is a copy of the third
1.2084 +** parameter to the sqlite3_set_authorizer() interface. The second parameter
1.2085 +** to the callback is an integer [SQLITE_COPY | action code] that specifies
1.2086 +** the particular action to be authorized. The third through sixth parameters
1.2087 +** to the callback are zero-terminated strings that contain additional
1.2088 +** details about the action to be authorized.
1.2089 +**
1.2090 +** An authorizer is used when [sqlite3_prepare | preparing]
1.2091 +** SQL statements from an untrusted source, to ensure that the SQL statements
1.2092 +** do not try to access data they are not allowed to see, or that they do not
1.2093 +** try to execute malicious statements that damage the database. For
1.2094 +** example, an application may allow a user to enter arbitrary
1.2095 +** SQL queries for evaluation by a database. But the application does
1.2096 +** not want the user to be able to make arbitrary changes to the
1.2097 +** database. An authorizer could then be put in place while the
1.2098 +** user-entered SQL is being [sqlite3_prepare | prepared] that
1.2099 +** disallows everything except [SELECT] statements.
1.2100 +**
1.2101 +** Applications that need to process SQL from untrusted sources
1.2102 +** might also consider lowering resource limits using [sqlite3_limit()]
1.2103 +** and limiting database size using the [max_page_count] [PRAGMA]
1.2104 +** in addition to using an authorizer.
1.2105 +**
1.2106 +** Only a single authorizer can be in place on a database connection
1.2107 +** at a time. Each call to sqlite3_set_authorizer overrides the
1.2108 +** previous call. Disable the authorizer by installing a NULL callback.
1.2109 +** The authorizer is disabled by default.
1.2110 +**
1.2111 +** The authorizer callback must not do anything that will modify
1.2112 +** the database connection that invoked the authorizer callback.
1.2113 +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
1.2114 +** database connections for the meaning of "modify" in this paragraph.
1.2115 +**
1.2116 +** When [sqlite3_prepare_v2()] is used to prepare a statement, the
1.2117 +** statement might be reprepared during [sqlite3_step()] due to a
1.2118 +** schema change. Hence, the application should ensure that the
1.2119 +** correct authorizer callback remains in place during the [sqlite3_step()].
1.2120 +**
1.2121 +** Note that the authorizer callback is invoked only during
1.2122 +** [sqlite3_prepare()] or its variants. Authorization is not
1.2123 +** performed during statement evaluation in [sqlite3_step()].
1.2124 +**
1.2125 +** INVARIANTS:
1.2126 +**
1.2127 +** {H12501} The [sqlite3_set_authorizer(D,...)] interface registers a
1.2128 +** authorizer callback with database connection D.
1.2129 +**
1.2130 +** {H12502} The authorizer callback is invoked as SQL statements are
1.2131 +** being parseed and compiled.
1.2132 +**
1.2133 +** {H12503} If the authorizer callback returns any value other than
1.2134 +** [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY], then
1.2135 +** the application interface call that caused
1.2136 +** the authorizer callback to run shall fail with an
1.2137 +** [SQLITE_ERROR] error code and an appropriate error message.
1.2138 +**
1.2139 +** {H12504} When the authorizer callback returns [SQLITE_OK], the operation
1.2140 +** described is processed normally.
1.2141 +**
1.2142 +** {H12505} When the authorizer callback returns [SQLITE_DENY], the
1.2143 +** application interface call that caused the
1.2144 +** authorizer callback to run shall fail
1.2145 +** with an [SQLITE_ERROR] error code and an error message
1.2146 +** explaining that access is denied.
1.2147 +**
1.2148 +** {H12506} If the authorizer code (the 2nd parameter to the authorizer
1.2149 +** callback) is [SQLITE_READ] and the authorizer callback returns
1.2150 +** [SQLITE_IGNORE], then the prepared statement is constructed to
1.2151 +** insert a NULL value in place of the table column that would have
1.2152 +** been read if [SQLITE_OK] had been returned.
1.2153 +**
1.2154 +** {H12507} If the authorizer code (the 2nd parameter to the authorizer
1.2155 +** callback) is anything other than [SQLITE_READ], then
1.2156 +** a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY].
1.2157 +**
1.2158 +** {H12510} The first parameter to the authorizer callback is a copy of
1.2159 +** the third parameter to the [sqlite3_set_authorizer()] interface.
1.2160 +**
1.2161 +** {H12511} The second parameter to the callback is an integer
1.2162 +** [SQLITE_COPY | action code] that specifies the particular action
1.2163 +** to be authorized.
1.2164 +**
1.2165 +** {H12512} The third through sixth parameters to the callback are
1.2166 +** zero-terminated strings that contain
1.2167 +** additional details about the action to be authorized.
1.2168 +**
1.2169 +** {H12520} Each call to [sqlite3_set_authorizer()] overrides
1.2170 +** any previously installed authorizer.
1.2171 +**
1.2172 +** {H12521} A NULL authorizer means that no authorization
1.2173 +** callback is invoked.
1.2174 +**
1.2175 +** {H12522} The default authorizer is NULL.
1.2176 +*/
1.2177 +IMPORT_C int sqlite3_set_authorizer(
1.2178 + sqlite3*,
1.2179 + int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
1.2180 + void *pUserData
1.2181 +);
1.2182 +
1.2183 +/*
1.2184 +** CAPI3REF: Authorizer Return Codes {H12590} <H12500>
1.2185 +**
1.2186 +** The [sqlite3_set_authorizer | authorizer callback function] must
1.2187 +** return either [SQLITE_OK] or one of these two constants in order
1.2188 +** to signal SQLite whether or not the action is permitted. See the
1.2189 +** [sqlite3_set_authorizer | authorizer documentation] for additional
1.2190 +** information.
1.2191 +*/
1.2192 +#define SQLITE_DENY 1 /* Abort the SQL statement with an error */
1.2193 +#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
1.2194 +
1.2195 +/*
1.2196 +** CAPI3REF: Authorizer Action Codes {H12550} <H12500>
1.2197 +**
1.2198 +** The [sqlite3_set_authorizer()] interface registers a callback function
1.2199 +** that is invoked to authorize certain SQL statement actions. The
1.2200 +** second parameter to the callback is an integer code that specifies
1.2201 +** what action is being authorized. These are the integer action codes that
1.2202 +** the authorizer callback may be passed.
1.2203 +**
1.2204 +** These action code values signify what kind of operation is to be
1.2205 +** authorized. The 3rd and 4th parameters to the authorization
1.2206 +** callback function will be parameters or NULL depending on which of these
1.2207 +** codes is used as the second parameter. The 5th parameter to the
1.2208 +** authorizer callback is the name of the database ("main", "temp",
1.2209 +** etc.) if applicable. The 6th parameter to the authorizer callback
1.2210 +** is the name of the inner-most trigger or view that is responsible for
1.2211 +** the access attempt or NULL if this access attempt is directly from
1.2212 +** top-level SQL code.
1.2213 +**
1.2214 +** INVARIANTS:
1.2215 +**
1.2216 +** {H12551} The second parameter to an
1.2217 +** [sqlite3_set_authorizer | authorizer callback] shall be an integer
1.2218 +** [SQLITE_COPY | authorizer code] that specifies what action
1.2219 +** is being authorized.
1.2220 +**
1.2221 +** {H12552} The 3rd and 4th parameters to the
1.2222 +** [sqlite3_set_authorizer | authorization callback]
1.2223 +** shall be parameters or NULL depending on which
1.2224 +** [SQLITE_COPY | authorizer code] is used as the second parameter.
1.2225 +**
1.2226 +** {H12553} The 5th parameter to the
1.2227 +** [sqlite3_set_authorizer | authorizer callback] shall be the name
1.2228 +** of the database (example: "main", "temp", etc.) if applicable.
1.2229 +**
1.2230 +** {H12554} The 6th parameter to the
1.2231 +** [sqlite3_set_authorizer | authorizer callback] shall be the name
1.2232 +** of the inner-most trigger or view that is responsible for
1.2233 +** the access attempt or NULL if this access attempt is directly from
1.2234 +** top-level SQL code.
1.2235 +*/
1.2236 +/******************************************* 3rd ************ 4th ***********/
1.2237 +#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
1.2238 +#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
1.2239 +#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
1.2240 +#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
1.2241 +#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
1.2242 +#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
1.2243 +#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
1.2244 +#define SQLITE_CREATE_VIEW 8 /* View Name NULL */
1.2245 +#define SQLITE_DELETE 9 /* Table Name NULL */
1.2246 +#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
1.2247 +#define SQLITE_DROP_TABLE 11 /* Table Name NULL */
1.2248 +#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
1.2249 +#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
1.2250 +#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
1.2251 +#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
1.2252 +#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
1.2253 +#define SQLITE_DROP_VIEW 17 /* View Name NULL */
1.2254 +#define SQLITE_INSERT 18 /* Table Name NULL */
1.2255 +#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
1.2256 +#define SQLITE_READ 20 /* Table Name Column Name */
1.2257 +#define SQLITE_SELECT 21 /* NULL NULL */
1.2258 +#define SQLITE_TRANSACTION 22 /* NULL NULL */
1.2259 +#define SQLITE_UPDATE 23 /* Table Name Column Name */
1.2260 +#define SQLITE_ATTACH 24 /* Filename NULL */
1.2261 +#define SQLITE_DETACH 25 /* Database Name NULL */
1.2262 +#define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */
1.2263 +#define SQLITE_REINDEX 27 /* Index Name NULL */
1.2264 +#define SQLITE_ANALYZE 28 /* Table Name NULL */
1.2265 +#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
1.2266 +#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
1.2267 +#define SQLITE_FUNCTION 31 /* Function Name NULL */
1.2268 +#define SQLITE_COPY 0 /* No longer used */
1.2269 +
1.2270 +/*
1.2271 +** CAPI3REF: Tracing And Profiling Functions {H12280} <S60400>
1.2272 +** EXPERIMENTAL
1.2273 +**
1.2274 +** These routines register callback functions that can be used for
1.2275 +** tracing and profiling the execution of SQL statements.
1.2276 +**
1.2277 +** The callback function registered by sqlite3_trace() is invoked at
1.2278 +** various times when an SQL statement is being run by [sqlite3_step()].
1.2279 +** The callback returns a UTF-8 rendering of the SQL statement text
1.2280 +** as the statement first begins executing. Additional callbacks occur
1.2281 +** as each triggered subprogram is entered. The callbacks for triggers
1.2282 +** contain a UTF-8 SQL comment that identifies the trigger.
1.2283 +**
1.2284 +** The callback function registered by sqlite3_profile() is invoked
1.2285 +** as each SQL statement finishes. The profile callback contains
1.2286 +** the original statement text and an estimate of wall-clock time
1.2287 +** of how long that statement took to run.
1.2288 +**
1.2289 +** INVARIANTS:
1.2290 +**
1.2291 +** {H12281} The callback function registered by [sqlite3_trace()]
1.2292 +** shall be invoked
1.2293 +** whenever an SQL statement first begins to execute and
1.2294 +** whenever a trigger subprogram first begins to run.
1.2295 +**
1.2296 +** {H12282} Each call to [sqlite3_trace()] shall override the previously
1.2297 +** registered trace callback.
1.2298 +**
1.2299 +** {H12283} A NULL trace callback shall disable tracing.
1.2300 +**
1.2301 +** {H12284} The first argument to the trace callback shall be a copy of
1.2302 +** the pointer which was the 3rd argument to [sqlite3_trace()].
1.2303 +**
1.2304 +** {H12285} The second argument to the trace callback is a
1.2305 +** zero-terminated UTF-8 string containing the original text
1.2306 +** of the SQL statement as it was passed into [sqlite3_prepare_v2()]
1.2307 +** or the equivalent, or an SQL comment indicating the beginning
1.2308 +** of a trigger subprogram.
1.2309 +**
1.2310 +** {H12287} The callback function registered by [sqlite3_profile()] is invoked
1.2311 +** as each SQL statement finishes.
1.2312 +**
1.2313 +** {H12288} The first parameter to the profile callback is a copy of
1.2314 +** the 3rd parameter to [sqlite3_profile()].
1.2315 +**
1.2316 +** {H12289} The second parameter to the profile callback is a
1.2317 +** zero-terminated UTF-8 string that contains the complete text of
1.2318 +** the SQL statement as it was processed by [sqlite3_prepare_v2()]
1.2319 +** or the equivalent.
1.2320 +**
1.2321 +** {H12290} The third parameter to the profile callback is an estimate
1.2322 +** of the number of nanoseconds of wall-clock time required to
1.2323 +** run the SQL statement from start to finish.
1.2324 +*/
1.2325 +IMPORT_C void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
1.2326 +IMPORT_C void *sqlite3_profile(sqlite3*,
1.2327 + void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
1.2328 +
1.2329 +/*
1.2330 +** CAPI3REF: Query Progress Callbacks {H12910} <S60400>
1.2331 +**
1.2332 +** This routine configures a callback function - the
1.2333 +** progress callback - that is invoked periodically during long
1.2334 +** running calls to [sqlite3_exec()], [sqlite3_step()] and
1.2335 +** [sqlite3_get_table()]. An example use for this
1.2336 +** interface is to keep a GUI updated during a large query.
1.2337 +**
1.2338 +** If the progress callback returns non-zero, the operation is
1.2339 +** interrupted. This feature can be used to implement a
1.2340 +** "Cancel" button on a GUI progress dialog box.
1.2341 +**
1.2342 +** The progress handler must not do anything that will modify
1.2343 +** the database connection that invoked the progress handler.
1.2344 +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
1.2345 +** database connections for the meaning of "modify" in this paragraph.
1.2346 +**
1.2347 +** INVARIANTS:
1.2348 +**
1.2349 +** {H12911} The callback function registered by sqlite3_progress_handler()
1.2350 +** is invoked periodically during long running calls to
1.2351 +** [sqlite3_step()].
1.2352 +**
1.2353 +** {H12912} The progress callback is invoked once for every N virtual
1.2354 +** machine opcodes, where N is the second argument to
1.2355 +** the [sqlite3_progress_handler()] call that registered
1.2356 +** the callback. If N is less than 1, sqlite3_progress_handler()
1.2357 +** acts as if a NULL progress handler had been specified.
1.2358 +**
1.2359 +** {H12913} The progress callback itself is identified by the third
1.2360 +** argument to sqlite3_progress_handler().
1.2361 +**
1.2362 +** {H12914} The fourth argument to sqlite3_progress_handler() is a
1.2363 +** void pointer passed to the progress callback
1.2364 +** function each time it is invoked.
1.2365 +**
1.2366 +** {H12915} If a call to [sqlite3_step()] results in fewer than N opcodes
1.2367 +** being executed, then the progress callback is never invoked.
1.2368 +**
1.2369 +** {H12916} Every call to [sqlite3_progress_handler()]
1.2370 +** overwrites any previously registered progress handler.
1.2371 +**
1.2372 +** {H12917} If the progress handler callback is NULL then no progress
1.2373 +** handler is invoked.
1.2374 +**
1.2375 +** {H12918} If the progress callback returns a result other than 0, then
1.2376 +** the behavior is a if [sqlite3_interrupt()] had been called.
1.2377 +** <S30500>
1.2378 +*/
1.2379 +IMPORT_C void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
1.2380 +
1.2381 +/*
1.2382 +** CAPI3REF: Opening A New Database Connection {H12700} <S40200>
1.2383 +**
1.2384 +** These routines open an SQLite database file whose name is given by the
1.2385 +** filename argument. The filename argument is interpreted as UTF-8 for
1.2386 +** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
1.2387 +** order for sqlite3_open16(). A [database connection] handle is usually
1.2388 +** returned in *ppDb, even if an error occurs. The only exception is that
1.2389 +** if SQLite is unable to allocate memory to hold the [sqlite3] object,
1.2390 +** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
1.2391 +** object. If the database is opened (and/or created) successfully, then
1.2392 +** [SQLITE_OK] is returned. Otherwise an [error code] is returned. The
1.2393 +** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
1.2394 +** an English language description of the error.
1.2395 +**
1.2396 +** The default encoding for the database will be UTF-8 if
1.2397 +** sqlite3_open() or sqlite3_open_v2() is called and
1.2398 +** UTF-16 in the native byte order if sqlite3_open16() is used.
1.2399 +**
1.2400 +** Whether or not an error occurs when it is opened, resources
1.2401 +** associated with the [database connection] handle should be released by
1.2402 +** passing it to [sqlite3_close()] when it is no longer required.
1.2403 +**
1.2404 +** The sqlite3_open_v2() interface works like sqlite3_open()
1.2405 +** except that it accepts two additional parameters for additional control
1.2406 +** over the new database connection. The flags parameter can take one of
1.2407 +** the following three values, optionally combined with the
1.2408 +** [SQLITE_OPEN_NOMUTEX] or [SQLITE_OPEN_FULLMUTEX] flags:
1.2409 +**
1.2410 +** <dl>
1.2411 +** <dt>[SQLITE_OPEN_READONLY]</dt>
1.2412 +** <dd>The database is opened in read-only mode. If the database does not
1.2413 +** already exist, an error is returned.</dd>
1.2414 +**
1.2415 +** <dt>[SQLITE_OPEN_READWRITE]</dt>
1.2416 +** <dd>The database is opened for reading and writing if possible, or reading
1.2417 +** only if the file is write protected by the operating system. In either
1.2418 +** case the database must already exist, otherwise an error is returned.</dd>
1.2419 +**
1.2420 +** <dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
1.2421 +** <dd>The database is opened for reading and writing, and is creates it if
1.2422 +** it does not already exist. This is the behavior that is always used for
1.2423 +** sqlite3_open() and sqlite3_open16().</dd>
1.2424 +** </dl>
1.2425 +**
1.2426 +** If the 3rd parameter to sqlite3_open_v2() is not one of the
1.2427 +** combinations shown above or one of the combinations shown above combined
1.2428 +** with the [SQLITE_OPEN_NOMUTEX] or [SQLITE_OPEN_FULLMUTEX] flags,
1.2429 +** then the behavior is undefined.
1.2430 +**
1.2431 +** If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
1.2432 +** opens in the multi-thread [threading mode] as long as the single-thread
1.2433 +** mode has not been set at compile-time or start-time. If the
1.2434 +** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
1.2435 +** in the serialized [threading mode] unless single-thread was
1.2436 +** previously selected at compile-time or start-time.
1.2437 +**
1.2438 +** If the filename is ":memory:", then a private, temporary in-memory database
1.2439 +** is created for the connection. This in-memory database will vanish when
1.2440 +** the database connection is closed. Future versions of SQLite might
1.2441 +** make use of additional special filenames that begin with the ":" character.
1.2442 +** It is recommended that when a database filename actually does begin with
1.2443 +** a ":" character you should prefix the filename with a pathname such as
1.2444 +** "./" to avoid ambiguity.
1.2445 +**
1.2446 +** If the filename is an empty string, then a private, temporary
1.2447 +** on-disk database will be created. This private database will be
1.2448 +** automatically deleted as soon as the database connection is closed.
1.2449 +**
1.2450 +** The fourth parameter to sqlite3_open_v2() is the name of the
1.2451 +** [sqlite3_vfs] object that defines the operating system interface that
1.2452 +** the new database connection should use. If the fourth parameter is
1.2453 +** a NULL pointer then the default [sqlite3_vfs] object is used.
1.2454 +**
1.2455 +** <b>Note to Windows users:</b> The encoding used for the filename argument
1.2456 +** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
1.2457 +** codepage is currently defined. Filenames containing international
1.2458 +** characters must be converted to UTF-8 prior to passing them into
1.2459 +** sqlite3_open() or sqlite3_open_v2().
1.2460 +**
1.2461 +** INVARIANTS:
1.2462 +**
1.2463 +** {H12701} The [sqlite3_open()], [sqlite3_open16()], and
1.2464 +** [sqlite3_open_v2()] interfaces create a new
1.2465 +** [database connection] associated with
1.2466 +** the database file given in their first parameter.
1.2467 +**
1.2468 +** {H12702} The filename argument is interpreted as UTF-8
1.2469 +** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16
1.2470 +** in the native byte order for [sqlite3_open16()].
1.2471 +**
1.2472 +** {H12703} A successful invocation of [sqlite3_open()], [sqlite3_open16()],
1.2473 +** or [sqlite3_open_v2()] writes a pointer to a new
1.2474 +** [database connection] into *ppDb.
1.2475 +**
1.2476 +** {H12704} The [sqlite3_open()], [sqlite3_open16()], and
1.2477 +** [sqlite3_open_v2()] interfaces return [SQLITE_OK] upon success,
1.2478 +** or an appropriate [error code] on failure.
1.2479 +**
1.2480 +** {H12706} The default text encoding for a new database created using
1.2481 +** [sqlite3_open()] or [sqlite3_open_v2()] will be UTF-8.
1.2482 +**
1.2483 +** {H12707} The default text encoding for a new database created using
1.2484 +** [sqlite3_open16()] will be UTF-16.
1.2485 +**
1.2486 +** {H12709} The [sqlite3_open(F,D)] interface is equivalent to
1.2487 +** [sqlite3_open_v2(F,D,G,0)] where the G parameter is
1.2488 +** [SQLITE_OPEN_READWRITE]|[SQLITE_OPEN_CREATE].
1.2489 +**
1.2490 +** {H12711} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the
1.2491 +** bit value [SQLITE_OPEN_READONLY] then the database is opened
1.2492 +** for reading only.
1.2493 +**
1.2494 +** {H12712} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the
1.2495 +** bit value [SQLITE_OPEN_READWRITE] then the database is opened
1.2496 +** reading and writing if possible, or for reading only if the
1.2497 +** file is write protected by the operating system.
1.2498 +**
1.2499 +** {H12713} If the G parameter to [sqlite3_open_v2(F,D,G,V)] omits the
1.2500 +** bit value [SQLITE_OPEN_CREATE] and the database does not
1.2501 +** previously exist, an error is returned.
1.2502 +**
1.2503 +** {H12714} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the
1.2504 +** bit value [SQLITE_OPEN_CREATE] and the database does not
1.2505 +** previously exist, then an attempt is made to create and
1.2506 +** initialize the database.
1.2507 +**
1.2508 +** {H12717} If the filename argument to [sqlite3_open()], [sqlite3_open16()],
1.2509 +** or [sqlite3_open_v2()] is ":memory:", then an private,
1.2510 +** ephemeral, in-memory database is created for the connection.
1.2511 +** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required
1.2512 +** in sqlite3_open_v2()?</todo>
1.2513 +**
1.2514 +** {H12719} If the filename is NULL or an empty string, then a private,
1.2515 +** ephemeral on-disk database will be created.
1.2516 +** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required
1.2517 +** in sqlite3_open_v2()?</todo>
1.2518 +**
1.2519 +** {H12721} The [database connection] created by [sqlite3_open_v2(F,D,G,V)]
1.2520 +** will use the [sqlite3_vfs] object identified by the V parameter,
1.2521 +** or the default [sqlite3_vfs] object if V is a NULL pointer.
1.2522 +**
1.2523 +** {H12723} Two [database connections] will share a common cache if both were
1.2524 +** opened with the same VFS while [shared cache mode] was enabled and
1.2525 +** if both filenames compare equal using memcmp() after having been
1.2526 +** processed by the [sqlite3_vfs | xFullPathname] method of the VFS.
1.2527 +*/
1.2528 +IMPORT_C int sqlite3_open(
1.2529 + const char *filename, /* Database filename (UTF-8) */
1.2530 + sqlite3 **ppDb /* OUT: SQLite db handle */
1.2531 +);
1.2532 +IMPORT_C int sqlite3_open16(
1.2533 + const void *filename, /* Database filename (UTF-16) */
1.2534 + sqlite3 **ppDb /* OUT: SQLite db handle */
1.2535 +);
1.2536 +IMPORT_C int sqlite3_open_v2(
1.2537 + const char *filename, /* Database filename (UTF-8) */
1.2538 + sqlite3 **ppDb, /* OUT: SQLite db handle */
1.2539 + int flags, /* Flags */
1.2540 + const char *zVfs /* Name of VFS module to use */
1.2541 +);
1.2542 +
1.2543 +/*
1.2544 +** CAPI3REF: Error Codes And Messages {H12800} <S60200>
1.2545 +**
1.2546 +** The sqlite3_errcode() interface returns the numeric [result code] or
1.2547 +** [extended result code] for the most recent failed sqlite3_* API call
1.2548 +** associated with a [database connection]. If a prior API call failed
1.2549 +** but the most recent API call succeeded, the return value from
1.2550 +** sqlite3_errcode() is undefined.
1.2551 +**
1.2552 +** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
1.2553 +** text that describes the error, as either UTF-8 or UTF-16 respectively.
1.2554 +** Memory to hold the error message string is managed internally.
1.2555 +** The application does not need to worry about freeing the result.
1.2556 +** However, the error string might be overwritten or deallocated by
1.2557 +** subsequent calls to other SQLite interface functions.
1.2558 +**
1.2559 +** If an interface fails with SQLITE_MISUSE, that means the interface
1.2560 +** was invoked incorrectly by the application. In that case, the
1.2561 +** error code and message may or may not be set.
1.2562 +**
1.2563 +** INVARIANTS:
1.2564 +**
1.2565 +** {H12801} The [sqlite3_errcode(D)] interface returns the numeric
1.2566 +** [result code] or [extended result code] for the most recently
1.2567 +** failed interface call associated with the [database connection] D.
1.2568 +**
1.2569 +** {H12803} The [sqlite3_errmsg(D)] and [sqlite3_errmsg16(D)]
1.2570 +** interfaces return English-language text that describes
1.2571 +** the error in the mostly recently failed interface call,
1.2572 +** encoded as either UTF-8 or UTF-16 respectively.
1.2573 +**
1.2574 +** {H12807} The strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()]
1.2575 +** are valid until the next SQLite interface call.
1.2576 +**
1.2577 +** {H12808} Calls to API routines that do not return an error code
1.2578 +** (example: [sqlite3_data_count()]) do not
1.2579 +** change the error code or message returned by
1.2580 +** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()].
1.2581 +**
1.2582 +** {H12809} Interfaces that are not associated with a specific
1.2583 +** [database connection] (examples:
1.2584 +** [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()]
1.2585 +** do not change the values returned by
1.2586 +** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()].
1.2587 +*/
1.2588 +IMPORT_C int sqlite3_errcode(sqlite3 *db);
1.2589 +IMPORT_C const char *sqlite3_errmsg(sqlite3*);
1.2590 +IMPORT_C const void *sqlite3_errmsg16(sqlite3*);
1.2591 +
1.2592 +/*
1.2593 +** CAPI3REF: SQL Statement Object {H13000} <H13010>
1.2594 +** KEYWORDS: {prepared statement} {prepared statements}
1.2595 +**
1.2596 +** An instance of this object represents a single SQL statement.
1.2597 +** This object is variously known as a "prepared statement" or a
1.2598 +** "compiled SQL statement" or simply as a "statement".
1.2599 +**
1.2600 +** The life of a statement object goes something like this:
1.2601 +**
1.2602 +** <ol>
1.2603 +** <li> Create the object using [sqlite3_prepare_v2()] or a related
1.2604 +** function.
1.2605 +** <li> Bind values to [host parameters] using the sqlite3_bind_*()
1.2606 +** interfaces.
1.2607 +** <li> Run the SQL by calling [sqlite3_step()] one or more times.
1.2608 +** <li> Reset the statement using [sqlite3_reset()] then go back
1.2609 +** to step 2. Do this zero or more times.
1.2610 +** <li> Destroy the object using [sqlite3_finalize()].
1.2611 +** </ol>
1.2612 +**
1.2613 +** Refer to documentation on individual methods above for additional
1.2614 +** information.
1.2615 +*/
1.2616 +typedef struct sqlite3_stmt sqlite3_stmt;
1.2617 +
1.2618 +/*
1.2619 +** CAPI3REF: Run-time Limits {H12760} <S20600>
1.2620 +**
1.2621 +** This interface allows the size of various constructs to be limited
1.2622 +** on a connection by connection basis. The first parameter is the
1.2623 +** [database connection] whose limit is to be set or queried. The
1.2624 +** second parameter is one of the [limit categories] that define a
1.2625 +** class of constructs to be size limited. The third parameter is the
1.2626 +** new limit for that construct. The function returns the old limit.
1.2627 +**
1.2628 +** If the new limit is a negative number, the limit is unchanged.
1.2629 +** For the limit category of SQLITE_LIMIT_XYZ there is a hard upper
1.2630 +** bound set by a compile-time C preprocessor macro named SQLITE_MAX_XYZ.
1.2631 +** (The "_LIMIT_" in the name is changed to "_MAX_".)
1.2632 +** Attempts to increase a limit above its hard upper bound are
1.2633 +** silently truncated to the hard upper limit.
1.2634 +**
1.2635 +** Run time limits are intended for use in applications that manage
1.2636 +** both their own internal database and also databases that are controlled
1.2637 +** by untrusted external sources. An example application might be a
1.2638 +** webbrowser that has its own databases for storing history and
1.2639 +** separate databases controlled by JavaScript applications downloaded
1.2640 +** off the Internet. The internal databases can be given the
1.2641 +** large, default limits. Databases managed by external sources can
1.2642 +** be given much smaller limits designed to prevent a denial of service
1.2643 +** attack. Developers might also want to use the [sqlite3_set_authorizer()]
1.2644 +** interface to further control untrusted SQL. The size of the database
1.2645 +** created by an untrusted script can be contained using the
1.2646 +** [max_page_count] [PRAGMA].
1.2647 +**
1.2648 +** New run-time limit categories may be added in future releases.
1.2649 +**
1.2650 +** INVARIANTS:
1.2651 +**
1.2652 +** {H12762} A successful call to [sqlite3_limit(D,C,V)] where V is
1.2653 +** positive changes the limit on the size of construct C in the
1.2654 +** [database connection] D to the lesser of V and the hard upper
1.2655 +** bound on the size of C that is set at compile-time.
1.2656 +**
1.2657 +** {H12766} A successful call to [sqlite3_limit(D,C,V)] where V is negative
1.2658 +** leaves the state of the [database connection] D unchanged.
1.2659 +**
1.2660 +** {H12769} A successful call to [sqlite3_limit(D,C,V)] returns the
1.2661 +** value of the limit on the size of construct C in the
1.2662 +** [database connection] D as it was prior to the call.
1.2663 +*/
1.2664 +IMPORT_C int sqlite3_limit(sqlite3*, int id, int newVal);
1.2665 +
1.2666 +/*
1.2667 +** CAPI3REF: Run-Time Limit Categories {H12790} <H12760>
1.2668 +** KEYWORDS: {limit category} {limit categories}
1.2669 +**
1.2670 +** These constants define various aspects of a [database connection]
1.2671 +** that can be limited in size by calls to [sqlite3_limit()].
1.2672 +** The meanings of the various limits are as follows:
1.2673 +**
1.2674 +** <dl>
1.2675 +** <dt>SQLITE_LIMIT_LENGTH</dt>
1.2676 +** <dd>The maximum size of any string or BLOB or table row.<dd>
1.2677 +**
1.2678 +** <dt>SQLITE_LIMIT_SQL_LENGTH</dt>
1.2679 +** <dd>The maximum length of an SQL statement.</dd>
1.2680 +**
1.2681 +** <dt>SQLITE_LIMIT_COLUMN</dt>
1.2682 +** <dd>The maximum number of columns in a table definition or in the
1.2683 +** result set of a SELECT or the maximum number of columns in an index
1.2684 +** or in an ORDER BY or GROUP BY clause.</dd>
1.2685 +**
1.2686 +** <dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
1.2687 +** <dd>The maximum depth of the parse tree on any expression.</dd>
1.2688 +**
1.2689 +** <dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
1.2690 +** <dd>The maximum number of terms in a compound SELECT statement.</dd>
1.2691 +**
1.2692 +** <dt>SQLITE_LIMIT_VDBE_OP</dt>
1.2693 +** <dd>The maximum number of instructions in a virtual machine program
1.2694 +** used to implement an SQL statement.</dd>
1.2695 +**
1.2696 +** <dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
1.2697 +** <dd>The maximum number of arguments on a function.</dd>
1.2698 +**
1.2699 +** <dt>SQLITE_LIMIT_ATTACHED</dt>
1.2700 +** <dd>The maximum number of attached databases.</dd>
1.2701 +**
1.2702 +** <dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
1.2703 +** <dd>The maximum length of the pattern argument to the LIKE or
1.2704 +** GLOB operators.</dd>
1.2705 +**
1.2706 +** <dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
1.2707 +** <dd>The maximum number of variables in an SQL statement that can
1.2708 +** be bound.</dd>
1.2709 +** </dl>
1.2710 +*/
1.2711 +#define SQLITE_LIMIT_LENGTH 0
1.2712 +#define SQLITE_LIMIT_SQL_LENGTH 1
1.2713 +#define SQLITE_LIMIT_COLUMN 2
1.2714 +#define SQLITE_LIMIT_EXPR_DEPTH 3
1.2715 +#define SQLITE_LIMIT_COMPOUND_SELECT 4
1.2716 +#define SQLITE_LIMIT_VDBE_OP 5
1.2717 +#define SQLITE_LIMIT_FUNCTION_ARG 6
1.2718 +#define SQLITE_LIMIT_ATTACHED 7
1.2719 +#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8
1.2720 +#define SQLITE_LIMIT_VARIABLE_NUMBER 9
1.2721 +
1.2722 +/*
1.2723 +** CAPI3REF: Compiling An SQL Statement {H13010} <S10000>
1.2724 +** KEYWORDS: {SQL statement compiler}
1.2725 +**
1.2726 +** To execute an SQL query, it must first be compiled into a byte-code
1.2727 +** program using one of these routines.
1.2728 +**
1.2729 +** The first argument, "db", is a [database connection] obtained from a
1.2730 +** prior call to [sqlite3_open()], [sqlite3_open_v2()] or [sqlite3_open16()].
1.2731 +**
1.2732 +** The second argument, "zSql", is the statement to be compiled, encoded
1.2733 +** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2()
1.2734 +** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()
1.2735 +** use UTF-16.
1.2736 +**
1.2737 +** If the nByte argument is less than zero, then zSql is read up to the
1.2738 +** first zero terminator. If nByte is non-negative, then it is the maximum
1.2739 +** number of bytes read from zSql. When nByte is non-negative, the
1.2740 +** zSql string ends at either the first '\000' or '\u0000' character or
1.2741 +** the nByte-th byte, whichever comes first. If the caller knows
1.2742 +** that the supplied string is nul-terminated, then there is a small
1.2743 +** performance advantage to be gained by passing an nByte parameter that
1.2744 +** is equal to the number of bytes in the input string <i>including</i>
1.2745 +** the nul-terminator bytes.
1.2746 +**
1.2747 +** *pzTail is made to point to the first byte past the end of the
1.2748 +** first SQL statement in zSql. These routines only compile the first
1.2749 +** statement in zSql, so *pzTail is left pointing to what remains
1.2750 +** uncompiled.
1.2751 +**
1.2752 +** *ppStmt is left pointing to a compiled [prepared statement] that can be
1.2753 +** executed using [sqlite3_step()]. If there is an error, *ppStmt is set
1.2754 +** to NULL. If the input text contains no SQL (if the input is an empty
1.2755 +** string or a comment) then *ppStmt is set to NULL.
1.2756 +** {A13018} The calling procedure is responsible for deleting the compiled
1.2757 +** SQL statement using [sqlite3_finalize()] after it has finished with it.
1.2758 +**
1.2759 +** On success, [SQLITE_OK] is returned, otherwise an [error code] is returned.
1.2760 +**
1.2761 +** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
1.2762 +** recommended for all new programs. The two older interfaces are retained
1.2763 +** for backwards compatibility, but their use is discouraged.
1.2764 +** In the "v2" interfaces, the prepared statement
1.2765 +** that is returned (the [sqlite3_stmt] object) contains a copy of the
1.2766 +** original SQL text. This causes the [sqlite3_step()] interface to
1.2767 +** behave a differently in two ways:
1.2768 +**
1.2769 +** <ol>
1.2770 +** <li>
1.2771 +** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
1.2772 +** always used to do, [sqlite3_step()] will automatically recompile the SQL
1.2773 +** statement and try to run it again. If the schema has changed in
1.2774 +** a way that makes the statement no longer valid, [sqlite3_step()] will still
1.2775 +** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is
1.2776 +** now a fatal error. Calling [sqlite3_prepare_v2()] again will not make the
1.2777 +** error go away. Note: use [sqlite3_errmsg()] to find the text
1.2778 +** of the parsing error that results in an [SQLITE_SCHEMA] return.
1.2779 +** </li>
1.2780 +**
1.2781 +** <li>
1.2782 +** When an error occurs, [sqlite3_step()] will return one of the detailed
1.2783 +** [error codes] or [extended error codes]. The legacy behavior was that
1.2784 +** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
1.2785 +** and you would have to make a second call to [sqlite3_reset()] in order
1.2786 +** to find the underlying cause of the problem. With the "v2" prepare
1.2787 +** interfaces, the underlying reason for the error is returned immediately.
1.2788 +** </li>
1.2789 +** </ol>
1.2790 +**
1.2791 +** INVARIANTS:
1.2792 +**
1.2793 +** {H13011} The [sqlite3_prepare(db,zSql,...)] and
1.2794 +** [sqlite3_prepare_v2(db,zSql,...)] interfaces interpret the
1.2795 +** text in their zSql parameter as UTF-8.
1.2796 +**
1.2797 +** {H13012} The [sqlite3_prepare16(db,zSql,...)] and
1.2798 +** [sqlite3_prepare16_v2(db,zSql,...)] interfaces interpret the
1.2799 +** text in their zSql parameter as UTF-16 in the native byte order.
1.2800 +**
1.2801 +** {H13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)]
1.2802 +** and its variants is less than zero, the SQL text is
1.2803 +** read from zSql is read up to the first zero terminator.
1.2804 +**
1.2805 +** {H13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)]
1.2806 +** and its variants is non-negative, then at most nBytes bytes of
1.2807 +** SQL text is read from zSql.
1.2808 +**
1.2809 +** {H13015} In [sqlite3_prepare_v2(db,zSql,N,P,pzTail)] and its variants
1.2810 +** if the zSql input text contains more than one SQL statement
1.2811 +** and pzTail is not NULL, then *pzTail is made to point to the
1.2812 +** first byte past the end of the first SQL statement in zSql.
1.2813 +** <todo>What does *pzTail point to if there is one statement?</todo>
1.2814 +**
1.2815 +** {H13016} A successful call to [sqlite3_prepare_v2(db,zSql,N,ppStmt,...)]
1.2816 +** or one of its variants writes into *ppStmt a pointer to a new
1.2817 +** [prepared statement] or a pointer to NULL if zSql contains
1.2818 +** nothing other than whitespace or comments.
1.2819 +**
1.2820 +** {H13019} The [sqlite3_prepare_v2()] interface and its variants return
1.2821 +** [SQLITE_OK] or an appropriate [error code] upon failure.
1.2822 +**
1.2823 +** {H13021} Before [sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail)] or its
1.2824 +** variants returns an error (any value other than [SQLITE_OK]),
1.2825 +** they first set *ppStmt to NULL.
1.2826 +*/
1.2827 +IMPORT_C int sqlite3_prepare(
1.2828 + sqlite3 *db, /* Database handle */
1.2829 + const char *zSql, /* SQL statement, UTF-8 encoded */
1.2830 + int nByte, /* Maximum length of zSql in bytes. */
1.2831 + sqlite3_stmt **ppStmt, /* OUT: Statement handle */
1.2832 + const char **pzTail /* OUT: Pointer to unused portion of zSql */
1.2833 +);
1.2834 +IMPORT_C int sqlite3_prepare_v2(
1.2835 + sqlite3 *db, /* Database handle */
1.2836 + const char *zSql, /* SQL statement, UTF-8 encoded */
1.2837 + int nByte, /* Maximum length of zSql in bytes. */
1.2838 + sqlite3_stmt **ppStmt, /* OUT: Statement handle */
1.2839 + const char **pzTail /* OUT: Pointer to unused portion of zSql */
1.2840 +);
1.2841 +IMPORT_C int sqlite3_prepare16(
1.2842 + sqlite3 *db, /* Database handle */
1.2843 + const void *zSql, /* SQL statement, UTF-16 encoded */
1.2844 + int nByte, /* Maximum length of zSql in bytes. */
1.2845 + sqlite3_stmt **ppStmt, /* OUT: Statement handle */
1.2846 + const void **pzTail /* OUT: Pointer to unused portion of zSql */
1.2847 +);
1.2848 +IMPORT_C int sqlite3_prepare16_v2(
1.2849 + sqlite3 *db, /* Database handle */
1.2850 + const void *zSql, /* SQL statement, UTF-16 encoded */
1.2851 + int nByte, /* Maximum length of zSql in bytes. */
1.2852 + sqlite3_stmt **ppStmt, /* OUT: Statement handle */
1.2853 + const void **pzTail /* OUT: Pointer to unused portion of zSql */
1.2854 +);
1.2855 +
1.2856 +/*
1.2857 +** CAPI3REF: Retrieving Statement SQL {H13100} <H13000>
1.2858 +**
1.2859 +** This interface can be used to retrieve a saved copy of the original
1.2860 +** SQL text used to create a [prepared statement] if that statement was
1.2861 +** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()].
1.2862 +**
1.2863 +** INVARIANTS:
1.2864 +**
1.2865 +** {H13101} If the [prepared statement] passed as the argument to
1.2866 +** [sqlite3_sql()] was compiled using either [sqlite3_prepare_v2()] or
1.2867 +** [sqlite3_prepare16_v2()], then [sqlite3_sql()] returns
1.2868 +** a pointer to a zero-terminated string containing a UTF-8 rendering
1.2869 +** of the original SQL statement.
1.2870 +**
1.2871 +** {H13102} If the [prepared statement] passed as the argument to
1.2872 +** [sqlite3_sql()] was compiled using either [sqlite3_prepare()] or
1.2873 +** [sqlite3_prepare16()], then [sqlite3_sql()] returns a NULL pointer.
1.2874 +**
1.2875 +** {H13103} The string returned by [sqlite3_sql(S)] is valid until the
1.2876 +** [prepared statement] S is deleted using [sqlite3_finalize(S)].
1.2877 +*/
1.2878 +IMPORT_C const char *sqlite3_sql(sqlite3_stmt *pStmt);
1.2879 +
1.2880 +/*
1.2881 +** CAPI3REF: Dynamically Typed Value Object {H15000} <S20200>
1.2882 +** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
1.2883 +**
1.2884 +** SQLite uses the sqlite3_value object to represent all values
1.2885 +** that can be stored in a database table. SQLite uses dynamic typing
1.2886 +** for the values it stores. Values stored in sqlite3_value objects
1.2887 +** can be integers, floating point values, strings, BLOBs, or NULL.
1.2888 +**
1.2889 +** An sqlite3_value object may be either "protected" or "unprotected".
1.2890 +** Some interfaces require a protected sqlite3_value. Other interfaces
1.2891 +** will accept either a protected or an unprotected sqlite3_value.
1.2892 +** Every interface that accepts sqlite3_value arguments specifies
1.2893 +** whether or not it requires a protected sqlite3_value.
1.2894 +**
1.2895 +** The terms "protected" and "unprotected" refer to whether or not
1.2896 +** a mutex is held. A internal mutex is held for a protected
1.2897 +** sqlite3_value object but no mutex is held for an unprotected
1.2898 +** sqlite3_value object. If SQLite is compiled to be single-threaded
1.2899 +** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
1.2900 +** or if SQLite is run in one of reduced mutex modes
1.2901 +** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
1.2902 +** then there is no distinction between protected and unprotected
1.2903 +** sqlite3_value objects and they can be used interchangeably. However,
1.2904 +** for maximum code portability it is recommended that applications
1.2905 +** still make the distinction between between protected and unprotected
1.2906 +** sqlite3_value objects even when not strictly required.
1.2907 +**
1.2908 +** The sqlite3_value objects that are passed as parameters into the
1.2909 +** implementation of [application-defined SQL functions] are protected.
1.2910 +** The sqlite3_value object returned by
1.2911 +** [sqlite3_column_value()] is unprotected.
1.2912 +** Unprotected sqlite3_value objects may only be used with
1.2913 +** [sqlite3_result_value()] and [sqlite3_bind_value()].
1.2914 +** The [sqlite3_value_blob | sqlite3_value_type()] family of
1.2915 +** interfaces require protected sqlite3_value objects.
1.2916 +*/
1.2917 +typedef struct Mem sqlite3_value;
1.2918 +
1.2919 +/*
1.2920 +** CAPI3REF: SQL Function Context Object {H16001} <S20200>
1.2921 +**
1.2922 +** The context in which an SQL function executes is stored in an
1.2923 +** sqlite3_context object. A pointer to an sqlite3_context object
1.2924 +** is always first parameter to [application-defined SQL functions].
1.2925 +** The application-defined SQL function implementation will pass this
1.2926 +** pointer through into calls to [sqlite3_result_int | sqlite3_result()],
1.2927 +** [sqlite3_aggregate_context()], [sqlite3_user_data()],
1.2928 +** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],
1.2929 +** and/or [sqlite3_set_auxdata()].
1.2930 +*/
1.2931 +typedef struct sqlite3_context sqlite3_context;
1.2932 +
1.2933 +/*
1.2934 +** CAPI3REF: Binding Values To Prepared Statements {H13500} <S70300>
1.2935 +** KEYWORDS: {host parameter} {host parameters} {host parameter name}
1.2936 +** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
1.2937 +**
1.2938 +** In the SQL strings input to [sqlite3_prepare_v2()] and its variants,
1.2939 +** literals may be replaced by a parameter in one of these forms:
1.2940 +**
1.2941 +** <ul>
1.2942 +** <li> ?
1.2943 +** <li> ?NNN
1.2944 +** <li> :VVV
1.2945 +** <li> @VVV
1.2946 +** <li> $VVV
1.2947 +** </ul>
1.2948 +**
1.2949 +** In the parameter forms shown above NNN is an integer literal,
1.2950 +** and VVV is an alpha-numeric parameter name. The values of these
1.2951 +** parameters (also called "host parameter names" or "SQL parameters")
1.2952 +** can be set using the sqlite3_bind_*() routines defined here.
1.2953 +**
1.2954 +** The first argument to the sqlite3_bind_*() routines is always
1.2955 +** a pointer to the [sqlite3_stmt] object returned from
1.2956 +** [sqlite3_prepare_v2()] or its variants.
1.2957 +**
1.2958 +** The second argument is the index of the SQL parameter to be set.
1.2959 +** The leftmost SQL parameter has an index of 1. When the same named
1.2960 +** SQL parameter is used more than once, second and subsequent
1.2961 +** occurrences have the same index as the first occurrence.
1.2962 +** The index for named parameters can be looked up using the
1.2963 +** [sqlite3_bind_parameter_index()] API if desired. The index
1.2964 +** for "?NNN" parameters is the value of NNN.
1.2965 +** The NNN value must be between 1 and the [sqlite3_limit()]
1.2966 +** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999).
1.2967 +**
1.2968 +** The third argument is the value to bind to the parameter.
1.2969 +**
1.2970 +** In those routines that have a fourth argument, its value is the
1.2971 +** number of bytes in the parameter. To be clear: the value is the
1.2972 +** number of <u>bytes</u> in the value, not the number of characters.
1.2973 +** If the fourth parameter is negative, the length of the string is
1.2974 +** the number of bytes up to the first zero terminator.
1.2975 +**
1.2976 +** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
1.2977 +** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
1.2978 +** string after SQLite has finished with it. If the fifth argument is
1.2979 +** the special value [SQLITE_STATIC], then SQLite assumes that the
1.2980 +** information is in static, unmanaged space and does not need to be freed.
1.2981 +** If the fifth argument has the value [SQLITE_TRANSIENT], then
1.2982 +** SQLite makes its own private copy of the data immediately, before
1.2983 +** the sqlite3_bind_*() routine returns.
1.2984 +**
1.2985 +** The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
1.2986 +** is filled with zeroes. A zeroblob uses a fixed amount of memory
1.2987 +** (just an integer to hold its size) while it is being processed.
1.2988 +** Zeroblobs are intended to serve as placeholders for BLOBs whose
1.2989 +** content is later written using
1.2990 +** [sqlite3_blob_open | incremental BLOB I/O] routines.
1.2991 +** A negative value for the zeroblob results in a zero-length BLOB.
1.2992 +**
1.2993 +** The sqlite3_bind_*() routines must be called after
1.2994 +** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and
1.2995 +** before [sqlite3_step()].
1.2996 +** Bindings are not cleared by the [sqlite3_reset()] routine.
1.2997 +** Unbound parameters are interpreted as NULL.
1.2998 +**
1.2999 +** These routines return [SQLITE_OK] on success or an error code if
1.3000 +** anything goes wrong. [SQLITE_RANGE] is returned if the parameter
1.3001 +** index is out of range. [SQLITE_NOMEM] is returned if malloc() fails.
1.3002 +** [SQLITE_MISUSE] might be returned if these routines are called on a
1.3003 +** virtual machine that is the wrong state or which has already been finalized.
1.3004 +** Detection of misuse is unreliable. Applications should not depend
1.3005 +** on SQLITE_MISUSE returns. SQLITE_MISUSE is intended to indicate a
1.3006 +** a logic error in the application. Future versions of SQLite might
1.3007 +** panic rather than return SQLITE_MISUSE.
1.3008 +**
1.3009 +** See also: [sqlite3_bind_parameter_count()],
1.3010 +** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
1.3011 +**
1.3012 +** INVARIANTS:
1.3013 +**
1.3014 +** {H13506} The [SQL statement compiler] recognizes tokens of the forms
1.3015 +** "?", "?NNN", "$VVV", ":VVV", and "@VVV" as SQL parameters,
1.3016 +** where NNN is any sequence of one or more digits
1.3017 +** and where VVV is any sequence of one or more alphanumeric
1.3018 +** characters or "::" optionally followed by a string containing
1.3019 +** no spaces and contained within parentheses.
1.3020 +**
1.3021 +** {H13509} The initial value of an SQL parameter is NULL.
1.3022 +**
1.3023 +** {H13512} The index of an "?" SQL parameter is one larger than the
1.3024 +** largest index of SQL parameter to the left, or 1 if
1.3025 +** the "?" is the leftmost SQL parameter.
1.3026 +**
1.3027 +** {H13515} The index of an "?NNN" SQL parameter is the integer NNN.
1.3028 +**
1.3029 +** {H13518} The index of an ":VVV", "$VVV", or "@VVV" SQL parameter is
1.3030 +** the same as the index of leftmost occurrences of the same
1.3031 +** parameter, or one more than the largest index over all
1.3032 +** parameters to the left if this is the first occurrence
1.3033 +** of this parameter, or 1 if this is the leftmost parameter.
1.3034 +**
1.3035 +** {H13521} The [SQL statement compiler] fails with an [SQLITE_RANGE]
1.3036 +** error if the index of an SQL parameter is less than 1
1.3037 +** or greater than the compile-time SQLITE_MAX_VARIABLE_NUMBER
1.3038 +** parameter.
1.3039 +**
1.3040 +** {H13524} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,V,...)]
1.3041 +** associate the value V with all SQL parameters having an
1.3042 +** index of N in the [prepared statement] S.
1.3043 +**
1.3044 +** {H13527} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,...)]
1.3045 +** override prior calls with the same values of S and N.
1.3046 +**
1.3047 +** {H13530} Bindings established by [sqlite3_bind_text | sqlite3_bind(S,...)]
1.3048 +** persist across calls to [sqlite3_reset(S)].
1.3049 +**
1.3050 +** {H13533} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
1.3051 +** [sqlite3_bind_text(S,N,V,L,D)], or
1.3052 +** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds the first L
1.3053 +** bytes of the BLOB or string pointed to by V, when L
1.3054 +** is non-negative.
1.3055 +**
1.3056 +** {H13536} In calls to [sqlite3_bind_text(S,N,V,L,D)] or
1.3057 +** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds characters
1.3058 +** from V through the first zero character when L is negative.
1.3059 +**
1.3060 +** {H13539} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
1.3061 +** [sqlite3_bind_text(S,N,V,L,D)], or
1.3062 +** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special
1.3063 +** constant [SQLITE_STATIC], SQLite assumes that the value V
1.3064 +** is held in static unmanaged space that will not change
1.3065 +** during the lifetime of the binding.
1.3066 +**
1.3067 +** {H13542} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
1.3068 +** [sqlite3_bind_text(S,N,V,L,D)], or
1.3069 +** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special
1.3070 +** constant [SQLITE_TRANSIENT], the routine makes a
1.3071 +** private copy of the value V before it returns.
1.3072 +**
1.3073 +** {H13545} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
1.3074 +** [sqlite3_bind_text(S,N,V,L,D)], or
1.3075 +** [sqlite3_bind_text16(S,N,V,L,D)] when D is a pointer to
1.3076 +** a function, SQLite invokes that function to destroy the
1.3077 +** value V after it has finished using the value V.
1.3078 +**
1.3079 +** {H13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound
1.3080 +** is a BLOB of L bytes, or a zero-length BLOB if L is negative.
1.3081 +**
1.3082 +** {H13551} In calls to [sqlite3_bind_value(S,N,V)] the V argument may
1.3083 +** be either a [protected sqlite3_value] object or an
1.3084 +** [unprotected sqlite3_value] object.
1.3085 +*/
1.3086 +IMPORT_C int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
1.3087 +IMPORT_C int sqlite3_bind_double(sqlite3_stmt*, int, double);
1.3088 +IMPORT_C int sqlite3_bind_int(sqlite3_stmt*, int, int);
1.3089 +IMPORT_C int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
1.3090 +IMPORT_C int sqlite3_bind_null(sqlite3_stmt*, int);
1.3091 +IMPORT_C int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
1.3092 +IMPORT_C int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
1.3093 +IMPORT_C int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
1.3094 +IMPORT_C int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
1.3095 +
1.3096 +/*
1.3097 +** CAPI3REF: Number Of SQL Parameters {H13600} <S70300>
1.3098 +**
1.3099 +** This routine can be used to find the number of [SQL parameters]
1.3100 +** in a [prepared statement]. SQL parameters are tokens of the
1.3101 +** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
1.3102 +** placeholders for values that are [sqlite3_bind_blob | bound]
1.3103 +** to the parameters at a later time.
1.3104 +**
1.3105 +** This routine actually returns the index of the largest (rightmost)
1.3106 +** parameter. For all forms except ?NNN, this will correspond to the
1.3107 +** number of unique parameters. If parameters of the ?NNN are used,
1.3108 +** there may be gaps in the list.
1.3109 +**
1.3110 +** See also: [sqlite3_bind_blob|sqlite3_bind()],
1.3111 +** [sqlite3_bind_parameter_name()], and
1.3112 +** [sqlite3_bind_parameter_index()].
1.3113 +**
1.3114 +** INVARIANTS:
1.3115 +**
1.3116 +** {H13601} The [sqlite3_bind_parameter_count(S)] interface returns
1.3117 +** the largest index of all SQL parameters in the
1.3118 +** [prepared statement] S, or 0 if S contains no SQL parameters.
1.3119 +*/
1.3120 +IMPORT_C int sqlite3_bind_parameter_count(sqlite3_stmt*);
1.3121 +
1.3122 +/*
1.3123 +** CAPI3REF: Name Of A Host Parameter {H13620} <S70300>
1.3124 +**
1.3125 +** This routine returns a pointer to the name of the n-th
1.3126 +** [SQL parameter] in a [prepared statement].
1.3127 +** SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
1.3128 +** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
1.3129 +** respectively.
1.3130 +** In other words, the initial ":" or "$" or "@" or "?"
1.3131 +** is included as part of the name.
1.3132 +** Parameters of the form "?" without a following integer have no name
1.3133 +** and are also referred to as "anonymous parameters".
1.3134 +**
1.3135 +** The first host parameter has an index of 1, not 0.
1.3136 +**
1.3137 +** If the value n is out of range or if the n-th parameter is
1.3138 +** nameless, then NULL is returned. The returned string is
1.3139 +** always in UTF-8 encoding even if the named parameter was
1.3140 +** originally specified as UTF-16 in [sqlite3_prepare16()] or
1.3141 +** [sqlite3_prepare16_v2()].
1.3142 +**
1.3143 +** See also: [sqlite3_bind_blob|sqlite3_bind()],
1.3144 +** [sqlite3_bind_parameter_count()], and
1.3145 +** [sqlite3_bind_parameter_index()].
1.3146 +**
1.3147 +** INVARIANTS:
1.3148 +**
1.3149 +** {H13621} The [sqlite3_bind_parameter_name(S,N)] interface returns
1.3150 +** a UTF-8 rendering of the name of the SQL parameter in
1.3151 +** the [prepared statement] S having index N, or
1.3152 +** NULL if there is no SQL parameter with index N or if the
1.3153 +** parameter with index N is an anonymous parameter "?".
1.3154 +*/
1.3155 +IMPORT_C const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
1.3156 +
1.3157 +/*
1.3158 +** CAPI3REF: Index Of A Parameter With A Given Name {H13640} <S70300>
1.3159 +**
1.3160 +** Return the index of an SQL parameter given its name. The
1.3161 +** index value returned is suitable for use as the second
1.3162 +** parameter to [sqlite3_bind_blob|sqlite3_bind()]. A zero
1.3163 +** is returned if no matching parameter is found. The parameter
1.3164 +** name must be given in UTF-8 even if the original statement
1.3165 +** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].
1.3166 +**
1.3167 +** See also: [sqlite3_bind_blob|sqlite3_bind()],
1.3168 +** [sqlite3_bind_parameter_count()], and
1.3169 +** [sqlite3_bind_parameter_index()].
1.3170 +**
1.3171 +** INVARIANTS:
1.3172 +**
1.3173 +** {H13641} The [sqlite3_bind_parameter_index(S,N)] interface returns
1.3174 +** the index of SQL parameter in the [prepared statement]
1.3175 +** S whose name matches the UTF-8 string N, or 0 if there is
1.3176 +** no match.
1.3177 +*/
1.3178 +IMPORT_C int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
1.3179 +
1.3180 +/*
1.3181 +** CAPI3REF: Reset All Bindings On A Prepared Statement {H13660} <S70300>
1.3182 +**
1.3183 +** Contrary to the intuition of many, [sqlite3_reset()] does not reset
1.3184 +** the [sqlite3_bind_blob | bindings] on a [prepared statement].
1.3185 +** Use this routine to reset all host parameters to NULL.
1.3186 +**
1.3187 +** INVARIANTS:
1.3188 +**
1.3189 +** {H13661} The [sqlite3_clear_bindings(S)] interface resets all SQL
1.3190 +** parameter bindings in the [prepared statement] S back to NULL.
1.3191 +*/
1.3192 +IMPORT_C int sqlite3_clear_bindings(sqlite3_stmt*);
1.3193 +
1.3194 +/*
1.3195 +** CAPI3REF: Number Of Columns In A Result Set {H13710} <S10700>
1.3196 +**
1.3197 +** Return the number of columns in the result set returned by the
1.3198 +** [prepared statement]. This routine returns 0 if pStmt is an SQL
1.3199 +** statement that does not return data (for example an [UPDATE]).
1.3200 +**
1.3201 +** INVARIANTS:
1.3202 +**
1.3203 +** {H13711} The [sqlite3_column_count(S)] interface returns the number of
1.3204 +** columns in the result set generated by the [prepared statement] S,
1.3205 +** or 0 if S does not generate a result set.
1.3206 +*/
1.3207 +IMPORT_C int sqlite3_column_count(sqlite3_stmt *pStmt);
1.3208 +
1.3209 +/*
1.3210 +** CAPI3REF: Column Names In A Result Set {H13720} <S10700>
1.3211 +**
1.3212 +** These routines return the name assigned to a particular column
1.3213 +** in the result set of a [SELECT] statement. The sqlite3_column_name()
1.3214 +** interface returns a pointer to a zero-terminated UTF-8 string
1.3215 +** and sqlite3_column_name16() returns a pointer to a zero-terminated
1.3216 +** UTF-16 string. The first parameter is the [prepared statement]
1.3217 +** that implements the [SELECT] statement. The second parameter is the
1.3218 +** column number. The leftmost column is number 0.
1.3219 +**
1.3220 +** The returned string pointer is valid until either the [prepared statement]
1.3221 +** is destroyed by [sqlite3_finalize()] or until the next call to
1.3222 +** sqlite3_column_name() or sqlite3_column_name16() on the same column.
1.3223 +**
1.3224 +** If sqlite3_malloc() fails during the processing of either routine
1.3225 +** (for example during a conversion from UTF-8 to UTF-16) then a
1.3226 +** NULL pointer is returned.
1.3227 +**
1.3228 +** The name of a result column is the value of the "AS" clause for
1.3229 +** that column, if there is an AS clause. If there is no AS clause
1.3230 +** then the name of the column is unspecified and may change from
1.3231 +** one release of SQLite to the next.
1.3232 +**
1.3233 +** INVARIANTS:
1.3234 +**
1.3235 +** {H13721} A successful invocation of the [sqlite3_column_name(S,N)]
1.3236 +** interface returns the name of the Nth column (where 0 is
1.3237 +** the leftmost column) for the result set of the
1.3238 +** [prepared statement] S as a zero-terminated UTF-8 string.
1.3239 +**
1.3240 +** {H13723} A successful invocation of the [sqlite3_column_name16(S,N)]
1.3241 +** interface returns the name of the Nth column (where 0 is
1.3242 +** the leftmost column) for the result set of the
1.3243 +** [prepared statement] S as a zero-terminated UTF-16 string
1.3244 +** in the native byte order.
1.3245 +**
1.3246 +** {H13724} The [sqlite3_column_name()] and [sqlite3_column_name16()]
1.3247 +** interfaces return a NULL pointer if they are unable to
1.3248 +** allocate memory to hold their normal return strings.
1.3249 +**
1.3250 +** {H13725} If the N parameter to [sqlite3_column_name(S,N)] or
1.3251 +** [sqlite3_column_name16(S,N)] is out of range, then the
1.3252 +** interfaces return a NULL pointer.
1.3253 +**
1.3254 +** {H13726} The strings returned by [sqlite3_column_name(S,N)] and
1.3255 +** [sqlite3_column_name16(S,N)] are valid until the next
1.3256 +** call to either routine with the same S and N parameters
1.3257 +** or until [sqlite3_finalize(S)] is called.
1.3258 +**
1.3259 +** {H13727} When a result column of a [SELECT] statement contains
1.3260 +** an AS clause, the name of that column is the identifier
1.3261 +** to the right of the AS keyword.
1.3262 +*/
1.3263 +IMPORT_C const char *sqlite3_column_name(sqlite3_stmt*, int N);
1.3264 +IMPORT_C const void *sqlite3_column_name16(sqlite3_stmt*, int N);
1.3265 +
1.3266 +/*
1.3267 +** CAPI3REF: Source Of Data In A Query Result {H13740} <S10700>
1.3268 +**
1.3269 +** These routines provide a means to determine what column of what
1.3270 +** table in which database a result of a [SELECT] statement comes from.
1.3271 +** The name of the database or table or column can be returned as
1.3272 +** either a UTF-8 or UTF-16 string. The _database_ routines return
1.3273 +** the database name, the _table_ routines return the table name, and
1.3274 +** the origin_ routines return the column name.
1.3275 +** The returned string is valid until the [prepared statement] is destroyed
1.3276 +** using [sqlite3_finalize()] or until the same information is requested
1.3277 +** again in a different encoding.
1.3278 +**
1.3279 +** The names returned are the original un-aliased names of the
1.3280 +** database, table, and column.
1.3281 +**
1.3282 +** The first argument to the following calls is a [prepared statement].
1.3283 +** These functions return information about the Nth column returned by
1.3284 +** the statement, where N is the second function argument.
1.3285 +**
1.3286 +** If the Nth column returned by the statement is an expression or
1.3287 +** subquery and is not a column value, then all of these functions return
1.3288 +** NULL. These routine might also return NULL if a memory allocation error
1.3289 +** occurs. Otherwise, they return the name of the attached database, table
1.3290 +** and column that query result column was extracted from.
1.3291 +**
1.3292 +** As with all other SQLite APIs, those postfixed with "16" return
1.3293 +** UTF-16 encoded strings, the other functions return UTF-8. {END}
1.3294 +**
1.3295 +** These APIs are only available if the library was compiled with the
1.3296 +** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined.
1.3297 +**
1.3298 +** {A13751}
1.3299 +** If two or more threads call one or more of these routines against the same
1.3300 +** prepared statement and column at the same time then the results are
1.3301 +** undefined.
1.3302 +**
1.3303 +** INVARIANTS:
1.3304 +**
1.3305 +** {H13741} The [sqlite3_column_database_name(S,N)] interface returns either
1.3306 +** the UTF-8 zero-terminated name of the database from which the
1.3307 +** Nth result column of the [prepared statement] S is extracted,
1.3308 +** or NULL if the Nth column of S is a general expression
1.3309 +** or if unable to allocate memory to store the name.
1.3310 +**
1.3311 +** {H13742} The [sqlite3_column_database_name16(S,N)] interface returns either
1.3312 +** the UTF-16 native byte order zero-terminated name of the database
1.3313 +** from which the Nth result column of the [prepared statement] S is
1.3314 +** extracted, or NULL if the Nth column of S is a general expression
1.3315 +** or if unable to allocate memory to store the name.
1.3316 +**
1.3317 +** {H13743} The [sqlite3_column_table_name(S,N)] interface returns either
1.3318 +** the UTF-8 zero-terminated name of the table from which the
1.3319 +** Nth result column of the [prepared statement] S is extracted,
1.3320 +** or NULL if the Nth column of S is a general expression
1.3321 +** or if unable to allocate memory to store the name.
1.3322 +**
1.3323 +** {H13744} The [sqlite3_column_table_name16(S,N)] interface returns either
1.3324 +** the UTF-16 native byte order zero-terminated name of the table
1.3325 +** from which the Nth result column of the [prepared statement] S is
1.3326 +** extracted, or NULL if the Nth column of S is a general expression
1.3327 +** or if unable to allocate memory to store the name.
1.3328 +**
1.3329 +** {H13745} The [sqlite3_column_origin_name(S,N)] interface returns either
1.3330 +** the UTF-8 zero-terminated name of the table column from which the
1.3331 +** Nth result column of the [prepared statement] S is extracted,
1.3332 +** or NULL if the Nth column of S is a general expression
1.3333 +** or if unable to allocate memory to store the name.
1.3334 +**
1.3335 +** {H13746} The [sqlite3_column_origin_name16(S,N)] interface returns either
1.3336 +** the UTF-16 native byte order zero-terminated name of the table
1.3337 +** column from which the Nth result column of the
1.3338 +** [prepared statement] S is extracted, or NULL if the Nth column
1.3339 +** of S is a general expression or if unable to allocate memory
1.3340 +** to store the name.
1.3341 +**
1.3342 +** {H13748} The return values from
1.3343 +** [sqlite3_column_database_name | column metadata interfaces]
1.3344 +** are valid for the lifetime of the [prepared statement]
1.3345 +** or until the encoding is changed by another metadata
1.3346 +** interface call for the same prepared statement and column.
1.3347 +**
1.3348 +** ASSUMPTIONS:
1.3349 +**
1.3350 +** {A13751} If two or more threads call one or more
1.3351 +** [sqlite3_column_database_name | column metadata interfaces]
1.3352 +** for the same [prepared statement] and result column
1.3353 +** at the same time then the results are undefined.
1.3354 +*/
1.3355 +IMPORT_C const char *sqlite3_column_database_name(sqlite3_stmt*,int);
1.3356 +IMPORT_C const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
1.3357 +IMPORT_C const char *sqlite3_column_table_name(sqlite3_stmt*,int);
1.3358 +IMPORT_C const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
1.3359 +IMPORT_C const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
1.3360 +IMPORT_C const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
1.3361 +
1.3362 +/*
1.3363 +** CAPI3REF: Declared Datatype Of A Query Result {H13760} <S10700>
1.3364 +**
1.3365 +** The first parameter is a [prepared statement].
1.3366 +** If this statement is a [SELECT] statement and the Nth column of the
1.3367 +** returned result set of that [SELECT] is a table column (not an
1.3368 +** expression or subquery) then the declared type of the table
1.3369 +** column is returned. If the Nth column of the result set is an
1.3370 +** expression or subquery, then a NULL pointer is returned.
1.3371 +** The returned string is always UTF-8 encoded. {END}
1.3372 +**
1.3373 +** For example, given the database schema:
1.3374 +**
1.3375 +** CREATE TABLE t1(c1 VARIANT);
1.3376 +**
1.3377 +** and the following statement to be compiled:
1.3378 +**
1.3379 +** SELECT c1 + 1, c1 FROM t1;
1.3380 +**
1.3381 +** this routine would return the string "VARIANT" for the second result
1.3382 +** column (i==1), and a NULL pointer for the first result column (i==0).
1.3383 +**
1.3384 +** SQLite uses dynamic run-time typing. So just because a column
1.3385 +** is declared to contain a particular type does not mean that the
1.3386 +** data stored in that column is of the declared type. SQLite is
1.3387 +** strongly typed, but the typing is dynamic not static. Type
1.3388 +** is associated with individual values, not with the containers
1.3389 +** used to hold those values.
1.3390 +**
1.3391 +** INVARIANTS:
1.3392 +**
1.3393 +** {H13761} A successful call to [sqlite3_column_decltype(S,N)] returns a
1.3394 +** zero-terminated UTF-8 string containing the declared datatype
1.3395 +** of the table column that appears as the Nth column (numbered
1.3396 +** from 0) of the result set to the [prepared statement] S.
1.3397 +**
1.3398 +** {H13762} A successful call to [sqlite3_column_decltype16(S,N)]
1.3399 +** returns a zero-terminated UTF-16 native byte order string
1.3400 +** containing the declared datatype of the table column that appears
1.3401 +** as the Nth column (numbered from 0) of the result set to the
1.3402 +** [prepared statement] S.
1.3403 +**
1.3404 +** {H13763} If N is less than 0 or N is greater than or equal to
1.3405 +** the number of columns in the [prepared statement] S,
1.3406 +** or if the Nth column of S is an expression or subquery rather
1.3407 +** than a table column, or if a memory allocation failure
1.3408 +** occurs during encoding conversions, then
1.3409 +** calls to [sqlite3_column_decltype(S,N)] or
1.3410 +** [sqlite3_column_decltype16(S,N)] return NULL.
1.3411 +*/
1.3412 +IMPORT_C const char *sqlite3_column_decltype(sqlite3_stmt*,int);
1.3413 +IMPORT_C const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
1.3414 +
1.3415 +/*
1.3416 +** CAPI3REF: Evaluate An SQL Statement {H13200} <S10000>
1.3417 +**
1.3418 +** After a [prepared statement] has been prepared using either
1.3419 +** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy
1.3420 +** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
1.3421 +** must be called one or more times to evaluate the statement.
1.3422 +**
1.3423 +** The details of the behavior of the sqlite3_step() interface depend
1.3424 +** on whether the statement was prepared using the newer "v2" interface
1.3425 +** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
1.3426 +** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the
1.3427 +** new "v2" interface is recommended for new applications but the legacy
1.3428 +** interface will continue to be supported.
1.3429 +**
1.3430 +** In the legacy interface, the return value will be either [SQLITE_BUSY],
1.3431 +** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
1.3432 +** With the "v2" interface, any of the other [result codes] or
1.3433 +** [extended result codes] might be returned as well.
1.3434 +**
1.3435 +** [SQLITE_BUSY] means that the database engine was unable to acquire the
1.3436 +** database locks it needs to do its job. If the statement is a [COMMIT]
1.3437 +** or occurs outside of an explicit transaction, then you can retry the
1.3438 +** statement. If the statement is not a [COMMIT] and occurs within a
1.3439 +** explicit transaction then you should rollback the transaction before
1.3440 +** continuing.
1.3441 +**
1.3442 +** [SQLITE_DONE] means that the statement has finished executing
1.3443 +** successfully. sqlite3_step() should not be called again on this virtual
1.3444 +** machine without first calling [sqlite3_reset()] to reset the virtual
1.3445 +** machine back to its initial state.
1.3446 +**
1.3447 +** If the SQL statement being executed returns any data, then [SQLITE_ROW]
1.3448 +** is returned each time a new row of data is ready for processing by the
1.3449 +** caller. The values may be accessed using the [column access functions].
1.3450 +** sqlite3_step() is called again to retrieve the next row of data.
1.3451 +**
1.3452 +** [SQLITE_ERROR] means that a run-time error (such as a constraint
1.3453 +** violation) has occurred. sqlite3_step() should not be called again on
1.3454 +** the VM. More information may be found by calling [sqlite3_errmsg()].
1.3455 +** With the legacy interface, a more specific error code (for example,
1.3456 +** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
1.3457 +** can be obtained by calling [sqlite3_reset()] on the
1.3458 +** [prepared statement]. In the "v2" interface,
1.3459 +** the more specific error code is returned directly by sqlite3_step().
1.3460 +**
1.3461 +** [SQLITE_MISUSE] means that the this routine was called inappropriately.
1.3462 +** Perhaps it was called on a [prepared statement] that has
1.3463 +** already been [sqlite3_finalize | finalized] or on one that had
1.3464 +** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could
1.3465 +** be the case that the same database connection is being used by two or
1.3466 +** more threads at the same moment in time.
1.3467 +**
1.3468 +** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
1.3469 +** API always returns a generic error code, [SQLITE_ERROR], following any
1.3470 +** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call
1.3471 +** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
1.3472 +** specific [error codes] that better describes the error.
1.3473 +** We admit that this is a goofy design. The problem has been fixed
1.3474 +** with the "v2" interface. If you prepare all of your SQL statements
1.3475 +** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
1.3476 +** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
1.3477 +** then the more specific [error codes] are returned directly
1.3478 +** by sqlite3_step(). The use of the "v2" interface is recommended.
1.3479 +**
1.3480 +** INVARIANTS:
1.3481 +**
1.3482 +** {H13202} If the [prepared statement] S is ready to be run, then
1.3483 +** [sqlite3_step(S)] advances that prepared statement until
1.3484 +** completion or until it is ready to return another row of the
1.3485 +** result set, or until an [sqlite3_interrupt | interrupt]
1.3486 +** or a run-time error occurs.
1.3487 +**
1.3488 +** {H15304} When a call to [sqlite3_step(S)] causes the [prepared statement]
1.3489 +** S to run to completion, the function returns [SQLITE_DONE].
1.3490 +**
1.3491 +** {H15306} When a call to [sqlite3_step(S)] stops because it is ready to
1.3492 +** return another row of the result set, it returns [SQLITE_ROW].
1.3493 +**
1.3494 +** {H15308} If a call to [sqlite3_step(S)] encounters an
1.3495 +** [sqlite3_interrupt | interrupt] or a run-time error,
1.3496 +** it returns an appropriate error code that is not one of
1.3497 +** [SQLITE_OK], [SQLITE_ROW], or [SQLITE_DONE].
1.3498 +**
1.3499 +** {H15310} If an [sqlite3_interrupt | interrupt] or a run-time error
1.3500 +** occurs during a call to [sqlite3_step(S)]
1.3501 +** for a [prepared statement] S created using
1.3502 +** legacy interfaces [sqlite3_prepare()] or
1.3503 +** [sqlite3_prepare16()], then the function returns either
1.3504 +** [SQLITE_ERROR], [SQLITE_BUSY], or [SQLITE_MISUSE].
1.3505 +*/
1.3506 +IMPORT_C int sqlite3_step(sqlite3_stmt*);
1.3507 +
1.3508 +/*
1.3509 +** CAPI3REF: Number of columns in a result set {H13770} <S10700>
1.3510 +**
1.3511 +** Returns the number of values in the current row of the result set.
1.3512 +**
1.3513 +** INVARIANTS:
1.3514 +**
1.3515 +** {H13771} After a call to [sqlite3_step(S)] that returns [SQLITE_ROW],
1.3516 +** the [sqlite3_data_count(S)] routine will return the same value
1.3517 +** as the [sqlite3_column_count(S)] function.
1.3518 +**
1.3519 +** {H13772} After [sqlite3_step(S)] has returned any value other than
1.3520 +** [SQLITE_ROW] or before [sqlite3_step(S)] has been called on the
1.3521 +** [prepared statement] for the first time since it was
1.3522 +** [sqlite3_prepare | prepared] or [sqlite3_reset | reset],
1.3523 +** the [sqlite3_data_count(S)] routine returns zero.
1.3524 +*/
1.3525 +IMPORT_C int sqlite3_data_count(sqlite3_stmt *pStmt);
1.3526 +
1.3527 +/*
1.3528 +** CAPI3REF: Fundamental Datatypes {H10265} <S10110><S10120>
1.3529 +** KEYWORDS: SQLITE_TEXT
1.3530 +**
1.3531 +** {H10266} Every value in SQLite has one of five fundamental datatypes:
1.3532 +**
1.3533 +** <ul>
1.3534 +** <li> 64-bit signed integer
1.3535 +** <li> 64-bit IEEE floating point number
1.3536 +** <li> string
1.3537 +** <li> BLOB
1.3538 +** <li> NULL
1.3539 +** </ul> {END}
1.3540 +**
1.3541 +** These constants are codes for each of those types.
1.3542 +**
1.3543 +** Note that the SQLITE_TEXT constant was also used in SQLite version 2
1.3544 +** for a completely different meaning. Software that links against both
1.3545 +** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
1.3546 +** SQLITE_TEXT.
1.3547 +*/
1.3548 +#define SQLITE_INTEGER 1
1.3549 +#define SQLITE_FLOAT 2
1.3550 +#define SQLITE_BLOB 4
1.3551 +#define SQLITE_NULL 5
1.3552 +#ifdef SQLITE_TEXT
1.3553 +# undef SQLITE_TEXT
1.3554 +#else
1.3555 +# define SQLITE_TEXT 3
1.3556 +#endif
1.3557 +#define SQLITE3_TEXT 3
1.3558 +
1.3559 +/*
1.3560 +** CAPI3REF: Result Values From A Query {H13800} <S10700>
1.3561 +** KEYWORDS: {column access functions}
1.3562 +**
1.3563 +** These routines form the "result set query" interface.
1.3564 +**
1.3565 +** These routines return information about a single column of the current
1.3566 +** result row of a query. In every case the first argument is a pointer
1.3567 +** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
1.3568 +** that was returned from [sqlite3_prepare_v2()] or one of its variants)
1.3569 +** and the second argument is the index of the column for which information
1.3570 +** should be returned. The leftmost column of the result set has the index 0.
1.3571 +**
1.3572 +** If the SQL statement does not currently point to a valid row, or if the
1.3573 +** column index is out of range, the result is undefined.
1.3574 +** These routines may only be called when the most recent call to
1.3575 +** [sqlite3_step()] has returned [SQLITE_ROW] and neither
1.3576 +** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently.
1.3577 +** If any of these routines are called after [sqlite3_reset()] or
1.3578 +** [sqlite3_finalize()] or after [sqlite3_step()] has returned
1.3579 +** something other than [SQLITE_ROW], the results are undefined.
1.3580 +** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
1.3581 +** are called from a different thread while any of these routines
1.3582 +** are pending, then the results are undefined.
1.3583 +**
1.3584 +** The sqlite3_column_type() routine returns the
1.3585 +** [SQLITE_INTEGER | datatype code] for the initial data type
1.3586 +** of the result column. The returned value is one of [SQLITE_INTEGER],
1.3587 +** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value
1.3588 +** returned by sqlite3_column_type() is only meaningful if no type
1.3589 +** conversions have occurred as described below. After a type conversion,
1.3590 +** the value returned by sqlite3_column_type() is undefined. Future
1.3591 +** versions of SQLite may change the behavior of sqlite3_column_type()
1.3592 +** following a type conversion.
1.3593 +**
1.3594 +** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
1.3595 +** routine returns the number of bytes in that BLOB or string.
1.3596 +** If the result is a UTF-16 string, then sqlite3_column_bytes() converts
1.3597 +** the string to UTF-8 and then returns the number of bytes.
1.3598 +** If the result is a numeric value then sqlite3_column_bytes() uses
1.3599 +** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
1.3600 +** the number of bytes in that string.
1.3601 +** The value returned does not include the zero terminator at the end
1.3602 +** of the string. For clarity: the value returned is the number of
1.3603 +** bytes in the string, not the number of characters.
1.3604 +**
1.3605 +** Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
1.3606 +** even empty strings, are always zero terminated. The return
1.3607 +** value from sqlite3_column_blob() for a zero-length BLOB is an arbitrary
1.3608 +** pointer, possibly even a NULL pointer.
1.3609 +**
1.3610 +** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
1.3611 +** but leaves the result in UTF-16 in native byte order instead of UTF-8.
1.3612 +** The zero terminator is not included in this count.
1.3613 +**
1.3614 +** The object returned by [sqlite3_column_value()] is an
1.3615 +** [unprotected sqlite3_value] object. An unprotected sqlite3_value object
1.3616 +** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].
1.3617 +** If the [unprotected sqlite3_value] object returned by
1.3618 +** [sqlite3_column_value()] is used in any other way, including calls
1.3619 +** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
1.3620 +** or [sqlite3_value_bytes()], then the behavior is undefined.
1.3621 +**
1.3622 +** These routines attempt to convert the value where appropriate. For
1.3623 +** example, if the internal representation is FLOAT and a text result
1.3624 +** is requested, [sqlite3_snprintf()] is used internally to perform the
1.3625 +** conversion automatically. The following table details the conversions
1.3626 +** that are applied:
1.3627 +**
1.3628 +** <blockquote>
1.3629 +** <table border="1">
1.3630 +** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion
1.3631 +**
1.3632 +** <tr><td> NULL <td> INTEGER <td> Result is 0
1.3633 +** <tr><td> NULL <td> FLOAT <td> Result is 0.0
1.3634 +** <tr><td> NULL <td> TEXT <td> Result is NULL pointer
1.3635 +** <tr><td> NULL <td> BLOB <td> Result is NULL pointer
1.3636 +** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float
1.3637 +** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer
1.3638 +** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT
1.3639 +** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer
1.3640 +** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float
1.3641 +** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT
1.3642 +** <tr><td> TEXT <td> INTEGER <td> Use atoi()
1.3643 +** <tr><td> TEXT <td> FLOAT <td> Use atof()
1.3644 +** <tr><td> TEXT <td> BLOB <td> No change
1.3645 +** <tr><td> BLOB <td> INTEGER <td> Convert to TEXT then use atoi()
1.3646 +** <tr><td> BLOB <td> FLOAT <td> Convert to TEXT then use atof()
1.3647 +** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed
1.3648 +** </table>
1.3649 +** </blockquote>
1.3650 +**
1.3651 +** The table above makes reference to standard C library functions atoi()
1.3652 +** and atof(). SQLite does not really use these functions. It has its
1.3653 +** own equivalent internal routines. The atoi() and atof() names are
1.3654 +** used in the table for brevity and because they are familiar to most
1.3655 +** C programmers.
1.3656 +**
1.3657 +** Note that when type conversions occur, pointers returned by prior
1.3658 +** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
1.3659 +** sqlite3_column_text16() may be invalidated.
1.3660 +** Type conversions and pointer invalidations might occur
1.3661 +** in the following cases:
1.3662 +**
1.3663 +** <ul>
1.3664 +** <li> The initial content is a BLOB and sqlite3_column_text() or
1.3665 +** sqlite3_column_text16() is called. A zero-terminator might
1.3666 +** need to be added to the string.</li>
1.3667 +** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
1.3668 +** sqlite3_column_text16() is called. The content must be converted
1.3669 +** to UTF-16.</li>
1.3670 +** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
1.3671 +** sqlite3_column_text() is called. The content must be converted
1.3672 +** to UTF-8.</li>
1.3673 +** </ul>
1.3674 +**
1.3675 +** Conversions between UTF-16be and UTF-16le are always done in place and do
1.3676 +** not invalidate a prior pointer, though of course the content of the buffer
1.3677 +** that the prior pointer points to will have been modified. Other kinds
1.3678 +** of conversion are done in place when it is possible, but sometimes they
1.3679 +** are not possible and in those cases prior pointers are invalidated.
1.3680 +**
1.3681 +** The safest and easiest to remember policy is to invoke these routines
1.3682 +** in one of the following ways:
1.3683 +**
1.3684 +** <ul>
1.3685 +** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
1.3686 +** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
1.3687 +** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
1.3688 +** </ul>
1.3689 +**
1.3690 +** In other words, you should call sqlite3_column_text(),
1.3691 +** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
1.3692 +** into the desired format, then invoke sqlite3_column_bytes() or
1.3693 +** sqlite3_column_bytes16() to find the size of the result. Do not mix calls
1.3694 +** to sqlite3_column_text() or sqlite3_column_blob() with calls to
1.3695 +** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
1.3696 +** with calls to sqlite3_column_bytes().
1.3697 +**
1.3698 +** The pointers returned are valid until a type conversion occurs as
1.3699 +** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
1.3700 +** [sqlite3_finalize()] is called. The memory space used to hold strings
1.3701 +** and BLOBs is freed automatically. Do <b>not</b> pass the pointers returned
1.3702 +** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
1.3703 +** [sqlite3_free()].
1.3704 +**
1.3705 +** If a memory allocation error occurs during the evaluation of any
1.3706 +** of these routines, a default value is returned. The default value
1.3707 +** is either the integer 0, the floating point number 0.0, or a NULL
1.3708 +** pointer. Subsequent calls to [sqlite3_errcode()] will return
1.3709 +** [SQLITE_NOMEM].
1.3710 +**
1.3711 +** INVARIANTS:
1.3712 +**
1.3713 +** {H13803} The [sqlite3_column_blob(S,N)] interface converts the
1.3714 +** Nth column in the current row of the result set for
1.3715 +** the [prepared statement] S into a BLOB and then returns a
1.3716 +** pointer to the converted value.
1.3717 +**
1.3718 +** {H13806} The [sqlite3_column_bytes(S,N)] interface returns the
1.3719 +** number of bytes in the BLOB or string (exclusive of the
1.3720 +** zero terminator on the string) that was returned by the
1.3721 +** most recent call to [sqlite3_column_blob(S,N)] or
1.3722 +** [sqlite3_column_text(S,N)].
1.3723 +**
1.3724 +** {H13809} The [sqlite3_column_bytes16(S,N)] interface returns the
1.3725 +** number of bytes in the string (exclusive of the
1.3726 +** zero terminator on the string) that was returned by the
1.3727 +** most recent call to [sqlite3_column_text16(S,N)].
1.3728 +**
1.3729 +** {H13812} The [sqlite3_column_double(S,N)] interface converts the
1.3730 +** Nth column in the current row of the result set for the
1.3731 +** [prepared statement] S into a floating point value and
1.3732 +** returns a copy of that value.
1.3733 +**
1.3734 +** {H13815} The [sqlite3_column_int(S,N)] interface converts the
1.3735 +** Nth column in the current row of the result set for the
1.3736 +** [prepared statement] S into a 64-bit signed integer and
1.3737 +** returns the lower 32 bits of that integer.
1.3738 +**
1.3739 +** {H13818} The [sqlite3_column_int64(S,N)] interface converts the
1.3740 +** Nth column in the current row of the result set for the
1.3741 +** [prepared statement] S into a 64-bit signed integer and
1.3742 +** returns a copy of that integer.
1.3743 +**
1.3744 +** {H13821} The [sqlite3_column_text(S,N)] interface converts the
1.3745 +** Nth column in the current row of the result set for
1.3746 +** the [prepared statement] S into a zero-terminated UTF-8
1.3747 +** string and returns a pointer to that string.
1.3748 +**
1.3749 +** {H13824} The [sqlite3_column_text16(S,N)] interface converts the
1.3750 +** Nth column in the current row of the result set for the
1.3751 +** [prepared statement] S into a zero-terminated 2-byte
1.3752 +** aligned UTF-16 native byte order string and returns
1.3753 +** a pointer to that string.
1.3754 +**
1.3755 +** {H13827} The [sqlite3_column_type(S,N)] interface returns
1.3756 +** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT],
1.3757 +** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for
1.3758 +** the Nth column in the current row of the result set for
1.3759 +** the [prepared statement] S.
1.3760 +**
1.3761 +** {H13830} The [sqlite3_column_value(S,N)] interface returns a
1.3762 +** pointer to an [unprotected sqlite3_value] object for the
1.3763 +** Nth column in the current row of the result set for
1.3764 +** the [prepared statement] S.
1.3765 +*/
1.3766 +IMPORT_C const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
1.3767 +IMPORT_C int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
1.3768 +IMPORT_C int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
1.3769 +IMPORT_C double sqlite3_column_double(sqlite3_stmt*, int iCol);
1.3770 +IMPORT_C int sqlite3_column_int(sqlite3_stmt*, int iCol);
1.3771 +IMPORT_C sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
1.3772 +IMPORT_C const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
1.3773 +IMPORT_C const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
1.3774 +IMPORT_C int sqlite3_column_type(sqlite3_stmt*, int iCol);
1.3775 +IMPORT_C sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
1.3776 +
1.3777 +/*
1.3778 +** CAPI3REF: Destroy A Prepared Statement Object {H13300} <S70300><S30100>
1.3779 +**
1.3780 +** The sqlite3_finalize() function is called to delete a [prepared statement].
1.3781 +** If the statement was executed successfully or not executed at all, then
1.3782 +** SQLITE_OK is returned. If execution of the statement failed then an
1.3783 +** [error code] or [extended error code] is returned.
1.3784 +**
1.3785 +** This routine can be called at any point during the execution of the
1.3786 +** [prepared statement]. If the virtual machine has not
1.3787 +** completed execution when this routine is called, that is like
1.3788 +** encountering an error or an [sqlite3_interrupt | interrupt].
1.3789 +** Incomplete updates may be rolled back and transactions canceled,
1.3790 +** depending on the circumstances, and the
1.3791 +** [error code] returned will be [SQLITE_ABORT].
1.3792 +**
1.3793 +** INVARIANTS:
1.3794 +**
1.3795 +** {H11302} The [sqlite3_finalize(S)] interface destroys the
1.3796 +** [prepared statement] S and releases all
1.3797 +** memory and file resources held by that object.
1.3798 +**
1.3799 +** {H11304} If the most recent call to [sqlite3_step(S)] for the
1.3800 +** [prepared statement] S returned an error,
1.3801 +** then [sqlite3_finalize(S)] returns that same error.
1.3802 +*/
1.3803 +IMPORT_C int sqlite3_finalize(sqlite3_stmt *pStmt);
1.3804 +
1.3805 +/*
1.3806 +** CAPI3REF: Reset A Prepared Statement Object {H13330} <S70300>
1.3807 +**
1.3808 +** The sqlite3_reset() function is called to reset a [prepared statement]
1.3809 +** object back to its initial state, ready to be re-executed.
1.3810 +** Any SQL statement variables that had values bound to them using
1.3811 +** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
1.3812 +** Use [sqlite3_clear_bindings()] to reset the bindings.
1.3813 +**
1.3814 +** {H11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S
1.3815 +** back to the beginning of its program.
1.3816 +**
1.3817 +** {H11334} If the most recent call to [sqlite3_step(S)] for the
1.3818 +** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
1.3819 +** or if [sqlite3_step(S)] has never before been called on S,
1.3820 +** then [sqlite3_reset(S)] returns [SQLITE_OK].
1.3821 +**
1.3822 +** {H11336} If the most recent call to [sqlite3_step(S)] for the
1.3823 +** [prepared statement] S indicated an error, then
1.3824 +** [sqlite3_reset(S)] returns an appropriate [error code].
1.3825 +**
1.3826 +** {H11338} The [sqlite3_reset(S)] interface does not change the values
1.3827 +** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
1.3828 +*/
1.3829 +IMPORT_C int sqlite3_reset(sqlite3_stmt *pStmt);
1.3830 +
1.3831 +/*
1.3832 +** CAPI3REF: Create Or Redefine SQL Functions {H16100} <S20200>
1.3833 +** KEYWORDS: {function creation routines}
1.3834 +** KEYWORDS: {application-defined SQL function}
1.3835 +** KEYWORDS: {application-defined SQL functions}
1.3836 +**
1.3837 +** These two functions (collectively known as "function creation routines")
1.3838 +** are used to add SQL functions or aggregates or to redefine the behavior
1.3839 +** of existing SQL functions or aggregates. The only difference between the
1.3840 +** two is that the second parameter, the name of the (scalar) function or
1.3841 +** aggregate, is encoded in UTF-8 for sqlite3_create_function() and UTF-16
1.3842 +** for sqlite3_create_function16().
1.3843 +**
1.3844 +** The first parameter is the [database connection] to which the SQL
1.3845 +** function is to be added. If a single program uses more than one database
1.3846 +** connection internally, then SQL functions must be added individually to
1.3847 +** each database connection.
1.3848 +**
1.3849 +** The second parameter is the name of the SQL function to be created or
1.3850 +** redefined. The length of the name is limited to 255 bytes, exclusive of
1.3851 +** the zero-terminator. Note that the name length limit is in bytes, not
1.3852 +** characters. Any attempt to create a function with a longer name
1.3853 +** will result in [SQLITE_ERROR] being returned.
1.3854 +**
1.3855 +** The third parameter (nArg)
1.3856 +** is the number of arguments that the SQL function or
1.3857 +** aggregate takes. If this parameter is negative, then the SQL function or
1.3858 +** aggregate may take any number of arguments.
1.3859 +**
1.3860 +** The fourth parameter, eTextRep, specifies what
1.3861 +** [SQLITE_UTF8 | text encoding] this SQL function prefers for
1.3862 +** its parameters. Any SQL function implementation should be able to work
1.3863 +** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be
1.3864 +** more efficient with one encoding than another. It is allowed to
1.3865 +** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
1.3866 +** times with the same function but with different values of eTextRep.
1.3867 +** When multiple implementations of the same function are available, SQLite
1.3868 +** will pick the one that involves the least amount of data conversion.
1.3869 +** If there is only a single implementation which does not care what text
1.3870 +** encoding is used, then the fourth argument should be [SQLITE_ANY].
1.3871 +**
1.3872 +** The fifth parameter is an arbitrary pointer. The implementation of the
1.3873 +** function can gain access to this pointer using [sqlite3_user_data()].
1.3874 +**
1.3875 +** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are
1.3876 +** pointers to C-language functions that implement the SQL function or
1.3877 +** aggregate. A scalar SQL function requires an implementation of the xFunc
1.3878 +** callback only, NULL pointers should be passed as the xStep and xFinal
1.3879 +** parameters. An aggregate SQL function requires an implementation of xStep
1.3880 +** and xFinal and NULL should be passed for xFunc. To delete an existing
1.3881 +** SQL function or aggregate, pass NULL for all three function callbacks.
1.3882 +**
1.3883 +** It is permitted to register multiple implementations of the same
1.3884 +** functions with the same name but with either differing numbers of
1.3885 +** arguments or differing preferred text encodings. SQLite will use
1.3886 +** the implementation most closely matches the way in which the
1.3887 +** SQL function is used. A function implementation with a non-negative
1.3888 +** nArg parameter is a better match than a function implementation with
1.3889 +** a negative nArg. A function where the preferred text encoding
1.3890 +** matches the database encoding is a better
1.3891 +** match than a function where the encoding is different.
1.3892 +** A function where the encoding difference is between UTF16le and UTF16be
1.3893 +** is a closer match than a function where the encoding difference is
1.3894 +** between UTF8 and UTF16.
1.3895 +**
1.3896 +** Built-in functions may be overloaded by new application-defined functions.
1.3897 +** The first application-defined function with a given name overrides all
1.3898 +** built-in functions in the same [database connection] with the same name.
1.3899 +** Subsequent application-defined functions of the same name only override
1.3900 +** prior application-defined functions that are an exact match for the
1.3901 +** number of parameters and preferred encoding.
1.3902 +**
1.3903 +** An application-defined function is permitted to call other
1.3904 +** SQLite interfaces. However, such calls must not
1.3905 +** close the database connection nor finalize or reset the prepared
1.3906 +** statement in which the function is running.
1.3907 +**
1.3908 +** INVARIANTS:
1.3909 +**
1.3910 +** {H16103} The [sqlite3_create_function16(D,X,...)] interface shall behave
1.3911 +** as [sqlite3_create_function(D,X,...)] in every way except that it
1.3912 +** interprets the X argument as zero-terminated UTF-16
1.3913 +** native byte order instead of as zero-terminated UTF-8.
1.3914 +**
1.3915 +** {H16106} A successful invocation of the
1.3916 +** [sqlite3_create_function(D,X,N,E,...)] interface shall register
1.3917 +** or replaces callback functions in the [database connection] D
1.3918 +** used to implement the SQL function named X with N parameters
1.3919 +** and having a preferred text encoding of E.
1.3920 +**
1.3921 +** {H16109} A successful call to [sqlite3_create_function(D,X,N,E,P,F,S,L)]
1.3922 +** shall replace the P, F, S, and L values from any prior calls with
1.3923 +** the same D, X, N, and E values.
1.3924 +**
1.3925 +** {H16112} The [sqlite3_create_function(D,X,...)] interface shall fail
1.3926 +** if the SQL function name X is
1.3927 +** longer than 255 bytes exclusive of the zero terminator.
1.3928 +**
1.3929 +** {H16118} The [sqlite3_create_function(D,X,N,E,P,F,S,L)] interface
1.3930 +** shall fail unless either F is NULL and S and L are non-NULL or
1.3931 +*** F is non-NULL and S and L are NULL.
1.3932 +**
1.3933 +** {H16121} The [sqlite3_create_function(D,...)] interface shall fails with an
1.3934 +** error code of [SQLITE_BUSY] if there exist [prepared statements]
1.3935 +** associated with the [database connection] D.
1.3936 +**
1.3937 +** {H16124} The [sqlite3_create_function(D,X,N,...)] interface shall fail with
1.3938 +** an error code of [SQLITE_ERROR] if parameter N is less
1.3939 +** than -1 or greater than 127.
1.3940 +**
1.3941 +** {H16127} When N is non-negative, the [sqlite3_create_function(D,X,N,...)]
1.3942 +** interface shall register callbacks to be invoked for the
1.3943 +** SQL function
1.3944 +** named X when the number of arguments to the SQL function is
1.3945 +** exactly N.
1.3946 +**
1.3947 +** {H16130} When N is -1, the [sqlite3_create_function(D,X,N,...)]
1.3948 +** interface shall register callbacks to be invoked for the SQL
1.3949 +** function named X with any number of arguments.
1.3950 +**
1.3951 +** {H16133} When calls to [sqlite3_create_function(D,X,N,...)]
1.3952 +** specify multiple implementations of the same function X
1.3953 +** and when one implementation has N>=0 and the other has N=(-1)
1.3954 +** the implementation with a non-zero N shall be preferred.
1.3955 +**
1.3956 +** {H16136} When calls to [sqlite3_create_function(D,X,N,E,...)]
1.3957 +** specify multiple implementations of the same function X with
1.3958 +** the same number of arguments N but with different
1.3959 +** encodings E, then the implementation where E matches the
1.3960 +** database encoding shall preferred.
1.3961 +**
1.3962 +** {H16139} For an aggregate SQL function created using
1.3963 +** [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finalizer
1.3964 +** function L shall always be invoked exactly once if the
1.3965 +** step function S is called one or more times.
1.3966 +**
1.3967 +** {H16142} When SQLite invokes either the xFunc or xStep function of
1.3968 +** an application-defined SQL function or aggregate created
1.3969 +** by [sqlite3_create_function()] or [sqlite3_create_function16()],
1.3970 +** then the array of [sqlite3_value] objects passed as the
1.3971 +** third parameter shall be [protected sqlite3_value] objects.
1.3972 +*/
1.3973 +IMPORT_C int sqlite3_create_function(
1.3974 + sqlite3 *db,
1.3975 + const char *zFunctionName,
1.3976 + int nArg,
1.3977 + int eTextRep,
1.3978 + void *pApp,
1.3979 + void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
1.3980 + void (*xStep)(sqlite3_context*,int,sqlite3_value**),
1.3981 + void (*xFinal)(sqlite3_context*)
1.3982 +);
1.3983 +IMPORT_C int sqlite3_create_function16(
1.3984 + sqlite3 *db,
1.3985 + const void *zFunctionName,
1.3986 + int nArg,
1.3987 + int eTextRep,
1.3988 + void *pApp,
1.3989 + void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
1.3990 + void (*xStep)(sqlite3_context*,int,sqlite3_value**),
1.3991 + void (*xFinal)(sqlite3_context*)
1.3992 +);
1.3993 +
1.3994 +/*
1.3995 +** CAPI3REF: Text Encodings {H10267} <S50200> <H16100>
1.3996 +**
1.3997 +** These constant define integer codes that represent the various
1.3998 +** text encodings supported by SQLite.
1.3999 +*/
1.4000 +#define SQLITE_UTF8 1
1.4001 +#define SQLITE_UTF16LE 2
1.4002 +#define SQLITE_UTF16BE 3
1.4003 +#define SQLITE_UTF16 4 /* Use native byte order */
1.4004 +#define SQLITE_ANY 5 /* sqlite3_create_function only */
1.4005 +#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
1.4006 +
1.4007 +/*
1.4008 +** CAPI3REF: Deprecated Functions
1.4009 +** DEPRECATED
1.4010 +**
1.4011 +** These functions are [deprecated]. In order to maintain
1.4012 +** backwards compatibility with older code, these functions continue
1.4013 +** to be supported. However, new applications should avoid
1.4014 +** the use of these functions. To help encourage people to avoid
1.4015 +** using these functions, we are not going to tell you want they do.
1.4016 +*/
1.4017 +IMPORT_C int sqlite3_aggregate_count(sqlite3_context*);
1.4018 +IMPORT_C int sqlite3_expired(sqlite3_stmt*);
1.4019 +IMPORT_C int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
1.4020 +IMPORT_C int sqlite3_global_recover(void);
1.4021 +IMPORT_C void sqlite3_thread_cleanup(void);
1.4022 +IMPORT_C int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64);
1.4023 +
1.4024 +/*
1.4025 +** CAPI3REF: Obtaining SQL Function Parameter Values {H15100} <S20200>
1.4026 +**
1.4027 +** The C-language implementation of SQL functions and aggregates uses
1.4028 +** this set of interface routines to access the parameter values on
1.4029 +** the function or aggregate.
1.4030 +**
1.4031 +** The xFunc (for scalar functions) or xStep (for aggregates) parameters
1.4032 +** to [sqlite3_create_function()] and [sqlite3_create_function16()]
1.4033 +** define callbacks that implement the SQL functions and aggregates.
1.4034 +** The 4th parameter to these callbacks is an array of pointers to
1.4035 +** [protected sqlite3_value] objects. There is one [sqlite3_value] object for
1.4036 +** each parameter to the SQL function. These routines are used to
1.4037 +** extract values from the [sqlite3_value] objects.
1.4038 +**
1.4039 +** These routines work only with [protected sqlite3_value] objects.
1.4040 +** Any attempt to use these routines on an [unprotected sqlite3_value]
1.4041 +** object results in undefined behavior.
1.4042 +**
1.4043 +** These routines work just like the corresponding [column access functions]
1.4044 +** except that these routines take a single [protected sqlite3_value] object
1.4045 +** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
1.4046 +**
1.4047 +** The sqlite3_value_text16() interface extracts a UTF-16 string
1.4048 +** in the native byte-order of the host machine. The
1.4049 +** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
1.4050 +** extract UTF-16 strings as big-endian and little-endian respectively.
1.4051 +**
1.4052 +** The sqlite3_value_numeric_type() interface attempts to apply
1.4053 +** numeric affinity to the value. This means that an attempt is
1.4054 +** made to convert the value to an integer or floating point. If
1.4055 +** such a conversion is possible without loss of information (in other
1.4056 +** words, if the value is a string that looks like a number)
1.4057 +** then the conversion is performed. Otherwise no conversion occurs.
1.4058 +** The [SQLITE_INTEGER | datatype] after conversion is returned.
1.4059 +**
1.4060 +** Please pay particular attention to the fact that the pointer returned
1.4061 +** from [sqlite3_value_blob()], [sqlite3_value_text()], or
1.4062 +** [sqlite3_value_text16()] can be invalidated by a subsequent call to
1.4063 +** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
1.4064 +** or [sqlite3_value_text16()].
1.4065 +**
1.4066 +** These routines must be called from the same thread as
1.4067 +** the SQL function that supplied the [sqlite3_value*] parameters.
1.4068 +**
1.4069 +** INVARIANTS:
1.4070 +**
1.4071 +** {H15103} The [sqlite3_value_blob(V)] interface converts the
1.4072 +** [protected sqlite3_value] object V into a BLOB and then
1.4073 +** returns a pointer to the converted value.
1.4074 +**
1.4075 +** {H15106} The [sqlite3_value_bytes(V)] interface returns the
1.4076 +** number of bytes in the BLOB or string (exclusive of the
1.4077 +** zero terminator on the string) that was returned by the
1.4078 +** most recent call to [sqlite3_value_blob(V)] or
1.4079 +** [sqlite3_value_text(V)].
1.4080 +**
1.4081 +** {H15109} The [sqlite3_value_bytes16(V)] interface returns the
1.4082 +** number of bytes in the string (exclusive of the
1.4083 +** zero terminator on the string) that was returned by the
1.4084 +** most recent call to [sqlite3_value_text16(V)],
1.4085 +** [sqlite3_value_text16be(V)], or [sqlite3_value_text16le(V)].
1.4086 +**
1.4087 +** {H15112} The [sqlite3_value_double(V)] interface converts the
1.4088 +** [protected sqlite3_value] object V into a floating point value and
1.4089 +** returns a copy of that value.
1.4090 +**
1.4091 +** {H15115} The [sqlite3_value_int(V)] interface converts the
1.4092 +** [protected sqlite3_value] object V into a 64-bit signed integer and
1.4093 +** returns the lower 32 bits of that integer.
1.4094 +**
1.4095 +** {H15118} The [sqlite3_value_int64(V)] interface converts the
1.4096 +** [protected sqlite3_value] object V into a 64-bit signed integer and
1.4097 +** returns a copy of that integer.
1.4098 +**
1.4099 +** {H15121} The [sqlite3_value_text(V)] interface converts the
1.4100 +** [protected sqlite3_value] object V into a zero-terminated UTF-8
1.4101 +** string and returns a pointer to that string.
1.4102 +**
1.4103 +** {H15124} The [sqlite3_value_text16(V)] interface converts the
1.4104 +** [protected sqlite3_value] object V into a zero-terminated 2-byte
1.4105 +** aligned UTF-16 native byte order
1.4106 +** string and returns a pointer to that string.
1.4107 +**
1.4108 +** {H15127} The [sqlite3_value_text16be(V)] interface converts the
1.4109 +** [protected sqlite3_value] object V into a zero-terminated 2-byte
1.4110 +** aligned UTF-16 big-endian
1.4111 +** string and returns a pointer to that string.
1.4112 +**
1.4113 +** {H15130} The [sqlite3_value_text16le(V)] interface converts the
1.4114 +** [protected sqlite3_value] object V into a zero-terminated 2-byte
1.4115 +** aligned UTF-16 little-endian
1.4116 +** string and returns a pointer to that string.
1.4117 +**
1.4118 +** {H15133} The [sqlite3_value_type(V)] interface returns
1.4119 +** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT],
1.4120 +** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for
1.4121 +** the [sqlite3_value] object V.
1.4122 +**
1.4123 +** {H15136} The [sqlite3_value_numeric_type(V)] interface converts
1.4124 +** the [protected sqlite3_value] object V into either an integer or
1.4125 +** a floating point value if it can do so without loss of
1.4126 +** information, and returns one of [SQLITE_NULL],
1.4127 +** [SQLITE_INTEGER], [SQLITE_FLOAT], [SQLITE_TEXT], or
1.4128 +** [SQLITE_BLOB] as appropriate for the
1.4129 +** [protected sqlite3_value] object V after the conversion attempt.
1.4130 +*/
1.4131 +IMPORT_C const void *sqlite3_value_blob(sqlite3_value*);
1.4132 +IMPORT_C int sqlite3_value_bytes(sqlite3_value*);
1.4133 +IMPORT_C int sqlite3_value_bytes16(sqlite3_value*);
1.4134 +IMPORT_C double sqlite3_value_double(sqlite3_value*);
1.4135 +IMPORT_C int sqlite3_value_int(sqlite3_value*);
1.4136 +IMPORT_C sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
1.4137 +IMPORT_C const unsigned char *sqlite3_value_text(sqlite3_value*);
1.4138 +IMPORT_C const void *sqlite3_value_text16(sqlite3_value*);
1.4139 +IMPORT_C const void *sqlite3_value_text16le(sqlite3_value*);
1.4140 +IMPORT_C const void *sqlite3_value_text16be(sqlite3_value*);
1.4141 +IMPORT_C int sqlite3_value_type(sqlite3_value*);
1.4142 +IMPORT_C int sqlite3_value_numeric_type(sqlite3_value*);
1.4143 +
1.4144 +/*
1.4145 +** CAPI3REF: Obtain Aggregate Function Context {H16210} <S20200>
1.4146 +**
1.4147 +** The implementation of aggregate SQL functions use this routine to allocate
1.4148 +** a structure for storing their state.
1.4149 +**
1.4150 +** The first time the sqlite3_aggregate_context() routine is called for a
1.4151 +** particular aggregate, SQLite allocates nBytes of memory, zeroes out that
1.4152 +** memory, and returns a pointer to it. On second and subsequent calls to
1.4153 +** sqlite3_aggregate_context() for the same aggregate function index,
1.4154 +** the same buffer is returned. The implementation of the aggregate can use
1.4155 +** the returned buffer to accumulate data.
1.4156 +**
1.4157 +** SQLite automatically frees the allocated buffer when the aggregate
1.4158 +** query concludes.
1.4159 +**
1.4160 +** The first parameter should be a copy of the
1.4161 +** [sqlite3_context | SQL function context] that is the first parameter
1.4162 +** to the callback routine that implements the aggregate function.
1.4163 +**
1.4164 +** This routine must be called from the same thread in which
1.4165 +** the aggregate SQL function is running.
1.4166 +**
1.4167 +** INVARIANTS:
1.4168 +**
1.4169 +** {H16211} The first invocation of [sqlite3_aggregate_context(C,N)] for
1.4170 +** a particular instance of an aggregate function (for a particular
1.4171 +** context C) causes SQLite to allocate N bytes of memory,
1.4172 +** zero that memory, and return a pointer to the allocated memory.
1.4173 +**
1.4174 +** {H16213} If a memory allocation error occurs during
1.4175 +** [sqlite3_aggregate_context(C,N)] then the function returns 0.
1.4176 +**
1.4177 +** {H16215} Second and subsequent invocations of
1.4178 +** [sqlite3_aggregate_context(C,N)] for the same context pointer C
1.4179 +** ignore the N parameter and return a pointer to the same
1.4180 +** block of memory returned by the first invocation.
1.4181 +**
1.4182 +** {H16217} The memory allocated by [sqlite3_aggregate_context(C,N)] is
1.4183 +** automatically freed on the next call to [sqlite3_reset()]
1.4184 +** or [sqlite3_finalize()] for the [prepared statement] containing
1.4185 +** the aggregate function associated with context C.
1.4186 +*/
1.4187 +IMPORT_C void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
1.4188 +
1.4189 +/*
1.4190 +** CAPI3REF: User Data For Functions {H16240} <S20200>
1.4191 +**
1.4192 +** The sqlite3_user_data() interface returns a copy of
1.4193 +** the pointer that was the pUserData parameter (the 5th parameter)
1.4194 +** of the [sqlite3_create_function()]
1.4195 +** and [sqlite3_create_function16()] routines that originally
1.4196 +** registered the application defined function. {END}
1.4197 +**
1.4198 +** This routine must be called from the same thread in which
1.4199 +** the application-defined function is running.
1.4200 +**
1.4201 +** INVARIANTS:
1.4202 +**
1.4203 +** {H16243} The [sqlite3_user_data(C)] interface returns a copy of the
1.4204 +** P pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)]
1.4205 +** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that
1.4206 +** registered the SQL function associated with [sqlite3_context] C.
1.4207 +*/
1.4208 +IMPORT_C void *sqlite3_user_data(sqlite3_context*);
1.4209 +
1.4210 +/*
1.4211 +** CAPI3REF: Database Connection For Functions {H16250} <S60600><S20200>
1.4212 +**
1.4213 +** The sqlite3_context_db_handle() interface returns a copy of
1.4214 +** the pointer to the [database connection] (the 1st parameter)
1.4215 +** of the [sqlite3_create_function()]
1.4216 +** and [sqlite3_create_function16()] routines that originally
1.4217 +** registered the application defined function.
1.4218 +**
1.4219 +** INVARIANTS:
1.4220 +**
1.4221 +** {H16253} The [sqlite3_context_db_handle(C)] interface returns a copy of the
1.4222 +** D pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)]
1.4223 +** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that
1.4224 +** registered the SQL function associated with [sqlite3_context] C.
1.4225 +*/
1.4226 +IMPORT_C sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
1.4227 +
1.4228 +/*
1.4229 +** CAPI3REF: Function Auxiliary Data {H16270} <S20200>
1.4230 +**
1.4231 +** The following two functions may be used by scalar SQL functions to
1.4232 +** associate metadata with argument values. If the same value is passed to
1.4233 +** multiple invocations of the same SQL function during query execution, under
1.4234 +** some circumstances the associated metadata may be preserved. This may
1.4235 +** be used, for example, to add a regular-expression matching scalar
1.4236 +** function. The compiled version of the regular expression is stored as
1.4237 +** metadata associated with the SQL value passed as the regular expression
1.4238 +** pattern. The compiled regular expression can be reused on multiple
1.4239 +** invocations of the same function so that the original pattern string
1.4240 +** does not need to be recompiled on each invocation.
1.4241 +**
1.4242 +** The sqlite3_get_auxdata() interface returns a pointer to the metadata
1.4243 +** associated by the sqlite3_set_auxdata() function with the Nth argument
1.4244 +** value to the application-defined function. If no metadata has been ever
1.4245 +** been set for the Nth argument of the function, or if the corresponding
1.4246 +** function parameter has changed since the meta-data was set,
1.4247 +** then sqlite3_get_auxdata() returns a NULL pointer.
1.4248 +**
1.4249 +** The sqlite3_set_auxdata() interface saves the metadata
1.4250 +** pointed to by its 3rd parameter as the metadata for the N-th
1.4251 +** argument of the application-defined function. Subsequent
1.4252 +** calls to sqlite3_get_auxdata() might return this data, if it has
1.4253 +** not been destroyed.
1.4254 +** If it is not NULL, SQLite will invoke the destructor
1.4255 +** function given by the 4th parameter to sqlite3_set_auxdata() on
1.4256 +** the metadata when the corresponding function parameter changes
1.4257 +** or when the SQL statement completes, whichever comes first.
1.4258 +**
1.4259 +** SQLite is free to call the destructor and drop metadata on any
1.4260 +** parameter of any function at any time. The only guarantee is that
1.4261 +** the destructor will be called before the metadata is dropped.
1.4262 +**
1.4263 +** In practice, metadata is preserved between function calls for
1.4264 +** expressions that are constant at compile time. This includes literal
1.4265 +** values and SQL variables.
1.4266 +**
1.4267 +** These routines must be called from the same thread in which
1.4268 +** the SQL function is running.
1.4269 +**
1.4270 +** INVARIANTS:
1.4271 +**
1.4272 +** {H16272} The [sqlite3_get_auxdata(C,N)] interface returns a pointer
1.4273 +** to metadata associated with the Nth parameter of the SQL function
1.4274 +** whose context is C, or NULL if there is no metadata associated
1.4275 +** with that parameter.
1.4276 +**
1.4277 +** {H16274} The [sqlite3_set_auxdata(C,N,P,D)] interface assigns a metadata
1.4278 +** pointer P to the Nth parameter of the SQL function with context C.
1.4279 +**
1.4280 +** {H16276} SQLite will invoke the destructor D with a single argument
1.4281 +** which is the metadata pointer P following a call to
1.4282 +** [sqlite3_set_auxdata(C,N,P,D)] when SQLite ceases to hold
1.4283 +** the metadata.
1.4284 +**
1.4285 +** {H16277} SQLite ceases to hold metadata for an SQL function parameter
1.4286 +** when the value of that parameter changes.
1.4287 +**
1.4288 +** {H16278} When [sqlite3_set_auxdata(C,N,P,D)] is invoked, the destructor
1.4289 +** is called for any prior metadata associated with the same function
1.4290 +** context C and parameter N.
1.4291 +**
1.4292 +** {H16279} SQLite will call destructors for any metadata it is holding
1.4293 +** in a particular [prepared statement] S when either
1.4294 +** [sqlite3_reset(S)] or [sqlite3_finalize(S)] is called.
1.4295 +*/
1.4296 +IMPORT_C void *sqlite3_get_auxdata(sqlite3_context*, int N);
1.4297 +IMPORT_C void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
1.4298 +
1.4299 +
1.4300 +/*
1.4301 +** CAPI3REF: Constants Defining Special Destructor Behavior {H10280} <S30100>
1.4302 +**
1.4303 +** These are special values for the destructor that is passed in as the
1.4304 +** final argument to routines like [sqlite3_result_blob()]. If the destructor
1.4305 +** argument is SQLITE_STATIC, it means that the content pointer is constant
1.4306 +** and will never change. It does not need to be destroyed. The
1.4307 +** SQLITE_TRANSIENT value means that the content will likely change in
1.4308 +** the near future and that SQLite should make its own private copy of
1.4309 +** the content before returning.
1.4310 +**
1.4311 +** The typedef is necessary to work around problems in certain
1.4312 +** C++ compilers. See ticket #2191.
1.4313 +*/
1.4314 +typedef void (*sqlite3_destructor_type)(void*);
1.4315 +#define SQLITE_STATIC ((sqlite3_destructor_type)0)
1.4316 +#define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1)
1.4317 +
1.4318 +/*
1.4319 +** CAPI3REF: Setting The Result Of An SQL Function {H16400} <S20200>
1.4320 +**
1.4321 +** These routines are used by the xFunc or xFinal callbacks that
1.4322 +** implement SQL functions and aggregates. See
1.4323 +** [sqlite3_create_function()] and [sqlite3_create_function16()]
1.4324 +** for additional information.
1.4325 +**
1.4326 +** These functions work very much like the [parameter binding] family of
1.4327 +** functions used to bind values to host parameters in prepared statements.
1.4328 +** Refer to the [SQL parameter] documentation for additional information.
1.4329 +**
1.4330 +** The sqlite3_result_blob() interface sets the result from
1.4331 +** an application-defined function to be the BLOB whose content is pointed
1.4332 +** to by the second parameter and which is N bytes long where N is the
1.4333 +** third parameter.
1.4334 +**
1.4335 +** The sqlite3_result_zeroblob() interfaces set the result of
1.4336 +** the application-defined function to be a BLOB containing all zero
1.4337 +** bytes and N bytes in size, where N is the value of the 2nd parameter.
1.4338 +**
1.4339 +** The sqlite3_result_double() interface sets the result from
1.4340 +** an application-defined function to be a floating point value specified
1.4341 +** by its 2nd argument.
1.4342 +**
1.4343 +** The sqlite3_result_error() and sqlite3_result_error16() functions
1.4344 +** cause the implemented SQL function to throw an exception.
1.4345 +** SQLite uses the string pointed to by the
1.4346 +** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
1.4347 +** as the text of an error message. SQLite interprets the error
1.4348 +** message string from sqlite3_result_error() as UTF-8. SQLite
1.4349 +** interprets the string from sqlite3_result_error16() as UTF-16 in native
1.4350 +** byte order. If the third parameter to sqlite3_result_error()
1.4351 +** or sqlite3_result_error16() is negative then SQLite takes as the error
1.4352 +** message all text up through the first zero character.
1.4353 +** If the third parameter to sqlite3_result_error() or
1.4354 +** sqlite3_result_error16() is non-negative then SQLite takes that many
1.4355 +** bytes (not characters) from the 2nd parameter as the error message.
1.4356 +** The sqlite3_result_error() and sqlite3_result_error16()
1.4357 +** routines make a private copy of the error message text before
1.4358 +** they return. Hence, the calling function can deallocate or
1.4359 +** modify the text after they return without harm.
1.4360 +** The sqlite3_result_error_code() function changes the error code
1.4361 +** returned by SQLite as a result of an error in a function. By default,
1.4362 +** the error code is SQLITE_ERROR. A subsequent call to sqlite3_result_error()
1.4363 +** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.
1.4364 +**
1.4365 +** The sqlite3_result_toobig() interface causes SQLite to throw an error
1.4366 +** indicating that a string or BLOB is to long to represent.
1.4367 +**
1.4368 +** The sqlite3_result_nomem() interface causes SQLite to throw an error
1.4369 +** indicating that a memory allocation failed.
1.4370 +**
1.4371 +** The sqlite3_result_int() interface sets the return value
1.4372 +** of the application-defined function to be the 32-bit signed integer
1.4373 +** value given in the 2nd argument.
1.4374 +** The sqlite3_result_int64() interface sets the return value
1.4375 +** of the application-defined function to be the 64-bit signed integer
1.4376 +** value given in the 2nd argument.
1.4377 +**
1.4378 +** The sqlite3_result_null() interface sets the return value
1.4379 +** of the application-defined function to be NULL.
1.4380 +**
1.4381 +** The sqlite3_result_text(), sqlite3_result_text16(),
1.4382 +** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
1.4383 +** set the return value of the application-defined function to be
1.4384 +** a text string which is represented as UTF-8, UTF-16 native byte order,
1.4385 +** UTF-16 little endian, or UTF-16 big endian, respectively.
1.4386 +** SQLite takes the text result from the application from
1.4387 +** the 2nd parameter of the sqlite3_result_text* interfaces.
1.4388 +** If the 3rd parameter to the sqlite3_result_text* interfaces
1.4389 +** is negative, then SQLite takes result text from the 2nd parameter
1.4390 +** through the first zero character.
1.4391 +** If the 3rd parameter to the sqlite3_result_text* interfaces
1.4392 +** is non-negative, then as many bytes (not characters) of the text
1.4393 +** pointed to by the 2nd parameter are taken as the application-defined
1.4394 +** function result.
1.4395 +** If the 4th parameter to the sqlite3_result_text* interfaces
1.4396 +** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
1.4397 +** function as the destructor on the text or BLOB result when it has
1.4398 +** finished using that result.
1.4399 +** If the 4th parameter to the sqlite3_result_text* interfaces or
1.4400 +** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
1.4401 +** assumes that the text or BLOB result is in constant space and does not
1.4402 +** copy the it or call a destructor when it has finished using that result.
1.4403 +** If the 4th parameter to the sqlite3_result_text* interfaces
1.4404 +** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
1.4405 +** then SQLite makes a copy of the result into space obtained from
1.4406 +** from [sqlite3_malloc()] before it returns.
1.4407 +**
1.4408 +** The sqlite3_result_value() interface sets the result of
1.4409 +** the application-defined function to be a copy the
1.4410 +** [unprotected sqlite3_value] object specified by the 2nd parameter. The
1.4411 +** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
1.4412 +** so that the [sqlite3_value] specified in the parameter may change or
1.4413 +** be deallocated after sqlite3_result_value() returns without harm.
1.4414 +** A [protected sqlite3_value] object may always be used where an
1.4415 +** [unprotected sqlite3_value] object is required, so either
1.4416 +** kind of [sqlite3_value] object can be used with this interface.
1.4417 +**
1.4418 +** If these routines are called from within the different thread
1.4419 +** than the one containing the application-defined function that received
1.4420 +** the [sqlite3_context] pointer, the results are undefined.
1.4421 +**
1.4422 +** INVARIANTS:
1.4423 +**
1.4424 +** {H16403} The default return value from any SQL function is NULL.
1.4425 +**
1.4426 +** {H16406} The [sqlite3_result_blob(C,V,N,D)] interface changes the
1.4427 +** return value of function C to be a BLOB that is N bytes
1.4428 +** in length and with content pointed to by V.
1.4429 +**
1.4430 +** {H16409} The [sqlite3_result_double(C,V)] interface changes the
1.4431 +** return value of function C to be the floating point value V.
1.4432 +**
1.4433 +** {H16412} The [sqlite3_result_error(C,V,N)] interface changes the return
1.4434 +** value of function C to be an exception with error code
1.4435 +** [SQLITE_ERROR] and a UTF-8 error message copied from V up to the
1.4436 +** first zero byte or until N bytes are read if N is positive.
1.4437 +**
1.4438 +** {H16415} The [sqlite3_result_error16(C,V,N)] interface changes the return
1.4439 +** value of function C to be an exception with error code
1.4440 +** [SQLITE_ERROR] and a UTF-16 native byte order error message
1.4441 +** copied from V up to the first zero terminator or until N bytes
1.4442 +** are read if N is positive.
1.4443 +**
1.4444 +** {H16418} The [sqlite3_result_error_toobig(C)] interface changes the return
1.4445 +** value of the function C to be an exception with error code
1.4446 +** [SQLITE_TOOBIG] and an appropriate error message.
1.4447 +**
1.4448 +** {H16421} The [sqlite3_result_error_nomem(C)] interface changes the return
1.4449 +** value of the function C to be an exception with error code
1.4450 +** [SQLITE_NOMEM] and an appropriate error message.
1.4451 +**
1.4452 +** {H16424} The [sqlite3_result_error_code(C,E)] interface changes the return
1.4453 +** value of the function C to be an exception with error code E.
1.4454 +** The error message text is unchanged.
1.4455 +**
1.4456 +** {H16427} The [sqlite3_result_int(C,V)] interface changes the
1.4457 +** return value of function C to be the 32-bit integer value V.
1.4458 +**
1.4459 +** {H16430} The [sqlite3_result_int64(C,V)] interface changes the
1.4460 +** return value of function C to be the 64-bit integer value V.
1.4461 +**
1.4462 +** {H16433} The [sqlite3_result_null(C)] interface changes the
1.4463 +** return value of function C to be NULL.
1.4464 +**
1.4465 +** {H16436} The [sqlite3_result_text(C,V,N,D)] interface changes the
1.4466 +** return value of function C to be the UTF-8 string
1.4467 +** V up to the first zero if N is negative
1.4468 +** or the first N bytes of V if N is non-negative.
1.4469 +**
1.4470 +** {H16439} The [sqlite3_result_text16(C,V,N,D)] interface changes the
1.4471 +** return value of function C to be the UTF-16 native byte order
1.4472 +** string V up to the first zero if N is negative
1.4473 +** or the first N bytes of V if N is non-negative.
1.4474 +**
1.4475 +** {H16442} The [sqlite3_result_text16be(C,V,N,D)] interface changes the
1.4476 +** return value of function C to be the UTF-16 big-endian
1.4477 +** string V up to the first zero if N is negative
1.4478 +** or the first N bytes or V if N is non-negative.
1.4479 +**
1.4480 +** {H16445} The [sqlite3_result_text16le(C,V,N,D)] interface changes the
1.4481 +** return value of function C to be the UTF-16 little-endian
1.4482 +** string V up to the first zero if N is negative
1.4483 +** or the first N bytes of V if N is non-negative.
1.4484 +**
1.4485 +** {H16448} The [sqlite3_result_value(C,V)] interface changes the
1.4486 +** return value of function C to be the [unprotected sqlite3_value]
1.4487 +** object V.
1.4488 +**
1.4489 +** {H16451} The [sqlite3_result_zeroblob(C,N)] interface changes the
1.4490 +** return value of function C to be an N-byte BLOB of all zeros.
1.4491 +**
1.4492 +** {H16454} The [sqlite3_result_error()] and [sqlite3_result_error16()]
1.4493 +** interfaces make a copy of their error message strings before
1.4494 +** returning.
1.4495 +**
1.4496 +** {H16457} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
1.4497 +** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
1.4498 +** [sqlite3_result_text16be(C,V,N,D)], or
1.4499 +** [sqlite3_result_text16le(C,V,N,D)] is the constant [SQLITE_STATIC]
1.4500 +** then no destructor is ever called on the pointer V and SQLite
1.4501 +** assumes that V is immutable.
1.4502 +**
1.4503 +** {H16460} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
1.4504 +** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
1.4505 +** [sqlite3_result_text16be(C,V,N,D)], or
1.4506 +** [sqlite3_result_text16le(C,V,N,D)] is the constant
1.4507 +** [SQLITE_TRANSIENT] then the interfaces makes a copy of the
1.4508 +** content of V and retains the copy.
1.4509 +**
1.4510 +** {H16463} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
1.4511 +** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
1.4512 +** [sqlite3_result_text16be(C,V,N,D)], or
1.4513 +** [sqlite3_result_text16le(C,V,N,D)] is some value other than
1.4514 +** the constants [SQLITE_STATIC] and [SQLITE_TRANSIENT] then
1.4515 +** SQLite will invoke the destructor D with V as its only argument
1.4516 +** when it has finished with the V value.
1.4517 +*/
1.4518 +IMPORT_C void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
1.4519 +IMPORT_C void sqlite3_result_double(sqlite3_context*, double);
1.4520 +IMPORT_C void sqlite3_result_error(sqlite3_context*, const char*, int);
1.4521 +IMPORT_C void sqlite3_result_error16(sqlite3_context*, const void*, int);
1.4522 +IMPORT_C void sqlite3_result_error_toobig(sqlite3_context*);
1.4523 +IMPORT_C void sqlite3_result_error_nomem(sqlite3_context*);
1.4524 +IMPORT_C void sqlite3_result_error_code(sqlite3_context*, int);
1.4525 +IMPORT_C void sqlite3_result_int(sqlite3_context*, int);
1.4526 +IMPORT_C void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
1.4527 +IMPORT_C void sqlite3_result_null(sqlite3_context*);
1.4528 +IMPORT_C void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
1.4529 +IMPORT_C void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
1.4530 +IMPORT_C void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
1.4531 +IMPORT_C void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
1.4532 +IMPORT_C void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
1.4533 +IMPORT_C void sqlite3_result_zeroblob(sqlite3_context*, int n);
1.4534 +
1.4535 +/*
1.4536 +** CAPI3REF: Define New Collating Sequences {H16600} <S20300>
1.4537 +**
1.4538 +** These functions are used to add new collation sequences to the
1.4539 +** [database connection] specified as the first argument.
1.4540 +**
1.4541 +** The name of the new collation sequence is specified as a UTF-8 string
1.4542 +** for sqlite3_create_collation() and sqlite3_create_collation_v2()
1.4543 +** and a UTF-16 string for sqlite3_create_collation16(). In all cases
1.4544 +** the name is passed as the second function argument.
1.4545 +**
1.4546 +** The third argument may be one of the constants [SQLITE_UTF8],
1.4547 +** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied
1.4548 +** routine expects to be passed pointers to strings encoded using UTF-8,
1.4549 +** UTF-16 little-endian, or UTF-16 big-endian, respectively. The
1.4550 +** third argument might also be [SQLITE_UTF16_ALIGNED] to indicate that
1.4551 +** the routine expects pointers to 16-bit word aligned strings
1.4552 +** of UTF-16 in the native byte order of the host computer.
1.4553 +**
1.4554 +** A pointer to the user supplied routine must be passed as the fifth
1.4555 +** argument. If it is NULL, this is the same as deleting the collation
1.4556 +** sequence (so that SQLite cannot call it anymore).
1.4557 +** Each time the application supplied function is invoked, it is passed
1.4558 +** as its first parameter a copy of the void* passed as the fourth argument
1.4559 +** to sqlite3_create_collation() or sqlite3_create_collation16().
1.4560 +**
1.4561 +** The remaining arguments to the application-supplied routine are two strings,
1.4562 +** each represented by a (length, data) pair and encoded in the encoding
1.4563 +** that was passed as the third argument when the collation sequence was
1.4564 +** registered. {END} The application defined collation routine should
1.4565 +** return negative, zero or positive if the first string is less than,
1.4566 +** equal to, or greater than the second string. i.e. (STRING1 - STRING2).
1.4567 +**
1.4568 +** The sqlite3_create_collation_v2() works like sqlite3_create_collation()
1.4569 +** except that it takes an extra argument which is a destructor for
1.4570 +** the collation. The destructor is called when the collation is
1.4571 +** destroyed and is passed a copy of the fourth parameter void* pointer
1.4572 +** of the sqlite3_create_collation_v2().
1.4573 +** Collations are destroyed when they are overridden by later calls to the
1.4574 +** collation creation functions or when the [database connection] is closed
1.4575 +** using [sqlite3_close()].
1.4576 +**
1.4577 +** INVARIANTS:
1.4578 +**
1.4579 +** {H16603} A successful call to the
1.4580 +** [sqlite3_create_collation_v2(B,X,E,P,F,D)] interface
1.4581 +** registers function F as the comparison function used to
1.4582 +** implement collation X on the [database connection] B for
1.4583 +** databases having encoding E.
1.4584 +**
1.4585 +** {H16604} SQLite understands the X parameter to
1.4586 +** [sqlite3_create_collation_v2(B,X,E,P,F,D)] as a zero-terminated
1.4587 +** UTF-8 string in which case is ignored for ASCII characters and
1.4588 +** is significant for non-ASCII characters.
1.4589 +**
1.4590 +** {H16606} Successive calls to [sqlite3_create_collation_v2(B,X,E,P,F,D)]
1.4591 +** with the same values for B, X, and E, override prior values
1.4592 +** of P, F, and D.
1.4593 +**
1.4594 +** {H16609} If the destructor D in [sqlite3_create_collation_v2(B,X,E,P,F,D)]
1.4595 +** is not NULL then it is called with argument P when the
1.4596 +** collating function is dropped by SQLite.
1.4597 +**
1.4598 +** {H16612} A collating function is dropped when it is overloaded.
1.4599 +**
1.4600 +** {H16615} A collating function is dropped when the database connection
1.4601 +** is closed using [sqlite3_close()].
1.4602 +**
1.4603 +** {H16618} The pointer P in [sqlite3_create_collation_v2(B,X,E,P,F,D)]
1.4604 +** is passed through as the first parameter to the comparison
1.4605 +** function F for all subsequent invocations of F.
1.4606 +**
1.4607 +** {H16621} A call to [sqlite3_create_collation(B,X,E,P,F)] is exactly
1.4608 +** the same as a call to [sqlite3_create_collation_v2()] with
1.4609 +** the same parameters and a NULL destructor.
1.4610 +**
1.4611 +** {H16624} Following a [sqlite3_create_collation_v2(B,X,E,P,F,D)],
1.4612 +** SQLite uses the comparison function F for all text comparison
1.4613 +** operations on the [database connection] B on text values that
1.4614 +** use the collating sequence named X.
1.4615 +**
1.4616 +** {H16627} The [sqlite3_create_collation16(B,X,E,P,F)] works the same
1.4617 +** as [sqlite3_create_collation(B,X,E,P,F)] except that the
1.4618 +** collation name X is understood as UTF-16 in native byte order
1.4619 +** instead of UTF-8.
1.4620 +**
1.4621 +** {H16630} When multiple comparison functions are available for the same
1.4622 +** collating sequence, SQLite chooses the one whose text encoding
1.4623 +** requires the least amount of conversion from the default
1.4624 +** text encoding of the database.
1.4625 +*/
1.4626 +IMPORT_C int sqlite3_create_collation(
1.4627 + sqlite3*,
1.4628 + const char *zName,
1.4629 + int eTextRep,
1.4630 + void*,
1.4631 + int(*xCompare)(void*,int,const void*,int,const void*)
1.4632 +);
1.4633 +IMPORT_C int sqlite3_create_collation_v2(
1.4634 + sqlite3*,
1.4635 + const char *zName,
1.4636 + int eTextRep,
1.4637 + void*,
1.4638 + int(*xCompare)(void*,int,const void*,int,const void*),
1.4639 + void(*xDestroy)(void*)
1.4640 +);
1.4641 +IMPORT_C int sqlite3_create_collation16(
1.4642 + sqlite3*,
1.4643 + const void *zName,
1.4644 + int eTextRep,
1.4645 + void*,
1.4646 + int(*xCompare)(void*,int,const void*,int,const void*)
1.4647 +);
1.4648 +
1.4649 +/*
1.4650 +** CAPI3REF: Collation Needed Callbacks {H16700} <S20300>
1.4651 +**
1.4652 +** To avoid having to register all collation sequences before a database
1.4653 +** can be used, a single callback function may be registered with the
1.4654 +** [database connection] to be called whenever an undefined collation
1.4655 +** sequence is required.
1.4656 +**
1.4657 +** If the function is registered using the sqlite3_collation_needed() API,
1.4658 +** then it is passed the names of undefined collation sequences as strings
1.4659 +** encoded in UTF-8. {H16703} If sqlite3_collation_needed16() is used,
1.4660 +** the names are passed as UTF-16 in machine native byte order.
1.4661 +** A call to either function replaces any existing callback.
1.4662 +**
1.4663 +** When the callback is invoked, the first argument passed is a copy
1.4664 +** of the second argument to sqlite3_collation_needed() or
1.4665 +** sqlite3_collation_needed16(). The second argument is the database
1.4666 +** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],
1.4667 +** or [SQLITE_UTF16LE], indicating the most desirable form of the collation
1.4668 +** sequence function required. The fourth parameter is the name of the
1.4669 +** required collation sequence.
1.4670 +**
1.4671 +** The callback function should register the desired collation using
1.4672 +** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
1.4673 +** [sqlite3_create_collation_v2()].
1.4674 +**
1.4675 +** INVARIANTS:
1.4676 +**
1.4677 +** {H16702} A successful call to [sqlite3_collation_needed(D,P,F)]
1.4678 +** or [sqlite3_collation_needed16(D,P,F)] causes
1.4679 +** the [database connection] D to invoke callback F with first
1.4680 +** parameter P whenever it needs a comparison function for a
1.4681 +** collating sequence that it does not know about.
1.4682 +**
1.4683 +** {H16704} Each successful call to [sqlite3_collation_needed()] or
1.4684 +** [sqlite3_collation_needed16()] overrides the callback registered
1.4685 +** on the same [database connection] by prior calls to either
1.4686 +** interface.
1.4687 +**
1.4688 +** {H16706} The name of the requested collating function passed in the
1.4689 +** 4th parameter to the callback is in UTF-8 if the callback
1.4690 +** was registered using [sqlite3_collation_needed()] and
1.4691 +** is in UTF-16 native byte order if the callback was
1.4692 +** registered using [sqlite3_collation_needed16()].
1.4693 +*/
1.4694 +IMPORT_C int sqlite3_collation_needed(
1.4695 + sqlite3*,
1.4696 + void*,
1.4697 + void(*)(void*,sqlite3*,int eTextRep,const char*)
1.4698 +);
1.4699 +IMPORT_C int sqlite3_collation_needed16(
1.4700 + sqlite3*,
1.4701 + void*,
1.4702 + void(*)(void*,sqlite3*,int eTextRep,const void*)
1.4703 +);
1.4704 +
1.4705 +/*
1.4706 +** Specify the key for an encrypted database. This routine should be
1.4707 +** called right after sqlite3_open().
1.4708 +**
1.4709 +** The code to implement this API is not available in the public release
1.4710 +** of SQLite.
1.4711 +*/
1.4712 +IMPORT_C int sqlite3_key(
1.4713 + sqlite3 *db, /* Database to be rekeyed */
1.4714 + const void *pKey, int nKey /* The key */
1.4715 +);
1.4716 +
1.4717 +/*
1.4718 +** Change the key on an open database. If the current database is not
1.4719 +** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the
1.4720 +** database is decrypted.
1.4721 +**
1.4722 +** The code to implement this API is not available in the public release
1.4723 +** of SQLite.
1.4724 +*/
1.4725 +IMPORT_C int sqlite3_rekey(
1.4726 + sqlite3 *db, /* Database to be rekeyed */
1.4727 + const void *pKey, int nKey /* The new key */
1.4728 +);
1.4729 +
1.4730 +/*
1.4731 +** CAPI3REF: Suspend Execution For A Short Time {H10530} <S40410>
1.4732 +**
1.4733 +** The sqlite3_sleep() function causes the current thread to suspend execution
1.4734 +** for at least a number of milliseconds specified in its parameter.
1.4735 +**
1.4736 +** If the operating system does not support sleep requests with
1.4737 +** millisecond time resolution, then the time will be rounded up to
1.4738 +** the nearest second. The number of milliseconds of sleep actually
1.4739 +** requested from the operating system is returned.
1.4740 +**
1.4741 +** SQLite implements this interface by calling the xSleep()
1.4742 +** method of the default [sqlite3_vfs] object.
1.4743 +**
1.4744 +** INVARIANTS:
1.4745 +**
1.4746 +** {H10533} The [sqlite3_sleep(M)] interface invokes the xSleep
1.4747 +** method of the default [sqlite3_vfs|VFS] in order to
1.4748 +** suspend execution of the current thread for at least
1.4749 +** M milliseconds.
1.4750 +**
1.4751 +** {H10536} The [sqlite3_sleep(M)] interface returns the number of
1.4752 +** milliseconds of sleep actually requested of the operating
1.4753 +** system, which might be larger than the parameter M.
1.4754 +*/
1.4755 +IMPORT_C int sqlite3_sleep(int);
1.4756 +
1.4757 +/*
1.4758 +** CAPI3REF: Name Of The Folder Holding Temporary Files {H10310} <S20000>
1.4759 +**
1.4760 +** If this global variable is made to point to a string which is
1.4761 +** the name of a folder (a.k.a. directory), then all temporary files
1.4762 +** created by SQLite will be placed in that directory. If this variable
1.4763 +** is a NULL pointer, then SQLite performs a search for an appropriate
1.4764 +** temporary file directory.
1.4765 +**
1.4766 +** It is not safe to modify this variable once a [database connection]
1.4767 +** has been opened. It is intended that this variable be set once
1.4768 +** as part of process initialization and before any SQLite interface
1.4769 +** routines have been call and remain unchanged thereafter.
1.4770 +*/
1.4771 +SQLITE_EXTERN char *sqlite3_temp_directory;
1.4772 +
1.4773 +/*
1.4774 +** CAPI3REF: Test For Auto-Commit Mode {H12930} <S60200>
1.4775 +** KEYWORDS: {autocommit mode}
1.4776 +**
1.4777 +** The sqlite3_get_autocommit() interface returns non-zero or
1.4778 +** zero if the given database connection is or is not in autocommit mode,
1.4779 +** respectively. Autocommit mode is on by default.
1.4780 +** Autocommit mode is disabled by a [BEGIN] statement.
1.4781 +** Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
1.4782 +**
1.4783 +** If certain kinds of errors occur on a statement within a multi-statement
1.4784 +** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR],
1.4785 +** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
1.4786 +** transaction might be rolled back automatically. The only way to
1.4787 +** find out whether SQLite automatically rolled back the transaction after
1.4788 +** an error is to use this function.
1.4789 +**
1.4790 +** INVARIANTS:
1.4791 +**
1.4792 +** {H12931} The [sqlite3_get_autocommit(D)] interface returns non-zero or
1.4793 +** zero if the [database connection] D is or is not in autocommit
1.4794 +** mode, respectively.
1.4795 +**
1.4796 +** {H12932} Autocommit mode is on by default.
1.4797 +**
1.4798 +** {H12933} Autocommit mode is disabled by a successful [BEGIN] statement.
1.4799 +**
1.4800 +** {H12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK]
1.4801 +** statement.
1.4802 +**
1.4803 +** ASSUMPTIONS:
1.4804 +**
1.4805 +** {A12936} If another thread changes the autocommit status of the database
1.4806 +** connection while this routine is running, then the return value
1.4807 +** is undefined.
1.4808 +*/
1.4809 +IMPORT_C int sqlite3_get_autocommit(sqlite3*);
1.4810 +
1.4811 +/*
1.4812 +** CAPI3REF: Find The Database Handle Of A Prepared Statement {H13120} <S60600>
1.4813 +**
1.4814 +** The sqlite3_db_handle interface returns the [database connection] handle
1.4815 +** to which a [prepared statement] belongs. The database handle returned by
1.4816 +** sqlite3_db_handle is the same database handle that was the first argument
1.4817 +** to the [sqlite3_prepare_v2()] call (or its variants) that was used to
1.4818 +** create the statement in the first place.
1.4819 +**
1.4820 +** INVARIANTS:
1.4821 +**
1.4822 +** {H13123} The [sqlite3_db_handle(S)] interface returns a pointer
1.4823 +** to the [database connection] associated with the
1.4824 +** [prepared statement] S.
1.4825 +*/
1.4826 +IMPORT_C sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
1.4827 +
1.4828 +/*
1.4829 +** CAPI3REF: Find the next prepared statement {H13140} <S60600>
1.4830 +**
1.4831 +** This interface returns a pointer to the next [prepared statement] after
1.4832 +** pStmt associated with the [database connection] pDb. If pStmt is NULL
1.4833 +** then this interface returns a pointer to the first prepared statement
1.4834 +** associated with the database connection pDb. If no prepared statement
1.4835 +** satisfies the conditions of this routine, it returns NULL.
1.4836 +**
1.4837 +** INVARIANTS:
1.4838 +**
1.4839 +** {H13143} If D is a [database connection] that holds one or more
1.4840 +** unfinalized [prepared statements] and S is a NULL pointer,
1.4841 +** then [sqlite3_next_stmt(D, S)] routine shall return a pointer
1.4842 +** to one of the prepared statements associated with D.
1.4843 +**
1.4844 +** {H13146} If D is a [database connection] that holds no unfinalized
1.4845 +** [prepared statements] and S is a NULL pointer, then
1.4846 +** [sqlite3_next_stmt(D, S)] routine shall return a NULL pointer.
1.4847 +**
1.4848 +** {H13149} If S is a [prepared statement] in the [database connection] D
1.4849 +** and S is not the last prepared statement in D, then
1.4850 +** [sqlite3_next_stmt(D, S)] routine shall return a pointer
1.4851 +** to the next prepared statement in D after S.
1.4852 +**
1.4853 +** {H13152} If S is the last [prepared statement] in the
1.4854 +** [database connection] D then the [sqlite3_next_stmt(D, S)]
1.4855 +** routine shall return a NULL pointer.
1.4856 +**
1.4857 +** ASSUMPTIONS:
1.4858 +**
1.4859 +** {A13154} The [database connection] pointer D in a call to
1.4860 +** [sqlite3_next_stmt(D,S)] must refer to an open database
1.4861 +** connection and in particular must not be a NULL pointer.
1.4862 +*/
1.4863 +IMPORT_C sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
1.4864 +
1.4865 +/*
1.4866 +** CAPI3REF: Commit And Rollback Notification Callbacks {H12950} <S60400>
1.4867 +**
1.4868 +** The sqlite3_commit_hook() interface registers a callback
1.4869 +** function to be invoked whenever a transaction is committed.
1.4870 +** Any callback set by a previous call to sqlite3_commit_hook()
1.4871 +** for the same database connection is overridden.
1.4872 +** The sqlite3_rollback_hook() interface registers a callback
1.4873 +** function to be invoked whenever a transaction is committed.
1.4874 +** Any callback set by a previous call to sqlite3_commit_hook()
1.4875 +** for the same database connection is overridden.
1.4876 +** The pArg argument is passed through to the callback.
1.4877 +** If the callback on a commit hook function returns non-zero,
1.4878 +** then the commit is converted into a rollback.
1.4879 +**
1.4880 +** If another function was previously registered, its
1.4881 +** pArg value is returned. Otherwise NULL is returned.
1.4882 +**
1.4883 +** The callback implementation must not do anything that will modify
1.4884 +** the database connection that invoked the callback. Any actions
1.4885 +** to modify the database connection must be deferred until after the
1.4886 +** completion of the [sqlite3_step()] call that triggered the commit
1.4887 +** or rollback hook in the first place.
1.4888 +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
1.4889 +** database connections for the meaning of "modify" in this paragraph.
1.4890 +**
1.4891 +** Registering a NULL function disables the callback.
1.4892 +**
1.4893 +** For the purposes of this API, a transaction is said to have been
1.4894 +** rolled back if an explicit "ROLLBACK" statement is executed, or
1.4895 +** an error or constraint causes an implicit rollback to occur.
1.4896 +** The rollback callback is not invoked if a transaction is
1.4897 +** automatically rolled back because the database connection is closed.
1.4898 +** The rollback callback is not invoked if a transaction is
1.4899 +** rolled back because a commit callback returned non-zero.
1.4900 +** <todo> Check on this </todo>
1.4901 +**
1.4902 +** INVARIANTS:
1.4903 +**
1.4904 +** {H12951} The [sqlite3_commit_hook(D,F,P)] interface registers the
1.4905 +** callback function F to be invoked with argument P whenever
1.4906 +** a transaction commits on the [database connection] D.
1.4907 +**
1.4908 +** {H12952} The [sqlite3_commit_hook(D,F,P)] interface returns the P argument
1.4909 +** from the previous call with the same [database connection] D,
1.4910 +** or NULL on the first call for a particular database connection D.
1.4911 +**
1.4912 +** {H12953} Each call to [sqlite3_commit_hook()] overwrites the callback
1.4913 +** registered by prior calls.
1.4914 +**
1.4915 +** {H12954} If the F argument to [sqlite3_commit_hook(D,F,P)] is NULL
1.4916 +** then the commit hook callback is canceled and no callback
1.4917 +** is invoked when a transaction commits.
1.4918 +**
1.4919 +** {H12955} If the commit callback returns non-zero then the commit is
1.4920 +** converted into a rollback.
1.4921 +**
1.4922 +** {H12961} The [sqlite3_rollback_hook(D,F,P)] interface registers the
1.4923 +** callback function F to be invoked with argument P whenever
1.4924 +** a transaction rolls back on the [database connection] D.
1.4925 +**
1.4926 +** {H12962} The [sqlite3_rollback_hook(D,F,P)] interface returns the P
1.4927 +** argument from the previous call with the same
1.4928 +** [database connection] D, or NULL on the first call
1.4929 +** for a particular database connection D.
1.4930 +**
1.4931 +** {H12963} Each call to [sqlite3_rollback_hook()] overwrites the callback
1.4932 +** registered by prior calls.
1.4933 +**
1.4934 +** {H12964} If the F argument to [sqlite3_rollback_hook(D,F,P)] is NULL
1.4935 +** then the rollback hook callback is canceled and no callback
1.4936 +** is invoked when a transaction rolls back.
1.4937 +*/
1.4938 +IMPORT_C void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
1.4939 +IMPORT_C void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
1.4940 +
1.4941 +/*
1.4942 +** CAPI3REF: Data Change Notification Callbacks {H12970} <S60400>
1.4943 +**
1.4944 +** The sqlite3_update_hook() interface registers a callback function
1.4945 +** with the [database connection] identified by the first argument
1.4946 +** to be invoked whenever a row is updated, inserted or deleted.
1.4947 +** Any callback set by a previous call to this function
1.4948 +** for the same database connection is overridden.
1.4949 +**
1.4950 +** The second argument is a pointer to the function to invoke when a
1.4951 +** row is updated, inserted or deleted.
1.4952 +** The first argument to the callback is a copy of the third argument
1.4953 +** to sqlite3_update_hook().
1.4954 +** The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
1.4955 +** or [SQLITE_UPDATE], depending on the operation that caused the callback
1.4956 +** to be invoked.
1.4957 +** The third and fourth arguments to the callback contain pointers to the
1.4958 +** database and table name containing the affected row.
1.4959 +** The final callback parameter is the rowid of the row. In the case of
1.4960 +** an update, this is the rowid after the update takes place.
1.4961 +**
1.4962 +** The update hook is not invoked when internal system tables are
1.4963 +** modified (i.e. sqlite_master and sqlite_sequence).
1.4964 +**
1.4965 +** The update hook implementation must not do anything that will modify
1.4966 +** the database connection that invoked the update hook. Any actions
1.4967 +** to modify the database connection must be deferred until after the
1.4968 +** completion of the [sqlite3_step()] call that triggered the update hook.
1.4969 +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
1.4970 +** database connections for the meaning of "modify" in this paragraph.
1.4971 +**
1.4972 +** If another function was previously registered, its pArg value
1.4973 +** is returned. Otherwise NULL is returned.
1.4974 +**
1.4975 +** INVARIANTS:
1.4976 +**
1.4977 +** {H12971} The [sqlite3_update_hook(D,F,P)] interface causes the callback
1.4978 +** function F to be invoked with first parameter P whenever
1.4979 +** a table row is modified, inserted, or deleted on
1.4980 +** the [database connection] D.
1.4981 +**
1.4982 +** {H12973} The [sqlite3_update_hook(D,F,P)] interface returns the value
1.4983 +** of P for the previous call on the same [database connection] D,
1.4984 +** or NULL for the first call.
1.4985 +**
1.4986 +** {H12975} If the update hook callback F in [sqlite3_update_hook(D,F,P)]
1.4987 +** is NULL then the no update callbacks are made.
1.4988 +**
1.4989 +** {H12977} Each call to [sqlite3_update_hook(D,F,P)] overrides prior calls
1.4990 +** to the same interface on the same [database connection] D.
1.4991 +**
1.4992 +** {H12979} The update hook callback is not invoked when internal system
1.4993 +** tables such as sqlite_master and sqlite_sequence are modified.
1.4994 +**
1.4995 +** {H12981} The second parameter to the update callback
1.4996 +** is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],
1.4997 +** depending on the operation that caused the callback to be invoked.
1.4998 +**
1.4999 +** {H12983} The third and fourth arguments to the callback contain pointers
1.5000 +** to zero-terminated UTF-8 strings which are the names of the
1.5001 +** database and table that is being updated.
1.5002 +
1.5003 +** {H12985} The final callback parameter is the rowid of the row after
1.5004 +** the change occurs.
1.5005 +*/
1.5006 +IMPORT_C void *sqlite3_update_hook(
1.5007 + sqlite3*,
1.5008 + void(*)(void *,int ,char const *,char const *,sqlite3_int64),
1.5009 + void*
1.5010 +);
1.5011 +
1.5012 +/*
1.5013 +** CAPI3REF: Enable Or Disable Shared Pager Cache {H10330} <S30900>
1.5014 +** KEYWORDS: {shared cache} {shared cache mode}
1.5015 +**
1.5016 +** This routine enables or disables the sharing of the database cache
1.5017 +** and schema data structures between [database connection | connections]
1.5018 +** to the same database. Sharing is enabled if the argument is true
1.5019 +** and disabled if the argument is false.
1.5020 +**
1.5021 +** Cache sharing is enabled and disabled for an entire process. {END}
1.5022 +** This is a change as of SQLite version 3.5.0. In prior versions of SQLite,
1.5023 +** sharing was enabled or disabled for each thread separately.
1.5024 +**
1.5025 +** The cache sharing mode set by this interface effects all subsequent
1.5026 +** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
1.5027 +** Existing database connections continue use the sharing mode
1.5028 +** that was in effect at the time they were opened.
1.5029 +**
1.5030 +** Virtual tables cannot be used with a shared cache. When shared
1.5031 +** cache is enabled, the [sqlite3_create_module()] API used to register
1.5032 +** virtual tables will always return an error.
1.5033 +**
1.5034 +** This routine returns [SQLITE_OK] if shared cache was enabled or disabled
1.5035 +** successfully. An [error code] is returned otherwise.
1.5036 +**
1.5037 +** Shared cache is disabled by default. But this might change in
1.5038 +** future releases of SQLite. Applications that care about shared
1.5039 +** cache setting should set it explicitly.
1.5040 +**
1.5041 +** INVARIANTS:
1.5042 +**
1.5043 +** {H10331} A successful invocation of [sqlite3_enable_shared_cache(B)]
1.5044 +** will enable or disable shared cache mode for any subsequently
1.5045 +** created [database connection] in the same process.
1.5046 +**
1.5047 +** {H10336} When shared cache is enabled, the [sqlite3_create_module()]
1.5048 +** interface will always return an error.
1.5049 +**
1.5050 +** {H10337} The [sqlite3_enable_shared_cache(B)] interface returns
1.5051 +** [SQLITE_OK] if shared cache was enabled or disabled successfully.
1.5052 +**
1.5053 +** {H10339} Shared cache is disabled by default.
1.5054 +*/
1.5055 +IMPORT_C int sqlite3_enable_shared_cache(int);
1.5056 +
1.5057 +/*
1.5058 +** CAPI3REF: Attempt To Free Heap Memory {H17340} <S30220>
1.5059 +**
1.5060 +** The sqlite3_release_memory() interface attempts to free N bytes
1.5061 +** of heap memory by deallocating non-essential memory allocations
1.5062 +** held by the database library. {END} Memory used to cache database
1.5063 +** pages to improve performance is an example of non-essential memory.
1.5064 +** sqlite3_release_memory() returns the number of bytes actually freed,
1.5065 +** which might be more or less than the amount requested.
1.5066 +**
1.5067 +** INVARIANTS:
1.5068 +**
1.5069 +** {H17341} The [sqlite3_release_memory(N)] interface attempts to
1.5070 +** free N bytes of heap memory by deallocating non-essential
1.5071 +** memory allocations held by the database library.
1.5072 +**
1.5073 +** {H16342} The [sqlite3_release_memory(N)] returns the number
1.5074 +** of bytes actually freed, which might be more or less
1.5075 +** than the amount requested.
1.5076 +*/
1.5077 +IMPORT_C int sqlite3_release_memory(int);
1.5078 +
1.5079 +/*
1.5080 +** CAPI3REF: Impose A Limit On Heap Size {H17350} <S30220>
1.5081 +**
1.5082 +** The sqlite3_soft_heap_limit() interface places a "soft" limit
1.5083 +** on the amount of heap memory that may be allocated by SQLite.
1.5084 +** If an internal allocation is requested that would exceed the
1.5085 +** soft heap limit, [sqlite3_release_memory()] is invoked one or
1.5086 +** more times to free up some space before the allocation is performed.
1.5087 +**
1.5088 +** The limit is called "soft", because if [sqlite3_release_memory()]
1.5089 +** cannot free sufficient memory to prevent the limit from being exceeded,
1.5090 +** the memory is allocated anyway and the current operation proceeds.
1.5091 +**
1.5092 +** A negative or zero value for N means that there is no soft heap limit and
1.5093 +** [sqlite3_release_memory()] will only be called when memory is exhausted.
1.5094 +** The default value for the soft heap limit is zero.
1.5095 +**
1.5096 +** SQLite makes a best effort to honor the soft heap limit.
1.5097 +** But if the soft heap limit cannot be honored, execution will
1.5098 +** continue without error or notification. This is why the limit is
1.5099 +** called a "soft" limit. It is advisory only.
1.5100 +**
1.5101 +** Prior to SQLite version 3.5.0, this routine only constrained the memory
1.5102 +** allocated by a single thread - the same thread in which this routine
1.5103 +** runs. Beginning with SQLite version 3.5.0, the soft heap limit is
1.5104 +** applied to all threads. The value specified for the soft heap limit
1.5105 +** is an upper bound on the total memory allocation for all threads. In
1.5106 +** version 3.5.0 there is no mechanism for limiting the heap usage for
1.5107 +** individual threads.
1.5108 +**
1.5109 +** INVARIANTS:
1.5110 +**
1.5111 +** {H16351} The [sqlite3_soft_heap_limit(N)] interface places a soft limit
1.5112 +** of N bytes on the amount of heap memory that may be allocated
1.5113 +** using [sqlite3_malloc()] or [sqlite3_realloc()] at any point
1.5114 +** in time.
1.5115 +**
1.5116 +** {H16352} If a call to [sqlite3_malloc()] or [sqlite3_realloc()] would
1.5117 +** cause the total amount of allocated memory to exceed the
1.5118 +** soft heap limit, then [sqlite3_release_memory()] is invoked
1.5119 +** in an attempt to reduce the memory usage prior to proceeding
1.5120 +** with the memory allocation attempt.
1.5121 +**
1.5122 +** {H16353} Calls to [sqlite3_malloc()] or [sqlite3_realloc()] that trigger
1.5123 +** attempts to reduce memory usage through the soft heap limit
1.5124 +** mechanism continue even if the attempt to reduce memory
1.5125 +** usage is unsuccessful.
1.5126 +**
1.5127 +** {H16354} A negative or zero value for N in a call to
1.5128 +** [sqlite3_soft_heap_limit(N)] means that there is no soft
1.5129 +** heap limit and [sqlite3_release_memory()] will only be
1.5130 +** called when memory is completely exhausted.
1.5131 +**
1.5132 +** {H16355} The default value for the soft heap limit is zero.
1.5133 +**
1.5134 +** {H16358} Each call to [sqlite3_soft_heap_limit(N)] overrides the
1.5135 +** values set by all prior calls.
1.5136 +*/
1.5137 +IMPORT_C void sqlite3_soft_heap_limit(int);
1.5138 +
1.5139 +/*
1.5140 +** CAPI3REF: Extract Metadata About A Column Of A Table {H12850} <S60300>
1.5141 +**
1.5142 +** This routine returns metadata about a specific column of a specific
1.5143 +** database table accessible using the [database connection] handle
1.5144 +** passed as the first function argument.
1.5145 +**
1.5146 +** The column is identified by the second, third and fourth parameters to
1.5147 +** this function. The second parameter is either the name of the database
1.5148 +** (i.e. "main", "temp" or an attached database) containing the specified
1.5149 +** table or NULL. If it is NULL, then all attached databases are searched
1.5150 +** for the table using the same algorithm used by the database engine to
1.5151 +** resolve unqualified table references.
1.5152 +**
1.5153 +** The third and fourth parameters to this function are the table and column
1.5154 +** name of the desired column, respectively. Neither of these parameters
1.5155 +** may be NULL.
1.5156 +**
1.5157 +** Metadata is returned by writing to the memory locations passed as the 5th
1.5158 +** and subsequent parameters to this function. Any of these arguments may be
1.5159 +** NULL, in which case the corresponding element of metadata is omitted.
1.5160 +**
1.5161 +** <blockquote>
1.5162 +** <table border="1">
1.5163 +** <tr><th> Parameter <th> Output<br>Type <th> Description
1.5164 +**
1.5165 +** <tr><td> 5th <td> const char* <td> Data type
1.5166 +** <tr><td> 6th <td> const char* <td> Name of default collation sequence
1.5167 +** <tr><td> 7th <td> int <td> True if column has a NOT NULL constraint
1.5168 +** <tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY
1.5169 +** <tr><td> 9th <td> int <td> True if column is AUTOINCREMENT
1.5170 +** </table>
1.5171 +** </blockquote>
1.5172 +**
1.5173 +** The memory pointed to by the character pointers returned for the
1.5174 +** declaration type and collation sequence is valid only until the next
1.5175 +** call to any SQLite API function.
1.5176 +**
1.5177 +** If the specified table is actually a view, an [error code] is returned.
1.5178 +**
1.5179 +** If the specified column is "rowid", "oid" or "_rowid_" and an
1.5180 +** INTEGER PRIMARY KEY column has been explicitly declared, then the output
1.5181 +** parameters are set for the explicitly declared column. If there is no
1.5182 +** explicitly declared INTEGER PRIMARY KEY column, then the output
1.5183 +** parameters are set as follows:
1.5184 +**
1.5185 +** <pre>
1.5186 +** data type: "INTEGER"
1.5187 +** collation sequence: "BINARY"
1.5188 +** not null: 0
1.5189 +** primary key: 1
1.5190 +** auto increment: 0
1.5191 +** </pre>
1.5192 +**
1.5193 +** This function may load one or more schemas from database files. If an
1.5194 +** error occurs during this process, or if the requested table or column
1.5195 +** cannot be found, an [error code] is returned and an error message left
1.5196 +** in the [database connection] (to be retrieved using sqlite3_errmsg()).
1.5197 +**
1.5198 +** This API is only available if the library was compiled with the
1.5199 +** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined.
1.5200 +*/
1.5201 +IMPORT_C int sqlite3_table_column_metadata(
1.5202 + sqlite3 *db, /* Connection handle */
1.5203 + const char *zDbName, /* Database name or NULL */
1.5204 + const char *zTableName, /* Table name */
1.5205 + const char *zColumnName, /* Column name */
1.5206 + char const **pzDataType, /* OUTPUT: Declared data type */
1.5207 + char const **pzCollSeq, /* OUTPUT: Collation sequence name */
1.5208 + int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */
1.5209 + int *pPrimaryKey, /* OUTPUT: True if column part of PK */
1.5210 + int *pAutoinc /* OUTPUT: True if column is auto-increment */
1.5211 +);
1.5212 +
1.5213 +/*
1.5214 +** CAPI3REF: Load An Extension {H12600} <S20500>
1.5215 +**
1.5216 +** This interface loads an SQLite extension library from the named file.
1.5217 +**
1.5218 +** {H12601} The sqlite3_load_extension() interface attempts to load an
1.5219 +** SQLite extension library contained in the file zFile.
1.5220 +**
1.5221 +** {H12602} The entry point is zProc.
1.5222 +**
1.5223 +** {H12603} zProc may be 0, in which case the name of the entry point
1.5224 +** defaults to "sqlite3_extension_init".
1.5225 +**
1.5226 +** {H12604} The sqlite3_load_extension() interface shall return
1.5227 +** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
1.5228 +**
1.5229 +** {H12605} If an error occurs and pzErrMsg is not 0, then the
1.5230 +** [sqlite3_load_extension()] interface shall attempt to
1.5231 +** fill *pzErrMsg with error message text stored in memory
1.5232 +** obtained from [sqlite3_malloc()]. {END} The calling function
1.5233 +** should free this memory by calling [sqlite3_free()].
1.5234 +**
1.5235 +** {H12606} Extension loading must be enabled using
1.5236 +** [sqlite3_enable_load_extension()] prior to calling this API,
1.5237 +** otherwise an error will be returned.
1.5238 +*/
1.5239 +IMPORT_C int sqlite3_load_extension(
1.5240 + sqlite3 *db, /* Load the extension into this database connection */
1.5241 + const char *zFile, /* Name of the shared library containing extension */
1.5242 + const char *zProc, /* Entry point. Derived from zFile if 0 */
1.5243 + char **pzErrMsg /* Put error message here if not 0 */
1.5244 +);
1.5245 +
1.5246 +/*
1.5247 +** CAPI3REF: Enable Or Disable Extension Loading {H12620} <S20500>
1.5248 +**
1.5249 +** So as not to open security holes in older applications that are
1.5250 +** unprepared to deal with extension loading, and as a means of disabling
1.5251 +** extension loading while evaluating user-entered SQL, the following API
1.5252 +** is provided to turn the [sqlite3_load_extension()] mechanism on and off.
1.5253 +**
1.5254 +** Extension loading is off by default. See ticket #1863.
1.5255 +**
1.5256 +** {H12621} Call the sqlite3_enable_load_extension() routine with onoff==1
1.5257 +** to turn extension loading on and call it with onoff==0 to turn
1.5258 +** it back off again.
1.5259 +**
1.5260 +** {H12622} Extension loading is off by default.
1.5261 +*/
1.5262 +IMPORT_C int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
1.5263 +
1.5264 +/*
1.5265 +** CAPI3REF: Automatically Load An Extensions {H12640} <S20500>
1.5266 +**
1.5267 +** This API can be invoked at program startup in order to register
1.5268 +** one or more statically linked extensions that will be available
1.5269 +** to all new [database connections]. {END}
1.5270 +**
1.5271 +** This routine stores a pointer to the extension in an array that is
1.5272 +** obtained from [sqlite3_malloc()]. If you run a memory leak checker
1.5273 +** on your program and it reports a leak because of this array, invoke
1.5274 +** [sqlite3_reset_auto_extension()] prior to shutdown to free the memory.
1.5275 +**
1.5276 +** {H12641} This function registers an extension entry point that is
1.5277 +** automatically invoked whenever a new [database connection]
1.5278 +** is opened using [sqlite3_open()], [sqlite3_open16()],
1.5279 +** or [sqlite3_open_v2()].
1.5280 +**
1.5281 +** {H12642} Duplicate extensions are detected so calling this routine
1.5282 +** multiple times with the same extension is harmless.
1.5283 +**
1.5284 +** {H12643} This routine stores a pointer to the extension in an array
1.5285 +** that is obtained from [sqlite3_malloc()].
1.5286 +**
1.5287 +** {H12644} Automatic extensions apply across all threads.
1.5288 +*/
1.5289 +IMPORT_C int sqlite3_auto_extension(void *xEntryPoint);
1.5290 +
1.5291 +/*
1.5292 +** CAPI3REF: Reset Automatic Extension Loading {H12660} <S20500>
1.5293 +**
1.5294 +** This function disables all previously registered automatic
1.5295 +** extensions. {END} It undoes the effect of all prior
1.5296 +** [sqlite3_auto_extension()] calls.
1.5297 +**
1.5298 +** {H12661} This function disables all previously registered
1.5299 +** automatic extensions.
1.5300 +**
1.5301 +** {H12662} This function disables automatic extensions in all threads.
1.5302 +*/
1.5303 +IMPORT_C void sqlite3_reset_auto_extension(void);
1.5304 +
1.5305 +/*
1.5306 +****** EXPERIMENTAL - subject to change without notice **************
1.5307 +**
1.5308 +** The interface to the virtual-table mechanism is currently considered
1.5309 +** to be experimental. The interface might change in incompatible ways.
1.5310 +** If this is a problem for you, do not use the interface at this time.
1.5311 +**
1.5312 +** When the virtual-table mechanism stabilizes, we will declare the
1.5313 +** interface fixed, support it indefinitely, and remove this comment.
1.5314 +*/
1.5315 +
1.5316 +/*
1.5317 +** Structures used by the virtual table interface
1.5318 +*/
1.5319 +typedef struct sqlite3_vtab sqlite3_vtab;
1.5320 +typedef struct sqlite3_index_info sqlite3_index_info;
1.5321 +typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
1.5322 +typedef struct sqlite3_module sqlite3_module;
1.5323 +
1.5324 +/*
1.5325 +** CAPI3REF: Virtual Table Object {H18000} <S20400>
1.5326 +** KEYWORDS: sqlite3_module
1.5327 +** EXPERIMENTAL
1.5328 +**
1.5329 +** A module is a class of virtual tables. Each module is defined
1.5330 +** by an instance of the following structure. This structure consists
1.5331 +** mostly of methods for the module.
1.5332 +**
1.5333 +** This interface is experimental and is subject to change or
1.5334 +** removal in future releases of SQLite.
1.5335 +*/
1.5336 +struct sqlite3_module {
1.5337 + int iVersion;
1.5338 + int (*xCreate)(sqlite3*, void *pAux,
1.5339 + int argc, const char *const*argv,
1.5340 + sqlite3_vtab **ppVTab, char**);
1.5341 + int (*xConnect)(sqlite3*, void *pAux,
1.5342 + int argc, const char *const*argv,
1.5343 + sqlite3_vtab **ppVTab, char**);
1.5344 + int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
1.5345 + int (*xDisconnect)(sqlite3_vtab *pVTab);
1.5346 + int (*xDestroy)(sqlite3_vtab *pVTab);
1.5347 + int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
1.5348 + int (*xClose)(sqlite3_vtab_cursor*);
1.5349 + int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
1.5350 + int argc, sqlite3_value **argv);
1.5351 + int (*xNext)(sqlite3_vtab_cursor*);
1.5352 + int (*xEof)(sqlite3_vtab_cursor*);
1.5353 + int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
1.5354 + int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
1.5355 + int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
1.5356 + int (*xBegin)(sqlite3_vtab *pVTab);
1.5357 + int (*xSync)(sqlite3_vtab *pVTab);
1.5358 + int (*xCommit)(sqlite3_vtab *pVTab);
1.5359 + int (*xRollback)(sqlite3_vtab *pVTab);
1.5360 + int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
1.5361 + void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
1.5362 + void **ppArg);
1.5363 + int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
1.5364 +};
1.5365 +
1.5366 +/*
1.5367 +** CAPI3REF: Virtual Table Indexing Information {H18100} <S20400>
1.5368 +** KEYWORDS: sqlite3_index_info
1.5369 +** EXPERIMENTAL
1.5370 +**
1.5371 +** The sqlite3_index_info structure and its substructures is used to
1.5372 +** pass information into and receive the reply from the xBestIndex
1.5373 +** method of an sqlite3_module. The fields under **Inputs** are the
1.5374 +** inputs to xBestIndex and are read-only. xBestIndex inserts its
1.5375 +** results into the **Outputs** fields.
1.5376 +**
1.5377 +** The aConstraint[] array records WHERE clause constraints of the form:
1.5378 +**
1.5379 +** <pre>column OP expr</pre>
1.5380 +**
1.5381 +** where OP is =, <, <=, >, or >=. The particular operator is
1.5382 +** stored in aConstraint[].op. The index of the column is stored in
1.5383 +** aConstraint[].iColumn. aConstraint[].usable is TRUE if the
1.5384 +** expr on the right-hand side can be evaluated (and thus the constraint
1.5385 +** is usable) and false if it cannot.
1.5386 +**
1.5387 +** The optimizer automatically inverts terms of the form "expr OP column"
1.5388 +** and makes other simplifications to the WHERE clause in an attempt to
1.5389 +** get as many WHERE clause terms into the form shown above as possible.
1.5390 +** The aConstraint[] array only reports WHERE clause terms in the correct
1.5391 +** form that refer to the particular virtual table being queried.
1.5392 +**
1.5393 +** Information about the ORDER BY clause is stored in aOrderBy[].
1.5394 +** Each term of aOrderBy records a column of the ORDER BY clause.
1.5395 +**
1.5396 +** The xBestIndex method must fill aConstraintUsage[] with information
1.5397 +** about what parameters to pass to xFilter. If argvIndex>0 then
1.5398 +** the right-hand side of the corresponding aConstraint[] is evaluated
1.5399 +** and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit
1.5400 +** is true, then the constraint is assumed to be fully handled by the
1.5401 +** virtual table and is not checked again by SQLite.
1.5402 +**
1.5403 +** The idxNum and idxPtr values are recorded and passed into xFilter.
1.5404 +** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true.
1.5405 +**
1.5406 +** The orderByConsumed means that output from xFilter will occur in
1.5407 +** the correct order to satisfy the ORDER BY clause so that no separate
1.5408 +** sorting step is required.
1.5409 +**
1.5410 +** The estimatedCost value is an estimate of the cost of doing the
1.5411 +** particular lookup. A full scan of a table with N entries should have
1.5412 +** a cost of N. A binary search of a table of N entries should have a
1.5413 +** cost of approximately log(N).
1.5414 +**
1.5415 +** This interface is experimental and is subject to change or
1.5416 +** removal in future releases of SQLite.
1.5417 +*/
1.5418 +struct sqlite3_index_info {
1.5419 + /* Inputs */
1.5420 + int nConstraint; /* Number of entries in aConstraint */
1.5421 + struct sqlite3_index_constraint {
1.5422 + int iColumn; /* Column on left-hand side of constraint */
1.5423 + unsigned char op; /* Constraint operator */
1.5424 + unsigned char usable; /* True if this constraint is usable */
1.5425 + int iTermOffset; /* Used internally - xBestIndex should ignore */
1.5426 + } *aConstraint; /* Table of WHERE clause constraints */
1.5427 + int nOrderBy; /* Number of terms in the ORDER BY clause */
1.5428 + struct sqlite3_index_orderby {
1.5429 + int iColumn; /* Column number */
1.5430 + unsigned char desc; /* True for DESC. False for ASC. */
1.5431 + } *aOrderBy; /* The ORDER BY clause */
1.5432 + /* Outputs */
1.5433 + struct sqlite3_index_constraint_usage {
1.5434 + int argvIndex; /* if >0, constraint is part of argv to xFilter */
1.5435 + unsigned char omit; /* Do not code a test for this constraint */
1.5436 + } *aConstraintUsage;
1.5437 + int idxNum; /* Number used to identify the index */
1.5438 + char *idxStr; /* String, possibly obtained from sqlite3_malloc */
1.5439 + int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
1.5440 + int orderByConsumed; /* True if output is already ordered */
1.5441 + double estimatedCost; /* Estimated cost of using this index */
1.5442 +};
1.5443 +#define SQLITE_INDEX_CONSTRAINT_EQ 2
1.5444 +#define SQLITE_INDEX_CONSTRAINT_GT 4
1.5445 +#define SQLITE_INDEX_CONSTRAINT_LE 8
1.5446 +#define SQLITE_INDEX_CONSTRAINT_LT 16
1.5447 +#define SQLITE_INDEX_CONSTRAINT_GE 32
1.5448 +#define SQLITE_INDEX_CONSTRAINT_MATCH 64
1.5449 +
1.5450 +/*
1.5451 +** CAPI3REF: Register A Virtual Table Implementation {H18200} <S20400>
1.5452 +** EXPERIMENTAL
1.5453 +**
1.5454 +** This routine is used to register a new module name with a
1.5455 +** [database connection]. Module names must be registered before
1.5456 +** creating new virtual tables on the module, or before using
1.5457 +** preexisting virtual tables of the module.
1.5458 +**
1.5459 +** This interface is experimental and is subject to change or
1.5460 +** removal in future releases of SQLite.
1.5461 +*/
1.5462 +IMPORT_C int sqlite3_create_module(
1.5463 + sqlite3 *db, /* SQLite connection to register module with */
1.5464 + const char *zName, /* Name of the module */
1.5465 + const sqlite3_module *, /* Methods for the module */
1.5466 + void * /* Client data for xCreate/xConnect */
1.5467 +);
1.5468 +
1.5469 +/*
1.5470 +** CAPI3REF: Register A Virtual Table Implementation {H18210} <S20400>
1.5471 +** EXPERIMENTAL
1.5472 +**
1.5473 +** This routine is identical to the [sqlite3_create_module()] method above,
1.5474 +** except that it allows a destructor function to be specified. It is
1.5475 +** even more experimental than the rest of the virtual tables API.
1.5476 +*/
1.5477 +IMPORT_C int sqlite3_create_module_v2(
1.5478 + sqlite3 *db, /* SQLite connection to register module with */
1.5479 + const char *zName, /* Name of the module */
1.5480 + const sqlite3_module *, /* Methods for the module */
1.5481 + void *, /* Client data for xCreate/xConnect */
1.5482 + void(*xDestroy)(void*) /* Module destructor function */
1.5483 +);
1.5484 +
1.5485 +/*
1.5486 +** CAPI3REF: Virtual Table Instance Object {H18010} <S20400>
1.5487 +** KEYWORDS: sqlite3_vtab
1.5488 +** EXPERIMENTAL
1.5489 +**
1.5490 +** Every module implementation uses a subclass of the following structure
1.5491 +** to describe a particular instance of the module. Each subclass will
1.5492 +** be tailored to the specific needs of the module implementation.
1.5493 +** The purpose of this superclass is to define certain fields that are
1.5494 +** common to all module implementations.
1.5495 +**
1.5496 +** Virtual tables methods can set an error message by assigning a
1.5497 +** string obtained from [sqlite3_mprintf()] to zErrMsg. The method should
1.5498 +** take care that any prior string is freed by a call to [sqlite3_free()]
1.5499 +** prior to assigning a new string to zErrMsg. After the error message
1.5500 +** is delivered up to the client application, the string will be automatically
1.5501 +** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note
1.5502 +** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field
1.5503 +** since virtual tables are commonly implemented in loadable extensions which
1.5504 +** do not have access to sqlite3MPrintf() or sqlite3Free().
1.5505 +**
1.5506 +** This interface is experimental and is subject to change or
1.5507 +** removal in future releases of SQLite.
1.5508 +*/
1.5509 +struct sqlite3_vtab {
1.5510 + const sqlite3_module *pModule; /* The module for this virtual table */
1.5511 + int nRef; /* Used internally */
1.5512 + char *zErrMsg; /* Error message from sqlite3_mprintf() */
1.5513 + /* Virtual table implementations will typically add additional fields */
1.5514 +};
1.5515 +
1.5516 +/*
1.5517 +** CAPI3REF: Virtual Table Cursor Object {H18020} <S20400>
1.5518 +** KEYWORDS: sqlite3_vtab_cursor
1.5519 +** EXPERIMENTAL
1.5520 +**
1.5521 +** Every module implementation uses a subclass of the following structure
1.5522 +** to describe cursors that point into the virtual table and are used
1.5523 +** to loop through the virtual table. Cursors are created using the
1.5524 +** xOpen method of the module. Each module implementation will define
1.5525 +** the content of a cursor structure to suit its own needs.
1.5526 +**
1.5527 +** This superclass exists in order to define fields of the cursor that
1.5528 +** are common to all implementations.
1.5529 +**
1.5530 +** This interface is experimental and is subject to change or
1.5531 +** removal in future releases of SQLite.
1.5532 +*/
1.5533 +struct sqlite3_vtab_cursor {
1.5534 + sqlite3_vtab *pVtab; /* Virtual table of this cursor */
1.5535 + /* Virtual table implementations will typically add additional fields */
1.5536 +};
1.5537 +
1.5538 +/*
1.5539 +** CAPI3REF: Declare The Schema Of A Virtual Table {H18280} <S20400>
1.5540 +** EXPERIMENTAL
1.5541 +**
1.5542 +** The xCreate and xConnect methods of a module use the following API
1.5543 +** to declare the format (the names and datatypes of the columns) of
1.5544 +** the virtual tables they implement.
1.5545 +**
1.5546 +** This interface is experimental and is subject to change or
1.5547 +** removal in future releases of SQLite.
1.5548 +*/
1.5549 +IMPORT_C int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable);
1.5550 +
1.5551 +/*
1.5552 +** CAPI3REF: Overload A Function For A Virtual Table {H18300} <S20400>
1.5553 +** EXPERIMENTAL
1.5554 +**
1.5555 +** Virtual tables can provide alternative implementations of functions
1.5556 +** using the xFindFunction method. But global versions of those functions
1.5557 +** must exist in order to be overloaded.
1.5558 +**
1.5559 +** This API makes sure a global version of a function with a particular
1.5560 +** name and number of parameters exists. If no such function exists
1.5561 +** before this API is called, a new function is created. The implementation
1.5562 +** of the new function always causes an exception to be thrown. So
1.5563 +** the new function is not good for anything by itself. Its only
1.5564 +** purpose is to be a placeholder function that can be overloaded
1.5565 +** by virtual tables.
1.5566 +**
1.5567 +** This API should be considered part of the virtual table interface,
1.5568 +** which is experimental and subject to change.
1.5569 +*/
1.5570 +IMPORT_C int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
1.5571 +
1.5572 +/*
1.5573 +** The interface to the virtual-table mechanism defined above (back up
1.5574 +** to a comment remarkably similar to this one) is currently considered
1.5575 +** to be experimental. The interface might change in incompatible ways.
1.5576 +** If this is a problem for you, do not use the interface at this time.
1.5577 +**
1.5578 +** When the virtual-table mechanism stabilizes, we will declare the
1.5579 +** interface fixed, support it indefinitely, and remove this comment.
1.5580 +**
1.5581 +****** EXPERIMENTAL - subject to change without notice **************
1.5582 +*/
1.5583 +
1.5584 +/*
1.5585 +** CAPI3REF: A Handle To An Open BLOB {H17800} <S30230>
1.5586 +** KEYWORDS: {BLOB handle} {BLOB handles}
1.5587 +**
1.5588 +** An instance of this object represents an open BLOB on which
1.5589 +** [sqlite3_blob_open | incremental BLOB I/O] can be performed.
1.5590 +** Objects of this type are created by [sqlite3_blob_open()]
1.5591 +** and destroyed by [sqlite3_blob_close()].
1.5592 +** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
1.5593 +** can be used to read or write small subsections of the BLOB.
1.5594 +** The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes.
1.5595 +*/
1.5596 +typedef struct sqlite3_blob sqlite3_blob;
1.5597 +
1.5598 +/*
1.5599 +** CAPI3REF: Open A BLOB For Incremental I/O {H17810} <S30230>
1.5600 +**
1.5601 +** This interfaces opens a [BLOB handle | handle] to the BLOB located
1.5602 +** in row iRow, column zColumn, table zTable in database zDb;
1.5603 +** in other words, the same BLOB that would be selected by:
1.5604 +**
1.5605 +** <pre>
1.5606 +** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;
1.5607 +** </pre> {END}
1.5608 +**
1.5609 +** If the flags parameter is non-zero, the the BLOB is opened for read
1.5610 +** and write access. If it is zero, the BLOB is opened for read access.
1.5611 +**
1.5612 +** Note that the database name is not the filename that contains
1.5613 +** the database but rather the symbolic name of the database that
1.5614 +** is assigned when the database is connected using [ATTACH].
1.5615 +** For the main database file, the database name is "main".
1.5616 +** For TEMP tables, the database name is "temp".
1.5617 +**
1.5618 +** On success, [SQLITE_OK] is returned and the new [BLOB handle] is written
1.5619 +** to *ppBlob. Otherwise an [error code] is returned and any value written
1.5620 +** to *ppBlob should not be used by the caller.
1.5621 +** This function sets the [database connection] error code and message
1.5622 +** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()].
1.5623 +**
1.5624 +** If the row that a BLOB handle points to is modified by an
1.5625 +** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
1.5626 +** then the BLOB handle is marked as "expired".
1.5627 +** This is true if any column of the row is changed, even a column
1.5628 +** other than the one the BLOB handle is open on.
1.5629 +** Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
1.5630 +** a expired BLOB handle fail with an return code of [SQLITE_ABORT].
1.5631 +** Changes written into a BLOB prior to the BLOB expiring are not
1.5632 +** rollback by the expiration of the BLOB. Such changes will eventually
1.5633 +** commit if the transaction continues to completion.
1.5634 +**
1.5635 +** INVARIANTS:
1.5636 +**
1.5637 +** {H17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)]
1.5638 +** interface shall open an [sqlite3_blob] object P on the BLOB
1.5639 +** in column C of the table T in the database B on
1.5640 +** the [database connection] D.
1.5641 +**
1.5642 +** {H17814} A successful invocation of [sqlite3_blob_open(D,...)] shall start
1.5643 +** a new transaction on the [database connection] D if that
1.5644 +** connection is not already in a transaction.
1.5645 +**
1.5646 +** {H17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface shall open
1.5647 +** the BLOB for read and write access if and only if the F
1.5648 +** parameter is non-zero.
1.5649 +**
1.5650 +** {H17819} The [sqlite3_blob_open()] interface shall return [SQLITE_OK] on
1.5651 +** success and an appropriate [error code] on failure.
1.5652 +**
1.5653 +** {H17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)]
1.5654 +** then subsequent calls to [sqlite3_errcode(D)],
1.5655 +** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return
1.5656 +** information appropriate for that error.
1.5657 +**
1.5658 +** {H17824} If any column in the row that a [sqlite3_blob] has open is
1.5659 +** changed by a separate [UPDATE] or [DELETE] statement or by
1.5660 +** an [ON CONFLICT] side effect, then the [sqlite3_blob] shall
1.5661 +** be marked as invalid.
1.5662 +*/
1.5663 +IMPORT_C int sqlite3_blob_open(
1.5664 + sqlite3*,
1.5665 + const char *zDb,
1.5666 + const char *zTable,
1.5667 + const char *zColumn,
1.5668 + sqlite3_int64 iRow,
1.5669 + int flags,
1.5670 + sqlite3_blob **ppBlob
1.5671 +);
1.5672 +
1.5673 +/*
1.5674 +** CAPI3REF: Close A BLOB Handle {H17830} <S30230>
1.5675 +**
1.5676 +** Closes an open [BLOB handle].
1.5677 +**
1.5678 +** Closing a BLOB shall cause the current transaction to commit
1.5679 +** if there are no other BLOBs, no pending prepared statements, and the
1.5680 +** database connection is in [autocommit mode].
1.5681 +** If any writes were made to the BLOB, they might be held in cache
1.5682 +** until the close operation if they will fit. {END}
1.5683 +**
1.5684 +** Closing the BLOB often forces the changes
1.5685 +** out to disk and so if any I/O errors occur, they will likely occur
1.5686 +** at the time when the BLOB is closed. {H17833} Any errors that occur during
1.5687 +** closing are reported as a non-zero return value.
1.5688 +**
1.5689 +** The BLOB is closed unconditionally. Even if this routine returns
1.5690 +** an error code, the BLOB is still closed.
1.5691 +**
1.5692 +** INVARIANTS:
1.5693 +**
1.5694 +** {H17833} The [sqlite3_blob_close(P)] interface closes an [sqlite3_blob]
1.5695 +** object P previously opened using [sqlite3_blob_open()].
1.5696 +**
1.5697 +** {H17836} Closing an [sqlite3_blob] object using
1.5698 +** [sqlite3_blob_close()] shall cause the current transaction to
1.5699 +** commit if there are no other open [sqlite3_blob] objects
1.5700 +** or [prepared statements] on the same [database connection] and
1.5701 +** the database connection is in [autocommit mode].
1.5702 +**
1.5703 +** {H17839} The [sqlite3_blob_close(P)] interfaces shall close the
1.5704 +** [sqlite3_blob] object P unconditionally, even if
1.5705 +** [sqlite3_blob_close(P)] returns something other than [SQLITE_OK].
1.5706 +*/
1.5707 +IMPORT_C int sqlite3_blob_close(sqlite3_blob *);
1.5708 +
1.5709 +/*
1.5710 +** CAPI3REF: Return The Size Of An Open BLOB {H17840} <S30230>
1.5711 +**
1.5712 +** Returns the size in bytes of the BLOB accessible via the open
1.5713 +** []BLOB handle] in its only argument.
1.5714 +**
1.5715 +** INVARIANTS:
1.5716 +**
1.5717 +** {H17843} The [sqlite3_blob_bytes(P)] interface returns the size
1.5718 +** in bytes of the BLOB that the [sqlite3_blob] object P
1.5719 +** refers to.
1.5720 +*/
1.5721 +IMPORT_C int sqlite3_blob_bytes(sqlite3_blob *);
1.5722 +
1.5723 +/*
1.5724 +** CAPI3REF: Read Data From A BLOB Incrementally {H17850} <S30230>
1.5725 +**
1.5726 +** This function is used to read data from an open [BLOB handle] into a
1.5727 +** caller-supplied buffer. N bytes of data are copied into buffer Z
1.5728 +** from the open BLOB, starting at offset iOffset.
1.5729 +**
1.5730 +** If offset iOffset is less than N bytes from the end of the BLOB,
1.5731 +** [SQLITE_ERROR] is returned and no data is read. If N or iOffset is
1.5732 +** less than zero, [SQLITE_ERROR] is returned and no data is read.
1.5733 +**
1.5734 +** An attempt to read from an expired [BLOB handle] fails with an
1.5735 +** error code of [SQLITE_ABORT].
1.5736 +**
1.5737 +** On success, SQLITE_OK is returned.
1.5738 +** Otherwise, an [error code] or an [extended error code] is returned.
1.5739 +**
1.5740 +** INVARIANTS:
1.5741 +**
1.5742 +** {H17853} A successful invocation of [sqlite3_blob_read(P,Z,N,X)]
1.5743 +** shall reads N bytes of data out of the BLOB referenced by
1.5744 +** [BLOB handle] P beginning at offset X and store those bytes
1.5745 +** into buffer Z.
1.5746 +**
1.5747 +** {H17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the BLOB
1.5748 +** is less than N+X bytes, then the function shall leave the
1.5749 +** Z buffer unchanged and return [SQLITE_ERROR].
1.5750 +**
1.5751 +** {H17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero
1.5752 +** then the function shall leave the Z buffer unchanged
1.5753 +** and return [SQLITE_ERROR].
1.5754 +**
1.5755 +** {H17862} The [sqlite3_blob_read(P,Z,N,X)] interface shall return [SQLITE_OK]
1.5756 +** if N bytes are successfully read into buffer Z.
1.5757 +**
1.5758 +** {H17863} If the [BLOB handle] P is expired and X and N are within bounds
1.5759 +** then [sqlite3_blob_read(P,Z,N,X)] shall leave the Z buffer
1.5760 +** unchanged and return [SQLITE_ABORT].
1.5761 +**
1.5762 +** {H17865} If the requested read could not be completed,
1.5763 +** the [sqlite3_blob_read(P,Z,N,X)] interface shall return an
1.5764 +** appropriate [error code] or [extended error code].
1.5765 +**
1.5766 +** {H17868} If an error occurs during evaluation of [sqlite3_blob_read(P,...)]
1.5767 +** then subsequent calls to [sqlite3_errcode(D)],
1.5768 +** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return
1.5769 +** information appropriate for that error, where D is the
1.5770 +** [database connection] that was used to open the [BLOB handle] P.
1.5771 +*/
1.5772 +IMPORT_C int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
1.5773 +
1.5774 +/*
1.5775 +** CAPI3REF: Write Data Into A BLOB Incrementally {H17870} <S30230>
1.5776 +**
1.5777 +** This function is used to write data into an open [BLOB handle] from a
1.5778 +** caller-supplied buffer. N bytes of data are copied from the buffer Z
1.5779 +** into the open BLOB, starting at offset iOffset.
1.5780 +**
1.5781 +** If the [BLOB handle] passed as the first argument was not opened for
1.5782 +** writing (the flags parameter to [sqlite3_blob_open()] was zero),
1.5783 +** this function returns [SQLITE_READONLY].
1.5784 +**
1.5785 +** This function may only modify the contents of the BLOB; it is
1.5786 +** not possible to increase the size of a BLOB using this API.
1.5787 +** If offset iOffset is less than N bytes from the end of the BLOB,
1.5788 +** [SQLITE_ERROR] is returned and no data is written. If N is
1.5789 +** less than zero [SQLITE_ERROR] is returned and no data is written.
1.5790 +**
1.5791 +** An attempt to write to an expired [BLOB handle] fails with an
1.5792 +** error code of [SQLITE_ABORT]. Writes to the BLOB that occurred
1.5793 +** before the [BLOB handle] expired are not rolled back by the
1.5794 +** expiration of the handle, though of course those changes might
1.5795 +** have been overwritten by the statement that expired the BLOB handle
1.5796 +** or by other independent statements.
1.5797 +**
1.5798 +** On success, SQLITE_OK is returned.
1.5799 +** Otherwise, an [error code] or an [extended error code] is returned.
1.5800 +**
1.5801 +** INVARIANTS:
1.5802 +**
1.5803 +** {H17873} A successful invocation of [sqlite3_blob_write(P,Z,N,X)]
1.5804 +** shall write N bytes of data from buffer Z into the BLOB
1.5805 +** referenced by [BLOB handle] P beginning at offset X into
1.5806 +** the BLOB.
1.5807 +**
1.5808 +** {H17874} In the absence of other overridding changes, the changes
1.5809 +** written to a BLOB by [sqlite3_blob_write()] shall
1.5810 +** remain in effect after the associated [BLOB handle] expires.
1.5811 +**
1.5812 +** {H17875} If the [BLOB handle] P was opened for reading only then
1.5813 +** an invocation of [sqlite3_blob_write(P,Z,N,X)] shall leave
1.5814 +** the referenced BLOB unchanged and return [SQLITE_READONLY].
1.5815 +**
1.5816 +** {H17876} If the size of the BLOB referenced by [BLOB handle] P is
1.5817 +** less than N+X bytes then [sqlite3_blob_write(P,Z,N,X)] shall
1.5818 +** leave the BLOB unchanged and return [SQLITE_ERROR].
1.5819 +**
1.5820 +** {H17877} If the [BLOB handle] P is expired and X and N are within bounds
1.5821 +** then [sqlite3_blob_read(P,Z,N,X)] shall leave the BLOB
1.5822 +** unchanged and return [SQLITE_ABORT].
1.5823 +**
1.5824 +** {H17879} If X or N are less than zero then [sqlite3_blob_write(P,Z,N,X)]
1.5825 +** shall leave the BLOB referenced by [BLOB handle] P unchanged
1.5826 +** and return [SQLITE_ERROR].
1.5827 +**
1.5828 +** {H17882} The [sqlite3_blob_write(P,Z,N,X)] interface shall return
1.5829 +** [SQLITE_OK] if N bytes where successfully written into the BLOB.
1.5830 +**
1.5831 +** {H17885} If the requested write could not be completed,
1.5832 +** the [sqlite3_blob_write(P,Z,N,X)] interface shall return an
1.5833 +** appropriate [error code] or [extended error code].
1.5834 +**
1.5835 +** {H17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)]
1.5836 +** then subsequent calls to [sqlite3_errcode(D)],
1.5837 +** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return
1.5838 +** information appropriate for that error.
1.5839 +*/
1.5840 +IMPORT_C int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
1.5841 +
1.5842 +/*
1.5843 +** CAPI3REF: Virtual File System Objects {H11200} <S20100>
1.5844 +**
1.5845 +** A virtual filesystem (VFS) is an [sqlite3_vfs] object
1.5846 +** that SQLite uses to interact
1.5847 +** with the underlying operating system. Most SQLite builds come with a
1.5848 +** single default VFS that is appropriate for the host computer.
1.5849 +** New VFSes can be registered and existing VFSes can be unregistered.
1.5850 +** The following interfaces are provided.
1.5851 +**
1.5852 +** The sqlite3_vfs_find() interface returns a pointer to a VFS given its name.
1.5853 +** Names are case sensitive.
1.5854 +** Names are zero-terminated UTF-8 strings.
1.5855 +** If there is no match, a NULL pointer is returned.
1.5856 +** If zVfsName is NULL then the default VFS is returned.
1.5857 +**
1.5858 +** New VFSes are registered with sqlite3_vfs_register().
1.5859 +** Each new VFS becomes the default VFS if the makeDflt flag is set.
1.5860 +** The same VFS can be registered multiple times without injury.
1.5861 +** To make an existing VFS into the default VFS, register it again
1.5862 +** with the makeDflt flag set. If two different VFSes with the
1.5863 +** same name are registered, the behavior is undefined. If a
1.5864 +** VFS is registered with a name that is NULL or an empty string,
1.5865 +** then the behavior is undefined.
1.5866 +**
1.5867 +** Unregister a VFS with the sqlite3_vfs_unregister() interface.
1.5868 +** If the default VFS is unregistered, another VFS is chosen as
1.5869 +** the default. The choice for the new VFS is arbitrary.
1.5870 +**
1.5871 +** INVARIANTS:
1.5872 +**
1.5873 +** {H11203} The [sqlite3_vfs_find(N)] interface returns a pointer to the
1.5874 +** registered [sqlite3_vfs] object whose name exactly matches
1.5875 +** the zero-terminated UTF-8 string N, or it returns NULL if
1.5876 +** there is no match.
1.5877 +**
1.5878 +** {H11206} If the N parameter to [sqlite3_vfs_find(N)] is NULL then
1.5879 +** the function returns a pointer to the default [sqlite3_vfs]
1.5880 +** object if there is one, or NULL if there is no default
1.5881 +** [sqlite3_vfs] object.
1.5882 +**
1.5883 +** {H11209} The [sqlite3_vfs_register(P,F)] interface registers the
1.5884 +** well-formed [sqlite3_vfs] object P using the name given
1.5885 +** by the zName field of the object.
1.5886 +**
1.5887 +** {H11212} Using the [sqlite3_vfs_register(P,F)] interface to register
1.5888 +** the same [sqlite3_vfs] object multiple times is a harmless no-op.
1.5889 +**
1.5890 +** {H11215} The [sqlite3_vfs_register(P,F)] interface makes the [sqlite3_vfs]
1.5891 +** object P the default [sqlite3_vfs] object if F is non-zero.
1.5892 +**
1.5893 +** {H11218} The [sqlite3_vfs_unregister(P)] interface unregisters the
1.5894 +** [sqlite3_vfs] object P so that it is no longer returned by
1.5895 +** subsequent calls to [sqlite3_vfs_find()].
1.5896 +*/
1.5897 +IMPORT_C sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
1.5898 +IMPORT_C int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
1.5899 +IMPORT_C int sqlite3_vfs_unregister(sqlite3_vfs*);
1.5900 +
1.5901 +/*
1.5902 +** CAPI3REF: Mutexes {H17000} <S20000>
1.5903 +**
1.5904 +** The SQLite core uses these routines for thread
1.5905 +** synchronization. Though they are intended for internal
1.5906 +** use by SQLite, code that links against SQLite is
1.5907 +** permitted to use any of these routines.
1.5908 +**
1.5909 +** The SQLite source code contains multiple implementations
1.5910 +** of these mutex routines. An appropriate implementation
1.5911 +** is selected automatically at compile-time. The following
1.5912 +** implementations are available in the SQLite core:
1.5913 +**
1.5914 +** <ul>
1.5915 +** <li> SQLITE_MUTEX_OS2
1.5916 +** <li> SQLITE_MUTEX_PTHREAD
1.5917 +** <li> SQLITE_MUTEX_W32
1.5918 +** <li> SQLITE_MUTEX_NOOP
1.5919 +** </ul>
1.5920 +**
1.5921 +** The SQLITE_MUTEX_NOOP implementation is a set of routines
1.5922 +** that does no real locking and is appropriate for use in
1.5923 +** a single-threaded application. The SQLITE_MUTEX_OS2,
1.5924 +** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations
1.5925 +** are appropriate for use on OS/2, Unix, and Windows.
1.5926 +**
1.5927 +** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
1.5928 +** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
1.5929 +** implementation is included with the library. In this case the
1.5930 +** application must supply a custom mutex implementation using the
1.5931 +** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function
1.5932 +** before calling sqlite3_initialize() or any other public sqlite3_
1.5933 +** function that calls sqlite3_initialize().
1.5934 +**
1.5935 +** {H17011} The sqlite3_mutex_alloc() routine allocates a new
1.5936 +** mutex and returns a pointer to it. {H17012} If it returns NULL
1.5937 +** that means that a mutex could not be allocated. {H17013} SQLite
1.5938 +** will unwind its stack and return an error. {H17014} The argument
1.5939 +** to sqlite3_mutex_alloc() is one of these integer constants:
1.5940 +**
1.5941 +** <ul>
1.5942 +** <li> SQLITE_MUTEX_FAST
1.5943 +** <li> SQLITE_MUTEX_RECURSIVE
1.5944 +** <li> SQLITE_MUTEX_STATIC_MASTER
1.5945 +** <li> SQLITE_MUTEX_STATIC_MEM
1.5946 +** <li> SQLITE_MUTEX_STATIC_MEM2
1.5947 +** <li> SQLITE_MUTEX_STATIC_PRNG
1.5948 +** <li> SQLITE_MUTEX_STATIC_LRU
1.5949 +** <li> SQLITE_MUTEX_STATIC_LRU2
1.5950 +** </ul>
1.5951 +**
1.5952 +** {H17015} The first two constants cause sqlite3_mutex_alloc() to create
1.5953 +** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
1.5954 +** is used but not necessarily so when SQLITE_MUTEX_FAST is used. {END}
1.5955 +** The mutex implementation does not need to make a distinction
1.5956 +** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
1.5957 +** not want to. {H17016} But SQLite will only request a recursive mutex in
1.5958 +** cases where it really needs one. {END} If a faster non-recursive mutex
1.5959 +** implementation is available on the host platform, the mutex subsystem
1.5960 +** might return such a mutex in response to SQLITE_MUTEX_FAST.
1.5961 +**
1.5962 +** {H17017} The other allowed parameters to sqlite3_mutex_alloc() each return
1.5963 +** a pointer to a static preexisting mutex. {END} Four static mutexes are
1.5964 +** used by the current version of SQLite. Future versions of SQLite
1.5965 +** may add additional static mutexes. Static mutexes are for internal
1.5966 +** use by SQLite only. Applications that use SQLite mutexes should
1.5967 +** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
1.5968 +** SQLITE_MUTEX_RECURSIVE.
1.5969 +**
1.5970 +** {H17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
1.5971 +** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
1.5972 +** returns a different mutex on every call. {H17034} But for the static
1.5973 +** mutex types, the same mutex is returned on every call that has
1.5974 +** the same type number.
1.5975 +**
1.5976 +** {H17019} The sqlite3_mutex_free() routine deallocates a previously
1.5977 +** allocated dynamic mutex. {H17020} SQLite is careful to deallocate every
1.5978 +** dynamic mutex that it allocates. {A17021} The dynamic mutexes must not be in
1.5979 +** use when they are deallocated. {A17022} Attempting to deallocate a static
1.5980 +** mutex results in undefined behavior. {H17023} SQLite never deallocates
1.5981 +** a static mutex. {END}
1.5982 +**
1.5983 +** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
1.5984 +** to enter a mutex. {H17024} If another thread is already within the mutex,
1.5985 +** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
1.5986 +** SQLITE_BUSY. {H17025} The sqlite3_mutex_try() interface returns [SQLITE_OK]
1.5987 +** upon successful entry. {H17026} Mutexes created using
1.5988 +** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
1.5989 +** {H17027} In such cases the,
1.5990 +** mutex must be exited an equal number of times before another thread
1.5991 +** can enter. {A17028} If the same thread tries to enter any other
1.5992 +** kind of mutex more than once, the behavior is undefined.
1.5993 +** {H17029} SQLite will never exhibit
1.5994 +** such behavior in its own use of mutexes.
1.5995 +**
1.5996 +** Some systems (for example, Windows 95) do not support the operation
1.5997 +** implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try()
1.5998 +** will always return SQLITE_BUSY. {H17030} The SQLite core only ever uses
1.5999 +** sqlite3_mutex_try() as an optimization so this is acceptable behavior.
1.6000 +**
1.6001 +** {H17031} The sqlite3_mutex_leave() routine exits a mutex that was
1.6002 +** previously entered by the same thread. {A17032} The behavior
1.6003 +** is undefined if the mutex is not currently entered by the
1.6004 +** calling thread or is not currently allocated. {H17033} SQLite will
1.6005 +** never do either. {END}
1.6006 +**
1.6007 +** If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or
1.6008 +** sqlite3_mutex_leave() is a NULL pointer, then all three routines
1.6009 +** behave as no-ops.
1.6010 +**
1.6011 +** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
1.6012 +*/
1.6013 +IMPORT_C sqlite3_mutex *sqlite3_mutex_alloc(int);
1.6014 +IMPORT_C void sqlite3_mutex_free(sqlite3_mutex*);
1.6015 +IMPORT_C void sqlite3_mutex_enter(sqlite3_mutex*);
1.6016 +IMPORT_C int sqlite3_mutex_try(sqlite3_mutex*);
1.6017 +IMPORT_C void sqlite3_mutex_leave(sqlite3_mutex*);
1.6018 +
1.6019 +/*
1.6020 +** CAPI3REF: Mutex Methods Object {H17120} <S20130>
1.6021 +** EXPERIMENTAL
1.6022 +**
1.6023 +** An instance of this structure defines the low-level routines
1.6024 +** used to allocate and use mutexes.
1.6025 +**
1.6026 +** Usually, the default mutex implementations provided by SQLite are
1.6027 +** sufficient, however the user has the option of substituting a custom
1.6028 +** implementation for specialized deployments or systems for which SQLite
1.6029 +** does not provide a suitable implementation. In this case, the user
1.6030 +** creates and populates an instance of this structure to pass
1.6031 +** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option.
1.6032 +** Additionally, an instance of this structure can be used as an
1.6033 +** output variable when querying the system for the current mutex
1.6034 +** implementation, using the [SQLITE_CONFIG_GETMUTEX] option.
1.6035 +**
1.6036 +** The xMutexInit method defined by this structure is invoked as
1.6037 +** part of system initialization by the sqlite3_initialize() function.
1.6038 +** {H17001} The xMutexInit routine shall be called by SQLite once for each
1.6039 +** effective call to [sqlite3_initialize()].
1.6040 +**
1.6041 +** The xMutexEnd method defined by this structure is invoked as
1.6042 +** part of system shutdown by the sqlite3_shutdown() function. The
1.6043 +** implementation of this method is expected to release all outstanding
1.6044 +** resources obtained by the mutex methods implementation, especially
1.6045 +** those obtained by the xMutexInit method. {H17003} The xMutexEnd()
1.6046 +** interface shall be invoked once for each call to [sqlite3_shutdown()].
1.6047 +**
1.6048 +** The remaining seven methods defined by this structure (xMutexAlloc,
1.6049 +** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and
1.6050 +** xMutexNotheld) implement the following interfaces (respectively):
1.6051 +**
1.6052 +** <ul>
1.6053 +** <li> [sqlite3_mutex_alloc()] </li>
1.6054 +** <li> [sqlite3_mutex_free()] </li>
1.6055 +** <li> [sqlite3_mutex_enter()] </li>
1.6056 +** <li> [sqlite3_mutex_try()] </li>
1.6057 +** <li> [sqlite3_mutex_leave()] </li>
1.6058 +** <li> [sqlite3_mutex_held()] </li>
1.6059 +** <li> [sqlite3_mutex_notheld()] </li>
1.6060 +** </ul>
1.6061 +**
1.6062 +** The only difference is that the public sqlite3_XXX functions enumerated
1.6063 +** above silently ignore any invocations that pass a NULL pointer instead
1.6064 +** of a valid mutex handle. The implementations of the methods defined
1.6065 +** by this structure are not required to handle this case, the results
1.6066 +** of passing a NULL pointer instead of a valid mutex handle are undefined
1.6067 +** (i.e. it is acceptable to provide an implementation that segfaults if
1.6068 +** it is passed a NULL pointer).
1.6069 +*/
1.6070 +typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
1.6071 +struct sqlite3_mutex_methods {
1.6072 + int (*xMutexInit)(void);
1.6073 + int (*xMutexEnd)(void);
1.6074 + sqlite3_mutex *(*xMutexAlloc)(int);
1.6075 + void (*xMutexFree)(sqlite3_mutex *);
1.6076 + void (*xMutexEnter)(sqlite3_mutex *);
1.6077 + int (*xMutexTry)(sqlite3_mutex *);
1.6078 + void (*xMutexLeave)(sqlite3_mutex *);
1.6079 + int (*xMutexHeld)(sqlite3_mutex *);
1.6080 + int (*xMutexNotheld)(sqlite3_mutex *);
1.6081 +};
1.6082 +
1.6083 +/*
1.6084 +** CAPI3REF: Mutex Verification Routines {H17080} <S20130> <S30800>
1.6085 +**
1.6086 +** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
1.6087 +** are intended for use inside assert() statements. {H17081} The SQLite core
1.6088 +** never uses these routines except inside an assert() and applications
1.6089 +** are advised to follow the lead of the core. {H17082} The core only
1.6090 +** provides implementations for these routines when it is compiled
1.6091 +** with the SQLITE_DEBUG flag. {A17087} External mutex implementations
1.6092 +** are only required to provide these routines if SQLITE_DEBUG is
1.6093 +** defined and if NDEBUG is not defined.
1.6094 +**
1.6095 +** {H17083} These routines should return true if the mutex in their argument
1.6096 +** is held or not held, respectively, by the calling thread.
1.6097 +**
1.6098 +** {X17084} The implementation is not required to provided versions of these
1.6099 +** routines that actually work. If the implementation does not provide working
1.6100 +** versions of these routines, it should at least provide stubs that always
1.6101 +** return true so that one does not get spurious assertion failures.
1.6102 +**
1.6103 +** {H17085} If the argument to sqlite3_mutex_held() is a NULL pointer then
1.6104 +** the routine should return 1. {END} This seems counter-intuitive since
1.6105 +** clearly the mutex cannot be held if it does not exist. But the
1.6106 +** the reason the mutex does not exist is because the build is not
1.6107 +** using mutexes. And we do not want the assert() containing the
1.6108 +** call to sqlite3_mutex_held() to fail, so a non-zero return is
1.6109 +** the appropriate thing to do. {H17086} The sqlite3_mutex_notheld()
1.6110 +** interface should also return 1 when given a NULL pointer.
1.6111 +*/
1.6112 +IMPORT_C int sqlite3_mutex_held(sqlite3_mutex*);
1.6113 +IMPORT_C int sqlite3_mutex_notheld(sqlite3_mutex*);
1.6114 +
1.6115 +/*
1.6116 +** CAPI3REF: Mutex Types {H17001} <H17000>
1.6117 +**
1.6118 +** The [sqlite3_mutex_alloc()] interface takes a single argument
1.6119 +** which is one of these integer constants.
1.6120 +**
1.6121 +** The set of static mutexes may change from one SQLite release to the
1.6122 +** next. Applications that override the built-in mutex logic must be
1.6123 +** prepared to accommodate additional static mutexes.
1.6124 +*/
1.6125 +#define SQLITE_MUTEX_FAST 0
1.6126 +#define SQLITE_MUTEX_RECURSIVE 1
1.6127 +#define SQLITE_MUTEX_STATIC_MASTER 2
1.6128 +#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */
1.6129 +#define SQLITE_MUTEX_STATIC_MEM2 4 /* sqlite3_release_memory() */
1.6130 +#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */
1.6131 +#define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
1.6132 +#define SQLITE_MUTEX_STATIC_LRU2 7 /* lru page list */
1.6133 +
1.6134 +/*
1.6135 +** CAPI3REF: Low-Level Control Of Database Files {H11300} <S30800>
1.6136 +**
1.6137 +** {H11301} The [sqlite3_file_control()] interface makes a direct call to the
1.6138 +** xFileControl method for the [sqlite3_io_methods] object associated
1.6139 +** with a particular database identified by the second argument. {H11302} The
1.6140 +** name of the database is the name assigned to the database by the
1.6141 +** <a href="lang_attach.html">ATTACH</a> SQL command that opened the
1.6142 +** database. {H11303} To control the main database file, use the name "main"
1.6143 +** or a NULL pointer. {H11304} The third and fourth parameters to this routine
1.6144 +** are passed directly through to the second and third parameters of
1.6145 +** the xFileControl method. {H11305} The return value of the xFileControl
1.6146 +** method becomes the return value of this routine.
1.6147 +**
1.6148 +** {H11306} If the second parameter (zDbName) does not match the name of any
1.6149 +** open database file, then SQLITE_ERROR is returned. {H11307} This error
1.6150 +** code is not remembered and will not be recalled by [sqlite3_errcode()]
1.6151 +** or [sqlite3_errmsg()]. {A11308} The underlying xFileControl method might
1.6152 +** also return SQLITE_ERROR. {A11309} There is no way to distinguish between
1.6153 +** an incorrect zDbName and an SQLITE_ERROR return from the underlying
1.6154 +** xFileControl method. {END}
1.6155 +**
1.6156 +** See also: [SQLITE_FCNTL_LOCKSTATE]
1.6157 +*/
1.6158 +IMPORT_C int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
1.6159 +
1.6160 +/*
1.6161 +** CAPI3REF: Testing Interface {H11400} <S30800>
1.6162 +**
1.6163 +** The sqlite3_test_control() interface is used to read out internal
1.6164 +** state of SQLite and to inject faults into SQLite for testing
1.6165 +** purposes. The first parameter is an operation code that determines
1.6166 +** the number, meaning, and operation of all subsequent parameters.
1.6167 +**
1.6168 +** This interface is not for use by applications. It exists solely
1.6169 +** for verifying the correct operation of the SQLite library. Depending
1.6170 +** on how the SQLite library is compiled, this interface might not exist.
1.6171 +**
1.6172 +** The details of the operation codes, their meanings, the parameters
1.6173 +** they take, and what they do are all subject to change without notice.
1.6174 +** Unlike most of the SQLite API, this function is not guaranteed to
1.6175 +** operate consistently from one release to the next.
1.6176 +*/
1.6177 +IMPORT_C int sqlite3_test_control(int op, ...);
1.6178 +
1.6179 +/*
1.6180 +** CAPI3REF: Testing Interface Operation Codes {H11410} <H11400>
1.6181 +**
1.6182 +** These constants are the valid operation code parameters used
1.6183 +** as the first argument to [sqlite3_test_control()].
1.6184 +**
1.6185 +** These parameters and their meanings are subject to change
1.6186 +** without notice. These values are for testing purposes only.
1.6187 +** Applications should not use any of these parameters or the
1.6188 +** [sqlite3_test_control()] interface.
1.6189 +*/
1.6190 +#define SQLITE_TESTCTRL_PRNG_SAVE 5
1.6191 +#define SQLITE_TESTCTRL_PRNG_RESTORE 6
1.6192 +#define SQLITE_TESTCTRL_PRNG_RESET 7
1.6193 +#define SQLITE_TESTCTRL_BITVEC_TEST 8
1.6194 +#define SQLITE_TESTCTRL_FAULT_INSTALL 9
1.6195 +#define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10
1.6196 +
1.6197 +/*
1.6198 +** CAPI3REF: SQLite Runtime Status {H17200} <S60200>
1.6199 +** EXPERIMENTAL
1.6200 +**
1.6201 +** This interface is used to retrieve runtime status information
1.6202 +** about the preformance of SQLite, and optionally to reset various
1.6203 +** highwater marks. The first argument is an integer code for
1.6204 +** the specific parameter to measure. Recognized integer codes
1.6205 +** are of the form [SQLITE_STATUS_MEMORY_USED | SQLITE_STATUS_...].
1.6206 +** The current value of the parameter is returned into *pCurrent.
1.6207 +** The highest recorded value is returned in *pHighwater. If the
1.6208 +** resetFlag is true, then the highest record value is reset after
1.6209 +** *pHighwater is written. Some parameters do not record the highest
1.6210 +** value. For those parameters
1.6211 +** nothing is written into *pHighwater and the resetFlag is ignored.
1.6212 +** Other parameters record only the highwater mark and not the current
1.6213 +** value. For these latter parameters nothing is written into *pCurrent.
1.6214 +**
1.6215 +** This routine returns SQLITE_OK on success and a non-zero
1.6216 +** [error code] on failure.
1.6217 +**
1.6218 +** This routine is threadsafe but is not atomic. This routine can
1.6219 +** called while other threads are running the same or different SQLite
1.6220 +** interfaces. However the values returned in *pCurrent and
1.6221 +** *pHighwater reflect the status of SQLite at different points in time
1.6222 +** and it is possible that another thread might change the parameter
1.6223 +** in between the times when *pCurrent and *pHighwater are written.
1.6224 +**
1.6225 +** See also: [sqlite3_db_status()]
1.6226 +*/
1.6227 +IMPORT_C int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
1.6228 +
1.6229 +/*
1.6230 +** CAPI3REF: Database Connection Status {H17201} <S60200>
1.6231 +** EXPERIMENTAL
1.6232 +**
1.6233 +** This interface is used to retrieve runtime status information
1.6234 +** about a single [database connection]. The first argument is the
1.6235 +** database connection object to be interrogated. The second argument
1.6236 +** is the parameter to interrogate. Currently, the only allowed value
1.6237 +** for the second parameter is [SQLITE_DBSTATUS_LOOKASIDE_USED].
1.6238 +** Additional options will likely appear in future releases of SQLite.
1.6239 +**
1.6240 +** The current value of the request parameter is written into *pCur
1.6241 +** and the highest instantaneous value is written into *pHiwtr. If
1.6242 +** the resetFlg is true, then the highest instantaneous value is
1.6243 +** reset back down to the current value.
1.6244 +**
1.6245 +** See also: [sqlite3_status()].
1.6246 +*/
1.6247 +IMPORT_C int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
1.6248 +
1.6249 +
1.6250 +int sqlite3_wsd_init(int N, int J);
1.6251 +void *sqlite3_wsd_find(void *K, int L);
1.6252 +
1.6253 +/*
1.6254 +** CAPI3REF: Status Parameters {H17250} <H17200>
1.6255 +** EXPERIMENTAL
1.6256 +**
1.6257 +** These integer constants designate various run-time status parameters
1.6258 +** that can be returned by [sqlite3_status()].
1.6259 +**
1.6260 +** <dl>
1.6261 +** <dt>SQLITE_STATUS_MEMORY_USED</dt>
1.6262 +** <dd>This parameter is the current amount of memory checked out
1.6263 +** using [sqlite3_malloc()], either directly or indirectly. The
1.6264 +** figure includes calls made to [sqlite3_malloc()] by the application
1.6265 +** and internal memory usage by the SQLite library. Scratch memory
1.6266 +** controlled by [SQLITE_CONFIG_SCRATCH] and auxiliary page-cache
1.6267 +** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
1.6268 +** this parameter. The amount returned is the sum of the allocation
1.6269 +** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>
1.6270 +**
1.6271 +** <dt>SQLITE_STATUS_MALLOC_SIZE</dt>
1.6272 +** <dd>This parameter records the largest memory allocation request
1.6273 +** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their
1.6274 +** internal equivalents). Only the value returned in the
1.6275 +** *pHighwater parameter to [sqlite3_status()] is of interest.
1.6276 +** The value written into the *pCurrent parameter is undefined.</dd>
1.6277 +**
1.6278 +** <dt>SQLITE_STATUS_PAGECACHE_USED</dt>
1.6279 +** <dd>This parameter returns the number of pages used out of the
1.6280 +** [pagecache memory allocator] that was configured using
1.6281 +** [SQLITE_CONFIG_PAGECACHE]. The
1.6282 +** value returned is in pages, not in bytes.</dd>
1.6283 +**
1.6284 +** <dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt>
1.6285 +** <dd>This parameter returns the number of bytes of page cache
1.6286 +** allocation which could not be statisfied by the [SQLITE_CONFIG_PAGECACHE]
1.6287 +** buffer and where forced to overflow to [sqlite3_malloc()]. The
1.6288 +** returned value includes allocations that overflowed because they
1.6289 +** where too large (they were larger than the "sz" parameter to
1.6290 +** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because
1.6291 +** no space was left in the page cache.</dd>
1.6292 +**
1.6293 +** <dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>
1.6294 +** <dd>This parameter records the largest memory allocation request
1.6295 +** handed to [pagecache memory allocator]. Only the value returned in the
1.6296 +** *pHighwater parameter to [sqlite3_status()] is of interest.
1.6297 +** The value written into the *pCurrent parameter is undefined.</dd>
1.6298 +**
1.6299 +** <dt>SQLITE_STATUS_SCRATCH_USED</dt>
1.6300 +** <dd>This parameter returns the number of allocations used out of the
1.6301 +** [scratch memory allocator] configured using
1.6302 +** [SQLITE_CONFIG_SCRATCH]. The value returned is in allocations, not
1.6303 +** in bytes. Since a single thread may only have one scratch allocation
1.6304 +** outstanding at time, this parameter also reports the number of threads
1.6305 +** using scratch memory at the same time.</dd>
1.6306 +**
1.6307 +** <dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>
1.6308 +** <dd>This parameter returns the number of bytes of scratch memory
1.6309 +** allocation which could not be statisfied by the [SQLITE_CONFIG_SCRATCH]
1.6310 +** buffer and where forced to overflow to [sqlite3_malloc()]. The values
1.6311 +** returned include overflows because the requested allocation was too
1.6312 +** larger (that is, because the requested allocation was larger than the
1.6313 +** "sz" parameter to [SQLITE_CONFIG_SCRATCH]) and because no scratch buffer
1.6314 +** slots were available.
1.6315 +** </dd>
1.6316 +**
1.6317 +** <dt>SQLITE_STATUS_SCRATCH_SIZE</dt>
1.6318 +** <dd>This parameter records the largest memory allocation request
1.6319 +** handed to [scratch memory allocator]. Only the value returned in the
1.6320 +** *pHighwater parameter to [sqlite3_status()] is of interest.
1.6321 +** The value written into the *pCurrent parameter is undefined.</dd>
1.6322 +**
1.6323 +** <dt>SQLITE_STATUS_PARSER_STACK</dt>
1.6324 +** <dd>This parameter records the deepest parser stack. It is only
1.6325 +** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>
1.6326 +** </dl>
1.6327 +**
1.6328 +** New status parameters may be added from time to time.
1.6329 +*/
1.6330 +#define SQLITE_STATUS_MEMORY_USED 0
1.6331 +#define SQLITE_STATUS_PAGECACHE_USED 1
1.6332 +#define SQLITE_STATUS_PAGECACHE_OVERFLOW 2
1.6333 +#define SQLITE_STATUS_SCRATCH_USED 3
1.6334 +#define SQLITE_STATUS_SCRATCH_OVERFLOW 4
1.6335 +#define SQLITE_STATUS_MALLOC_SIZE 5
1.6336 +#define SQLITE_STATUS_PARSER_STACK 6
1.6337 +#define SQLITE_STATUS_PAGECACHE_SIZE 7
1.6338 +#define SQLITE_STATUS_SCRATCH_SIZE 8
1.6339 +
1.6340 +/*
1.6341 +** CAPI3REF: Status Parameters for database connections {H17275} <H17200>
1.6342 +** EXPERIMENTAL
1.6343 +**
1.6344 +** Status verbs for [sqlite3_db_status()].
1.6345 +**
1.6346 +** <dl>
1.6347 +** <dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>
1.6348 +** <dd>This parameter returns the number of lookaside memory slots currently
1.6349 +** checked out.</dd>
1.6350 +** </dl>
1.6351 +*/
1.6352 +#define SQLITE_DBSTATUS_LOOKASIDE_USED 0
1.6353 +
1.6354 +/*
1.6355 +** Undo the hack that converts floating point types to integer for
1.6356 +** builds on processors without floating point support.
1.6357 +*/
1.6358 +#ifdef SQLITE_OMIT_FLOATING_POINT
1.6359 +# undef double
1.6360 +#endif
1.6361 +
1.6362 +#ifdef __cplusplus
1.6363 +} /* End of the 'extern "C"' block */
1.6364 +#endif
1.6365 +#endif