diff options
Diffstat (limited to 'Plugins/DbSqliteCipher/sqlcipher.h')
| -rw-r--r-- | Plugins/DbSqliteCipher/sqlcipher.h | 2764 |
1 files changed, 2385 insertions, 379 deletions
diff --git a/Plugins/DbSqliteCipher/sqlcipher.h b/Plugins/DbSqliteCipher/sqlcipher.h index eac591f..12122ff 100644 --- a/Plugins/DbSqliteCipher/sqlcipher.h +++ b/Plugins/DbSqliteCipher/sqlcipher.h @@ -1,5 +1,5 @@ /* -** 2001 September 15 +** 2001-09-15 ** ** The author disclaims copyright to this source code. In place of ** a legal notice, here is a blessing: @@ -30,8 +30,8 @@ ** the version number) and changes its name to "sqlcipher_sqlite3.h" as ** part of the build process. */ -#ifndef _SQLITE3_H_ -#define _SQLITE3_H_ +#ifndef SQLITE3_H +#define SQLITE3_H #include <stdarg.h> /* Needed for the definition of va_list */ /* @@ -54,8 +54,17 @@ extern "C" { #ifndef SQLITE_CDECL # define SQLITE_CDECL #endif +#ifndef SQLITE_APICALL +# define SQLITE_APICALL +#endif #ifndef SQLITE_STDCALL -# define SQLITE_STDCALL +# define SQLITE_STDCALL SQLITE_APICALL +#endif +#ifndef SQLITE_CALLBACK +# define SQLITE_CALLBACK +#endif +#ifndef SQLITE_SYSAPI +# define SQLITE_SYSAPI #endif /* @@ -99,25 +108,26 @@ extern "C" { ** be held constant and Z will be incremented or else Y will be incremented ** and Z will be reset to zero. ** -** Since version 3.6.18, SQLite source code has been stored in the +** Since [version 3.6.18] ([dateof:3.6.18]), +** SQLite source code has been stored in the ** <a href="http://www.fossil-scm.org/">Fossil configuration management ** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to ** a string which identifies a particular check-in of SQLite ** within its configuration management system. ^The SQLITE_SOURCE_ID -** string contains the date and time of the check-in (UTC) and an SHA1 -** hash of the entire source tree. +** string contains the date and time of the check-in (UTC) and a SHA1 +** or SHA3-256 hash of the entire source tree. ** ** See also: [sqlcipher_sqlite3_libversion()], ** [sqlcipher_sqlite3_libversion_number()], [sqlcipher_sqlite3_sourceid()], ** [sqlite_version()] and [sqlite_source_id()]. */ -#define SQLITE_VERSION "3.11.0" -#define SQLITE_VERSION_NUMBER 3011000 -#define SQLITE_SOURCE_ID "2016-02-15 17:29:24 3d862f207e3adc00f78066799ac5a8c282430a5f" +#define SQLITE_VERSION "3.20.1" +#define SQLITE_VERSION_NUMBER 3020001 +#define SQLITE_SOURCE_ID "2017-08-24 16:21:36 8d3a7ea6c5690d6b7c3767558f4f01b511c55463e3f9e64506801fe9b74dce34" /* ** CAPI3REF: Run-Time Library Version Numbers -** KEYWORDS: sqlcipher_sqlite3_version, sqlcipher_sqlite3_sourceid +** KEYWORDS: sqlcipher_sqlite3_version sqlcipher_sqlite3_sourceid ** ** These interfaces provide the same information as the [SQLITE_VERSION], ** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros @@ -146,9 +156,9 @@ extern "C" { ** See also: [sqlite_version()] and [sqlite_source_id()]. */ SQLITE_API SQLITE_EXTERN const char sqlcipher_sqlite3_version[]; -SQLITE_API const char *SQLITE_STDCALL sqlcipher_sqlite3_libversion(void); -SQLITE_API const char *SQLITE_STDCALL sqlcipher_sqlite3_sourceid(void); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_libversion_number(void); +SQLITE_API const char *sqlcipher_sqlite3_libversion(void); +SQLITE_API const char *sqlcipher_sqlite3_sourceid(void); +SQLITE_API int sqlcipher_sqlite3_libversion_number(void); /* ** CAPI3REF: Run-Time Library Compilation Options Diagnostics @@ -173,8 +183,8 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_libversion_number(void); ** [sqlite_compileoption_get()] and the [compile_options pragma]. */ #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_compileoption_used(const char *zOptName); -SQLITE_API const char *SQLITE_STDCALL sqlcipher_sqlite3_compileoption_get(int N); +SQLITE_API int sqlcipher_sqlite3_compileoption_used(const char *zOptName); +SQLITE_API const char *sqlcipher_sqlite3_compileoption_get(int N); #endif /* @@ -213,7 +223,7 @@ SQLITE_API const char *SQLITE_STDCALL sqlcipher_sqlite3_compileoption_get(int N) ** ** See the [threading mode] documentation for additional information. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_threadsafe(void); +SQLITE_API int sqlcipher_sqlite3_threadsafe(void); /* ** CAPI3REF: Database Connection Handle @@ -249,7 +259,11 @@ typedef struct sqlcipher_sqlite3 sqlcipher_sqlite3; */ #ifdef SQLITE_INT64_TYPE typedef SQLITE_INT64_TYPE sqlite_int64; - typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; +# ifdef SQLITE_UINT64_TYPE + typedef SQLITE_UINT64_TYPE sqlite_uint64; +# else + typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; +# endif #elif defined(_MSC_VER) || defined(__BORLANDC__) typedef __int64 sqlite_int64; typedef unsigned __int64 sqlite_uint64; @@ -310,8 +324,8 @@ typedef sqlite_uint64 sqlcipher_sqlite3_uint64; ** ^Calling sqlcipher_sqlite3_close() or sqlcipher_sqlite3_close_v2() with a NULL pointer ** argument is a harmless no-op. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_close(sqlcipher_sqlite3*); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_close_v2(sqlcipher_sqlite3*); +SQLITE_API int sqlcipher_sqlite3_close(sqlcipher_sqlite3*); +SQLITE_API int sqlcipher_sqlite3_close_v2(sqlcipher_sqlite3*); /* ** The type for a callback function. @@ -382,7 +396,7 @@ typedef int (*sqlcipher_sqlite3_callback)(void*,int,char**, char**); ** the 2nd parameter of sqlcipher_sqlite3_exec() while sqlcipher_sqlite3_exec() is running. ** </ul> */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_exec( +SQLITE_API int sqlcipher_sqlite3_exec( sqlcipher_sqlite3*, /* An open database */ const char *sql, /* SQL to be evaluated */ int (*callback)(void*,int,char**,char**), /* Callback function */ @@ -403,7 +417,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_exec( */ #define SQLITE_OK 0 /* Successful result */ /* beginning-of-error-codes */ -#define SQLITE_ERROR 1 /* SQL error or missing database */ +#define SQLITE_ERROR 1 /* Generic error */ #define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */ #define SQLITE_PERM 3 /* Access permission denied */ #define SQLITE_ABORT 4 /* Callback routine requested an abort */ @@ -418,7 +432,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_exec( #define SQLITE_FULL 13 /* Insertion failed because database is full */ #define SQLITE_CANTOPEN 14 /* Unable to open the database file */ #define SQLITE_PROTOCOL 15 /* Database lock protocol error */ -#define SQLITE_EMPTY 16 /* Database is empty */ +#define SQLITE_EMPTY 16 /* Not used */ #define SQLITE_SCHEMA 17 /* The database schema changed */ #define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */ #define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */ @@ -426,7 +440,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_exec( #define SQLITE_MISUSE 21 /* Library used incorrectly */ #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ #define SQLITE_AUTH 23 /* Authorization denied */ -#define SQLITE_FORMAT 24 /* Auxiliary database format error */ +#define SQLITE_FORMAT 24 /* Not used */ #define SQLITE_RANGE 25 /* 2nd parameter to sqlcipher_sqlite3_bind out of range */ #define SQLITE_NOTADB 26 /* File opened that is not a database file */ #define SQLITE_NOTICE 27 /* Notifications from sqlcipher_sqlite3_log() */ @@ -443,7 +457,8 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_exec( ** [result codes]. However, experience has shown that many of ** these result codes are too coarse-grained. They do not provide as ** much information about problems as programmers might like. In an effort to -** address this, newer versions of SQLite (version 3.3.8 and later) include +** address this, newer versions of SQLite (version 3.3.8 [dateof:3.3.8] +** and later) include ** support for additional result codes that provide more detailed information ** about errors. These [extended result codes] are enabled or disabled ** on a per database connection basis using the @@ -506,6 +521,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_exec( #define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8)) #define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8)) #define SQLITE_AUTH_USER (SQLITE_AUTH | (1<<8)) +#define SQLITE_OK_LOAD_PERMANENTLY (SQLITE_OK | (1<<8)) /* ** CAPI3REF: Flags For File Open Operations @@ -560,7 +576,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_exec( ** file that were written at the application level might have changed ** and that adjacent bytes, even bytes within the same sector are ** guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN -** flag indicate that a file cannot be deleted when open. The +** flag indicates that a file cannot be deleted when open. The ** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on ** read-only media and cannot be changed even by processes with ** elevated privileges. @@ -710,6 +726,9 @@ struct sqlcipher_sqlite3_file { ** <li> [SQLITE_IOCAP_ATOMIC64K] ** <li> [SQLITE_IOCAP_SAFE_APPEND] ** <li> [SQLITE_IOCAP_SEQUENTIAL] +** <li> [SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN] +** <li> [SQLITE_IOCAP_POWERSAFE_OVERWRITE] +** <li> [SQLITE_IOCAP_IMMUTABLE] ** </ul> ** ** The SQLITE_IOCAP_ATOMIC property means that all writes of @@ -838,7 +857,7 @@ struct sqlcipher_sqlite3_io_methods { ** opcode allows these two values (10 retries and 25 milliseconds of delay) ** to be adjusted. The values are changed for all database connections ** within the same process. The argument is a pointer to an array of two -** integers where the first integer i the new retry count and the second +** integers where the first integer is the new retry count and the second ** integer is the delay. If either integer is negative, then the setting ** is not changed but instead the prior value of that setting is written ** into the array entry, allowing the current retry settings to be @@ -966,6 +985,12 @@ struct sqlcipher_sqlite3_io_methods { ** on whether or not the file has been renamed, moved, or deleted since it ** was first opened. ** +** <li>[[SQLITE_FCNTL_WIN32_GET_HANDLE]] +** The [SQLITE_FCNTL_WIN32_GET_HANDLE] opcode can be used to obtain the +** underlying native file handle associated with a file handle. This file +** control interprets its argument as a pointer to a native file handle and +** writes the resulting value there. +** ** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]] ** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This ** opcode causes the xFileControl method to swap the file handle with the one @@ -1016,6 +1041,8 @@ struct sqlcipher_sqlite3_io_methods { #define SQLITE_FCNTL_RBU 26 #define SQLITE_FCNTL_VFS_POINTER 27 #define SQLITE_FCNTL_JOURNAL_POINTER 28 +#define SQLITE_FCNTL_WIN32_GET_HANDLE 29 +#define SQLITE_FCNTL_PDB 30 /* deprecated names */ #define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE @@ -1036,6 +1063,16 @@ struct sqlcipher_sqlite3_io_methods { typedef struct sqlcipher_sqlite3_mutex sqlcipher_sqlite3_mutex; /* +** CAPI3REF: Loadable Extension Thunk +** +** A pointer to the opaque sqlcipher_sqlite3_api_routines structure is passed as +** the third parameter to entry points of [loadable extensions]. This +** structure must be typedefed in order to work around compiler warnings +** on some platforms. +*/ +typedef struct sqlcipher_sqlite3_api_routines sqlcipher_sqlite3_api_routines; + +/* ** CAPI3REF: OS Interface Object ** ** An instance of the sqlcipher_sqlite3_vfs object defines the interface between @@ -1228,7 +1265,7 @@ struct sqlcipher_sqlite3_vfs { const char *(*xNextSystemCall)(sqlcipher_sqlite3_vfs*, const char *zName); /* ** The methods above are in versions 1 through 3 of the sqlite_vfs object. - ** New fields may be appended in figure versions. The iVersion + ** New fields may be appended in future versions. The iVersion ** value will increment whenever this happens. */ }; @@ -1370,10 +1407,10 @@ struct sqlcipher_sqlite3_vfs { ** must return [SQLITE_OK] on success and some other [error code] upon ** failure. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_initialize(void); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_shutdown(void); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_os_init(void); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_os_end(void); +SQLITE_API int sqlcipher_sqlite3_initialize(void); +SQLITE_API int sqlcipher_sqlite3_shutdown(void); +SQLITE_API int sqlcipher_sqlite3_os_init(void); +SQLITE_API int sqlcipher_sqlite3_os_end(void); /* ** CAPI3REF: Configuring The SQLite Library @@ -1406,7 +1443,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_os_end(void); ** ^If the option is unknown or SQLite is unable to set the option ** then this routine returns a non-zero [error code]. */ -SQLITE_API int SQLITE_CDECL sqlcipher_sqlite3_config(int, ...); +SQLITE_API int sqlcipher_sqlite3_config(int, ...); /* ** CAPI3REF: Configure database connections @@ -1425,7 +1462,7 @@ SQLITE_API int SQLITE_CDECL sqlcipher_sqlite3_config(int, ...); ** ^Calls to sqlcipher_sqlite3_db_config() return SQLITE_OK if and only if ** the call is considered successful. */ -SQLITE_API int SQLITE_CDECL sqlcipher_sqlite3_db_config(sqlcipher_sqlite3*, int op, ...); +SQLITE_API int sqlcipher_sqlite3_db_config(sqlcipher_sqlite3*, int op, ...); /* ** CAPI3REF: Memory Allocation Routines @@ -1820,6 +1857,20 @@ struct sqlcipher_sqlite3_mem_methods { ** is enabled (using the [PRAGMA threads] command) and the amount of content ** to be sorted exceeds the page size times the minimum of the ** [PRAGMA cache_size] setting and this value. +** +** [[SQLITE_CONFIG_STMTJRNL_SPILL]] +** <dt>SQLITE_CONFIG_STMTJRNL_SPILL +** <dd>^The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which +** becomes the [statement journal] spill-to-disk threshold. +** [Statement journals] are held in memory until their size (in bytes) +** exceeds this threshold, at which point they are written to disk. +** Or if the threshold is -1, statement journals are always held +** exclusively in memory. +** Since many statement journals never become large, setting the spill +** threshold to a value such as 64KiB can greatly reduce the amount of +** I/O required to support statement rollback. +** The default value for this setting is controlled by the +** [SQLITE_STMTJRNL_SPILL] compile-time option. ** </dl> */ #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ @@ -1847,6 +1898,7 @@ struct sqlcipher_sqlite3_mem_methods { #define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */ #define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */ #define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */ +#define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */ /* ** CAPI3REF: Database Connection Configuration Options @@ -1904,11 +1956,78 @@ struct sqlcipher_sqlite3_mem_methods { ** following this call. The second parameter may be a NULL pointer, in ** which case the trigger setting is not reported back. </dd> ** +** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt> +** <dd> ^This option is used to enable or disable the two-argument +** version of the [fts3_tokenizer()] function which is part of the +** [FTS3] full-text search engine extension. +** There should be two additional arguments. +** The first argument is an integer which is 0 to disable fts3_tokenizer() or +** positive to enable fts3_tokenizer() or negative to leave the setting +** unchanged. +** The second parameter is a pointer to an integer into which +** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled +** following this call. The second parameter may be a NULL pointer, in +** which case the new setting is not reported back. </dd> +** +** <dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt> +** <dd> ^This option is used to enable or disable the [sqlcipher_sqlite3_load_extension()] +** interface independently of the [load_extension()] SQL function. +** The [sqlcipher_sqlite3_enable_load_extension()] API enables or disables both the +** C-API [sqlcipher_sqlite3_load_extension()] and the SQL function [load_extension()]. +** There should be two additional arguments. +** When the first argument to this interface is 1, then only the C-API is +** enabled and the SQL function remains disabled. If the first argument to +** this interface is 0, then both the C-API and the SQL function are disabled. +** If the first argument is -1, then no changes are made to state of either the +** C-API or the SQL function. +** The second parameter is a pointer to an integer into which +** is written 0 or 1 to indicate whether [sqlcipher_sqlite3_load_extension()] interface +** is disabled or enabled following this call. The second parameter may +** be a NULL pointer, in which case the new setting is not reported back. +** </dd> +** +** <dt>SQLITE_DBCONFIG_MAINDBNAME</dt> +** <dd> ^This option is used to change the name of the "main" database +** schema. ^The sole argument is a pointer to a constant UTF8 string +** which will become the new schema name in place of "main". ^SQLite +** does not make a copy of the new main schema name string, so the application +** must ensure that the argument passed into this DBCONFIG option is unchanged +** until after the database connection closes. +** </dd> +** +** <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt> +** <dd> Usually, when a database in wal mode is closed or detached from a +** database handle, SQLite checks if this will mean that there are now no +** connections at all to the database. If so, it performs a checkpoint +** operation before closing the connection. This option may be used to +** override this behaviour. The first parameter passed to this operation +** is an integer - non-zero to disable checkpoints-on-close, or zero (the +** default) to enable them. The second parameter is a pointer to an integer +** into which is written 0 or 1 to indicate whether checkpoints-on-close +** have been disabled - 0 if they are not disabled, 1 if they are. +** </dd> +** +** <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt> +** <dd>^(The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates +** the [query planner stability guarantee] (QPSG). When the QPSG is active, +** a single SQL query statement will always use the same algorithm regardless +** of values of [bound parameters].)^ The QPSG disables some query optimizations +** that look at the values of bound parameters, which can make some queries +** slower. But the QPSG has the advantage of more predictable behavior. With +** the QPSG active, SQLite will always use the same query plan in the field as +** was used during testing in the lab. +** </dd> +** ** </dl> */ -#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ -#define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */ -#define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */ +#define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */ +#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ +#define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */ +#define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */ +#define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */ /* @@ -1919,7 +2038,7 @@ struct sqlcipher_sqlite3_mem_methods { ** [extended result codes] feature of SQLite. ^The extended result ** codes are disabled by default for historical compatibility. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_extended_result_codes(sqlcipher_sqlite3*, int onoff); +SQLITE_API int sqlcipher_sqlite3_extended_result_codes(sqlcipher_sqlite3*, int onoff); /* ** CAPI3REF: Last Insert Rowid @@ -1933,20 +2052,30 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_extended_result_codes(sqlcipher_ ** the table has a column of type [INTEGER PRIMARY KEY] then that column ** is another alias for the rowid. ** -** ^The sqlcipher_sqlite3_last_insert_rowid(D) interface returns the [rowid] of the -** most recent successful [INSERT] into a rowid table or [virtual table] -** on database connection D. -** ^Inserts into [WITHOUT ROWID] tables are not recorded. -** ^If no successful [INSERT]s into rowid tables -** have ever occurred on the database connection D, -** then sqlcipher_sqlite3_last_insert_rowid(D) returns zero. -** -** ^(If an [INSERT] occurs within a trigger or within a [virtual table] -** method, then this routine will return the [rowid] of the inserted -** row as long as the trigger or virtual table method is running. -** But once the trigger or virtual table method ends, the value returned -** by this routine reverts to what it was before the trigger or virtual -** table method began.)^ +** ^The sqlcipher_sqlite3_last_insert_rowid(D) interface usually returns the [rowid] of +** the most recent successful [INSERT] into a rowid table or [virtual table] +** on database connection D. ^Inserts into [WITHOUT ROWID] tables are not +** recorded. ^If no successful [INSERT]s into rowid tables have ever occurred +** on the database connection D, then sqlcipher_sqlite3_last_insert_rowid(D) returns +** zero. +** +** As well as being set automatically as rows are inserted into database +** tables, the value returned by this function may be set explicitly by +** [sqlcipher_sqlite3_set_last_insert_rowid()] +** +** Some virtual table implementations may INSERT rows into rowid tables as +** part of committing a transaction (e.g. to flush data accumulated in memory +** to disk). In this case subsequent calls to this function return the rowid +** associated with these internal INSERT operations, which leads to +** unintuitive results. Virtual table implementations that do write to rowid +** tables in this way can avoid this problem by restoring the original +** rowid value using [sqlcipher_sqlite3_set_last_insert_rowid()] before returning +** control to the user. +** +** ^(If an [INSERT] occurs within a trigger then this routine will +** return the [rowid] of the inserted row as long as the trigger is +** running. Once the trigger program ends, the value returned +** by this routine reverts to what it was before the trigger was fired.)^ ** ** ^An [INSERT] that fails due to a constraint violation is not a ** successful [INSERT] and does not change the value returned by this @@ -1971,7 +2100,17 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_extended_result_codes(sqlcipher_ ** unpredictable and might not equal either the old or the new ** last insert [rowid]. */ -SQLITE_API sqlcipher_sqlite3_int64 SQLITE_STDCALL sqlcipher_sqlite3_last_insert_rowid(sqlcipher_sqlite3*); +SQLITE_API sqlcipher_sqlite3_int64 sqlcipher_sqlite3_last_insert_rowid(sqlcipher_sqlite3*); + +/* +** CAPI3REF: Set the Last Insert Rowid value. +** METHOD: sqlcipher_sqlite3 +** +** The sqlcipher_sqlite3_set_last_insert_rowid(D, R) method allows the application to +** set the value returned by calling sqlcipher_sqlite3_last_insert_rowid(D) to R +** without inserting a row into the database. +*/ +SQLITE_API void sqlcipher_sqlite3_set_last_insert_rowid(sqlcipher_sqlite3*,sqlcipher_sqlite3_int64); /* ** CAPI3REF: Count The Number Of Rows Modified @@ -2024,7 +2163,7 @@ SQLITE_API sqlcipher_sqlite3_int64 SQLITE_STDCALL sqlcipher_sqlite3_last_insert_ ** while [sqlcipher_sqlite3_changes()] is running then the value returned ** is unpredictable and not meaningful. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_changes(sqlcipher_sqlite3*); +SQLITE_API int sqlcipher_sqlite3_changes(sqlcipher_sqlite3*); /* ** CAPI3REF: Total Number Of Rows Modified @@ -2048,7 +2187,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_changes(sqlcipher_sqlite3*); ** while [sqlcipher_sqlite3_total_changes()] is running then the value ** returned is unpredictable and not meaningful. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_total_changes(sqlcipher_sqlite3*); +SQLITE_API int sqlcipher_sqlite3_total_changes(sqlcipher_sqlite3*); /* ** CAPI3REF: Interrupt A Long-Running Query @@ -2084,11 +2223,8 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_total_changes(sqlcipher_sqlite3* ** ^A call to sqlcipher_sqlite3_interrupt(D) that occurs when there are no running ** SQL statements is a no-op and has no effect on SQL statements ** that are started after the sqlcipher_sqlite3_interrupt() call returns. -** -** If the database connection closes while [sqlcipher_sqlite3_interrupt()] -** is running then bad things will likely happen. */ -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_interrupt(sqlcipher_sqlite3*); +SQLITE_API void sqlcipher_sqlite3_interrupt(sqlcipher_sqlite3*); /* ** CAPI3REF: Determine If An SQL Statement Is Complete @@ -2123,8 +2259,8 @@ SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_interrupt(sqlcipher_sqlite3*); ** The input to [sqlcipher_sqlite3_complete16()] must be a zero-terminated ** UTF-16 string in native byte order. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_complete(const char *sql); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_complete16(const void *sql); +SQLITE_API int sqlcipher_sqlite3_complete(const char *sql); +SQLITE_API int sqlcipher_sqlite3_complete16(const void *sql); /* ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors @@ -2185,7 +2321,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_complete16(const void *sql); ** A busy handler must not close the database connection ** or [prepared statement] that invoked the busy handler. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_busy_handler(sqlcipher_sqlite3*, int(*)(void*,int), void*); +SQLITE_API int sqlcipher_sqlite3_busy_handler(sqlcipher_sqlite3*,int(*)(void*,int),void*); /* ** CAPI3REF: Set A Busy Timeout @@ -2208,7 +2344,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_busy_handler(sqlcipher_sqlite3*, ** ** See also: [PRAGMA busy_timeout] */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_busy_timeout(sqlcipher_sqlite3*, int ms); +SQLITE_API int sqlcipher_sqlite3_busy_timeout(sqlcipher_sqlite3*, int ms); /* ** CAPI3REF: Convenience Routines For Running Queries @@ -2283,7 +2419,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_busy_timeout(sqlcipher_sqlite3*, ** reflected in subsequent calls to [sqlcipher_sqlite3_errcode()] or ** [sqlcipher_sqlite3_errmsg()]. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_get_table( +SQLITE_API int sqlcipher_sqlite3_get_table( sqlcipher_sqlite3 *db, /* An open database */ const char *zSql, /* SQL to be evaluated */ char ***pazResult, /* Results of the query */ @@ -2291,7 +2427,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_get_table( int *pnColumn, /* Number of result columns written here */ char **pzErrmsg /* Error msg written here */ ); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_free_table(char **result); +SQLITE_API void sqlcipher_sqlite3_free_table(char **result); /* ** CAPI3REF: Formatted String Printing Functions @@ -2397,10 +2533,10 @@ SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_free_table(char **result); ** addition that after the string has been read and copied into ** the result, [sqlcipher_sqlite3_free()] is called on the input string.)^ */ -SQLITE_API char *SQLITE_CDECL sqlcipher_sqlite3_mprintf(const char*,...); -SQLITE_API char *SQLITE_STDCALL sqlcipher_sqlite3_vmprintf(const char*, va_list); -SQLITE_API char *SQLITE_CDECL sqlcipher_sqlite3_snprintf(int,char*,const char*, ...); -SQLITE_API char *SQLITE_STDCALL sqlcipher_sqlite3_vsnprintf(int,char*,const char*, va_list); +SQLITE_API char *sqlcipher_sqlite3_mprintf(const char*,...); +SQLITE_API char *sqlcipher_sqlite3_vmprintf(const char*, va_list); +SQLITE_API char *sqlcipher_sqlite3_snprintf(int,char*,const char*, ...); +SQLITE_API char *sqlcipher_sqlite3_vsnprintf(int,char*,const char*, va_list); /* ** CAPI3REF: Memory Allocation Subsystem @@ -2490,12 +2626,12 @@ SQLITE_API char *SQLITE_STDCALL sqlcipher_sqlite3_vsnprintf(int,char*,const char ** a block of memory after it has been released using ** [sqlcipher_sqlite3_free()] or [sqlcipher_sqlite3_realloc()]. */ -SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_malloc(int); -SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_malloc64(sqlcipher_sqlite3_uint64); -SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_realloc(void*, int); -SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_realloc64(void*, sqlcipher_sqlite3_uint64); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_free(void*); -SQLITE_API sqlcipher_sqlite3_uint64 SQLITE_STDCALL sqlcipher_sqlite3_msize(void*); +SQLITE_API void *sqlcipher_sqlite3_malloc(int); +SQLITE_API void *sqlcipher_sqlite3_malloc64(sqlcipher_sqlite3_uint64); +SQLITE_API void *sqlcipher_sqlite3_realloc(void*, int); +SQLITE_API void *sqlcipher_sqlite3_realloc64(void*, sqlcipher_sqlite3_uint64); +SQLITE_API void sqlcipher_sqlite3_free(void*); +SQLITE_API sqlcipher_sqlite3_uint64 sqlcipher_sqlite3_msize(void*); /* ** CAPI3REF: Memory Allocator Statistics @@ -2520,8 +2656,8 @@ SQLITE_API sqlcipher_sqlite3_uint64 SQLITE_STDCALL sqlcipher_sqlite3_msize(void* ** by [sqlcipher_sqlite3_memory_highwater(1)] is the high-water mark ** prior to the reset. */ -SQLITE_API sqlcipher_sqlite3_int64 SQLITE_STDCALL sqlcipher_sqlite3_memory_used(void); -SQLITE_API sqlcipher_sqlite3_int64 SQLITE_STDCALL sqlcipher_sqlite3_memory_highwater(int resetFlag); +SQLITE_API sqlcipher_sqlite3_int64 sqlcipher_sqlite3_memory_used(void); +SQLITE_API sqlcipher_sqlite3_int64 sqlcipher_sqlite3_memory_highwater(int resetFlag); /* ** CAPI3REF: Pseudo-Random Number Generator @@ -2544,17 +2680,19 @@ SQLITE_API sqlcipher_sqlite3_int64 SQLITE_STDCALL sqlcipher_sqlite3_memory_highw ** internally and without recourse to the [sqlcipher_sqlite3_vfs] xRandomness ** method. */ -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_randomness(int N, void *P); +SQLITE_API void sqlcipher_sqlite3_randomness(int N, void *P); /* ** CAPI3REF: Compile-Time Authorization Callbacks ** METHOD: sqlcipher_sqlite3 +** KEYWORDS: {authorizer callback} ** ** ^This routine registers an authorizer callback with a particular ** [database connection], supplied in the first argument. ** ^The authorizer callback is invoked as SQL statements are being compiled ** by [sqlcipher_sqlite3_prepare()] or its variants [sqlcipher_sqlite3_prepare_v2()], -** [sqlcipher_sqlite3_prepare16()] and [sqlcipher_sqlite3_prepare16_v2()]. ^At various +** [sqlcipher_sqlite3_prepare_v3()], [sqlcipher_sqlite3_prepare16()], [sqlcipher_sqlite3_prepare16_v2()], +** and [sqlcipher_sqlite3_prepare16_v3()]. ^At various ** points during the compilation process, as logic is being created ** to perform various actions, the authorizer callback is invoked to ** see if those actions are allowed. ^The authorizer callback should @@ -2576,8 +2714,10 @@ SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_randomness(int N, void *P); ** parameter to the sqlcipher_sqlite3_set_authorizer() interface. ^The second parameter ** to the callback is an integer [SQLITE_COPY | action code] that specifies ** the particular action to be authorized. ^The third through sixth parameters -** to the callback are zero-terminated strings that contain additional -** details about the action to be authorized. +** to the callback are either NULL pointers or zero-terminated strings +** that contain additional details about the action to be authorized. +** Applications must always be prepared to encounter a NULL pointer in any +** of the third through the sixth parameters of the authorization callback. ** ** ^If the action code is [SQLITE_READ] ** and the callback returns [SQLITE_IGNORE] then the @@ -2586,6 +2726,10 @@ SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_randomness(int N, void *P); ** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE] ** return can be used to deny an untrusted user access to individual ** columns of a table. +** ^When a table is referenced by a [SELECT] but no column values are +** extracted from that table (for example in a query like +** "SELECT count(*) FROM tab") then the [SQLITE_READ] authorizer callback +** is invoked once for that table with a column name that is an empty string. ** ^If the action code is [SQLITE_DELETE] and the callback returns ** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the ** [truncate optimization] is disabled and all rows are deleted individually. @@ -2627,7 +2771,7 @@ SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_randomness(int N, void *P); ** as stated in the previous paragraph, sqlcipher_sqlite3_step() invokes ** sqlcipher_sqlite3_prepare_v2() to reprepare a statement after a schema change. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_set_authorizer( +SQLITE_API int sqlcipher_sqlite3_set_authorizer( sqlcipher_sqlite3*, int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), void *pUserData @@ -2707,6 +2851,9 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_set_authorizer( ** CAPI3REF: Tracing And Profiling Functions ** METHOD: sqlcipher_sqlite3 ** +** These routines are deprecated. Use the [sqlcipher_sqlite3_trace_v2()] interface +** instead of the routines described here. +** ** These routines register callback functions that can be used for ** tracing and profiling the execution of SQL statements. ** @@ -2732,11 +2879,105 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_set_authorizer( ** sqlcipher_sqlite3_profile() function is considered experimental and is ** subject to change in future versions of SQLite. */ -SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_trace(sqlcipher_sqlite3*, void(*xTrace)(void*,const char*), void*); -SQLITE_API SQLITE_EXPERIMENTAL void *SQLITE_STDCALL sqlcipher_sqlite3_profile(sqlcipher_sqlite3*, +SQLITE_API SQLITE_DEPRECATED void *sqlcipher_sqlite3_trace(sqlcipher_sqlite3*, + void(*xTrace)(void*,const char*), void*); +SQLITE_API SQLITE_DEPRECATED void *sqlcipher_sqlite3_profile(sqlcipher_sqlite3*, void(*xProfile)(void*,const char*,sqlcipher_sqlite3_uint64), void*); /* +** CAPI3REF: SQL Trace Event Codes +** KEYWORDS: SQLITE_TRACE +** +** These constants identify classes of events that can be monitored +** using the [sqlcipher_sqlite3_trace_v2()] tracing logic. The third argument +** to [sqlcipher_sqlite3_trace_v2()] is an OR-ed combination of one or more of +** the following constants. ^The first argument to the trace callback +** is one of the following constants. +** +** New tracing constants may be added in future releases. +** +** ^A trace callback has four arguments: xCallback(T,C,P,X). +** ^The T argument is one of the integer type codes above. +** ^The C argument is a copy of the context pointer passed in as the +** fourth argument to [sqlcipher_sqlite3_trace_v2()]. +** The P and X arguments are pointers whose meanings depend on T. +** +** <dl> +** [[SQLITE_TRACE_STMT]] <dt>SQLITE_TRACE_STMT</dt> +** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement +** first begins running and possibly at other times during the +** execution of the prepared statement, such as at the start of each +** trigger subprogram. ^The P argument is a pointer to the +** [prepared statement]. ^The X argument is a pointer to a string which +** is the unexpanded SQL text of the prepared statement or an SQL comment +** that indicates the invocation of a trigger. ^The callback can compute +** the same text that would have been returned by the legacy [sqlcipher_sqlite3_trace()] +** interface by using the X argument when X begins with "--" and invoking +** [sqlcipher_sqlite3_expanded_sql(P)] otherwise. +** +** [[SQLITE_TRACE_PROFILE]] <dt>SQLITE_TRACE_PROFILE</dt> +** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same +** information as is provided by the [sqlcipher_sqlite3_profile()] callback. +** ^The P argument is a pointer to the [prepared statement] and the +** X argument points to a 64-bit integer which is the estimated of +** the number of nanosecond that the prepared statement took to run. +** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes. +** +** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt> +** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared +** statement generates a single row of result. +** ^The P argument is a pointer to the [prepared statement] and the +** X argument is unused. +** +** [[SQLITE_TRACE_CLOSE]] <dt>SQLITE_TRACE_CLOSE</dt> +** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database +** connection closes. +** ^The P argument is a pointer to the [database connection] object +** and the X argument is unused. +** </dl> +*/ +#define SQLITE_TRACE_STMT 0x01 +#define SQLITE_TRACE_PROFILE 0x02 +#define SQLITE_TRACE_ROW 0x04 +#define SQLITE_TRACE_CLOSE 0x08 + +/* +** CAPI3REF: SQL Trace Hook +** METHOD: sqlcipher_sqlite3 +** +** ^The sqlcipher_sqlite3_trace_v2(D,M,X,P) interface registers a trace callback +** function X against [database connection] D, using property mask M +** and context pointer P. ^If the X callback is +** NULL or if the M mask is zero, then tracing is disabled. The +** M argument should be the bitwise OR-ed combination of +** zero or more [SQLITE_TRACE] constants. +** +** ^Each call to either sqlcipher_sqlite3_trace() or sqlcipher_sqlite3_trace_v2() overrides +** (cancels) any prior calls to sqlcipher_sqlite3_trace() or sqlcipher_sqlite3_trace_v2(). +** +** ^The X callback is invoked whenever any of the events identified by +** mask M occur. ^The integer return value from the callback is currently +** ignored, though this may change in future releases. Callback +** implementations should return zero to ensure future compatibility. +** +** ^A trace callback is invoked with four arguments: callback(T,C,P,X). +** ^The T argument is one of the [SQLITE_TRACE] +** constants to indicate why the callback was invoked. +** ^The C argument is a copy of the context pointer. +** The P and X arguments are pointers whose meanings depend on T. +** +** The sqlcipher_sqlite3_trace_v2() interface is intended to replace the legacy +** interfaces [sqlcipher_sqlite3_trace()] and [sqlcipher_sqlite3_profile()], both of which +** are deprecated. +*/ +SQLITE_API int sqlcipher_sqlite3_trace_v2( + sqlcipher_sqlite3*, + unsigned uMask, + int(*xCallback)(unsigned,void*,void*,void*), + void *pCtx +); + +/* ** CAPI3REF: Query Progress Callbacks ** METHOD: sqlcipher_sqlite3 ** @@ -2768,7 +3009,7 @@ SQLITE_API SQLITE_EXPERIMENTAL void *SQLITE_STDCALL sqlcipher_sqlite3_profile(sq ** database connections for the meaning of "modify" in this paragraph. ** */ -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_progress_handler(sqlcipher_sqlite3*, int, int(*)(void*), void*); +SQLITE_API void sqlcipher_sqlite3_progress_handler(sqlcipher_sqlite3*, int, int(*)(void*), void*); /* ** CAPI3REF: Opening A New Database Connection @@ -2997,15 +3238,15 @@ SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_progress_handler(sqlcipher_sqli ** ** See also: [sqlcipher_sqlite3_temp_directory] */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_open( +SQLITE_API int sqlcipher_sqlite3_open( const char *filename, /* Database filename (UTF-8) */ sqlcipher_sqlite3 **ppDb /* OUT: SQLite db handle */ ); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_open16( +SQLITE_API int sqlcipher_sqlite3_open16( const void *filename, /* Database filename (UTF-16) */ sqlcipher_sqlite3 **ppDb /* OUT: SQLite db handle */ ); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_open_v2( +SQLITE_API int sqlcipher_sqlite3_open_v2( const char *filename, /* Database filename (UTF-8) */ sqlcipher_sqlite3 **ppDb, /* OUT: SQLite db handle */ int flags, /* Flags */ @@ -3051,9 +3292,9 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_open_v2( ** VFS method, then the behavior of this routine is undefined and probably ** undesirable. */ -SQLITE_API const char *SQLITE_STDCALL sqlcipher_sqlite3_uri_parameter(const char *zFilename, const char *zParam); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault); -SQLITE_API sqlcipher_sqlite3_int64 SQLITE_STDCALL sqlcipher_sqlite3_uri_int64(const char*, const char*, sqlcipher_sqlite3_int64); +SQLITE_API const char *sqlcipher_sqlite3_uri_parameter(const char *zFilename, const char *zParam); +SQLITE_API int sqlcipher_sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault); +SQLITE_API sqlcipher_sqlite3_int64 sqlcipher_sqlite3_uri_int64(const char*, const char*, sqlcipher_sqlite3_int64); /* @@ -3097,11 +3338,11 @@ SQLITE_API sqlcipher_sqlite3_int64 SQLITE_STDCALL sqlcipher_sqlite3_uri_int64(co ** was invoked incorrectly by the application. In that case, the ** error code and message may or may not be set. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_errcode(sqlcipher_sqlite3 *db); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_extended_errcode(sqlcipher_sqlite3 *db); -SQLITE_API const char *SQLITE_STDCALL sqlcipher_sqlite3_errmsg(sqlcipher_sqlite3*); -SQLITE_API const void *SQLITE_STDCALL sqlcipher_sqlite3_errmsg16(sqlcipher_sqlite3*); -SQLITE_API const char *SQLITE_STDCALL sqlcipher_sqlite3_errstr(int); +SQLITE_API int sqlcipher_sqlite3_errcode(sqlcipher_sqlite3 *db); +SQLITE_API int sqlcipher_sqlite3_extended_errcode(sqlcipher_sqlite3 *db); +SQLITE_API const char *sqlcipher_sqlite3_errmsg(sqlcipher_sqlite3*); +SQLITE_API const void *sqlcipher_sqlite3_errmsg16(sqlcipher_sqlite3*); +SQLITE_API const char *sqlcipher_sqlite3_errstr(int); /* ** CAPI3REF: Prepared Statement Object @@ -3169,7 +3410,7 @@ typedef struct sqlcipher_sqlite3_stmt sqlcipher_sqlite3_stmt; ** ** New run-time limit categories may be added in future releases. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_limit(sqlcipher_sqlite3*, int id, int newVal); +SQLITE_API int sqlcipher_sqlite3_limit(sqlcipher_sqlite3*, int id, int newVal); /* ** CAPI3REF: Run-Time Limit Categories @@ -3200,9 +3441,9 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_limit(sqlcipher_sqlite3*, int id ** ** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt> ** <dd>The maximum number of instructions in a virtual machine program -** used to implement an SQL statement. This limit is not currently -** enforced, though that might be added in some future release of -** SQLite.</dd>)^ +** used to implement an SQL statement. If [sqlcipher_sqlite3_prepare_v2()] or +** the equivalent tries to allocate space for more than this many opcodes +** in a single prepared statement, an SQLITE_NOMEM error is returned.</dd>)^ ** ** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt> ** <dd>The maximum number of arguments on a function.</dd>)^ @@ -3241,22 +3482,58 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_limit(sqlcipher_sqlite3*, int id #define SQLITE_LIMIT_WORKER_THREADS 11 /* +** CAPI3REF: Prepare Flags +** +** These constants define various flags that can be passed into +** "prepFlags" parameter of the [sqlcipher_sqlite3_prepare_v3()] and +** [sqlcipher_sqlite3_prepare16_v3()] interfaces. +** +** New flags may be added in future releases of SQLite. +** +** <dl> +** [[SQLITE_PREPARE_PERSISTENT]] ^(<dt>SQLITE_PREPARE_PERSISTENT</dt> +** <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner +** that the prepared statement will be retained for a long time and +** probably reused many times.)^ ^Without this flag, [sqlcipher_sqlite3_prepare_v3()] +** and [sqlcipher_sqlite3_prepare16_v3()] assume that the prepared statement will +** be used just once or at most a few times and then destroyed using +** [sqlcipher_sqlite3_finalize()] relatively soon. The current implementation acts +** on this hint by avoiding the use of [lookaside memory] so as not to +** deplete the limited store of lookaside memory. Future versions of +** SQLite may act on this hint differently. +** </dl> +*/ +#define SQLITE_PREPARE_PERSISTENT 0x01 + +/* ** CAPI3REF: Compiling An SQL Statement ** KEYWORDS: {SQL statement compiler} ** METHOD: sqlcipher_sqlite3 ** CONSTRUCTOR: sqlcipher_sqlite3_stmt ** -** To execute an SQL query, it must first be compiled into a byte-code -** program using one of these routines. +** To execute an SQL statement, it must first be compiled into a byte-code +** program using one of these routines. Or, in other words, these routines +** are constructors for the [prepared statement] object. +** +** The preferred routine to use is [sqlcipher_sqlite3_prepare_v2()]. The +** [sqlcipher_sqlite3_prepare()] interface is legacy and should be avoided. +** [sqlcipher_sqlite3_prepare_v3()] has an extra "prepFlags" option that is used +** for special purposes. +** +** The use of the UTF-8 interfaces is preferred, as SQLite currently +** does all parsing using UTF-8. The UTF-16 interfaces are provided +** as a convenience. The UTF-16 interfaces work by converting the +** input text into UTF-8, then invoking the corresponding UTF-8 interface. ** ** The first argument, "db", is a [database connection] obtained from a ** prior successful call to [sqlcipher_sqlite3_open()], [sqlcipher_sqlite3_open_v2()] or ** [sqlcipher_sqlite3_open16()]. The database connection must not have been closed. ** ** The second argument, "zSql", is the statement to be compiled, encoded -** as either UTF-8 or UTF-16. The sqlcipher_sqlite3_prepare() and sqlcipher_sqlite3_prepare_v2() -** interfaces use UTF-8, and sqlcipher_sqlite3_prepare16() and sqlcipher_sqlite3_prepare16_v2() -** use UTF-16. +** as either UTF-8 or UTF-16. The sqlcipher_sqlite3_prepare(), sqlcipher_sqlite3_prepare_v2(), +** and sqlcipher_sqlite3_prepare_v3() +** interfaces use UTF-8, and sqlcipher_sqlite3_prepare16(), sqlcipher_sqlite3_prepare16_v2(), +** and sqlcipher_sqlite3_prepare16_v3() use UTF-16. ** ** ^If the nByte argument is negative, then zSql is read up to the ** first zero terminator. ^If nByte is positive, then it is the @@ -3283,10 +3560,11 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_limit(sqlcipher_sqlite3*, int id ** ^On success, the sqlcipher_sqlite3_prepare() family of routines return [SQLITE_OK]; ** otherwise an [error code] is returned. ** -** The sqlcipher_sqlite3_prepare_v2() and sqlcipher_sqlite3_prepare16_v2() interfaces are -** recommended for all new programs. The two older interfaces are retained -** for backwards compatibility, but their use is discouraged. -** ^In the "v2" interfaces, the prepared statement +** The sqlcipher_sqlite3_prepare_v2(), sqlcipher_sqlite3_prepare_v3(), sqlcipher_sqlite3_prepare16_v2(), +** and sqlcipher_sqlite3_prepare16_v3() interfaces are recommended for all new programs. +** The older interfaces (sqlcipher_sqlite3_prepare() and sqlcipher_sqlite3_prepare16()) +** are retained for backwards compatibility, but their use is discouraged. +** ^In the "vX" interfaces, the prepared statement ** that is returned (the [sqlcipher_sqlite3_stmt] object) contains a copy of the ** original SQL text. This causes the [sqlcipher_sqlite3_step()] interface to ** behave differently in three ways: @@ -3319,33 +3597,55 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_limit(sqlcipher_sqlite3*, int id ** or [GLOB] operator or if the parameter is compared to an indexed column ** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled. ** </li> +** +** <p>^sqlcipher_sqlite3_prepare_v3() differs from sqlcipher_sqlite3_prepare_v2() only in having +** the extra prepFlags parameter, which is a bit array consisting of zero or +** more of the [SQLITE_PREPARE_PERSISTENT|SQLITE_PREPARE_*] flags. ^The +** sqlcipher_sqlite3_prepare_v2() interface works exactly the same as +** sqlcipher_sqlite3_prepare_v3() with a zero prepFlags parameter. ** </ol> */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_prepare( +SQLITE_API int sqlcipher_sqlite3_prepare( + sqlcipher_sqlite3 *db, /* Database handle */ + const char *zSql, /* SQL statement, UTF-8 encoded */ + int nByte, /* Maximum length of zSql in bytes. */ + sqlcipher_sqlite3_stmt **ppStmt, /* OUT: Statement handle */ + const char **pzTail /* OUT: Pointer to unused portion of zSql */ +); +SQLITE_API int sqlcipher_sqlite3_prepare_v2( sqlcipher_sqlite3 *db, /* Database handle */ const char *zSql, /* SQL statement, UTF-8 encoded */ int nByte, /* Maximum length of zSql in bytes. */ sqlcipher_sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const char **pzTail /* OUT: Pointer to unused portion of zSql */ ); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_prepare_v2( +SQLITE_API int sqlcipher_sqlite3_prepare_v3( sqlcipher_sqlite3 *db, /* Database handle */ const char *zSql, /* SQL statement, UTF-8 encoded */ int nByte, /* Maximum length of zSql in bytes. */ + unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */ sqlcipher_sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const char **pzTail /* OUT: Pointer to unused portion of zSql */ ); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_prepare16( +SQLITE_API int sqlcipher_sqlite3_prepare16( + sqlcipher_sqlite3 *db, /* Database handle */ + const void *zSql, /* SQL statement, UTF-16 encoded */ + int nByte, /* Maximum length of zSql in bytes. */ + sqlcipher_sqlite3_stmt **ppStmt, /* OUT: Statement handle */ + const void **pzTail /* OUT: Pointer to unused portion of zSql */ +); +SQLITE_API int sqlcipher_sqlite3_prepare16_v2( sqlcipher_sqlite3 *db, /* Database handle */ const void *zSql, /* SQL statement, UTF-16 encoded */ int nByte, /* Maximum length of zSql in bytes. */ sqlcipher_sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const void **pzTail /* OUT: Pointer to unused portion of zSql */ ); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_prepare16_v2( +SQLITE_API int sqlcipher_sqlite3_prepare16_v3( sqlcipher_sqlite3 *db, /* Database handle */ const void *zSql, /* SQL statement, UTF-16 encoded */ int nByte, /* Maximum length of zSql in bytes. */ + unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */ sqlcipher_sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const void **pzTail /* OUT: Pointer to unused portion of zSql */ ); @@ -3354,11 +3654,36 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_prepare16_v2( ** CAPI3REF: Retrieving Statement SQL ** METHOD: sqlcipher_sqlite3_stmt ** -** ^This interface can be used to retrieve a saved copy of the original -** SQL text used to create a [prepared statement] if that statement was -** compiled using either [sqlcipher_sqlite3_prepare_v2()] or [sqlcipher_sqlite3_prepare16_v2()]. +** ^The sqlcipher_sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8 +** SQL text used to create [prepared statement] P if P was +** created by [sqlcipher_sqlite3_prepare_v2()], [sqlcipher_sqlite3_prepare_v3()], +** [sqlcipher_sqlite3_prepare16_v2()], or [sqlcipher_sqlite3_prepare16_v3()]. +** ^The sqlcipher_sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8 +** string containing the SQL text of prepared statement P with +** [bound parameters] expanded. +** +** ^(For example, if a prepared statement is created using the SQL +** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345 +** and parameter :xyz is unbound, then sqlcipher_sqlite3_sql() will return +** the original string, "SELECT $abc,:xyz" but sqlcipher_sqlite3_expanded_sql() +** will return "SELECT 2345,NULL".)^ +** +** ^The sqlcipher_sqlite3_expanded_sql() interface returns NULL if insufficient memory +** is available to hold the result, or if the result would exceed the +** the maximum string length determined by the [SQLITE_LIMIT_LENGTH]. +** +** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of +** bound parameter expansions. ^The [SQLITE_OMIT_TRACE] compile-time +** option causes sqlcipher_sqlite3_expanded_sql() to always return NULL. +** +** ^The string returned by sqlcipher_sqlite3_sql(P) is managed by SQLite and is +** automatically freed when the prepared statement is finalized. +** ^The string returned by sqlcipher_sqlite3_expanded_sql(P), on the other hand, +** is obtained from [sqlcipher_sqlite3_malloc()] and must be free by the application +** by passing it to [sqlcipher_sqlite3_free()]. */ -SQLITE_API const char *SQLITE_STDCALL sqlcipher_sqlite3_sql(sqlcipher_sqlite3_stmt *pStmt); +SQLITE_API const char *sqlcipher_sqlite3_sql(sqlcipher_sqlite3_stmt *pStmt); +SQLITE_API char *sqlcipher_sqlite3_expanded_sql(sqlcipher_sqlite3_stmt *pStmt); /* ** CAPI3REF: Determine If An SQL Statement Writes The Database @@ -3389,8 +3714,12 @@ SQLITE_API const char *SQLITE_STDCALL sqlcipher_sqlite3_sql(sqlcipher_sqlite3_st ** sqlcipher_sqlite3_stmt_readonly() to return true since, while those statements ** change the configuration of a database connection, they do not make ** changes to the content of the database files on disk. +** ^The sqlcipher_sqlite3_stmt_readonly() interface returns true for [BEGIN] since +** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and +** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so +** sqlcipher_sqlite3_stmt_readonly() returns false for those commands. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_stmt_readonly(sqlcipher_sqlite3_stmt *pStmt); +SQLITE_API int sqlcipher_sqlite3_stmt_readonly(sqlcipher_sqlite3_stmt *pStmt); /* ** CAPI3REF: Determine If A Prepared Statement Has Been Reset @@ -3411,7 +3740,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_stmt_readonly(sqlcipher_sqlite3_ ** for example, in diagnostic routines to search for prepared ** statements that are holding a transaction open. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_stmt_busy(sqlcipher_sqlite3_stmt*); +SQLITE_API int sqlcipher_sqlite3_stmt_busy(sqlcipher_sqlite3_stmt*); /* ** CAPI3REF: Dynamically Typed Value Object @@ -3452,7 +3781,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_stmt_busy(sqlcipher_sqlite3_stmt ** The [sqlcipher_sqlite3_value_blob | sqlcipher_sqlite3_value_type()] family of ** interfaces require protected sqlcipher_sqlite3_value objects. */ -typedef struct Mem sqlcipher_sqlite3_value; +typedef struct sqlcipher_sqlite3_value sqlcipher_sqlite3_value; /* ** CAPI3REF: SQL Function Context Object @@ -3554,6 +3883,15 @@ typedef struct sqlcipher_sqlite3_context sqlcipher_sqlite3_context; ** [sqlcipher_sqlite3_blob_open | incremental BLOB I/O] routines. ** ^A negative value for the zeroblob results in a zero-length BLOB. ** +** ^The sqlcipher_sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in +** [prepared statement] S to have an SQL value of NULL, but to also be +** associated with the pointer P of type T. ^D is either a NULL pointer or +** a pointer to a destructor function for P. ^SQLite will invoke the +** destructor D with a single argument of P when it is finished using +** P. The T parameter should be a static string, preferably a string +** literal. The sqlcipher_sqlite3_bind_pointer() routine is part of the +** [pointer passing interface] added for SQLite 3.20.0. +** ** ^If any of the sqlcipher_sqlite3_bind_*() routines are called with a NULL pointer ** for the [prepared statement] or with a prepared statement for which ** [sqlcipher_sqlite3_step()] has been called more recently than [sqlcipher_sqlite3_reset()], @@ -3575,20 +3913,21 @@ typedef struct sqlcipher_sqlite3_context sqlcipher_sqlite3_context; ** See also: [sqlcipher_sqlite3_bind_parameter_count()], ** [sqlcipher_sqlite3_bind_parameter_name()], and [sqlcipher_sqlite3_bind_parameter_index()]. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_bind_blob(sqlcipher_sqlite3_stmt*, int, const void*, int n, void(*)(void*)); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_bind_blob64(sqlcipher_sqlite3_stmt*, int, const void*, sqlcipher_sqlite3_uint64, +SQLITE_API int sqlcipher_sqlite3_bind_blob(sqlcipher_sqlite3_stmt*, int, const void*, int n, void(*)(void*)); +SQLITE_API int sqlcipher_sqlite3_bind_blob64(sqlcipher_sqlite3_stmt*, int, const void*, sqlcipher_sqlite3_uint64, void(*)(void*)); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_bind_double(sqlcipher_sqlite3_stmt*, int, double); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_bind_int(sqlcipher_sqlite3_stmt*, int, int); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_bind_int64(sqlcipher_sqlite3_stmt*, int, sqlcipher_sqlite3_int64); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_bind_null(sqlcipher_sqlite3_stmt*, int); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_bind_text(sqlcipher_sqlite3_stmt*,int,const char*,int,void(*)(void*)); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_bind_text16(sqlcipher_sqlite3_stmt*, int, const void*, int, void(*)(void*)); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_bind_text64(sqlcipher_sqlite3_stmt*, int, const char*, sqlcipher_sqlite3_uint64, +SQLITE_API int sqlcipher_sqlite3_bind_double(sqlcipher_sqlite3_stmt*, int, double); +SQLITE_API int sqlcipher_sqlite3_bind_int(sqlcipher_sqlite3_stmt*, int, int); +SQLITE_API int sqlcipher_sqlite3_bind_int64(sqlcipher_sqlite3_stmt*, int, sqlcipher_sqlite3_int64); +SQLITE_API int sqlcipher_sqlite3_bind_null(sqlcipher_sqlite3_stmt*, int); +SQLITE_API int sqlcipher_sqlite3_bind_text(sqlcipher_sqlite3_stmt*,int,const char*,int,void(*)(void*)); +SQLITE_API int sqlcipher_sqlite3_bind_text16(sqlcipher_sqlite3_stmt*, int, const void*, int, void(*)(void*)); +SQLITE_API int sqlcipher_sqlite3_bind_text64(sqlcipher_sqlite3_stmt*, int, const char*, sqlcipher_sqlite3_uint64, void(*)(void*), unsigned char encoding); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_bind_value(sqlcipher_sqlite3_stmt*, int, const sqlcipher_sqlite3_value*); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_bind_zeroblob(sqlcipher_sqlite3_stmt*, int, int n); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_bind_zeroblob64(sqlcipher_sqlite3_stmt*, int, sqlcipher_sqlite3_uint64); +SQLITE_API int sqlcipher_sqlite3_bind_value(sqlcipher_sqlite3_stmt*, int, const sqlcipher_sqlite3_value*); +SQLITE_API int sqlcipher_sqlite3_bind_pointer(sqlcipher_sqlite3_stmt*, int, void*, const char*,void(*)(void*)); +SQLITE_API int sqlcipher_sqlite3_bind_zeroblob(sqlcipher_sqlite3_stmt*, int, int n); +SQLITE_API int sqlcipher_sqlite3_bind_zeroblob64(sqlcipher_sqlite3_stmt*, int, sqlcipher_sqlite3_uint64); /* ** CAPI3REF: Number Of SQL Parameters @@ -3609,7 +3948,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_bind_zeroblob64(sqlcipher_sqlite ** [sqlcipher_sqlite3_bind_parameter_name()], and ** [sqlcipher_sqlite3_bind_parameter_index()]. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_bind_parameter_count(sqlcipher_sqlite3_stmt*); +SQLITE_API int sqlcipher_sqlite3_bind_parameter_count(sqlcipher_sqlite3_stmt*); /* ** CAPI3REF: Name Of A Host Parameter @@ -3630,14 +3969,14 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_bind_parameter_count(sqlcipher_s ** ^If the value N is out of range or if the N-th parameter is ** nameless, then NULL is returned. ^The returned string is ** always in UTF-8 encoding even if the named parameter was -** originally specified as UTF-16 in [sqlcipher_sqlite3_prepare16()] or -** [sqlcipher_sqlite3_prepare16_v2()]. +** originally specified as UTF-16 in [sqlcipher_sqlite3_prepare16()], +** [sqlcipher_sqlite3_prepare16_v2()], or [sqlcipher_sqlite3_prepare16_v3()]. ** ** See also: [sqlcipher_sqlite3_bind_blob|sqlcipher_sqlite3_bind()], ** [sqlcipher_sqlite3_bind_parameter_count()], and ** [sqlcipher_sqlite3_bind_parameter_index()]. */ -SQLITE_API const char *SQLITE_STDCALL sqlcipher_sqlite3_bind_parameter_name(sqlcipher_sqlite3_stmt*, int); +SQLITE_API const char *sqlcipher_sqlite3_bind_parameter_name(sqlcipher_sqlite3_stmt*, int); /* ** CAPI3REF: Index Of A Parameter With A Given Name @@ -3648,13 +3987,14 @@ SQLITE_API const char *SQLITE_STDCALL sqlcipher_sqlite3_bind_parameter_name(sqlc ** parameter to [sqlcipher_sqlite3_bind_blob|sqlcipher_sqlite3_bind()]. ^A zero ** is returned if no matching parameter is found. ^The parameter ** name must be given in UTF-8 even if the original statement -** was prepared from UTF-16 text using [sqlcipher_sqlite3_prepare16_v2()]. +** was prepared from UTF-16 text using [sqlcipher_sqlite3_prepare16_v2()] or +** [sqlcipher_sqlite3_prepare16_v3()]. ** ** See also: [sqlcipher_sqlite3_bind_blob|sqlcipher_sqlite3_bind()], ** [sqlcipher_sqlite3_bind_parameter_count()], and ** [sqlcipher_sqlite3_bind_parameter_name()]. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_bind_parameter_index(sqlcipher_sqlite3_stmt*, const char *zName); +SQLITE_API int sqlcipher_sqlite3_bind_parameter_index(sqlcipher_sqlite3_stmt*, const char *zName); /* ** CAPI3REF: Reset All Bindings On A Prepared Statement @@ -3664,19 +4004,23 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_bind_parameter_index(sqlcipher_s ** the [sqlcipher_sqlite3_bind_blob | bindings] on a [prepared statement]. ** ^Use this routine to reset all host parameters to NULL. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_clear_bindings(sqlcipher_sqlite3_stmt*); +SQLITE_API int sqlcipher_sqlite3_clear_bindings(sqlcipher_sqlite3_stmt*); /* ** CAPI3REF: Number Of Columns In A Result Set ** METHOD: sqlcipher_sqlite3_stmt ** ** ^Return the number of columns in the result set returned by the -** [prepared statement]. ^This routine returns 0 if pStmt is an SQL -** statement that does not return data (for example an [UPDATE]). +** [prepared statement]. ^If this routine returns 0, that means the +** [prepared statement] returns no data (for example an [UPDATE]). +** ^However, just because this routine returns a positive number does not +** mean that one or more rows of data will be returned. ^A SELECT statement +** will always have a positive sqlcipher_sqlite3_column_count() but depending on the +** WHERE clause constraints and the table content, it might return no rows. ** ** See also: [sqlcipher_sqlite3_data_count()] */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_column_count(sqlcipher_sqlite3_stmt *pStmt); +SQLITE_API int sqlcipher_sqlite3_column_count(sqlcipher_sqlite3_stmt *pStmt); /* ** CAPI3REF: Column Names In A Result Set @@ -3705,8 +4049,8 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_column_count(sqlcipher_sqlite3_s ** then the name of the column is unspecified and may change from ** one release of SQLite to the next. */ -SQLITE_API const char *SQLITE_STDCALL sqlcipher_sqlite3_column_name(sqlcipher_sqlite3_stmt*, int N); -SQLITE_API const void *SQLITE_STDCALL sqlcipher_sqlite3_column_name16(sqlcipher_sqlite3_stmt*, int N); +SQLITE_API const char *sqlcipher_sqlite3_column_name(sqlcipher_sqlite3_stmt*, int N); +SQLITE_API const void *sqlcipher_sqlite3_column_name16(sqlcipher_sqlite3_stmt*, int N); /* ** CAPI3REF: Source Of Data In A Query Result @@ -3754,12 +4098,12 @@ SQLITE_API const void *SQLITE_STDCALL sqlcipher_sqlite3_column_name16(sqlcipher_ ** for the same [prepared statement] and result column ** at the same time then the results are undefined. */ -SQLITE_API const char *SQLITE_STDCALL sqlcipher_sqlite3_column_database_name(sqlcipher_sqlite3_stmt*,int); -SQLITE_API const void *SQLITE_STDCALL sqlcipher_sqlite3_column_database_name16(sqlcipher_sqlite3_stmt*,int); -SQLITE_API const char *SQLITE_STDCALL sqlcipher_sqlite3_column_table_name(sqlcipher_sqlite3_stmt*,int); -SQLITE_API const void *SQLITE_STDCALL sqlcipher_sqlite3_column_table_name16(sqlcipher_sqlite3_stmt*,int); -SQLITE_API const char *SQLITE_STDCALL sqlcipher_sqlite3_column_origin_name(sqlcipher_sqlite3_stmt*,int); -SQLITE_API const void *SQLITE_STDCALL sqlcipher_sqlite3_column_origin_name16(sqlcipher_sqlite3_stmt*,int); +SQLITE_API const char *sqlcipher_sqlite3_column_database_name(sqlcipher_sqlite3_stmt*,int); +SQLITE_API const void *sqlcipher_sqlite3_column_database_name16(sqlcipher_sqlite3_stmt*,int); +SQLITE_API const char *sqlcipher_sqlite3_column_table_name(sqlcipher_sqlite3_stmt*,int); +SQLITE_API const void *sqlcipher_sqlite3_column_table_name16(sqlcipher_sqlite3_stmt*,int); +SQLITE_API const char *sqlcipher_sqlite3_column_origin_name(sqlcipher_sqlite3_stmt*,int); +SQLITE_API const void *sqlcipher_sqlite3_column_origin_name16(sqlcipher_sqlite3_stmt*,int); /* ** CAPI3REF: Declared Datatype Of A Query Result @@ -3791,23 +4135,25 @@ SQLITE_API const void *SQLITE_STDCALL sqlcipher_sqlite3_column_origin_name16(sql ** is associated with individual values, not with the containers ** used to hold those values. */ -SQLITE_API const char *SQLITE_STDCALL sqlcipher_sqlite3_column_decltype(sqlcipher_sqlite3_stmt*,int); -SQLITE_API const void *SQLITE_STDCALL sqlcipher_sqlite3_column_decltype16(sqlcipher_sqlite3_stmt*,int); +SQLITE_API const char *sqlcipher_sqlite3_column_decltype(sqlcipher_sqlite3_stmt*,int); +SQLITE_API const void *sqlcipher_sqlite3_column_decltype16(sqlcipher_sqlite3_stmt*,int); /* ** CAPI3REF: Evaluate An SQL Statement ** METHOD: sqlcipher_sqlite3_stmt ** -** After a [prepared statement] has been prepared using either -** [sqlcipher_sqlite3_prepare_v2()] or [sqlcipher_sqlite3_prepare16_v2()] or one of the legacy +** After a [prepared statement] has been prepared using any of +** [sqlcipher_sqlite3_prepare_v2()], [sqlcipher_sqlite3_prepare_v3()], [sqlcipher_sqlite3_prepare16_v2()], +** or [sqlcipher_sqlite3_prepare16_v3()] or one of the legacy ** interfaces [sqlcipher_sqlite3_prepare()] or [sqlcipher_sqlite3_prepare16()], this function ** must be called one or more times to evaluate the statement. ** ** The details of the behavior of the sqlcipher_sqlite3_step() interface depend -** on whether the statement was prepared using the newer "v2" interface -** [sqlcipher_sqlite3_prepare_v2()] and [sqlcipher_sqlite3_prepare16_v2()] or the older legacy -** interface [sqlcipher_sqlite3_prepare()] and [sqlcipher_sqlite3_prepare16()]. The use of the -** new "v2" interface is recommended for new applications but the legacy +** on whether the statement was prepared using the newer "vX" interfaces +** [sqlcipher_sqlite3_prepare_v3()], [sqlcipher_sqlite3_prepare_v2()], [sqlcipher_sqlite3_prepare16_v3()], +** [sqlcipher_sqlite3_prepare16_v2()] or the older legacy +** interfaces [sqlcipher_sqlite3_prepare()] and [sqlcipher_sqlite3_prepare16()]. The use of the +** new "vX" interface is recommended for new applications but the legacy ** interface will continue to be supported. ** ** ^In the legacy interface, the return value will be either [SQLITE_BUSY], @@ -3853,7 +4199,8 @@ SQLITE_API const void *SQLITE_STDCALL sqlcipher_sqlite3_column_decltype16(sqlcip ** other than [SQLITE_ROW] before any subsequent invocation of ** sqlcipher_sqlite3_step(). Failure to reset the prepared statement using ** [sqlcipher_sqlite3_reset()] would result in an [SQLITE_MISUSE] return from -** sqlcipher_sqlite3_step(). But after version 3.6.23.1, sqlcipher_sqlite3_step() began +** sqlcipher_sqlite3_step(). But after [version 3.6.23.1] ([dateof:3.6.23.1]), +** sqlcipher_sqlite3_step() began ** calling [sqlcipher_sqlite3_reset()] automatically in this circumstance rather ** than returning [SQLITE_MISUSE]. This is not considered a compatibility ** break because any application that ever receives an SQLITE_MISUSE error @@ -3867,12 +4214,13 @@ SQLITE_API const void *SQLITE_STDCALL sqlcipher_sqlite3_column_decltype16(sqlcip ** specific [error codes] that better describes the error. ** We admit that this is a goofy design. The problem has been fixed ** with the "v2" interface. If you prepare all of your SQL statements -** using either [sqlcipher_sqlite3_prepare_v2()] or [sqlcipher_sqlite3_prepare16_v2()] instead +** using [sqlcipher_sqlite3_prepare_v3()] or [sqlcipher_sqlite3_prepare_v2()] +** or [sqlcipher_sqlite3_prepare16_v2()] or [sqlcipher_sqlite3_prepare16_v3()] instead ** of the legacy [sqlcipher_sqlite3_prepare()] and [sqlcipher_sqlite3_prepare16()] interfaces, ** then the more specific [error codes] are returned directly -** by sqlcipher_sqlite3_step(). The use of the "v2" interface is recommended. +** by sqlcipher_sqlite3_step(). The use of the "vX" interfaces is recommended. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_step(sqlcipher_sqlite3_stmt*); +SQLITE_API int sqlcipher_sqlite3_step(sqlcipher_sqlite3_stmt*); /* ** CAPI3REF: Number of columns in a result set @@ -3893,7 +4241,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_step(sqlcipher_sqlite3_stmt*); ** ** See also: [sqlcipher_sqlite3_column_count()] */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_data_count(sqlcipher_sqlite3_stmt *pStmt); +SQLITE_API int sqlcipher_sqlite3_data_count(sqlcipher_sqlite3_stmt *pStmt); /* ** CAPI3REF: Fundamental Datatypes @@ -3932,6 +4280,28 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_data_count(sqlcipher_sqlite3_stm ** KEYWORDS: {column access functions} ** METHOD: sqlcipher_sqlite3_stmt ** +** <b>Summary:</b> +** <blockquote><table border=0 cellpadding=0 cellspacing=0> +** <tr><td><b>sqlcipher_sqlite3_column_blob</b><td>→<td>BLOB result +** <tr><td><b>sqlcipher_sqlite3_column_double</b><td>→<td>REAL result +** <tr><td><b>sqlcipher_sqlite3_column_int</b><td>→<td>32-bit INTEGER result +** <tr><td><b>sqlcipher_sqlite3_column_int64</b><td>→<td>64-bit INTEGER result +** <tr><td><b>sqlcipher_sqlite3_column_text</b><td>→<td>UTF-8 TEXT result +** <tr><td><b>sqlcipher_sqlite3_column_text16</b><td>→<td>UTF-16 TEXT result +** <tr><td><b>sqlcipher_sqlite3_column_value</b><td>→<td>The result as an +** [sqlcipher_sqlite3_value|unprotected sqlcipher_sqlite3_value] object. +** <tr><td> <td> <td> +** <tr><td><b>sqlcipher_sqlite3_column_bytes</b><td>→<td>Size of a BLOB +** or a UTF-8 TEXT result in bytes +** <tr><td><b>sqlcipher_sqlite3_column_bytes16 </b> +** <td>→ <td>Size of UTF-16 +** TEXT in bytes +** <tr><td><b>sqlcipher_sqlite3_column_type</b><td>→<td>Default +** datatype of the result +** </table></blockquote> +** +** <b>Details:</b> +** ** ^These routines return information about a single column of the current ** result row of a query. ^In every case the first argument is a pointer ** to the [prepared statement] that is being evaluated (the [sqlcipher_sqlite3_stmt*] @@ -3953,16 +4323,29 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_data_count(sqlcipher_sqlite3_stm ** are called from a different thread while any of these routines ** are pending, then the results are undefined. ** +** The first six interfaces (_blob, _double, _int, _int64, _text, and _text16) +** each return the value of a result column in a specific data format. If +** the result column is not initially in the requested format (for example, +** if the query returns an integer but the sqlcipher_sqlite3_column_text() interface +** is used to extract the value) then an automatic type conversion is performed. +** ** ^The sqlcipher_sqlite3_column_type() routine returns the ** [SQLITE_INTEGER | datatype code] for the initial data type ** of the result column. ^The returned value is one of [SQLITE_INTEGER], -** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value -** returned by sqlcipher_sqlite3_column_type() is only meaningful if no type -** conversions have occurred as described below. After a type conversion, -** the value returned by sqlcipher_sqlite3_column_type() is undefined. Future +** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. +** The return value of sqlcipher_sqlite3_column_type() can be used to decide which +** of the first six interface should be used to extract the column value. +** The value returned by sqlcipher_sqlite3_column_type() is only meaningful if no +** automatic type conversions have occurred for the value in question. +** After a type conversion, the result of calling sqlcipher_sqlite3_column_type() +** is undefined, though harmless. Future ** versions of SQLite may change the behavior of sqlcipher_sqlite3_column_type() ** following a type conversion. ** +** If the result is a BLOB or a TEXT string, then the sqlcipher_sqlite3_column_bytes() +** or sqlcipher_sqlite3_column_bytes16() interfaces can be used to determine the size +** of that BLOB or string. +** ** ^If the result is a BLOB or UTF-8 string then the sqlcipher_sqlite3_column_bytes() ** routine returns the number of bytes in that BLOB or string. ** ^If the result is a UTF-16 string, then sqlcipher_sqlite3_column_bytes() converts @@ -3999,9 +4382,13 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_data_count(sqlcipher_sqlite3_stm ** [sqlcipher_sqlite3_column_value()] is used in any other way, including calls ** to routines like [sqlcipher_sqlite3_value_int()], [sqlcipher_sqlite3_value_text()], ** or [sqlcipher_sqlite3_value_bytes()], the behavior is not threadsafe. +** Hence, the sqlcipher_sqlite3_column_value() interface +** is normally only useful within the implementation of +** [application-defined SQL functions] or [virtual tables], not within +** top-level application code. ** -** These routines attempt to convert the value where appropriate. ^For -** example, if the internal representation is FLOAT and a text result +** The these routines may attempt to convert the datatype of the result. +** ^For example, if the internal representation is FLOAT and a text result ** is requested, [sqlcipher_sqlite3_snprintf()] is used internally to perform the ** conversion automatically. ^(The following table details the conversions ** that are applied: @@ -4073,7 +4460,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_data_count(sqlcipher_sqlite3_stm ** ^The pointers returned are valid until a type conversion occurs as ** described above, or until [sqlcipher_sqlite3_step()] or [sqlcipher_sqlite3_reset()] or ** [sqlcipher_sqlite3_finalize()] is called. ^The memory space used to hold strings -** and BLOBs is freed automatically. Do <em>not</em> pass the pointers returned +** and BLOBs is freed automatically. Do not pass the pointers returned ** from [sqlcipher_sqlite3_column_blob()], [sqlcipher_sqlite3_column_text()], etc. into ** [sqlcipher_sqlite3_free()]. ** @@ -4083,16 +4470,16 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_data_count(sqlcipher_sqlite3_stm ** pointer. Subsequent calls to [sqlcipher_sqlite3_errcode()] will return ** [SQLITE_NOMEM].)^ */ -SQLITE_API const void *SQLITE_STDCALL sqlcipher_sqlite3_column_blob(sqlcipher_sqlite3_stmt*, int iCol); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_column_bytes(sqlcipher_sqlite3_stmt*, int iCol); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_column_bytes16(sqlcipher_sqlite3_stmt*, int iCol); -SQLITE_API double SQLITE_STDCALL sqlcipher_sqlite3_column_double(sqlcipher_sqlite3_stmt*, int iCol); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_column_int(sqlcipher_sqlite3_stmt*, int iCol); -SQLITE_API sqlcipher_sqlite3_int64 SQLITE_STDCALL sqlcipher_sqlite3_column_int64(sqlcipher_sqlite3_stmt*, int iCol); -SQLITE_API const unsigned char *SQLITE_STDCALL sqlcipher_sqlite3_column_text(sqlcipher_sqlite3_stmt*, int iCol); -SQLITE_API const void *SQLITE_STDCALL sqlcipher_sqlite3_column_text16(sqlcipher_sqlite3_stmt*, int iCol); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_column_type(sqlcipher_sqlite3_stmt*, int iCol); -SQLITE_API sqlcipher_sqlite3_value *SQLITE_STDCALL sqlcipher_sqlite3_column_value(sqlcipher_sqlite3_stmt*, int iCol); +SQLITE_API const void *sqlcipher_sqlite3_column_blob(sqlcipher_sqlite3_stmt*, int iCol); +SQLITE_API double sqlcipher_sqlite3_column_double(sqlcipher_sqlite3_stmt*, int iCol); +SQLITE_API int sqlcipher_sqlite3_column_int(sqlcipher_sqlite3_stmt*, int iCol); +SQLITE_API sqlcipher_sqlite3_int64 sqlcipher_sqlite3_column_int64(sqlcipher_sqlite3_stmt*, int iCol); +SQLITE_API const unsigned char *sqlcipher_sqlite3_column_text(sqlcipher_sqlite3_stmt*, int iCol); +SQLITE_API const void *sqlcipher_sqlite3_column_text16(sqlcipher_sqlite3_stmt*, int iCol); +SQLITE_API sqlcipher_sqlite3_value *sqlcipher_sqlite3_column_value(sqlcipher_sqlite3_stmt*, int iCol); +SQLITE_API int sqlcipher_sqlite3_column_bytes(sqlcipher_sqlite3_stmt*, int iCol); +SQLITE_API int sqlcipher_sqlite3_column_bytes16(sqlcipher_sqlite3_stmt*, int iCol); +SQLITE_API int sqlcipher_sqlite3_column_type(sqlcipher_sqlite3_stmt*, int iCol); /* ** CAPI3REF: Destroy A Prepared Statement Object @@ -4120,7 +4507,7 @@ SQLITE_API sqlcipher_sqlite3_value *SQLITE_STDCALL sqlcipher_sqlite3_column_valu ** statement after it has been finalized can result in undefined and ** undesirable behavior such as segfaults and heap corruption. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_finalize(sqlcipher_sqlite3_stmt *pStmt); +SQLITE_API int sqlcipher_sqlite3_finalize(sqlcipher_sqlite3_stmt *pStmt); /* ** CAPI3REF: Reset A Prepared Statement Object @@ -4147,7 +4534,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_finalize(sqlcipher_sqlite3_stmt ** ^The [sqlcipher_sqlite3_reset(S)] interface does not change the values ** of any [sqlcipher_sqlite3_bind_blob|bindings] on the [prepared statement] S. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_reset(sqlcipher_sqlite3_stmt *pStmt); +SQLITE_API int sqlcipher_sqlite3_reset(sqlcipher_sqlite3_stmt *pStmt); /* ** CAPI3REF: Create Or Redefine SQL Functions @@ -4247,7 +4634,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_reset(sqlcipher_sqlite3_stmt *pS ** close the database connection nor finalize or reset the prepared ** statement in which the function is running. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_create_function( +SQLITE_API int sqlcipher_sqlite3_create_function( sqlcipher_sqlite3 *db, const char *zFunctionName, int nArg, @@ -4257,7 +4644,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_create_function( void (*xStep)(sqlcipher_sqlite3_context*,int,sqlcipher_sqlite3_value**), void (*xFinal)(sqlcipher_sqlite3_context*) ); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_create_function16( +SQLITE_API int sqlcipher_sqlite3_create_function16( sqlcipher_sqlite3 *db, const void *zFunctionName, int nArg, @@ -4267,7 +4654,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_create_function16( void (*xStep)(sqlcipher_sqlite3_context*,int,sqlcipher_sqlite3_value**), void (*xFinal)(sqlcipher_sqlite3_context*) ); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_create_function_v2( +SQLITE_API int sqlcipher_sqlite3_create_function_v2( sqlcipher_sqlite3 *db, const char *zFunctionName, int nArg, @@ -4313,12 +4700,12 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_create_function_v2( ** these functions, we will not explain what they do. */ #ifndef SQLITE_OMIT_DEPRECATED -SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlcipher_sqlite3_aggregate_count(sqlcipher_sqlite3_context*); -SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlcipher_sqlite3_expired(sqlcipher_sqlite3_stmt*); -SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlcipher_sqlite3_transfer_bindings(sqlcipher_sqlite3_stmt*, sqlcipher_sqlite3_stmt*); -SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlcipher_sqlite3_global_recover(void); -SQLITE_API SQLITE_DEPRECATED void SQLITE_STDCALL sqlcipher_sqlite3_thread_cleanup(void); -SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlcipher_sqlite3_memory_alarm(void(*)(void*,sqlcipher_sqlite3_int64,int), +SQLITE_API SQLITE_DEPRECATED int sqlcipher_sqlite3_aggregate_count(sqlcipher_sqlite3_context*); +SQLITE_API SQLITE_DEPRECATED int sqlcipher_sqlite3_expired(sqlcipher_sqlite3_stmt*); +SQLITE_API SQLITE_DEPRECATED int sqlcipher_sqlite3_transfer_bindings(sqlcipher_sqlite3_stmt*, sqlcipher_sqlite3_stmt*); +SQLITE_API SQLITE_DEPRECATED int sqlcipher_sqlite3_global_recover(void); +SQLITE_API SQLITE_DEPRECATED void sqlcipher_sqlite3_thread_cleanup(void); +SQLITE_API SQLITE_DEPRECATED int sqlcipher_sqlite3_memory_alarm(void(*)(void*,sqlcipher_sqlite3_int64,int), void*,sqlcipher_sqlite3_int64); #endif @@ -4326,21 +4713,40 @@ SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlcipher_sqlite3_memory_alarm(v ** CAPI3REF: Obtaining SQL Values ** METHOD: sqlcipher_sqlite3_value ** -** The C-language implementation of SQL functions and aggregates uses -** this set of interface routines to access the parameter values on -** the function or aggregate. -** -** The xFunc (for scalar functions) or xStep (for aggregates) parameters -** to [sqlcipher_sqlite3_create_function()] and [sqlcipher_sqlite3_create_function16()] -** define callbacks that implement the SQL functions and aggregates. -** The 3rd parameter to these callbacks is an array of pointers to -** [protected sqlcipher_sqlite3_value] objects. There is one [sqlcipher_sqlite3_value] object for -** each parameter to the SQL function. These routines are used to -** extract values from the [sqlcipher_sqlite3_value] objects. +** <b>Summary:</b> +** <blockquote><table border=0 cellpadding=0 cellspacing=0> +** <tr><td><b>sqlcipher_sqlite3_value_blob</b><td>→<td>BLOB value +** <tr><td><b>sqlcipher_sqlite3_value_double</b><td>→<td>REAL value +** <tr><td><b>sqlcipher_sqlite3_value_int</b><td>→<td>32-bit INTEGER value +** <tr><td><b>sqlcipher_sqlite3_value_int64</b><td>→<td>64-bit INTEGER value +** <tr><td><b>sqlcipher_sqlite3_value_pointer</b><td>→<td>Pointer value +** <tr><td><b>sqlcipher_sqlite3_value_text</b><td>→<td>UTF-8 TEXT value +** <tr><td><b>sqlcipher_sqlite3_value_text16</b><td>→<td>UTF-16 TEXT value in +** the native byteorder +** <tr><td><b>sqlcipher_sqlite3_value_text16be</b><td>→<td>UTF-16be TEXT value +** <tr><td><b>sqlcipher_sqlite3_value_text16le</b><td>→<td>UTF-16le TEXT value +** <tr><td> <td> <td> +** <tr><td><b>sqlcipher_sqlite3_value_bytes</b><td>→<td>Size of a BLOB +** or a UTF-8 TEXT in bytes +** <tr><td><b>sqlcipher_sqlite3_value_bytes16 </b> +** <td>→ <td>Size of UTF-16 +** TEXT in bytes +** <tr><td><b>sqlcipher_sqlite3_value_type</b><td>→<td>Default +** datatype of the value +** <tr><td><b>sqlcipher_sqlite3_value_numeric_type </b> +** <td>→ <td>Best numeric datatype of the value +** </table></blockquote> +** +** <b>Details:</b> +** +** These routines extract type, size, and content information from +** [protected sqlcipher_sqlite3_value] objects. Protected sqlcipher_sqlite3_value objects +** are used to pass parameter information into implementation of +** [application-defined SQL functions] and [virtual tables]. ** ** These routines work only with [protected sqlcipher_sqlite3_value] objects. ** Any attempt to use these routines on an [unprotected sqlcipher_sqlite3_value] -** object results in undefined behavior. +** is not threadsafe. ** ** ^These routines work just like the corresponding [column access functions] ** except that these routines take a single [protected sqlcipher_sqlite3_value] object @@ -4351,6 +4757,24 @@ SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlcipher_sqlite3_memory_alarm(v ** sqlcipher_sqlite3_value_text16be() and sqlcipher_sqlite3_value_text16le() interfaces ** extract UTF-16 strings as big-endian and little-endian respectively. ** +** ^If [sqlcipher_sqlite3_value] object V was initialized +** using [sqlcipher_sqlite3_bind_pointer(S,I,P,X,D)] or [sqlcipher_sqlite3_result_pointer(C,P,X,D)] +** and if X and Y are strings that compare equal according to strcmp(X,Y), +** then sqlcipher_sqlite3_value_pointer(V,Y) will return the pointer P. ^Otherwise, +** sqlcipher_sqlite3_value_pointer(V,Y) returns a NULL. The sqlcipher_sqlite3_bind_pointer() +** routine is part of the [pointer passing interface] added for SQLite 3.20.0. +** +** ^(The sqlcipher_sqlite3_value_type(V) interface returns the +** [SQLITE_INTEGER | datatype code] for the initial datatype of the +** [sqlcipher_sqlite3_value] object V. The returned value is one of [SQLITE_INTEGER], +** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].)^ +** Other interfaces might change the datatype for an sqlcipher_sqlite3_value object. +** For example, if the datatype is initially SQLITE_INTEGER and +** sqlcipher_sqlite3_value_text(V) is called to extract a text value for that +** integer, then subsequent calls to sqlcipher_sqlite3_value_type(V) might return +** SQLITE_TEXT. Whether or not a persistent internal datatype conversion +** occurs is undefined and may change from one release of SQLite to the next. +** ** ^(The sqlcipher_sqlite3_value_numeric_type() interface attempts to apply ** numeric affinity to the value. This means that an attempt is ** made to convert the value to an integer or floating point. If @@ -4368,18 +4792,19 @@ SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlcipher_sqlite3_memory_alarm(v ** These routines must be called from the same thread as ** the SQL function that supplied the [sqlcipher_sqlite3_value*] parameters. */ -SQLITE_API const void *SQLITE_STDCALL sqlcipher_sqlite3_value_blob(sqlcipher_sqlite3_value*); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_value_bytes(sqlcipher_sqlite3_value*); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_value_bytes16(sqlcipher_sqlite3_value*); -SQLITE_API double SQLITE_STDCALL sqlcipher_sqlite3_value_double(sqlcipher_sqlite3_value*); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_value_int(sqlcipher_sqlite3_value*); -SQLITE_API sqlcipher_sqlite3_int64 SQLITE_STDCALL sqlcipher_sqlite3_value_int64(sqlcipher_sqlite3_value*); -SQLITE_API const unsigned char *SQLITE_STDCALL sqlcipher_sqlite3_value_text(sqlcipher_sqlite3_value*); -SQLITE_API const void *SQLITE_STDCALL sqlcipher_sqlite3_value_text16(sqlcipher_sqlite3_value*); -SQLITE_API const void *SQLITE_STDCALL sqlcipher_sqlite3_value_text16le(sqlcipher_sqlite3_value*); -SQLITE_API const void *SQLITE_STDCALL sqlcipher_sqlite3_value_text16be(sqlcipher_sqlite3_value*); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_value_type(sqlcipher_sqlite3_value*); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_value_numeric_type(sqlcipher_sqlite3_value*); +SQLITE_API const void *sqlcipher_sqlite3_value_blob(sqlcipher_sqlite3_value*); +SQLITE_API double sqlcipher_sqlite3_value_double(sqlcipher_sqlite3_value*); +SQLITE_API int sqlcipher_sqlite3_value_int(sqlcipher_sqlite3_value*); +SQLITE_API sqlcipher_sqlite3_int64 sqlcipher_sqlite3_value_int64(sqlcipher_sqlite3_value*); +SQLITE_API void *sqlcipher_sqlite3_value_pointer(sqlcipher_sqlite3_value*, const char*); +SQLITE_API const unsigned char *sqlcipher_sqlite3_value_text(sqlcipher_sqlite3_value*); +SQLITE_API const void *sqlcipher_sqlite3_value_text16(sqlcipher_sqlite3_value*); +SQLITE_API const void *sqlcipher_sqlite3_value_text16le(sqlcipher_sqlite3_value*); +SQLITE_API const void *sqlcipher_sqlite3_value_text16be(sqlcipher_sqlite3_value*); +SQLITE_API int sqlcipher_sqlite3_value_bytes(sqlcipher_sqlite3_value*); +SQLITE_API int sqlcipher_sqlite3_value_bytes16(sqlcipher_sqlite3_value*); +SQLITE_API int sqlcipher_sqlite3_value_type(sqlcipher_sqlite3_value*); +SQLITE_API int sqlcipher_sqlite3_value_numeric_type(sqlcipher_sqlite3_value*); /* ** CAPI3REF: Finding The Subtype Of SQL Values @@ -4390,12 +4815,8 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_value_numeric_type(sqlcipher_sql ** information can be used to pass a limited amount of context from ** one SQL function to another. Use the [sqlcipher_sqlite3_result_subtype()] ** routine to set the subtype for the return value of an SQL function. -** -** SQLite makes no use of subtype itself. It merely passes the subtype -** from the result of one [application-defined SQL function] into the -** input of another. */ -SQLITE_API unsigned int SQLITE_STDCALL sqlcipher_sqlite3_value_subtype(sqlcipher_sqlite3_value*); +SQLITE_API unsigned int sqlcipher_sqlite3_value_subtype(sqlcipher_sqlite3_value*); /* ** CAPI3REF: Copy And Free SQL Values @@ -4411,8 +4832,8 @@ SQLITE_API unsigned int SQLITE_STDCALL sqlcipher_sqlite3_value_subtype(sqlcipher ** previously obtained from [sqlcipher_sqlite3_value_dup()]. ^If V is a NULL pointer ** then sqlcipher_sqlite3_value_free(V) is a harmless no-op. */ -SQLITE_API sqlcipher_sqlite3_value *SQLITE_STDCALL sqlcipher_sqlite3_value_dup(const sqlcipher_sqlite3_value*); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_value_free(sqlcipher_sqlite3_value*); +SQLITE_API sqlcipher_sqlite3_value *sqlcipher_sqlite3_value_dup(const sqlcipher_sqlite3_value*); +SQLITE_API void sqlcipher_sqlite3_value_free(sqlcipher_sqlite3_value*); /* ** CAPI3REF: Obtain Aggregate Function Context @@ -4457,7 +4878,7 @@ SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_value_free(sqlcipher_sqlite3_va ** This routine must be called from the same thread in which ** the aggregate SQL function is running. */ -SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_aggregate_context(sqlcipher_sqlite3_context*, int nBytes); +SQLITE_API void *sqlcipher_sqlite3_aggregate_context(sqlcipher_sqlite3_context*, int nBytes); /* ** CAPI3REF: User Data For Functions @@ -4472,7 +4893,7 @@ SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_aggregate_context(sqlcipher_sq ** This routine must be called from the same thread in which ** the application-defined function is running. */ -SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_user_data(sqlcipher_sqlite3_context*); +SQLITE_API void *sqlcipher_sqlite3_user_data(sqlcipher_sqlite3_context*); /* ** CAPI3REF: Database Connection For Functions @@ -4484,7 +4905,7 @@ SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_user_data(sqlcipher_sqlite3_co ** and [sqlcipher_sqlite3_create_function16()] routines that originally ** registered the application defined function. */ -SQLITE_API sqlcipher_sqlite3 *SQLITE_STDCALL sqlcipher_sqlite3_context_db_handle(sqlcipher_sqlite3_context*); +SQLITE_API sqlcipher_sqlite3 *sqlcipher_sqlite3_context_db_handle(sqlcipher_sqlite3_context*); /* ** CAPI3REF: Function Auxiliary Data @@ -4501,10 +4922,11 @@ SQLITE_API sqlcipher_sqlite3 *SQLITE_STDCALL sqlcipher_sqlite3_context_db_handle ** the compiled regular expression can be reused on multiple ** invocations of the same function. ** -** ^The sqlcipher_sqlite3_get_auxdata() interface returns a pointer to the metadata -** associated by the sqlcipher_sqlite3_set_auxdata() function with the Nth argument -** value to the application-defined function. ^If there is no metadata -** associated with the function argument, this sqlcipher_sqlite3_get_auxdata() interface +** ^The sqlcipher_sqlite3_get_auxdata(C,N) interface returns a pointer to the metadata +** associated by the sqlcipher_sqlite3_set_auxdata(C,N,P,X) function with the Nth argument +** value to the application-defined function. ^N is zero for the left-most +** function argument. ^If there is no metadata +** associated with the function argument, the sqlcipher_sqlite3_get_auxdata(C,N) interface ** returns a NULL pointer. ** ** ^The sqlcipher_sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th @@ -4516,12 +4938,13 @@ SQLITE_API sqlcipher_sqlite3 *SQLITE_STDCALL sqlcipher_sqlite3_context_db_handle ** SQLite will invoke the destructor function X with parameter P exactly ** once, when the metadata is discarded. ** SQLite is free to discard the metadata at any time, including: <ul> -** <li> when the corresponding function parameter changes, or -** <li> when [sqlcipher_sqlite3_reset()] or [sqlcipher_sqlite3_finalize()] is called for the -** SQL statement, or -** <li> when sqlcipher_sqlite3_set_auxdata() is invoked again on the same parameter, or -** <li> during the original sqlcipher_sqlite3_set_auxdata() call when a memory -** allocation error occurs. </ul>)^ +** <li> ^(when the corresponding function parameter changes)^, or +** <li> ^(when [sqlcipher_sqlite3_reset()] or [sqlcipher_sqlite3_finalize()] is called for the +** SQL statement)^, or +** <li> ^(when sqlcipher_sqlite3_set_auxdata() is invoked again on the same +** parameter)^, or +** <li> ^(during the original sqlcipher_sqlite3_set_auxdata() call when a memory +** allocation error occurs.)^ </ul> ** ** Note the last bullet in particular. The destructor X in ** sqlcipher_sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the @@ -4534,11 +4957,15 @@ SQLITE_API sqlcipher_sqlite3 *SQLITE_STDCALL sqlcipher_sqlite3_context_db_handle ** function parameters that are compile-time constants, including literal ** values and [parameters] and expressions composed from the same.)^ ** +** The value of the N parameter to these interfaces should be non-negative. +** Future enhancements may make use of negative N values to define new +** kinds of function caching behavior. +** ** These routines must be called from the same thread in which ** the SQL function is running. */ -SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_get_auxdata(sqlcipher_sqlite3_context*, int N); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_set_auxdata(sqlcipher_sqlite3_context*, int N, void*, void (*)(void*)); +SQLITE_API void *sqlcipher_sqlite3_get_auxdata(sqlcipher_sqlite3_context*, int N); +SQLITE_API void sqlcipher_sqlite3_set_auxdata(sqlcipher_sqlite3_context*, int N, void*, void (*)(void*)); /* @@ -4657,7 +5084,7 @@ typedef void (*sqlcipher_sqlite3_destructor_type)(void*); ** when it has finished using that result. ** ^If the 4th parameter to the sqlcipher_sqlite3_result_text* interfaces ** or sqlcipher_sqlite3_result_blob is the special constant SQLITE_TRANSIENT -** then SQLite makes a copy of the result into space obtained from +** then SQLite makes a copy of the result into space obtained ** from [sqlcipher_sqlite3_malloc()] before it returns. ** ** ^The sqlcipher_sqlite3_result_value() interface sets the result of @@ -4670,31 +5097,43 @@ typedef void (*sqlcipher_sqlite3_destructor_type)(void*); ** [unprotected sqlcipher_sqlite3_value] object is required, so either ** kind of [sqlcipher_sqlite3_value] object can be used with this interface. ** +** ^The sqlcipher_sqlite3_result_pointer(C,P,T,D) interface sets the result to an +** SQL NULL value, just like [sqlcipher_sqlite3_result_null(C)], except that it +** also associates the host-language pointer P or type T with that +** NULL value such that the pointer can be retrieved within an +** [application-defined SQL function] using [sqlcipher_sqlite3_value_pointer()]. +** ^If the D parameter is not NULL, then it is a pointer to a destructor +** for the P parameter. ^SQLite invokes D with P as its only argument +** when SQLite is finished with P. The T parameter should be a static +** string and preferably a string literal. The sqlcipher_sqlite3_result_pointer() +** routine is part of the [pointer passing interface] added for SQLite 3.20.0. +** ** If these routines are called from within the different thread ** than the one containing the application-defined function that received ** the [sqlcipher_sqlite3_context] pointer, the results are undefined. */ -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_blob(sqlcipher_sqlite3_context*, const void*, int, void(*)(void*)); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_blob64(sqlcipher_sqlite3_context*,const void*, +SQLITE_API void sqlcipher_sqlite3_result_blob(sqlcipher_sqlite3_context*, const void*, int, void(*)(void*)); +SQLITE_API void sqlcipher_sqlite3_result_blob64(sqlcipher_sqlite3_context*,const void*, sqlcipher_sqlite3_uint64,void(*)(void*)); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_double(sqlcipher_sqlite3_context*, double); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_error(sqlcipher_sqlite3_context*, const char*, int); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_error16(sqlcipher_sqlite3_context*, const void*, int); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_error_toobig(sqlcipher_sqlite3_context*); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_error_nomem(sqlcipher_sqlite3_context*); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_error_code(sqlcipher_sqlite3_context*, int); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_int(sqlcipher_sqlite3_context*, int); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_int64(sqlcipher_sqlite3_context*, sqlcipher_sqlite3_int64); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_null(sqlcipher_sqlite3_context*); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_text(sqlcipher_sqlite3_context*, const char*, int, void(*)(void*)); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_text64(sqlcipher_sqlite3_context*, const char*,sqlcipher_sqlite3_uint64, +SQLITE_API void sqlcipher_sqlite3_result_double(sqlcipher_sqlite3_context*, double); +SQLITE_API void sqlcipher_sqlite3_result_error(sqlcipher_sqlite3_context*, const char*, int); +SQLITE_API void sqlcipher_sqlite3_result_error16(sqlcipher_sqlite3_context*, const void*, int); +SQLITE_API void sqlcipher_sqlite3_result_error_toobig(sqlcipher_sqlite3_context*); +SQLITE_API void sqlcipher_sqlite3_result_error_nomem(sqlcipher_sqlite3_context*); +SQLITE_API void sqlcipher_sqlite3_result_error_code(sqlcipher_sqlite3_context*, int); +SQLITE_API void sqlcipher_sqlite3_result_int(sqlcipher_sqlite3_context*, int); +SQLITE_API void sqlcipher_sqlite3_result_int64(sqlcipher_sqlite3_context*, sqlcipher_sqlite3_int64); +SQLITE_API void sqlcipher_sqlite3_result_null(sqlcipher_sqlite3_context*); +SQLITE_API void sqlcipher_sqlite3_result_text(sqlcipher_sqlite3_context*, const char*, int, void(*)(void*)); +SQLITE_API void sqlcipher_sqlite3_result_text64(sqlcipher_sqlite3_context*, const char*,sqlcipher_sqlite3_uint64, void(*)(void*), unsigned char encoding); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_text16(sqlcipher_sqlite3_context*, const void*, int, void(*)(void*)); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_text16le(sqlcipher_sqlite3_context*, const void*, int,void(*)(void*)); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_text16be(sqlcipher_sqlite3_context*, const void*, int,void(*)(void*)); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_value(sqlcipher_sqlite3_context*, sqlcipher_sqlite3_value*); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_zeroblob(sqlcipher_sqlite3_context*, int n); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_result_zeroblob64(sqlcipher_sqlite3_context*, sqlcipher_sqlite3_uint64 n); +SQLITE_API void sqlcipher_sqlite3_result_text16(sqlcipher_sqlite3_context*, const void*, int, void(*)(void*)); +SQLITE_API void sqlcipher_sqlite3_result_text16le(sqlcipher_sqlite3_context*, const void*, int,void(*)(void*)); +SQLITE_API void sqlcipher_sqlite3_result_text16be(sqlcipher_sqlite3_context*, const void*, int,void(*)(void*)); +SQLITE_API void sqlcipher_sqlite3_result_value(sqlcipher_sqlite3_context*, sqlcipher_sqlite3_value*); +SQLITE_API void sqlcipher_sqlite3_result_pointer(sqlcipher_sqlite3_context*, void*,const char*,void(*)(void*)); +SQLITE_API void sqlcipher_sqlite3_result_zeroblob(sqlcipher_sqlite3_context*, int n); +SQLITE_API int sqlcipher_sqlite3_result_zeroblob64(sqlcipher_sqlite3_context*, sqlcipher_sqlite3_uint64 n); /* @@ -4709,7 +5148,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_result_zeroblob64(sqlcipher_sqli ** The number of subtype bytes preserved by SQLite might increase ** in future releases of SQLite. */ -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_subtype(sqlcipher_sqlite3_context*,unsigned int); +SQLITE_API void sqlcipher_sqlite3_result_subtype(sqlcipher_sqlite3_context*,unsigned int); /* ** CAPI3REF: Define New Collating Sequences @@ -4791,14 +5230,14 @@ SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_result_subtype(sqlcipher_sqlite ** ** See also: [sqlcipher_sqlite3_collation_needed()] and [sqlcipher_sqlite3_collation_needed16()]. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_create_collation( +SQLITE_API int sqlcipher_sqlite3_create_collation( sqlcipher_sqlite3*, const char *zName, int eTextRep, void *pArg, int(*xCompare)(void*,int,const void*,int,const void*) ); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_create_collation_v2( +SQLITE_API int sqlcipher_sqlite3_create_collation_v2( sqlcipher_sqlite3*, const char *zName, int eTextRep, @@ -4806,7 +5245,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_create_collation_v2( int(*xCompare)(void*,int,const void*,int,const void*), void(*xDestroy)(void*) ); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_create_collation16( +SQLITE_API int sqlcipher_sqlite3_create_collation16( sqlcipher_sqlite3*, const void *zName, int eTextRep, @@ -4841,12 +5280,12 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_create_collation16( ** [sqlcipher_sqlite3_create_collation()], [sqlcipher_sqlite3_create_collation16()], or ** [sqlcipher_sqlite3_create_collation_v2()]. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_collation_needed( +SQLITE_API int sqlcipher_sqlite3_collation_needed( sqlcipher_sqlite3*, void*, void(*)(void*,sqlcipher_sqlite3*,int eTextRep,const char*) ); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_collation_needed16( +SQLITE_API int sqlcipher_sqlite3_collation_needed16( sqlcipher_sqlite3*, void*, void(*)(void*,sqlcipher_sqlite3*,int eTextRep,const void*) @@ -4860,11 +5299,11 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_collation_needed16( ** The code to implement this API is not available in the public release ** of SQLite. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_key( +SQLITE_API int sqlcipher_sqlite3_key( sqlcipher_sqlite3 *db, /* Database to be rekeyed */ const void *pKey, int nKey /* The key */ ); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_key_v2( +SQLITE_API int sqlcipher_sqlite3_key_v2( sqlcipher_sqlite3 *db, /* Database to be rekeyed */ const char *zDbName, /* Name of the database */ const void *pKey, int nKey /* The key */ @@ -4878,11 +5317,11 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_key_v2( ** The code to implement this API is not available in the public release ** of SQLite. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_rekey( +SQLITE_API int sqlcipher_sqlite3_rekey( sqlcipher_sqlite3 *db, /* Database to be rekeyed */ const void *pKey, int nKey /* The new key */ ); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_rekey_v2( +SQLITE_API int sqlcipher_sqlite3_rekey_v2( sqlcipher_sqlite3 *db, /* Database to be rekeyed */ const char *zDbName, /* Name of the database */ const void *pKey, int nKey /* The new key */ @@ -4892,7 +5331,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_rekey_v2( ** Specify the activation key for a SEE database. Unless ** activated, none of the SEE routines will work. */ -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_activate_see( +SQLITE_API void sqlcipher_sqlite3_activate_see( const char *zPassPhrase /* Activation phrase */ ); #endif @@ -4902,7 +5341,7 @@ SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_activate_see( ** Specify the activation key for a CEROD database. Unless ** activated, none of the CEROD routines will work. */ -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_activate_cerod( +SQLITE_API void sqlcipher_sqlite3_activate_cerod( const char *zPassPhrase /* Activation phrase */ ); #endif @@ -4924,7 +5363,7 @@ SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_activate_cerod( ** all, then the behavior of sqlcipher_sqlite3_sleep() may deviate from the description ** in the previous paragraphs. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_sleep(int); +SQLITE_API int sqlcipher_sqlite3_sleep(int); /* ** CAPI3REF: Name Of The Folder Holding Temporary Files @@ -5043,7 +5482,7 @@ SQLITE_API SQLITE_EXTERN char *sqlcipher_sqlite3_data_directory; ** connection while this routine is running, then the return value ** is undefined. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_get_autocommit(sqlcipher_sqlite3*); +SQLITE_API int sqlcipher_sqlite3_get_autocommit(sqlcipher_sqlite3*); /* ** CAPI3REF: Find The Database Handle Of A Prepared Statement @@ -5056,7 +5495,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_get_autocommit(sqlcipher_sqlite3 ** to the [sqlcipher_sqlite3_prepare_v2()] call (or its variants) that was used to ** create the statement in the first place. */ -SQLITE_API sqlcipher_sqlite3 *SQLITE_STDCALL sqlcipher_sqlite3_db_handle(sqlcipher_sqlite3_stmt*); +SQLITE_API sqlcipher_sqlite3 *sqlcipher_sqlite3_db_handle(sqlcipher_sqlite3_stmt*); /* ** CAPI3REF: Return The Filename For A Database Connection @@ -5073,7 +5512,7 @@ SQLITE_API sqlcipher_sqlite3 *SQLITE_STDCALL sqlcipher_sqlite3_db_handle(sqlciph ** will be an absolute pathname, even if the filename used ** to open the database originally was a URI or relative pathname. */ -SQLITE_API const char *SQLITE_STDCALL sqlcipher_sqlite3_db_filename(sqlcipher_sqlite3 *db, const char *zDbName); +SQLITE_API const char *sqlcipher_sqlite3_db_filename(sqlcipher_sqlite3 *db, const char *zDbName); /* ** CAPI3REF: Determine if a database is read-only @@ -5083,7 +5522,7 @@ SQLITE_API const char *SQLITE_STDCALL sqlcipher_sqlite3_db_filename(sqlcipher_sq ** of connection D is read-only, 0 if it is read/write, or -1 if N is not ** the name of a database on connection D. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_db_readonly(sqlcipher_sqlite3 *db, const char *zDbName); +SQLITE_API int sqlcipher_sqlite3_db_readonly(sqlcipher_sqlite3 *db, const char *zDbName); /* ** CAPI3REF: Find the next prepared statement @@ -5099,7 +5538,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_db_readonly(sqlcipher_sqlite3 *d ** [sqlcipher_sqlite3_next_stmt(D,S)] must refer to an open database ** connection and in particular must not be a NULL pointer. */ -SQLITE_API sqlcipher_sqlite3_stmt *SQLITE_STDCALL sqlcipher_sqlite3_next_stmt(sqlcipher_sqlite3 *pDb, sqlcipher_sqlite3_stmt *pStmt); +SQLITE_API sqlcipher_sqlite3_stmt *sqlcipher_sqlite3_next_stmt(sqlcipher_sqlite3 *pDb, sqlcipher_sqlite3_stmt *pStmt); /* ** CAPI3REF: Commit And Rollback Notification Callbacks @@ -5148,8 +5587,8 @@ SQLITE_API sqlcipher_sqlite3_stmt *SQLITE_STDCALL sqlcipher_sqlite3_next_stmt(sq ** ** See also the [sqlcipher_sqlite3_update_hook()] interface. */ -SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_commit_hook(sqlcipher_sqlite3*, int(*)(void*), void*); -SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_rollback_hook(sqlcipher_sqlite3*, void(*)(void *), void*); +SQLITE_API void *sqlcipher_sqlite3_commit_hook(sqlcipher_sqlite3*, int(*)(void*), void*); +SQLITE_API void *sqlcipher_sqlite3_rollback_hook(sqlcipher_sqlite3*, void(*)(void *), void*); /* ** CAPI3REF: Data Change Notification Callbacks @@ -5158,7 +5597,7 @@ SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_rollback_hook(sqlcipher_sqlite ** ^The sqlcipher_sqlite3_update_hook() interface registers a callback function ** with the [database connection] identified by the first argument ** to be invoked whenever a row is updated, inserted or deleted in -** a rowid table. +** a [rowid table]. ** ^Any callback set by a previous call to this function ** for the same database connection is overridden. ** @@ -5179,7 +5618,7 @@ SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_rollback_hook(sqlcipher_sqlite ** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified. ** ** ^In the current implementation, the update hook -** is not invoked when duplication rows are deleted because of an +** is not invoked when conflicting rows are deleted because of an ** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook ** invoked when rows are deleted using the [truncate optimization]. ** The exceptions defined in this paragraph might change in a future @@ -5197,10 +5636,10 @@ SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_rollback_hook(sqlcipher_sqlite ** on the same [database connection] D, or NULL for ** the first call on D. ** -** See also the [sqlcipher_sqlite3_commit_hook()] and [sqlcipher_sqlite3_rollback_hook()] -** interfaces. +** See also the [sqlcipher_sqlite3_commit_hook()], [sqlcipher_sqlite3_rollback_hook()], +** and [sqlcipher_sqlite3_preupdate_hook()] interfaces. */ -SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_update_hook( +SQLITE_API void *sqlcipher_sqlite3_update_hook( sqlcipher_sqlite3*, void(*)(void *,int ,char const *,char const *,sqlcipher_sqlite3_int64), void* @@ -5215,7 +5654,8 @@ SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_update_hook( ** and disabled if the argument is false.)^ ** ** ^Cache sharing is enabled and disabled for an entire process. -** This is a change as of SQLite version 3.5.0. In prior versions of SQLite, +** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]). +** In prior versions of SQLite, ** sharing was enabled or disabled for each thread separately. ** ** ^(The cache sharing mode set by this interface effects all subsequent @@ -5240,7 +5680,7 @@ SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_update_hook( ** ** See Also: [SQLite Shared-Cache Mode] */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_enable_shared_cache(int); +SQLITE_API int sqlcipher_sqlite3_enable_shared_cache(int); /* ** CAPI3REF: Attempt To Free Heap Memory @@ -5256,7 +5696,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_enable_shared_cache(int); ** ** See also: [sqlcipher_sqlite3_db_release_memory()] */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_release_memory(int); +SQLITE_API int sqlcipher_sqlite3_release_memory(int); /* ** CAPI3REF: Free Memory Used By A Database Connection @@ -5270,7 +5710,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_release_memory(int); ** ** See also: [sqlcipher_sqlite3_release_memory()] */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_db_release_memory(sqlcipher_sqlite3*); +SQLITE_API int sqlcipher_sqlite3_db_release_memory(sqlcipher_sqlite3*); /* ** CAPI3REF: Impose A Limit On Heap Size @@ -5309,7 +5749,8 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_db_release_memory(sqlcipher_sqli ** from the heap. ** </ul>)^ ** -** Beginning with SQLite version 3.7.3, the soft heap limit is enforced +** Beginning with SQLite [version 3.7.3] ([dateof:3.7.3]), +** the soft heap limit is enforced ** regardless of whether or not the [SQLITE_ENABLE_MEMORY_MANAGEMENT] ** compile-time option is invoked. With [SQLITE_ENABLE_MEMORY_MANAGEMENT], ** the soft heap limit is enforced on every memory allocation. Without @@ -5322,7 +5763,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_db_release_memory(sqlcipher_sqli ** The circumstances under which SQLite will enforce the soft heap limit may ** changes in future releases of SQLite. */ -SQLITE_API sqlcipher_sqlite3_int64 SQLITE_STDCALL sqlcipher_sqlite3_soft_heap_limit64(sqlcipher_sqlite3_int64 N); +SQLITE_API sqlcipher_sqlite3_int64 sqlcipher_sqlite3_soft_heap_limit64(sqlcipher_sqlite3_int64 N); /* ** CAPI3REF: Deprecated Soft Heap Limit Interface @@ -5333,7 +5774,7 @@ SQLITE_API sqlcipher_sqlite3_int64 SQLITE_STDCALL sqlcipher_sqlite3_soft_heap_li ** only. All new applications should use the ** [sqlcipher_sqlite3_soft_heap_limit64()] interface rather than this one. */ -SQLITE_API SQLITE_DEPRECATED void SQLITE_STDCALL sqlcipher_sqlite3_soft_heap_limit(int N); +SQLITE_API SQLITE_DEPRECATED void sqlcipher_sqlite3_soft_heap_limit(int N); /* @@ -5348,9 +5789,11 @@ SQLITE_API SQLITE_DEPRECATED void SQLITE_STDCALL sqlcipher_sqlite3_soft_heap_lim ** column exists. ^The sqlcipher_sqlite3_table_column_metadata() interface returns ** SQLITE_ERROR and if the specified column does not exist. ** ^If the column-name parameter to sqlcipher_sqlite3_table_column_metadata() is a -** NULL pointer, then this routine simply checks for the existance of the +** NULL pointer, then this routine simply checks for the existence of the ** table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it -** does not. +** does not. If the table name parameter T in a call to +** sqlcipher_sqlite3_table_column_metadata(X,D,T,C,...) is NULL then the result is +** undefined behavior. ** ** ^The column is identified by the second, third and fourth parameters to ** this function. ^(The second parameter is either the name of the database @@ -5403,7 +5846,7 @@ SQLITE_API SQLITE_DEPRECATED void SQLITE_STDCALL sqlcipher_sqlite3_soft_heap_lim ** parsed, if that has not already been done, and returns an error if ** any errors are encountered while loading the schema. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_table_column_metadata( +SQLITE_API int sqlcipher_sqlite3_table_column_metadata( sqlcipher_sqlite3 *db, /* Connection handle */ const char *zDbName, /* Database name or NULL */ const char *zTableName, /* Table name */ @@ -5445,12 +5888,21 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_table_column_metadata( ** should free this memory by calling [sqlcipher_sqlite3_free()]. ** ** ^Extension loading must be enabled using -** [sqlcipher_sqlite3_enable_load_extension()] prior to calling this API, +** [sqlcipher_sqlite3_enable_load_extension()] or +** [sqlcipher_sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],1,NULL) +** prior to calling this API, ** otherwise an error will be returned. ** +** <b>Security warning:</b> It is recommended that the +** [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method be used to enable only this +** interface. The use of the [sqlcipher_sqlite3_enable_load_extension()] interface +** should be avoided. This will keep the SQL function [load_extension()] +** disabled and prevent SQL injections from giving attackers +** access to extension loading capabilities. +** ** See also the [load_extension() SQL function]. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_load_extension( +SQLITE_API int sqlcipher_sqlite3_load_extension( sqlcipher_sqlite3 *db, /* Load the extension into this database connection */ const char *zFile, /* Name of the shared library containing extension */ const char *zProc, /* Entry point. Derived from zFile if 0 */ @@ -5470,8 +5922,19 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_load_extension( ** ^Call the sqlcipher_sqlite3_enable_load_extension() routine with onoff==1 ** to turn extension loading on and call it with onoff==0 to turn ** it back off again. +** +** ^This interface enables or disables both the C-API +** [sqlcipher_sqlite3_load_extension()] and the SQL function [load_extension()]. +** ^(Use [sqlcipher_sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],..) +** to enable or disable only the C-API.)^ +** +** <b>Security warning:</b> It is recommended that extension loading +** be disabled using the [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method +** rather than this interface, so the [load_extension()] SQL function +** remains disabled. This will prevent SQL injections from giving attackers +** access to extension loading capabilities. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_enable_load_extension(sqlcipher_sqlite3 *db, int onoff); +SQLITE_API int sqlcipher_sqlite3_enable_load_extension(sqlcipher_sqlite3 *db, int onoff); /* ** CAPI3REF: Automatically Load Statically Linked Extensions @@ -5483,7 +5946,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_enable_load_extension(sqlcipher_ ** ** ^(Even though the function prototype shows that xEntryPoint() takes ** no arguments and returns void, SQLite invokes xEntryPoint() with three -** arguments and expects and integer result as if the signature of the +** arguments and expects an integer result as if the signature of the ** entry point where as follows: ** ** <blockquote><pre> @@ -5509,7 +5972,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_enable_load_extension(sqlcipher_ ** See also: [sqlcipher_sqlite3_reset_auto_extension()] ** and [sqlcipher_sqlite3_cancel_auto_extension()] */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_auto_extension(void (*xEntryPoint)(void)); +SQLITE_API int sqlcipher_sqlite3_auto_extension(void(*xEntryPoint)(void)); /* ** CAPI3REF: Cancel Automatic Extension Loading @@ -5521,7 +5984,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_auto_extension(void (*xEntryPoin ** unregistered and it returns 0 if X was not on the list of initialization ** routines. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_cancel_auto_extension(void (*xEntryPoint)(void)); +SQLITE_API int sqlcipher_sqlite3_cancel_auto_extension(void(*xEntryPoint)(void)); /* ** CAPI3REF: Reset Automatic Extension Loading @@ -5529,7 +5992,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_cancel_auto_extension(void (*xEn ** ^This interface disables all automatic extensions previously ** registered using [sqlcipher_sqlite3_auto_extension()]. */ -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_reset_auto_extension(void); +SQLITE_API void sqlcipher_sqlite3_reset_auto_extension(void); /* ** The interface to the virtual-table mechanism is currently considered @@ -5683,13 +6146,15 @@ struct sqlcipher_sqlite3_module { ** the xUpdate method are automatically rolled back by SQLite. ** ** IMPORTANT: The estimatedRows field was added to the sqlcipher_sqlite3_index_info -** structure for SQLite version 3.8.2. If a virtual table extension is +** structure for SQLite [version 3.8.2] ([dateof:3.8.2]). +** If a virtual table extension is ** used with an SQLite version earlier than 3.8.2, the results of attempting ** to read or write the estimatedRows field are undefined (but are likely ** to included crashing the application). The estimatedRows field should ** therefore only be used if [sqlcipher_sqlite3_libversion_number()] returns a ** value greater than or equal to 3008002. Similarly, the idxFlags field -** was added for version 3.9.0. It may therefore only be used if +** was added for [version 3.9.0] ([dateof:3.9.0]). +** It may therefore only be used if ** sqlcipher_sqlite3_libversion_number() returns a value greater than or equal to ** 3009000. */ @@ -5774,13 +6239,13 @@ struct sqlcipher_sqlite3_index_info { ** interface is equivalent to sqlcipher_sqlite3_create_module_v2() with a NULL ** destructor. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_create_module( +SQLITE_API int sqlcipher_sqlite3_create_module( sqlcipher_sqlite3 *db, /* SQLite connection to register module with */ const char *zName, /* Name of the module */ const sqlcipher_sqlite3_module *p, /* Methods for the module */ void *pClientData /* Client data for xCreate/xConnect */ ); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_create_module_v2( +SQLITE_API int sqlcipher_sqlite3_create_module_v2( sqlcipher_sqlite3 *db, /* SQLite connection to register module with */ const char *zName, /* Name of the module */ const sqlcipher_sqlite3_module *p, /* Methods for the module */ @@ -5843,7 +6308,7 @@ struct sqlcipher_sqlite3_vtab_cursor { ** to declare the format (the names and datatypes of the columns) of ** the virtual tables they implement. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_declare_vtab(sqlcipher_sqlite3*, const char *zSQL); +SQLITE_API int sqlcipher_sqlite3_declare_vtab(sqlcipher_sqlite3*, const char *zSQL); /* ** CAPI3REF: Overload A Function For A Virtual Table @@ -5862,7 +6327,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_declare_vtab(sqlcipher_sqlite3*, ** purpose is to be a placeholder function that can be overloaded ** by a [virtual table]. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_overload_function(sqlcipher_sqlite3*, const char *zFuncName, int nArg); +SQLITE_API int sqlcipher_sqlite3_overload_function(sqlcipher_sqlite3*, const char *zFuncName, int nArg); /* ** The interface to the virtual-table mechanism defined above (back up @@ -5937,6 +6402,12 @@ typedef struct sqlcipher_sqlite3_blob sqlcipher_sqlite3_blob; ** [database connection] error code and message accessible via ** [sqlcipher_sqlite3_errcode()] and [sqlcipher_sqlite3_errmsg()] and related functions. ** +** A BLOB referenced by sqlcipher_sqlite3_blob_open() may be read using the +** [sqlcipher_sqlite3_blob_read()] interface and modified by using +** [sqlcipher_sqlite3_blob_write()]. The [BLOB handle] can be moved to a +** different row of the same table using the [sqlcipher_sqlite3_blob_reopen()] +** interface. However, the column, table, or database of a [BLOB handle] +** cannot be changed after the [BLOB handle] is opened. ** ** ^(If the row that a BLOB handle points to is modified by an ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects @@ -5960,8 +6431,12 @@ typedef struct sqlcipher_sqlite3_blob sqlcipher_sqlite3_blob; ** ** To avoid a resource leak, every open [BLOB handle] should eventually ** be released by a call to [sqlcipher_sqlite3_blob_close()]. +** +** See also: [sqlcipher_sqlite3_blob_close()], +** [sqlcipher_sqlite3_blob_reopen()], [sqlcipher_sqlite3_blob_read()], +** [sqlcipher_sqlite3_blob_bytes()], [sqlcipher_sqlite3_blob_write()]. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_blob_open( +SQLITE_API int sqlcipher_sqlite3_blob_open( sqlcipher_sqlite3*, const char *zDb, const char *zTable, @@ -5975,11 +6450,11 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_blob_open( ** CAPI3REF: Move a BLOB Handle to a New Row ** METHOD: sqlcipher_sqlite3_blob ** -** ^This function is used to move an existing blob handle so that it points +** ^This function is used to move an existing [BLOB handle] so that it points ** to a different row of the same database table. ^The new row is identified ** by the rowid value passed as the second argument. Only the row can be ** changed. ^The database, table and column on which the blob handle is open -** remain the same. Moving an existing blob handle to a new row can be +** remain the same. Moving an existing [BLOB handle] to a new row is ** faster than closing the existing handle and opening a new one. ** ** ^(The new row must meet the same criteria as for [sqlcipher_sqlite3_blob_open()] - @@ -5994,7 +6469,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_blob_open( ** ** ^This function sets the database handle error code and message. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_blob_reopen(sqlcipher_sqlite3_blob *, sqlcipher_sqlite3_int64); +SQLITE_API int sqlcipher_sqlite3_blob_reopen(sqlcipher_sqlite3_blob *, sqlcipher_sqlite3_int64); /* ** CAPI3REF: Close A BLOB Handle @@ -6017,7 +6492,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_blob_reopen(sqlcipher_sqlite3_bl ** is passed a valid open blob handle, the values returned by the ** sqlcipher_sqlite3_errcode() and sqlcipher_sqlite3_errmsg() functions are set before returning. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_blob_close(sqlcipher_sqlite3_blob *); +SQLITE_API int sqlcipher_sqlite3_blob_close(sqlcipher_sqlite3_blob *); /* ** CAPI3REF: Return The Size Of An Open BLOB @@ -6033,7 +6508,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_blob_close(sqlcipher_sqlite3_blo ** been closed by [sqlcipher_sqlite3_blob_close()]. Passing any other pointer in ** to this routine results in undefined and probably undesirable behavior. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_blob_bytes(sqlcipher_sqlite3_blob *); +SQLITE_API int sqlcipher_sqlite3_blob_bytes(sqlcipher_sqlite3_blob *); /* ** CAPI3REF: Read Data From A BLOB Incrementally @@ -6062,7 +6537,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_blob_bytes(sqlcipher_sqlite3_blo ** ** See also: [sqlcipher_sqlite3_blob_write()]. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_blob_read(sqlcipher_sqlite3_blob *, void *Z, int N, int iOffset); +SQLITE_API int sqlcipher_sqlite3_blob_read(sqlcipher_sqlite3_blob *, void *Z, int N, int iOffset); /* ** CAPI3REF: Write Data Into A BLOB Incrementally @@ -6104,7 +6579,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_blob_read(sqlcipher_sqlite3_blob ** ** See also: [sqlcipher_sqlite3_blob_read()]. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_blob_write(sqlcipher_sqlite3_blob *, const void *z, int n, int iOffset); +SQLITE_API int sqlcipher_sqlite3_blob_write(sqlcipher_sqlite3_blob *, const void *z, int n, int iOffset); /* ** CAPI3REF: Virtual File System Objects @@ -6135,9 +6610,9 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_blob_write(sqlcipher_sqlite3_blo ** ^(If the default VFS is unregistered, another VFS is chosen as ** the default. The choice for the new VFS is arbitrary.)^ */ -SQLITE_API sqlcipher_sqlite3_vfs *SQLITE_STDCALL sqlcipher_sqlite3_vfs_find(const char *zVfsName); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_vfs_register(sqlcipher_sqlite3_vfs*, int makeDflt); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_vfs_unregister(sqlcipher_sqlite3_vfs*); +SQLITE_API sqlcipher_sqlite3_vfs *sqlcipher_sqlite3_vfs_find(const char *zVfsName); +SQLITE_API int sqlcipher_sqlite3_vfs_register(sqlcipher_sqlite3_vfs*, int makeDflt); +SQLITE_API int sqlcipher_sqlite3_vfs_unregister(sqlcipher_sqlite3_vfs*); /* ** CAPI3REF: Mutexes @@ -6253,11 +6728,11 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_vfs_unregister(sqlcipher_sqlite3 ** ** See also: [sqlcipher_sqlite3_mutex_held()] and [sqlcipher_sqlite3_mutex_notheld()]. */ -SQLITE_API sqlcipher_sqlite3_mutex *SQLITE_STDCALL sqlcipher_sqlite3_mutex_alloc(int); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_mutex_free(sqlcipher_sqlite3_mutex*); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_mutex_enter(sqlcipher_sqlite3_mutex*); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_mutex_try(sqlcipher_sqlite3_mutex*); -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_mutex_leave(sqlcipher_sqlite3_mutex*); +SQLITE_API sqlcipher_sqlite3_mutex *sqlcipher_sqlite3_mutex_alloc(int); +SQLITE_API void sqlcipher_sqlite3_mutex_free(sqlcipher_sqlite3_mutex*); +SQLITE_API void sqlcipher_sqlite3_mutex_enter(sqlcipher_sqlite3_mutex*); +SQLITE_API int sqlcipher_sqlite3_mutex_try(sqlcipher_sqlite3_mutex*); +SQLITE_API void sqlcipher_sqlite3_mutex_leave(sqlcipher_sqlite3_mutex*); /* ** CAPI3REF: Mutex Methods Object @@ -6367,8 +6842,8 @@ struct sqlcipher_sqlite3_mutex_methods { ** interface should also return 1 when given a NULL pointer. */ #ifndef NDEBUG -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_mutex_held(sqlcipher_sqlite3_mutex*); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_mutex_notheld(sqlcipher_sqlite3_mutex*); +SQLITE_API int sqlcipher_sqlite3_mutex_held(sqlcipher_sqlite3_mutex*); +SQLITE_API int sqlcipher_sqlite3_mutex_notheld(sqlcipher_sqlite3_mutex*); #endif /* @@ -6387,7 +6862,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_mutex_notheld(sqlcipher_sqlite3_ #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlcipher_sqlite3_malloc() */ #define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */ #define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlcipher_sqlite3BtreeOpen() */ -#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlcipher_sqlite3_random() */ +#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlcipher_sqlite3_randomness() */ #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ #define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */ #define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlcipher_sqlite3PageMalloc() */ @@ -6408,7 +6883,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_mutex_notheld(sqlcipher_sqlite3_ ** ^If the [threading mode] is Single-thread or Multi-thread then this ** routine returns a NULL pointer. */ -SQLITE_API sqlcipher_sqlite3_mutex *SQLITE_STDCALL sqlcipher_sqlite3_db_mutex(sqlcipher_sqlite3*); +SQLITE_API sqlcipher_sqlite3_mutex *sqlcipher_sqlite3_db_mutex(sqlcipher_sqlite3*); /* ** CAPI3REF: Low-Level Control Of Database Files @@ -6443,7 +6918,7 @@ SQLITE_API sqlcipher_sqlite3_mutex *SQLITE_STDCALL sqlcipher_sqlite3_db_mutex(sq ** ** See also: [SQLITE_FCNTL_LOCKSTATE] */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_file_control(sqlcipher_sqlite3*, const char *zDbName, int op, void*); +SQLITE_API int sqlcipher_sqlite3_file_control(sqlcipher_sqlite3*, const char *zDbName, int op, void*); /* ** CAPI3REF: Testing Interface @@ -6462,7 +6937,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_file_control(sqlcipher_sqlite3*, ** Unlike most of the SQLite API, this function is not guaranteed to ** operate consistently from one release to the next. */ -SQLITE_API int SQLITE_CDECL sqlcipher_sqlite3_test_control(int op, ...); +SQLITE_API int sqlcipher_sqlite3_test_control(int op, ...); /* ** CAPI3REF: Testing Interface Operation Codes @@ -6491,6 +6966,7 @@ SQLITE_API int SQLITE_CDECL sqlcipher_sqlite3_test_control(int op, ...); #define SQLITE_TESTCTRL_SCRATCHMALLOC 17 #define SQLITE_TESTCTRL_LOCALTIME_FAULT 18 #define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */ +#define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD 19 #define SQLITE_TESTCTRL_NEVER_CORRUPT 20 #define SQLITE_TESTCTRL_VDBE_COVERAGE 21 #define SQLITE_TESTCTRL_BYTEORDER 22 @@ -6525,8 +7001,8 @@ SQLITE_API int SQLITE_CDECL sqlcipher_sqlite3_test_control(int op, ...); ** ** See also: [sqlcipher_sqlite3_db_status()] */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_status64( +SQLITE_API int sqlcipher_sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag); +SQLITE_API int sqlcipher_sqlite3_status64( int op, sqlcipher_sqlite3_int64 *pCurrent, sqlcipher_sqlite3_int64 *pHighwater, @@ -6651,7 +7127,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_status64( ** ** See also: [sqlcipher_sqlite3_status()] and [sqlcipher_sqlite3_stmt_status()]. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_db_status(sqlcipher_sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg); +SQLITE_API int sqlcipher_sqlite3_db_status(sqlcipher_sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg); /* ** CAPI3REF: Status Parameters for database connections @@ -6697,6 +7173,18 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_db_status(sqlcipher_sqlite3*, in ** memory used by all pager caches associated with the database connection.)^ ** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0. ** +** [[SQLITE_DBSTATUS_CACHE_USED_SHARED]] +** ^(<dt>SQLITE_DBSTATUS_CACHE_USED_SHARED</dt> +** <dd>This parameter is similar to DBSTATUS_CACHE_USED, except that if a +** pager cache is shared between two or more connections the bytes of heap +** memory used by that pager cache is divided evenly between the attached +** connections.)^ In other words, if none of the pager caches associated +** with the database connection are shared, this request returns the same +** value as DBSTATUS_CACHE_USED. Or, if one or more or the pager caches are +** shared, the value returned by this call will be smaller than that returned +** by DBSTATUS_CACHE_USED. ^The highwater mark associated with +** SQLITE_DBSTATUS_CACHE_USED_SHARED is always 0. +** ** [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt> ** <dd>This parameter returns the approximate number of bytes of heap ** memory used to store the schema for all databases associated @@ -6754,7 +7242,8 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_db_status(sqlcipher_sqlite3*, in #define SQLITE_DBSTATUS_CACHE_MISS 8 #define SQLITE_DBSTATUS_CACHE_WRITE 9 #define SQLITE_DBSTATUS_DEFERRED_FKS 10 -#define SQLITE_DBSTATUS_MAX 10 /* Largest defined DBSTATUS */ +#define SQLITE_DBSTATUS_CACHE_USED_SHARED 11 +#define SQLITE_DBSTATUS_MAX 11 /* Largest defined DBSTATUS */ /* @@ -6781,7 +7270,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_db_status(sqlcipher_sqlite3*, in ** ** See also: [sqlcipher_sqlite3_status()] and [sqlcipher_sqlite3_db_status()]. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_stmt_status(sqlcipher_sqlite3_stmt*, int op,int resetFlg); +SQLITE_API int sqlcipher_sqlite3_stmt_status(sqlcipher_sqlite3_stmt*, int op,int resetFlg); /* ** CAPI3REF: Status Parameters for prepared statements @@ -6817,6 +7306,24 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_stmt_status(sqlcipher_sqlite3_st ** used as a proxy for the total work done by the prepared statement. ** If the number of virtual machine operations exceeds 2147483647 ** then the value returned by this statement status code is undefined. +** +** [[SQLITE_STMTSTATUS_REPREPARE]] <dt>SQLITE_STMTSTATUS_REPREPARE</dt> +** <dd>^This is the number of times that the prepare statement has been +** automatically regenerated due to schema changes or change to +** [bound parameters] that might affect the query plan. +** +** [[SQLITE_STMTSTATUS_RUN]] <dt>SQLITE_STMTSTATUS_RUN</dt> +** <dd>^This is the number of times that the prepared statement has +** been run. A single "run" for the purposes of this counter is one +** or more calls to [sqlcipher_sqlite3_step()] followed by a call to [sqlcipher_sqlite3_reset()]. +** The counter is incremented on the first [sqlcipher_sqlite3_step()] call of each +** cycle. +** +** [[SQLITE_STMTSTATUS_MEMUSED]] <dt>SQLITE_STMTSTATUS_MEMUSED</dt> +** <dd>^This is the approximate number of bytes of heap memory +** used to store the prepared statement. ^This value is not actually +** a counter, and so the resetFlg parameter to sqlcipher_sqlite3_stmt_status() +** is ignored when the opcode is SQLITE_STMTSTATUS_MEMUSED. ** </dd> ** </dl> */ @@ -6824,6 +7331,9 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_stmt_status(sqlcipher_sqlite3_st #define SQLITE_STMTSTATUS_SORT 2 #define SQLITE_STMTSTATUS_AUTOINDEX 3 #define SQLITE_STMTSTATUS_VM_STEP 4 +#define SQLITE_STMTSTATUS_REPREPARE 5 +#define SQLITE_STMTSTATUS_RUN 6 +#define SQLITE_STMTSTATUS_MEMUSED 99 /* ** CAPI3REF: Custom Page Cache Object @@ -7108,7 +7618,7 @@ typedef struct sqlcipher_sqlite3_backup sqlcipher_sqlite3_backup; ** must be different or else sqlcipher_sqlite3_backup_init(D,N,S,M) will fail with ** an error. ** -** ^A call to sqlcipher_sqlite3_backup_init() will fail, returning SQLITE_ERROR, if +** ^A call to sqlcipher_sqlite3_backup_init() will fail, returning NULL, if ** there is already a read or read-write transaction open on the ** destination database. ** @@ -7250,16 +7760,16 @@ typedef struct sqlcipher_sqlite3_backup sqlcipher_sqlite3_backup; ** same time as another thread is invoking sqlcipher_sqlite3_backup_step() it is ** possible that they return invalid values. */ -SQLITE_API sqlcipher_sqlite3_backup *SQLITE_STDCALL sqlcipher_sqlite3_backup_init( +SQLITE_API sqlcipher_sqlite3_backup *sqlcipher_sqlite3_backup_init( sqlcipher_sqlite3 *pDest, /* Destination database handle */ const char *zDestName, /* Destination database name */ sqlcipher_sqlite3 *pSource, /* Source database handle */ const char *zSourceName /* Source database name */ ); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_backup_step(sqlcipher_sqlite3_backup *p, int nPage); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_backup_finish(sqlcipher_sqlite3_backup *p); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_backup_remaining(sqlcipher_sqlite3_backup *p); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_backup_pagecount(sqlcipher_sqlite3_backup *p); +SQLITE_API int sqlcipher_sqlite3_backup_step(sqlcipher_sqlite3_backup *p, int nPage); +SQLITE_API int sqlcipher_sqlite3_backup_finish(sqlcipher_sqlite3_backup *p); +SQLITE_API int sqlcipher_sqlite3_backup_remaining(sqlcipher_sqlite3_backup *p); +SQLITE_API int sqlcipher_sqlite3_backup_pagecount(sqlcipher_sqlite3_backup *p); /* ** CAPI3REF: Unlock Notification @@ -7376,7 +7886,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_backup_pagecount(sqlcipher_sqlit ** the special "DROP TABLE/INDEX" case, the extended error code is just ** SQLITE_LOCKED.)^ */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_unlock_notify( +SQLITE_API int sqlcipher_sqlite3_unlock_notify( sqlcipher_sqlite3 *pBlocked, /* Waiting connection */ void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */ void *pNotifyArg /* Argument to pass to xNotify */ @@ -7391,8 +7901,8 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_unlock_notify( ** strings in a case-independent fashion, using the same definition of "case ** independence" that SQLite uses internally when comparing identifiers. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_stricmp(const char *, const char *); -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_strnicmp(const char *, const char *, int); +SQLITE_API int sqlcipher_sqlite3_stricmp(const char *, const char *); +SQLITE_API int sqlcipher_sqlite3_strnicmp(const char *, const char *, int); /* ** CAPI3REF: String Globbing @@ -7409,7 +7919,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_strnicmp(const char *, const cha ** ** See also: [sqlcipher_sqlite3_strlike()]. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_strglob(const char *zGlob, const char *zStr); +SQLITE_API int sqlcipher_sqlite3_strglob(const char *zGlob, const char *zStr); /* ** CAPI3REF: String LIKE Matching @@ -7432,7 +7942,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_strglob(const char *zGlob, const ** ** See also: [sqlcipher_sqlite3_strglob()]. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int cEsc); +SQLITE_API int sqlcipher_sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int cEsc); /* ** CAPI3REF: Error Logging Interface @@ -7455,7 +7965,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_strlike(const char *zGlob, const ** a few hundred characters, it will be truncated to the length of the ** buffer. */ -SQLITE_API void SQLITE_CDECL sqlcipher_sqlite3_log(int iErrCode, const char *zFormat, ...); +SQLITE_API void sqlcipher_sqlite3_log(int iErrCode, const char *zFormat, ...); /* ** CAPI3REF: Write-Ahead Log Commit Hook @@ -7489,9 +7999,9 @@ SQLITE_API void SQLITE_CDECL sqlcipher_sqlite3_log(int iErrCode, const char *zFo ** previously registered write-ahead log callback. ^Note that the ** [sqlcipher_sqlite3_wal_autocheckpoint()] interface and the ** [wal_autocheckpoint pragma] both invoke [sqlcipher_sqlite3_wal_hook()] and will -** those overwrite any prior [sqlcipher_sqlite3_wal_hook()] settings. +** overwrite any prior [sqlcipher_sqlite3_wal_hook()] settings. */ -SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_wal_hook( +SQLITE_API void *sqlcipher_sqlite3_wal_hook( sqlcipher_sqlite3*, int(*)(void *,sqlcipher_sqlite3*,const char*,int), void* @@ -7526,7 +8036,7 @@ SQLITE_API void *SQLITE_STDCALL sqlcipher_sqlite3_wal_hook( ** is only necessary if the default setting is found to be suboptimal ** for a particular application. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_wal_autocheckpoint(sqlcipher_sqlite3 *db, int N); +SQLITE_API int sqlcipher_sqlite3_wal_autocheckpoint(sqlcipher_sqlite3 *db, int N); /* ** CAPI3REF: Checkpoint a database @@ -7548,7 +8058,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_wal_autocheckpoint(sqlcipher_sql ** start a callback but which do not need the full power (and corresponding ** complication) of [sqlcipher_sqlite3_wal_checkpoint_v2()]. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_wal_checkpoint(sqlcipher_sqlite3 *db, const char *zDb); +SQLITE_API int sqlcipher_sqlite3_wal_checkpoint(sqlcipher_sqlite3 *db, const char *zDb); /* ** CAPI3REF: Checkpoint a database @@ -7642,7 +8152,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_wal_checkpoint(sqlcipher_sqlite3 ** ^The [PRAGMA wal_checkpoint] command can be used to invoke this interface ** from SQL. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_wal_checkpoint_v2( +SQLITE_API int sqlcipher_sqlite3_wal_checkpoint_v2( sqlcipher_sqlite3 *db, /* Database handle */ const char *zDb, /* Name of attached database (or NULL) */ int eMode, /* SQLITE_CHECKPOINT_* value */ @@ -7678,7 +8188,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_wal_checkpoint_v2( ** this function. (See [SQLITE_VTAB_CONSTRAINT_SUPPORT].) Further options ** may be added in the future. */ -SQLITE_API int SQLITE_CDECL sqlcipher_sqlite3_vtab_config(sqlcipher_sqlite3*, int op, ...); +SQLITE_API int sqlcipher_sqlite3_vtab_config(sqlcipher_sqlite3*, int op, ...); /* ** CAPI3REF: Virtual Table Configuration Options @@ -7731,7 +8241,7 @@ SQLITE_API int SQLITE_CDECL sqlcipher_sqlite3_vtab_config(sqlcipher_sqlite3*, in ** of the SQL statement that triggered the call to the [xUpdate] method of the ** [virtual table]. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_vtab_on_conflict(sqlcipher_sqlite3 *); +SQLITE_API int sqlcipher_sqlite3_vtab_on_conflict(sqlcipher_sqlite3 *); /* ** CAPI3REF: Conflict resolution modes @@ -7836,7 +8346,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_vtab_on_conflict(sqlcipher_sqlit ** ** See also: [sqlcipher_sqlite3_stmt_scanstatus_reset()] */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_stmt_scanstatus( +SQLITE_API int sqlcipher_sqlite3_stmt_scanstatus( sqlcipher_sqlite3_stmt *pStmt, /* Prepared statement for which info desired */ int idx, /* Index of loop to report on */ int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */ @@ -7852,7 +8362,7 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_stmt_scanstatus( ** This API is only available if the library is built with pre-processor ** symbol [SQLITE_ENABLE_STMT_SCANSTATUS] defined. */ -SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_stmt_scanstatus_reset(sqlcipher_sqlite3_stmt*); +SQLITE_API void sqlcipher_sqlite3_stmt_scanstatus_reset(sqlcipher_sqlite3_stmt*); /* ** CAPI3REF: Flush caches to disk mid-transaction @@ -7884,11 +8394,125 @@ SQLITE_API void SQLITE_STDCALL sqlcipher_sqlite3_stmt_scanstatus_reset(sqlcipher ** ^This function does not set the database handle error code or message ** returned by the [sqlcipher_sqlite3_errcode()] and [sqlcipher_sqlite3_errmsg()] functions. */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_db_cacheflush(sqlcipher_sqlite3*); +SQLITE_API int sqlcipher_sqlite3_db_cacheflush(sqlcipher_sqlite3*); + +/* +** CAPI3REF: The pre-update hook. +** +** ^These interfaces are only available if SQLite is compiled using the +** [SQLITE_ENABLE_PREUPDATE_HOOK] compile-time option. +** +** ^The [sqlcipher_sqlite3_preupdate_hook()] interface registers a callback function +** that is invoked prior to each [INSERT], [UPDATE], and [DELETE] operation +** on a database table. +** ^At most one preupdate hook may be registered at a time on a single +** [database connection]; each call to [sqlcipher_sqlite3_preupdate_hook()] overrides +** the previous setting. +** ^The preupdate hook is disabled by invoking [sqlcipher_sqlite3_preupdate_hook()] +** with a NULL pointer as the second parameter. +** ^The third parameter to [sqlcipher_sqlite3_preupdate_hook()] is passed through as +** the first parameter to callbacks. +** +** ^The preupdate hook only fires for changes to real database tables; the +** preupdate hook is not invoked for changes to [virtual tables] or to +** system tables like sqlite_master or sqlite_stat1. +** +** ^The second parameter to the preupdate callback is a pointer to +** the [database connection] that registered the preupdate hook. +** ^The third parameter to the preupdate callback is one of the constants +** [SQLITE_INSERT], [SQLITE_DELETE], or [SQLITE_UPDATE] to identify the +** kind of update operation that is about to occur. +** ^(The fourth parameter to the preupdate callback is the name of the +** database within the database connection that is being modified. This +** will be "main" for the main database or "temp" for TEMP tables or +** the name given after the AS keyword in the [ATTACH] statement for attached +** databases.)^ +** ^The fifth parameter to the preupdate callback is the name of the +** table that is being modified. +** +** For an UPDATE or DELETE operation on a [rowid table], the sixth +** parameter passed to the preupdate callback is the initial [rowid] of the +** row being modified or deleted. For an INSERT operation on a rowid table, +** or any operation on a WITHOUT ROWID table, the value of the sixth +** parameter is undefined. For an INSERT or UPDATE on a rowid table the +** seventh parameter is the final rowid value of the row being inserted +** or updated. The value of the seventh parameter passed to the callback +** function is not defined for operations on WITHOUT ROWID tables, or for +** INSERT operations on rowid tables. +** +** The [sqlcipher_sqlite3_preupdate_old()], [sqlcipher_sqlite3_preupdate_new()], +** [sqlcipher_sqlite3_preupdate_count()], and [sqlcipher_sqlite3_preupdate_depth()] interfaces +** provide additional information about a preupdate event. These routines +** may only be called from within a preupdate callback. Invoking any of +** these routines from outside of a preupdate callback or with a +** [database connection] pointer that is different from the one supplied +** to the preupdate callback results in undefined and probably undesirable +** behavior. +** +** ^The [sqlcipher_sqlite3_preupdate_count(D)] interface returns the number of columns +** in the row that is being inserted, updated, or deleted. +** +** ^The [sqlcipher_sqlite3_preupdate_old(D,N,P)] interface writes into P a pointer to +** a [protected sqlcipher_sqlite3_value] that contains the value of the Nth column of +** the table row before it is updated. The N parameter must be between 0 +** and one less than the number of columns or the behavior will be +** undefined. This must only be used within SQLITE_UPDATE and SQLITE_DELETE +** preupdate callbacks; if it is used by an SQLITE_INSERT callback then the +** behavior is undefined. The [sqlcipher_sqlite3_value] that P points to +** will be destroyed when the preupdate callback returns. +** +** ^The [sqlcipher_sqlite3_preupdate_new(D,N,P)] interface writes into P a pointer to +** a [protected sqlcipher_sqlite3_value] that contains the value of the Nth column of +** the table row after it is updated. The N parameter must be between 0 +** and one less than the number of columns or the behavior will be +** undefined. This must only be used within SQLITE_INSERT and SQLITE_UPDATE +** preupdate callbacks; if it is used by an SQLITE_DELETE callback then the +** behavior is undefined. The [sqlcipher_sqlite3_value] that P points to +** will be destroyed when the preupdate callback returns. +** +** ^The [sqlcipher_sqlite3_preupdate_depth(D)] interface returns 0 if the preupdate +** callback was invoked as a result of a direct insert, update, or delete +** operation; or 1 for inserts, updates, or deletes invoked by top-level +** triggers; or 2 for changes resulting from triggers called by top-level +** triggers; and so forth. +** +** See also: [sqlcipher_sqlite3_update_hook()] +*/ +#if defined(SQLITE_ENABLE_PREUPDATE_HOOK) +SQLITE_API void *sqlcipher_sqlite3_preupdate_hook( + sqlcipher_sqlite3 *db, + void(*xPreUpdate)( + void *pCtx, /* Copy of third arg to preupdate_hook() */ + sqlcipher_sqlite3 *db, /* Database handle */ + int op, /* SQLITE_UPDATE, DELETE or INSERT */ + char const *zDb, /* Database name */ + char const *zName, /* Table name */ + sqlcipher_sqlite3_int64 iKey1, /* Rowid of row about to be deleted/updated */ + sqlcipher_sqlite3_int64 iKey2 /* New rowid value (for a rowid UPDATE) */ + ), + void* +); +SQLITE_API int sqlcipher_sqlite3_preupdate_old(sqlcipher_sqlite3 *, int, sqlcipher_sqlite3_value **); +SQLITE_API int sqlcipher_sqlite3_preupdate_count(sqlcipher_sqlite3 *); +SQLITE_API int sqlcipher_sqlite3_preupdate_depth(sqlcipher_sqlite3 *); +SQLITE_API int sqlcipher_sqlite3_preupdate_new(sqlcipher_sqlite3 *, int, sqlcipher_sqlite3_value **); +#endif + +/* +** CAPI3REF: Low-level system error code +** +** ^Attempt to return the underlying operating system error code or error +** number that caused the most recent I/O error or failure to open a file. +** The return value is OS-dependent. For example, on unix systems, after +** [sqlcipher_sqlite3_open_v2()] returns [SQLITE_CANTOPEN], this interface could be +** called to get back the underlying "errno" that caused the problem, such +** as ENOSPC, EAUTH, EISDIR, and so forth. +*/ +SQLITE_API int sqlcipher_sqlite3_system_errno(sqlcipher_sqlite3*); /* ** CAPI3REF: Database Snapshot -** KEYWORDS: {snapshot} +** KEYWORDS: {snapshot} {sqlcipher_sqlite3_snapshot} ** EXPERIMENTAL ** ** An instance of the snapshot object records the state of a [WAL mode] @@ -7912,7 +8536,9 @@ SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_db_cacheflush(sqlcipher_sqlite3* ** to an historical snapshot (if possible). The destructor for ** sqlcipher_sqlite3_snapshot objects is [sqlcipher_sqlite3_snapshot_free()]. */ -typedef struct sqlcipher_sqlite3_snapshot sqlcipher_sqlite3_snapshot; +typedef struct sqlcipher_sqlite3_snapshot { + unsigned char hidden[48]; +} sqlcipher_sqlite3_snapshot; /* ** CAPI3REF: Record A Database Snapshot @@ -7923,9 +8549,32 @@ typedef struct sqlcipher_sqlite3_snapshot sqlcipher_sqlite3_snapshot; ** schema S in database connection D. ^On success, the ** [sqlcipher_sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly ** created [sqlcipher_sqlite3_snapshot] object into *P and returns SQLITE_OK. -** ^If schema S of [database connection] D is not a [WAL mode] database -** that is in a read transaction, then [sqlcipher_sqlite3_snapshot_get(D,S,P)] -** leaves the *P value unchanged and returns an appropriate [error code]. +** If there is not already a read-transaction open on schema S when +** this function is called, one is opened automatically. +** +** The following must be true for this function to succeed. If any of +** the following statements are false when sqlcipher_sqlite3_snapshot_get() is +** called, SQLITE_ERROR is returned. The final value of *P is undefined +** in this case. +** +** <ul> +** <li> The database handle must be in [autocommit mode]. +** +** <li> Schema S of [database connection] D must be a [WAL mode] database. +** +** <li> There must not be a write transaction open on schema S of database +** connection D. +** +** <li> One or more transactions must have been written to the current wal +** file since it was created on disk (by any connection). This means +** that a snapshot cannot be taken on a wal mode database with no wal +** file immediately after it is first opened. At least one transaction +** must be written to it first. +** </ul> +** +** This function may also return SQLITE_NOMEM. If it is called with the +** database handle in autocommit mode but fails for some other reason, +** whether or not a read transaction is opened on schema S is undefined. ** ** The [sqlcipher_sqlite3_snapshot] object returned from a successful call to ** [sqlcipher_sqlite3_snapshot_get()] must be freed using [sqlcipher_sqlite3_snapshot_free()] @@ -7934,7 +8583,7 @@ typedef struct sqlcipher_sqlite3_snapshot sqlcipher_sqlite3_snapshot; ** The [sqlcipher_sqlite3_snapshot_get()] interface is only available when the ** SQLITE_ENABLE_SNAPSHOT compile-time option is used. */ -SQLITE_API SQLITE_EXPERIMENTAL int SQLITE_STDCALL sqlcipher_sqlite3_snapshot_get( +SQLITE_API SQLITE_EXPERIMENTAL int sqlcipher_sqlite3_snapshot_get( sqlcipher_sqlite3 *db, const char *zSchema, sqlcipher_sqlite3_snapshot **ppSnapshot @@ -7944,22 +8593,35 @@ SQLITE_API SQLITE_EXPERIMENTAL int SQLITE_STDCALL sqlcipher_sqlite3_snapshot_get ** CAPI3REF: Start a read transaction on an historical snapshot ** EXPERIMENTAL ** -** ^The [sqlcipher_sqlite3_snapshot_open(D,S,P)] interface attempts to move the -** read transaction that is currently open on schema S of -** [database connection] D so that it refers to historical [snapshot] P. +** ^The [sqlcipher_sqlite3_snapshot_open(D,S,P)] interface starts a +** read transaction for schema S of +** [database connection] D such that the read transaction +** refers to historical [snapshot] P, rather than the most +** recent change to the database. ** ^The [sqlcipher_sqlite3_snapshot_open()] interface returns SQLITE_OK on success ** or an appropriate [error code] if it fails. ** ** ^In order to succeed, a call to [sqlcipher_sqlite3_snapshot_open(D,S,P)] must be -** the first operation, apart from other sqlcipher_sqlite3_snapshot_open() calls, -** following the [BEGIN] that starts a new read transaction. -** ^A [snapshot] will fail to open if it has been overwritten by a -** [checkpoint]. +** the first operation following the [BEGIN] that takes the schema S +** out of [autocommit mode]. +** ^In other words, schema S must not currently be in +** a transaction for [sqlcipher_sqlite3_snapshot_open(D,S,P)] to work, but the +** database connection D must be out of [autocommit mode]. +** ^A [snapshot] will fail to open if it has been overwritten by a +** [checkpoint]. +** ^(A call to [sqlcipher_sqlite3_snapshot_open(D,S,P)] will fail if the +** database connection D does not know that the database file for +** schema S is in [WAL mode]. A database connection might not know +** that the database file is in [WAL mode] if there has been no prior +** I/O on that database connection, or if the database entered [WAL mode] +** after the most recent I/O on the database connection.)^ +** (Hint: Run "[PRAGMA application_id]" against a newly opened +** database connection in order to make it ready to use snapshots.) ** ** The [sqlcipher_sqlite3_snapshot_open()] interface is only available when the ** SQLITE_ENABLE_SNAPSHOT compile-time option is used. */ -SQLITE_API SQLITE_EXPERIMENTAL int SQLITE_STDCALL sqlcipher_sqlite3_snapshot_open( +SQLITE_API SQLITE_EXPERIMENTAL int sqlcipher_sqlite3_snapshot_open( sqlcipher_sqlite3 *db, const char *zSchema, sqlcipher_sqlite3_snapshot *pSnapshot @@ -7976,7 +8638,56 @@ SQLITE_API SQLITE_EXPERIMENTAL int SQLITE_STDCALL sqlcipher_sqlite3_snapshot_ope ** The [sqlcipher_sqlite3_snapshot_free()] interface is only available when the ** SQLITE_ENABLE_SNAPSHOT compile-time option is used. */ -SQLITE_API SQLITE_EXPERIMENTAL void SQLITE_STDCALL sqlcipher_sqlite3_snapshot_free(sqlcipher_sqlite3_snapshot*); +SQLITE_API SQLITE_EXPERIMENTAL void sqlcipher_sqlite3_snapshot_free(sqlcipher_sqlite3_snapshot*); + +/* +** CAPI3REF: Compare the ages of two snapshot handles. +** EXPERIMENTAL +** +** The sqlcipher_sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages +** of two valid snapshot handles. +** +** If the two snapshot handles are not associated with the same database +** file, the result of the comparison is undefined. +** +** Additionally, the result of the comparison is only valid if both of the +** snapshot handles were obtained by calling sqlcipher_sqlite3_snapshot_get() since the +** last time the wal file was deleted. The wal file is deleted when the +** database is changed back to rollback mode or when the number of database +** clients drops to zero. If either snapshot handle was obtained before the +** wal file was last deleted, the value returned by this function +** is undefined. +** +** Otherwise, this API returns a negative value if P1 refers to an older +** snapshot than P2, zero if the two handles refer to the same database +** snapshot, and a positive value if P1 is a newer snapshot than P2. +*/ +SQLITE_API SQLITE_EXPERIMENTAL int sqlcipher_sqlite3_snapshot_cmp( + sqlcipher_sqlite3_snapshot *p1, + sqlcipher_sqlite3_snapshot *p2 +); + +/* +** CAPI3REF: Recover snapshots from a wal file +** EXPERIMENTAL +** +** If all connections disconnect from a database file but do not perform +** a checkpoint, the existing wal file is opened along with the database +** file the next time the database is opened. At this point it is only +** possible to successfully call sqlcipher_sqlite3_snapshot_open() to open the most +** recent snapshot of the database (the one at the head of the wal file), +** even though the wal file may contain other valid snapshots for which +** clients have sqlcipher_sqlite3_snapshot handles. +** +** This function attempts to scan the wal file associated with database zDb +** of database handle db and make all valid snapshots available to +** sqlcipher_sqlite3_snapshot_open(). It is an error if there is already a read +** transaction open on the database, or if the database is not a wal mode +** database. +** +** SQLITE_OK is returned if successful, or an SQLite error code otherwise. +*/ +SQLITE_API SQLITE_EXPERIMENTAL int sqlcipher_sqlite3_snapshot_recover(sqlcipher_sqlite3 *db, const char *zDb); /* ** Undo the hack that converts floating point types to integer for @@ -7989,8 +8700,9 @@ SQLITE_API SQLITE_EXPERIMENTAL void SQLITE_STDCALL sqlcipher_sqlite3_snapshot_fr #ifdef __cplusplus } /* End of the 'extern "C"' block */ #endif -#endif /* _SQLITE3_H_ */ +#endif /* SQLITE3_H */ +/******** Begin file sqlcipher_sqlite3rtree.h *********/ /* ** 2010 August 30 ** @@ -8030,7 +8742,7 @@ typedef struct sqlcipher_sqlite3_rtree_query_info sqlcipher_sqlite3_rtree_query_ ** ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...) */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_rtree_geometry_callback( +SQLITE_API int sqlcipher_sqlite3_rtree_geometry_callback( sqlcipher_sqlite3 *db, const char *zGeom, int (*xGeom)(sqlcipher_sqlite3_rtree_geometry*, int, sqlcipher_sqlite3_rtree_dbl*,int*), @@ -8056,7 +8768,7 @@ struct sqlcipher_sqlite3_rtree_geometry { ** ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zQueryFunc(... params ...) */ -SQLITE_API int SQLITE_STDCALL sqlcipher_sqlite3_rtree_query_callback( +SQLITE_API int sqlcipher_sqlite3_rtree_query_callback( sqlcipher_sqlite3 *db, const char *zQueryFunc, int (*xQueryFunc)(sqlcipher_sqlite3_rtree_query_info*), @@ -8108,6 +8820,1298 @@ struct sqlcipher_sqlite3_rtree_query_info { #endif /* ifndef _SQLITE3RTREE_H_ */ +/******** End of sqlcipher_sqlite3rtree.h *********/ +/******** Begin file sqlcipher_sqlite3session.h *********/ + +#if !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION) +#define __SQLITESESSION_H_ 1 + +/* +** Make sure we can call this stuff from C++. +*/ +#ifdef __cplusplus +extern "C" { +#endif + + +/* +** CAPI3REF: Session Object Handle +*/ +typedef struct sqlcipher_sqlite3_session sqlcipher_sqlite3_session; + +/* +** CAPI3REF: Changeset Iterator Handle +*/ +typedef struct sqlcipher_sqlite3_changeset_iter sqlcipher_sqlite3_changeset_iter; + +/* +** CAPI3REF: Create A New Session Object +** +** Create a new session object attached to database handle db. If successful, +** a pointer to the new object is written to *ppSession and SQLITE_OK is +** returned. If an error occurs, *ppSession is set to NULL and an SQLite +** error code (e.g. SQLITE_NOMEM) is returned. +** +** It is possible to create multiple session objects attached to a single +** database handle. +** +** Session objects created using this function should be deleted using the +** [sqlcipher_sqlite3session_delete()] function before the database handle that they +** are attached to is itself closed. If the database handle is closed before +** the session object is deleted, then the results of calling any session +** module function, including [sqlcipher_sqlite3session_delete()] on the session object +** are undefined. +** +** Because the session module uses the [sqlcipher_sqlite3_preupdate_hook()] API, it +** is not possible for an application to register a pre-update hook on a +** database handle that has one or more session objects attached. Nor is +** it possible to create a session object attached to a database handle for +** which a pre-update hook is already defined. The results of attempting +** either of these things are undefined. +** +** The session object will be used to create changesets for tables in +** database zDb, where zDb is either "main", or "temp", or the name of an +** attached database. It is not an error if database zDb is not attached +** to the database when the session object is created. +*/ +SQLITE_API int sqlcipher_sqlite3session_create( + sqlcipher_sqlite3 *db, /* Database handle */ + const char *zDb, /* Name of db (e.g. "main") */ + sqlcipher_sqlite3_session **ppSession /* OUT: New session object */ +); + +/* +** CAPI3REF: Delete A Session Object +** +** Delete a session object previously allocated using +** [sqlcipher_sqlite3session_create()]. Once a session object has been deleted, the +** results of attempting to use pSession with any other session module +** function are undefined. +** +** Session objects must be deleted before the database handle to which they +** are attached is closed. Refer to the documentation for +** [sqlcipher_sqlite3session_create()] for details. +*/ +SQLITE_API void sqlcipher_sqlite3session_delete(sqlcipher_sqlite3_session *pSession); + + +/* +** CAPI3REF: Enable Or Disable A Session Object +** +** Enable or disable the recording of changes by a session object. When +** enabled, a session object records changes made to the database. When +** disabled - it does not. A newly created session object is enabled. +** Refer to the documentation for [sqlcipher_sqlite3session_changeset()] for further +** details regarding how enabling and disabling a session object affects +** the eventual changesets. +** +** Passing zero to this function disables the session. Passing a value +** greater than zero enables it. Passing a value less than zero is a +** no-op, and may be used to query the current state of the session. +** +** The return value indicates the final state of the session object: 0 if +** the session is disabled, or 1 if it is enabled. +*/ +SQLITE_API int sqlcipher_sqlite3session_enable(sqlcipher_sqlite3_session *pSession, int bEnable); + +/* +** CAPI3REF: Set Or Clear the Indirect Change Flag +** +** Each change recorded by a session object is marked as either direct or +** indirect. A change is marked as indirect if either: +** +** <ul> +** <li> The session object "indirect" flag is set when the change is +** made, or +** <li> The change is made by an SQL trigger or foreign key action +** instead of directly as a result of a users SQL statement. +** </ul> +** +** If a single row is affected by more than one operation within a session, +** then the change is considered indirect if all operations meet the criteria +** for an indirect change above, or direct otherwise. +** +** This function is used to set, clear or query the session object indirect +** flag. If the second argument passed to this function is zero, then the +** indirect flag is cleared. If it is greater than zero, the indirect flag +** is set. Passing a value less than zero does not modify the current value +** of the indirect flag, and may be used to query the current state of the +** indirect flag for the specified session object. +** +** The return value indicates the final state of the indirect flag: 0 if +** it is clear, or 1 if it is set. +*/ +SQLITE_API int sqlcipher_sqlite3session_indirect(sqlcipher_sqlite3_session *pSession, int bIndirect); + +/* +** CAPI3REF: Attach A Table To A Session Object +** +** If argument zTab is not NULL, then it is the name of a table to attach +** to the session object passed as the first argument. All subsequent changes +** made to the table while the session object is enabled will be recorded. See +** documentation for [sqlcipher_sqlite3session_changeset()] for further details. +** +** Or, if argument zTab is NULL, then changes are recorded for all tables +** in the database. If additional tables are added to the database (by +** executing "CREATE TABLE" statements) after this call is made, changes for +** the new tables are also recorded. +** +** Changes can only be recorded for tables that have a PRIMARY KEY explicitly +** defined as part of their CREATE TABLE statement. It does not matter if the +** PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY +** KEY may consist of a single column, or may be a composite key. +** +** It is not an error if the named table does not exist in the database. Nor +** is it an error if the named table does not have a PRIMARY KEY. However, +** no changes will be recorded in either of these scenarios. +** +** Changes are not recorded for individual rows that have NULL values stored +** in one or more of their PRIMARY KEY columns. +** +** SQLITE_OK is returned if the call completes without error. Or, if an error +** occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned. +*/ +SQLITE_API int sqlcipher_sqlite3session_attach( + sqlcipher_sqlite3_session *pSession, /* Session object */ + const char *zTab /* Table name */ +); + +/* +** CAPI3REF: Set a table filter on a Session Object. +** +** The second argument (xFilter) is the "filter callback". For changes to rows +** in tables that are not attached to the Session object, the filter is called +** to determine whether changes to the table's rows should be tracked or not. +** If xFilter returns 0, changes is not tracked. Note that once a table is +** attached, xFilter will not be called again. +*/ +SQLITE_API void sqlcipher_sqlite3session_table_filter( + sqlcipher_sqlite3_session *pSession, /* Session object */ + int(*xFilter)( + void *pCtx, /* Copy of third arg to _filter_table() */ + const char *zTab /* Table name */ + ), + void *pCtx /* First argument passed to xFilter */ +); + +/* +** CAPI3REF: Generate A Changeset From A Session Object +** +** Obtain a changeset containing changes to the tables attached to the +** session object passed as the first argument. If successful, +** set *ppChangeset to point to a buffer containing the changeset +** and *pnChangeset to the size of the changeset in bytes before returning +** SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to +** zero and return an SQLite error code. +** +** A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes, +** each representing a change to a single row of an attached table. An INSERT +** change contains the values of each field of a new database row. A DELETE +** contains the original values of each field of a deleted database row. An +** UPDATE change contains the original values of each field of an updated +** database row along with the updated values for each updated non-primary-key +** column. It is not possible for an UPDATE change to represent a change that +** modifies the values of primary key columns. If such a change is made, it +** is represented in a changeset as a DELETE followed by an INSERT. +** +** Changes are not recorded for rows that have NULL values stored in one or +** more of their PRIMARY KEY columns. If such a row is inserted or deleted, +** no corresponding change is present in the changesets returned by this +** function. If an existing row with one or more NULL values stored in +** PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL, +** only an INSERT is appears in the changeset. Similarly, if an existing row +** with non-NULL PRIMARY KEY values is updated so that one or more of its +** PRIMARY KEY columns are set to NULL, the resulting changeset contains a +** DELETE change only. +** +** The contents of a changeset may be traversed using an iterator created +** using the [sqlcipher_sqlite3changeset_start()] API. A changeset may be applied to +** a database with a compatible schema using the [sqlcipher_sqlite3changeset_apply()] +** API. +** +** Within a changeset generated by this function, all changes related to a +** single table are grouped together. In other words, when iterating through +** a changeset or when applying a changeset to a database, all changes related +** to a single table are processed before moving on to the next table. Tables +** are sorted in the same order in which they were attached (or auto-attached) +** to the sqlcipher_sqlite3_session object. The order in which the changes related to +** a single table are stored is undefined. +** +** Following a successful call to this function, it is the responsibility of +** the caller to eventually free the buffer that *ppChangeset points to using +** [sqlcipher_sqlite3_free()]. +** +** <h3>Changeset Generation</h3> +** +** Once a table has been attached to a session object, the session object +** records the primary key values of all new rows inserted into the table. +** It also records the original primary key and other column values of any +** deleted or updated rows. For each unique primary key value, data is only +** recorded once - the first time a row with said primary key is inserted, +** updated or deleted in the lifetime of the session. +** +** There is one exception to the previous paragraph: when a row is inserted, +** updated or deleted, if one or more of its primary key columns contain a +** NULL value, no record of the change is made. +** +** The session object therefore accumulates two types of records - those +** that consist of primary key values only (created when the user inserts +** a new record) and those that consist of the primary key values and the +** original values of other table columns (created when the users deletes +** or updates a record). +** +** When this function is called, the requested changeset is created using +** both the accumulated records and the current contents of the database +** file. Specifically: +** +** <ul> +** <li> For each record generated by an insert, the database is queried +** for a row with a matching primary key. If one is found, an INSERT +** change is added to the changeset. If no such row is found, no change +** is added to the changeset. +** +** <li> For each record generated by an update or delete, the database is +** queried for a row with a matching primary key. If such a row is +** found and one or more of the non-primary key fields have been +** modified from their original values, an UPDATE change is added to +** the changeset. Or, if no such row is found in the table, a DELETE +** change is added to the changeset. If there is a row with a matching +** primary key in the database, but all fields contain their original +** values, no change is added to the changeset. +** </ul> +** +** This means, amongst other things, that if a row is inserted and then later +** deleted while a session object is active, neither the insert nor the delete +** will be present in the changeset. Or if a row is deleted and then later a +** row with the same primary key values inserted while a session object is +** active, the resulting changeset will contain an UPDATE change instead of +** a DELETE and an INSERT. +** +** When a session object is disabled (see the [sqlcipher_sqlite3session_enable()] API), +** it does not accumulate records when rows are inserted, updated or deleted. +** This may appear to have some counter-intuitive effects if a single row +** is written to more than once during a session. For example, if a row +** is inserted while a session object is enabled, then later deleted while +** the same session object is disabled, no INSERT record will appear in the +** changeset, even though the delete took place while the session was disabled. +** Or, if one field of a row is updated while a session is disabled, and +** another field of the same row is updated while the session is enabled, the +** resulting changeset will contain an UPDATE change that updates both fields. +*/ +SQLITE_API int sqlcipher_sqlite3session_changeset( + sqlcipher_sqlite3_session *pSession, /* Session object */ + int *pnChangeset, /* OUT: Size of buffer at *ppChangeset */ + void **ppChangeset /* OUT: Buffer containing changeset */ +); + +/* +** CAPI3REF: Load The Difference Between Tables Into A Session +** +** If it is not already attached to the session object passed as the first +** argument, this function attaches table zTbl in the same manner as the +** [sqlcipher_sqlite3session_attach()] function. If zTbl does not exist, or if it +** does not have a primary key, this function is a no-op (but does not return +** an error). +** +** Argument zFromDb must be the name of a database ("main", "temp" etc.) +** attached to the same database handle as the session object that contains +** a table compatible with the table attached to the session by this function. +** A table is considered compatible if it: +** +** <ul> +** <li> Has the same name, +** <li> Has the same set of columns declared in the same order, and +** <li> Has the same PRIMARY KEY definition. +** </ul> +** +** If the tables are not compatible, SQLITE_SCHEMA is returned. If the tables +** are compatible but do not have any PRIMARY KEY columns, it is not an error +** but no changes are added to the session object. As with other session +** APIs, tables without PRIMARY KEYs are simply ignored. +** +** This function adds a set of changes to the session object that could be +** used to update the table in database zFrom (call this the "from-table") +** so that its content is the same as the table attached to the session +** object (call this the "to-table"). Specifically: +** +** <ul> +** <li> For each row (primary key) that exists in the to-table but not in +** the from-table, an INSERT record is added to the session object. +** +** <li> For each row (primary key) that exists in the to-table but not in +** the from-table, a DELETE record is added to the session object. +** +** <li> For each row (primary key) that exists in both tables, but features +** different non-PK values in each, an UPDATE record is added to the +** session. +** </ul> +** +** To clarify, if this function is called and then a changeset constructed +** using [sqlcipher_sqlite3session_changeset()], then after applying that changeset to +** database zFrom the contents of the two compatible tables would be +** identical. +** +** It an error if database zFrom does not exist or does not contain the +** required compatible table. +** +** If the operation successful, SQLITE_OK is returned. Otherwise, an SQLite +** error code. In this case, if argument pzErrMsg is not NULL, *pzErrMsg +** may be set to point to a buffer containing an English language error +** message. It is the responsibility of the caller to free this buffer using +** sqlcipher_sqlite3_free(). +*/ +SQLITE_API int sqlcipher_sqlite3session_diff( + sqlcipher_sqlite3_session *pSession, + const char *zFromDb, + const char *zTbl, + char **pzErrMsg +); + + +/* +** CAPI3REF: Generate A Patchset From A Session Object +** +** The differences between a patchset and a changeset are that: +** +** <ul> +** <li> DELETE records consist of the primary key fields only. The +** original values of other fields are omitted. +** <li> The original values of any modified fields are omitted from +** UPDATE records. +** </ul> +** +** A patchset blob may be used with up to date versions of all +** sqlcipher_sqlite3changeset_xxx API functions except for sqlcipher_sqlite3changeset_invert(), +** which returns SQLITE_CORRUPT if it is passed a patchset. Similarly, +** attempting to use a patchset blob with old versions of the +** sqlcipher_sqlite3changeset_xxx APIs also provokes an SQLITE_CORRUPT error. +** +** Because the non-primary key "old.*" fields are omitted, no +** SQLITE_CHANGESET_DATA conflicts can be detected or reported if a patchset +** is passed to the sqlcipher_sqlite3changeset_apply() API. Other conflict types work +** in the same way as for changesets. +** +** Changes within a patchset are ordered in the same way as for changesets +** generated by the sqlcipher_sqlite3session_changeset() function (i.e. all changes for +** a single table are grouped together, tables appear in the order in which +** they were attached to the session object). +*/ +SQLITE_API int sqlcipher_sqlite3session_patchset( + sqlcipher_sqlite3_session *pSession, /* Session object */ + int *pnPatchset, /* OUT: Size of buffer at *ppChangeset */ + void **ppPatchset /* OUT: Buffer containing changeset */ +); + +/* +** CAPI3REF: Test if a changeset has recorded any changes. +** +** Return non-zero if no changes to attached tables have been recorded by +** the session object passed as the first argument. Otherwise, if one or +** more changes have been recorded, return zero. +** +** Even if this function returns zero, it is possible that calling +** [sqlcipher_sqlite3session_changeset()] on the session handle may still return a +** changeset that contains no changes. This can happen when a row in +** an attached table is modified and then later on the original values +** are restored. However, if this function returns non-zero, then it is +** guaranteed that a call to sqlcipher_sqlite3session_changeset() will return a +** changeset containing zero changes. +*/ +SQLITE_API int sqlcipher_sqlite3session_isempty(sqlcipher_sqlite3_session *pSession); + +/* +** CAPI3REF: Create An Iterator To Traverse A Changeset +** +** Create an iterator used to iterate through the contents of a changeset. +** If successful, *pp is set to point to the iterator handle and SQLITE_OK +** is returned. Otherwise, if an error occurs, *pp is set to zero and an +** SQLite error code is returned. +** +** The following functions can be used to advance and query a changeset +** iterator created by this function: +** +** <ul> +** <li> [sqlcipher_sqlite3changeset_next()] +** <li> [sqlcipher_sqlite3changeset_op()] +** <li> [sqlcipher_sqlite3changeset_new()] +** <li> [sqlcipher_sqlite3changeset_old()] +** </ul> +** +** It is the responsibility of the caller to eventually destroy the iterator +** by passing it to [sqlcipher_sqlite3changeset_finalize()]. The buffer containing the +** changeset (pChangeset) must remain valid until after the iterator is +** destroyed. +** +** Assuming the changeset blob was created by one of the +** [sqlcipher_sqlite3session_changeset()], [sqlcipher_sqlite3changeset_concat()] or +** [sqlcipher_sqlite3changeset_invert()] functions, all changes within the changeset +** that apply to a single table are grouped together. This means that when +** an application iterates through a changeset using an iterator created by +** this function, all changes that relate to a single table are visited +** consecutively. There is no chance that the iterator will visit a change +** the applies to table X, then one for table Y, and then later on visit +** another change for table X. +*/ +SQLITE_API int sqlcipher_sqlite3changeset_start( + sqlcipher_sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */ + int nChangeset, /* Size of changeset blob in bytes */ + void *pChangeset /* Pointer to blob containing changeset */ +); + + +/* +** CAPI3REF: Advance A Changeset Iterator +** +** This function may only be used with iterators created by function +** [sqlcipher_sqlite3changeset_start()]. If it is called on an iterator passed to +** a conflict-handler callback by [sqlcipher_sqlite3changeset_apply()], SQLITE_MISUSE +** is returned and the call has no effect. +** +** Immediately after an iterator is created by sqlcipher_sqlite3changeset_start(), it +** does not point to any change in the changeset. Assuming the changeset +** is not empty, the first call to this function advances the iterator to +** point to the first change in the changeset. Each subsequent call advances +** the iterator to point to the next change in the changeset (if any). If +** no error occurs and the iterator points to a valid change after a call +** to sqlcipher_sqlite3changeset_next() has advanced it, SQLITE_ROW is returned. +** Otherwise, if all changes in the changeset have already been visited, +** SQLITE_DONE is returned. +** +** If an error occurs, an SQLite error code is returned. Possible error +** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or +** SQLITE_NOMEM. +*/ +SQLITE_API int sqlcipher_sqlite3changeset_next(sqlcipher_sqlite3_changeset_iter *pIter); + +/* +** CAPI3REF: Obtain The Current Operation From A Changeset Iterator +** +** The pIter argument passed to this function may either be an iterator +** passed to a conflict-handler by [sqlcipher_sqlite3changeset_apply()], or an iterator +** created by [sqlcipher_sqlite3changeset_start()]. In the latter case, the most recent +** call to [sqlcipher_sqlite3changeset_next()] must have returned [SQLITE_ROW]. If this +** is not the case, this function returns [SQLITE_MISUSE]. +** +** If argument pzTab is not NULL, then *pzTab is set to point to a +** nul-terminated utf-8 encoded string containing the name of the table +** affected by the current change. The buffer remains valid until either +** sqlcipher_sqlite3changeset_next() is called on the iterator or until the +** conflict-handler function returns. If pnCol is not NULL, then *pnCol is +** set to the number of columns in the table affected by the change. If +** pbIncorrect is not NULL, then *pbIndirect is set to true (1) if the change +** is an indirect change, or false (0) otherwise. See the documentation for +** [sqlcipher_sqlite3session_indirect()] for a description of direct and indirect +** changes. Finally, if pOp is not NULL, then *pOp is set to one of +** [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], depending on the +** type of change that the iterator currently points to. +** +** If no error occurs, SQLITE_OK is returned. If an error does occur, an +** SQLite error code is returned. The values of the output variables may not +** be trusted in this case. +*/ +SQLITE_API int sqlcipher_sqlite3changeset_op( + sqlcipher_sqlite3_changeset_iter *pIter, /* Iterator object */ + const char **pzTab, /* OUT: Pointer to table name */ + int *pnCol, /* OUT: Number of columns in table */ + int *pOp, /* OUT: SQLITE_INSERT, DELETE or UPDATE */ + int *pbIndirect /* OUT: True for an 'indirect' change */ +); + +/* +** CAPI3REF: Obtain The Primary Key Definition Of A Table +** +** For each modified table, a changeset includes the following: +** +** <ul> +** <li> The number of columns in the table, and +** <li> Which of those columns make up the tables PRIMARY KEY. +** </ul> +** +** This function is used to find which columns comprise the PRIMARY KEY of +** the table modified by the change that iterator pIter currently points to. +** If successful, *pabPK is set to point to an array of nCol entries, where +** nCol is the number of columns in the table. Elements of *pabPK are set to +** 0x01 if the corresponding column is part of the tables primary key, or +** 0x00 if it is not. +** +** If argument pnCol is not NULL, then *pnCol is set to the number of columns +** in the table. +** +** If this function is called when the iterator does not point to a valid +** entry, SQLITE_MISUSE is returned and the output variables zeroed. Otherwise, +** SQLITE_OK is returned and the output variables populated as described +** above. +*/ +SQLITE_API int sqlcipher_sqlite3changeset_pk( + sqlcipher_sqlite3_changeset_iter *pIter, /* Iterator object */ + unsigned char **pabPK, /* OUT: Array of boolean - true for PK cols */ + int *pnCol /* OUT: Number of entries in output array */ +); + +/* +** CAPI3REF: Obtain old.* Values From A Changeset Iterator +** +** The pIter argument passed to this function may either be an iterator +** passed to a conflict-handler by [sqlcipher_sqlite3changeset_apply()], or an iterator +** created by [sqlcipher_sqlite3changeset_start()]. In the latter case, the most recent +** call to [sqlcipher_sqlite3changeset_next()] must have returned SQLITE_ROW. +** Furthermore, it may only be called if the type of change that the iterator +** currently points to is either [SQLITE_DELETE] or [SQLITE_UPDATE]. Otherwise, +** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL. +** +** Argument iVal must be greater than or equal to 0, and less than the number +** of columns in the table affected by the current change. Otherwise, +** [SQLITE_RANGE] is returned and *ppValue is set to NULL. +** +** If successful, this function sets *ppValue to point to a protected +** sqlcipher_sqlite3_value object containing the iVal'th value from the vector of +** original row values stored as part of the UPDATE or DELETE change and +** returns SQLITE_OK. The name of the function comes from the fact that this +** is similar to the "old.*" columns available to update or delete triggers. +** +** If some other error occurs (e.g. an OOM condition), an SQLite error code +** is returned and *ppValue is set to NULL. +*/ +SQLITE_API int sqlcipher_sqlite3changeset_old( + sqlcipher_sqlite3_changeset_iter *pIter, /* Changeset iterator */ + int iVal, /* Column number */ + sqlcipher_sqlite3_value **ppValue /* OUT: Old value (or NULL pointer) */ +); + +/* +** CAPI3REF: Obtain new.* Values From A Changeset Iterator +** +** The pIter argument passed to this function may either be an iterator +** passed to a conflict-handler by [sqlcipher_sqlite3changeset_apply()], or an iterator +** created by [sqlcipher_sqlite3changeset_start()]. In the latter case, the most recent +** call to [sqlcipher_sqlite3changeset_next()] must have returned SQLITE_ROW. +** Furthermore, it may only be called if the type of change that the iterator +** currently points to is either [SQLITE_UPDATE] or [SQLITE_INSERT]. Otherwise, +** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL. +** +** Argument iVal must be greater than or equal to 0, and less than the number +** of columns in the table affected by the current change. Otherwise, +** [SQLITE_RANGE] is returned and *ppValue is set to NULL. +** +** If successful, this function sets *ppValue to point to a protected +** sqlcipher_sqlite3_value object containing the iVal'th value from the vector of +** new row values stored as part of the UPDATE or INSERT change and +** returns SQLITE_OK. If the change is an UPDATE and does not include +** a new value for the requested column, *ppValue is set to NULL and +** SQLITE_OK returned. The name of the function comes from the fact that +** this is similar to the "new.*" columns available to update or delete +** triggers. +** +** If some other error occurs (e.g. an OOM condition), an SQLite error code +** is returned and *ppValue is set to NULL. +*/ +SQLITE_API int sqlcipher_sqlite3changeset_new( + sqlcipher_sqlite3_changeset_iter *pIter, /* Changeset iterator */ + int iVal, /* Column number */ + sqlcipher_sqlite3_value **ppValue /* OUT: New value (or NULL pointer) */ +); + +/* +** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator +** +** This function should only be used with iterator objects passed to a +** conflict-handler callback by [sqlcipher_sqlite3changeset_apply()] with either +** [SQLITE_CHANGESET_DATA] or [SQLITE_CHANGESET_CONFLICT]. If this function +** is called on any other iterator, [SQLITE_MISUSE] is returned and *ppValue +** is set to NULL. +** +** Argument iVal must be greater than or equal to 0, and less than the number +** of columns in the table affected by the current change. Otherwise, +** [SQLITE_RANGE] is returned and *ppValue is set to NULL. +** +** If successful, this function sets *ppValue to point to a protected +** sqlcipher_sqlite3_value object containing the iVal'th value from the +** "conflicting row" associated with the current conflict-handler callback +** and returns SQLITE_OK. +** +** If some other error occurs (e.g. an OOM condition), an SQLite error code +** is returned and *ppValue is set to NULL. +*/ +SQLITE_API int sqlcipher_sqlite3changeset_conflict( + sqlcipher_sqlite3_changeset_iter *pIter, /* Changeset iterator */ + int iVal, /* Column number */ + sqlcipher_sqlite3_value **ppValue /* OUT: Value from conflicting row */ +); + +/* +** CAPI3REF: Determine The Number Of Foreign Key Constraint Violations +** +** This function may only be called with an iterator passed to an +** SQLITE_CHANGESET_FOREIGN_KEY conflict handler callback. In this case +** it sets the output variable to the total number of known foreign key +** violations in the destination database and returns SQLITE_OK. +** +** In all other cases this function returns SQLITE_MISUSE. +*/ +SQLITE_API int sqlcipher_sqlite3changeset_fk_conflicts( + sqlcipher_sqlite3_changeset_iter *pIter, /* Changeset iterator */ + int *pnOut /* OUT: Number of FK violations */ +); + + +/* +** CAPI3REF: Finalize A Changeset Iterator +** +** This function is used to finalize an iterator allocated with +** [sqlcipher_sqlite3changeset_start()]. +** +** This function should only be called on iterators created using the +** [sqlcipher_sqlite3changeset_start()] function. If an application calls this +** function with an iterator passed to a conflict-handler by +** [sqlcipher_sqlite3changeset_apply()], [SQLITE_MISUSE] is immediately returned and the +** call has no effect. +** +** If an error was encountered within a call to an sqlcipher_sqlite3changeset_xxx() +** function (for example an [SQLITE_CORRUPT] in [sqlcipher_sqlite3changeset_next()] or an +** [SQLITE_NOMEM] in [sqlcipher_sqlite3changeset_new()]) then an error code corresponding +** to that error is returned by this function. Otherwise, SQLITE_OK is +** returned. This is to allow the following pattern (pseudo-code): +** +** sqlcipher_sqlite3changeset_start(); +** while( SQLITE_ROW==sqlcipher_sqlite3changeset_next() ){ +** // Do something with change. +** } +** rc = sqlcipher_sqlite3changeset_finalize(); +** if( rc!=SQLITE_OK ){ +** // An error has occurred +** } +*/ +SQLITE_API int sqlcipher_sqlite3changeset_finalize(sqlcipher_sqlite3_changeset_iter *pIter); + +/* +** CAPI3REF: Invert A Changeset +** +** This function is used to "invert" a changeset object. Applying an inverted +** changeset to a database reverses the effects of applying the uninverted +** changeset. Specifically: +** +** <ul> +** <li> Each DELETE change is changed to an INSERT, and +** <li> Each INSERT change is changed to a DELETE, and +** <li> For each UPDATE change, the old.* and new.* values are exchanged. +** </ul> +** +** This function does not change the order in which changes appear within +** the changeset. It merely reverses the sense of each individual change. +** +** If successful, a pointer to a buffer containing the inverted changeset +** is stored in *ppOut, the size of the same buffer is stored in *pnOut, and +** SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are +** zeroed and an SQLite error code returned. +** +** It is the responsibility of the caller to eventually call sqlcipher_sqlite3_free() +** on the *ppOut pointer to free the buffer allocation following a successful +** call to this function. +** +** WARNING/TODO: This function currently assumes that the input is a valid +** changeset. If it is not, the results are undefined. +*/ +SQLITE_API int sqlcipher_sqlite3changeset_invert( + int nIn, const void *pIn, /* Input changeset */ + int *pnOut, void **ppOut /* OUT: Inverse of input */ +); + +/* +** CAPI3REF: Concatenate Two Changeset Objects +** +** This function is used to concatenate two changesets, A and B, into a +** single changeset. The result is a changeset equivalent to applying +** changeset A followed by changeset B. +** +** This function combines the two input changesets using an +** sqlcipher_sqlite3_changegroup object. Calling it produces similar results as the +** following code fragment: +** +** sqlcipher_sqlite3_changegroup *pGrp; +** rc = sqlcipher_sqlite3_changegroup_new(&pGrp); +** if( rc==SQLITE_OK ) rc = sqlcipher_sqlite3changegroup_add(pGrp, nA, pA); +** if( rc==SQLITE_OK ) rc = sqlcipher_sqlite3changegroup_add(pGrp, nB, pB); +** if( rc==SQLITE_OK ){ +** rc = sqlcipher_sqlite3changegroup_output(pGrp, pnOut, ppOut); +** }else{ +** *ppOut = 0; +** *pnOut = 0; +** } +** +** Refer to the sqlcipher_sqlite3_changegroup documentation below for details. +*/ +SQLITE_API int sqlcipher_sqlite3changeset_concat( + int nA, /* Number of bytes in buffer pA */ + void *pA, /* Pointer to buffer containing changeset A */ + int nB, /* Number of bytes in buffer pB */ + void *pB, /* Pointer to buffer containing changeset B */ + int *pnOut, /* OUT: Number of bytes in output changeset */ + void **ppOut /* OUT: Buffer containing output changeset */ +); + + +/* +** CAPI3REF: Changegroup Handle +*/ +typedef struct sqlcipher_sqlite3_changegroup sqlcipher_sqlite3_changegroup; + +/* +** CAPI3REF: Create A New Changegroup Object +** +** An sqlcipher_sqlite3_changegroup object is used to combine two or more changesets +** (or patchsets) into a single changeset (or patchset). A single changegroup +** object may combine changesets or patchsets, but not both. The output is +** always in the same format as the input. +** +** If successful, this function returns SQLITE_OK and populates (*pp) with +** a pointer to a new sqlcipher_sqlite3_changegroup object before returning. The caller +** should eventually free the returned object using a call to +** sqlcipher_sqlite3changegroup_delete(). If an error occurs, an SQLite error code +** (i.e. SQLITE_NOMEM) is returned and *pp is set to NULL. +** +** The usual usage pattern for an sqlcipher_sqlite3_changegroup object is as follows: +** +** <ul> +** <li> It is created using a call to sqlcipher_sqlite3changegroup_new(). +** +** <li> Zero or more changesets (or patchsets) are added to the object +** by calling sqlcipher_sqlite3changegroup_add(). +** +** <li> The result of combining all input changesets together is obtained +** by the application via a call to sqlcipher_sqlite3changegroup_output(). +** +** <li> The object is deleted using a call to sqlcipher_sqlite3changegroup_delete(). +** </ul> +** +** Any number of calls to add() and output() may be made between the calls to +** new() and delete(), and in any order. +** +** As well as the regular sqlcipher_sqlite3changegroup_add() and +** sqlcipher_sqlite3changegroup_output() functions, also available are the streaming +** versions sqlcipher_sqlite3changegroup_add_strm() and sqlcipher_sqlite3changegroup_output_strm(). +*/ +SQLITE_API int sqlcipher_sqlite3changegroup_new(sqlcipher_sqlite3_changegroup **pp); + +/* +** CAPI3REF: Add A Changeset To A Changegroup +** +** Add all changes within the changeset (or patchset) in buffer pData (size +** nData bytes) to the changegroup. +** +** If the buffer contains a patchset, then all prior calls to this function +** on the same changegroup object must also have specified patchsets. Or, if +** the buffer contains a changeset, so must have the earlier calls to this +** function. Otherwise, SQLITE_ERROR is returned and no changes are added +** to the changegroup. +** +** Rows within the changeset and changegroup are identified by the values in +** their PRIMARY KEY columns. A change in the changeset is considered to +** apply to the same row as a change already present in the changegroup if +** the two rows have the same primary key. +** +** Changes to rows that do not already appear in the changegroup are +** simply copied into it. Or, if both the new changeset and the changegroup +** contain changes that apply to a single row, the final contents of the +** changegroup depends on the type of each change, as follows: +** +** <table border=1 style="margin-left:8ex;margin-right:8ex"> +** <tr><th style="white-space:pre">Existing Change </th> +** <th style="white-space:pre">New Change </th> +** <th>Output Change +** <tr><td>INSERT <td>INSERT <td> +** The new change is ignored. This case does not occur if the new +** changeset was recorded immediately after the changesets already +** added to the changegroup. +** <tr><td>INSERT <td>UPDATE <td> +** The INSERT change remains in the changegroup. The values in the +** INSERT change are modified as if the row was inserted by the +** existing change and then updated according to the new change. +** <tr><td>INSERT <td>DELETE <td> +** The existing INSERT is removed from the changegroup. The DELETE is +** not added. +** <tr><td>UPDATE <td>INSERT <td> +** The new change is ignored. This case does not occur if the new +** changeset was recorded immediately after the changesets already +** added to the changegroup. +** <tr><td>UPDATE <td>UPDATE <td> +** The existing UPDATE remains within the changegroup. It is amended +** so that the accompanying values are as if the row was updated once +** by the existing change and then again by the new change. +** <tr><td>UPDATE <td>DELETE <td> +** The existing UPDATE is replaced by the new DELETE within the +** changegroup. +** <tr><td>DELETE <td>INSERT <td> +** If one or more of the column values in the row inserted by the +** new change differ from those in the row deleted by the existing +** change, the existing DELETE is replaced by an UPDATE within the +** changegroup. Otherwise, if the inserted row is exactly the same +** as the deleted row, the existing DELETE is simply discarded. +** <tr><td>DELETE <td>UPDATE <td> +** The new change is ignored. This case does not occur if the new +** changeset was recorded immediately after the changesets already +** added to the changegroup. +** <tr><td>DELETE <td>DELETE <td> +** The new change is ignored. This case does not occur if the new +** changeset was recorded immediately after the changesets already +** added to the changegroup. +** </table> +** +** If the new changeset contains changes to a table that is already present +** in the changegroup, then the number of columns and the position of the +** primary key columns for the table must be consistent. If this is not the +** case, this function fails with SQLITE_SCHEMA. If the input changeset +** appears to be corrupt and the corruption is detected, SQLITE_CORRUPT is +** returned. Or, if an out-of-memory condition occurs during processing, this +** function returns SQLITE_NOMEM. In all cases, if an error occurs the +** final contents of the changegroup is undefined. +** +** If no error occurs, SQLITE_OK is returned. +*/ +SQLITE_API int sqlcipher_sqlite3changegroup_add(sqlcipher_sqlite3_changegroup*, int nData, void *pData); + +/* +** CAPI3REF: Obtain A Composite Changeset From A Changegroup +** +** Obtain a buffer containing a changeset (or patchset) representing the +** current contents of the changegroup. If the inputs to the changegroup +** were themselves changesets, the output is a changeset. Or, if the +** inputs were patchsets, the output is also a patchset. +** +** As with the output of the sqlcipher_sqlite3session_changeset() and +** sqlcipher_sqlite3session_patchset() functions, all changes related to a single +** table are grouped together in the output of this function. Tables appear +** in the same order as for the very first changeset added to the changegroup. +** If the second or subsequent changesets added to the changegroup contain +** changes for tables that do not appear in the first changeset, they are +** appended onto the end of the output changeset, again in the order in +** which they are first encountered. +** +** If an error occurs, an SQLite error code is returned and the output +** variables (*pnData) and (*ppData) are set to 0. Otherwise, SQLITE_OK +** is returned and the output variables are set to the size of and a +** pointer to the output buffer, respectively. In this case it is the +** responsibility of the caller to eventually free the buffer using a +** call to sqlcipher_sqlite3_free(). +*/ +SQLITE_API int sqlcipher_sqlite3changegroup_output( + sqlcipher_sqlite3_changegroup*, + int *pnData, /* OUT: Size of output buffer in bytes */ + void **ppData /* OUT: Pointer to output buffer */ +); + +/* +** CAPI3REF: Delete A Changegroup Object +*/ +SQLITE_API void sqlcipher_sqlite3changegroup_delete(sqlcipher_sqlite3_changegroup*); + +/* +** CAPI3REF: Apply A Changeset To A Database +** +** Apply a changeset to a database. This function attempts to update the +** "main" database attached to handle db with the changes found in the +** changeset passed via the second and third arguments. +** +** The fourth argument (xFilter) passed to this function is the "filter +** callback". If it is not NULL, then for each table affected by at least one +** change in the changeset, the filter callback is invoked with +** the table name as the second argument, and a copy of the context pointer +** passed as the sixth argument to this function as the first. If the "filter +** callback" returns zero, then no attempt is made to apply any changes to +** the table. Otherwise, if the return value is non-zero or the xFilter +** argument to this function is NULL, all changes related to the table are +** attempted. +** +** For each table that is not excluded by the filter callback, this function +** tests that the target database contains a compatible table. A table is +** considered compatible if all of the following are true: +** +** <ul> +** <li> The table has the same name as the name recorded in the +** changeset, and +** <li> The table has at least as many columns as recorded in the +** changeset, and +** <li> The table has primary key columns in the same position as +** recorded in the changeset. +** </ul> +** +** If there is no compatible table, it is not an error, but none of the +** changes associated with the table are applied. A warning message is issued +** via the sqlcipher_sqlite3_log() mechanism with the error code SQLITE_SCHEMA. At most +** one such warning is issued for each table in the changeset. +** +** For each change for which there is a compatible table, an attempt is made +** to modify the table contents according to the UPDATE, INSERT or DELETE +** change. If a change cannot be applied cleanly, the conflict handler +** function passed as the fifth argument to sqlcipher_sqlite3changeset_apply() may be +** invoked. A description of exactly when the conflict handler is invoked for +** each type of change is below. +** +** Unlike the xFilter argument, xConflict may not be passed NULL. The results +** of passing anything other than a valid function pointer as the xConflict +** argument are undefined. +** +** Each time the conflict handler function is invoked, it must return one +** of [SQLITE_CHANGESET_OMIT], [SQLITE_CHANGESET_ABORT] or +** [SQLITE_CHANGESET_REPLACE]. SQLITE_CHANGESET_REPLACE may only be returned +** if the second argument passed to the conflict handler is either +** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler +** returns an illegal value, any changes already made are rolled back and +** the call to sqlcipher_sqlite3changeset_apply() returns SQLITE_MISUSE. Different +** actions are taken by sqlcipher_sqlite3changeset_apply() depending on the value +** returned by each invocation of the conflict-handler function. Refer to +** the documentation for the three +** [SQLITE_CHANGESET_OMIT|available return values] for details. +** +** <dl> +** <dt>DELETE Changes<dd> +** For each DELETE change, this function checks if the target database +** contains a row with the same primary key value (or values) as the +** original row values stored in the changeset. If it does, and the values +** stored in all non-primary key columns also match the values stored in +** the changeset the row is deleted from the target database. +** +** If a row with matching primary key values is found, but one or more of +** the non-primary key fields contains a value different from the original +** row value stored in the changeset, the conflict-handler function is +** invoked with [SQLITE_CHANGESET_DATA] as the second argument. If the +** database table has more columns than are recorded in the changeset, +** only the values of those non-primary key fields are compared against +** the current database contents - any trailing database table columns +** are ignored. +** +** If no row with matching primary key values is found in the database, +** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND] +** passed as the second argument. +** +** If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT +** (which can only happen if a foreign key constraint is violated), the +** conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT] +** passed as the second argument. This includes the case where the DELETE +** operation is attempted because an earlier call to the conflict handler +** function returned [SQLITE_CHANGESET_REPLACE]. +** +** <dt>INSERT Changes<dd> +** For each INSERT change, an attempt is made to insert the new row into +** the database. If the changeset row contains fewer fields than the +** database table, the trailing fields are populated with their default +** values. +** +** If the attempt to insert the row fails because the database already +** contains a row with the same primary key values, the conflict handler +** function is invoked with the second argument set to +** [SQLITE_CHANGESET_CONFLICT]. +** +** If the attempt to insert the row fails because of some other constraint +** violation (e.g. NOT NULL or UNIQUE), the conflict handler function is +** invoked with the second argument set to [SQLITE_CHANGESET_CONSTRAINT]. +** This includes the case where the INSERT operation is re-attempted because +** an earlier call to the conflict handler function returned +** [SQLITE_CHANGESET_REPLACE]. +** +** <dt>UPDATE Changes<dd> +** For each UPDATE change, this function checks if the target database +** contains a row with the same primary key value (or values) as the +** original row values stored in the changeset. If it does, and the values +** stored in all modified non-primary key columns also match the values +** stored in the changeset the row is updated within the target database. +** +** If a row with matching primary key values is found, but one or more of +** the modified non-primary key fields contains a value different from an +** original row value stored in the changeset, the conflict-handler function +** is invoked with [SQLITE_CHANGESET_DATA] as the second argument. Since +** UPDATE changes only contain values for non-primary key fields that are +** to be modified, only those fields need to match the original values to +** avoid the SQLITE_CHANGESET_DATA conflict-handler callback. +** +** If no row with matching primary key values is found in the database, +** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND] +** passed as the second argument. +** +** If the UPDATE operation is attempted, but SQLite returns +** SQLITE_CONSTRAINT, the conflict-handler function is invoked with +** [SQLITE_CHANGESET_CONSTRAINT] passed as the second argument. +** This includes the case where the UPDATE operation is attempted after +** an earlier call to the conflict handler function returned +** [SQLITE_CHANGESET_REPLACE]. +** </dl> +** +** It is safe to execute SQL statements, including those that write to the +** table that the callback related to, from within the xConflict callback. +** This can be used to further customize the applications conflict +** resolution strategy. +** +** All changes made by this function are enclosed in a savepoint transaction. +** If any other error (aside from a constraint failure when attempting to +** write to the target database) occurs, then the savepoint transaction is +** rolled back, restoring the target database to its original state, and an +** SQLite error code returned. +*/ +SQLITE_API int sqlcipher_sqlite3changeset_apply( + sqlcipher_sqlite3 *db, /* Apply change to "main" db of this handle */ + int nChangeset, /* Size of changeset in bytes */ + void *pChangeset, /* Changeset blob */ + int(*xFilter)( + void *pCtx, /* Copy of sixth arg to _apply() */ + const char *zTab /* Table name */ + ), + int(*xConflict)( + void *pCtx, /* Copy of sixth arg to _apply() */ + int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */ + sqlcipher_sqlite3_changeset_iter *p /* Handle describing change and conflict */ + ), + void *pCtx /* First argument passed to xConflict */ +); + +/* +** CAPI3REF: Constants Passed To The Conflict Handler +** +** Values that may be passed as the second argument to a conflict-handler. +** +** <dl> +** <dt>SQLITE_CHANGESET_DATA<dd> +** The conflict handler is invoked with CHANGESET_DATA as the second argument +** when processing a DELETE or UPDATE change if a row with the required +** PRIMARY KEY fields is present in the database, but one or more other +** (non primary-key) fields modified by the update do not contain the +** expected "before" values. +** +** The conflicting row, in this case, is the database row with the matching +** primary key. +** +** <dt>SQLITE_CHANGESET_NOTFOUND<dd> +** The conflict handler is invoked with CHANGESET_NOTFOUND as the second +** argument when processing a DELETE or UPDATE change if a row with the +** required PRIMARY KEY fields is not present in the database. +** +** There is no conflicting row in this case. The results of invoking the +** sqlcipher_sqlite3changeset_conflict() API are undefined. +** +** <dt>SQLITE_CHANGESET_CONFLICT<dd> +** CHANGESET_CONFLICT is passed as the second argument to the conflict +** handler while processing an INSERT change if the operation would result +** in duplicate primary key values. +** +** The conflicting row in this case is the database row with the matching +** primary key. +** +** <dt>SQLITE_CHANGESET_FOREIGN_KEY<dd> +** If foreign key handling is enabled, and applying a changeset leaves the +** database in a state containing foreign key violations, the conflict +** handler is invoked with CHANGESET_FOREIGN_KEY as the second argument +** exactly once before the changeset is committed. If the conflict handler +** returns CHANGESET_OMIT, the changes, including those that caused the +** foreign key constraint violation, are committed. Or, if it returns +** CHANGESET_ABORT, the changeset is rolled back. +** +** No current or conflicting row information is provided. The only function +** it is possible to call on the supplied sqlcipher_sqlite3_changeset_iter handle +** is sqlcipher_sqlite3changeset_fk_conflicts(). +** +** <dt>SQLITE_CHANGESET_CONSTRAINT<dd> +** If any other constraint violation occurs while applying a change (i.e. +** a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is +** invoked with CHANGESET_CONSTRAINT as the second argument. +** +** There is no conflicting row in this case. The results of invoking the +** sqlcipher_sqlite3changeset_conflict() API are undefined. +** +** </dl> +*/ +#define SQLITE_CHANGESET_DATA 1 +#define SQLITE_CHANGESET_NOTFOUND 2 +#define SQLITE_CHANGESET_CONFLICT 3 +#define SQLITE_CHANGESET_CONSTRAINT 4 +#define SQLITE_CHANGESET_FOREIGN_KEY 5 + +/* +** CAPI3REF: Constants Returned By The Conflict Handler +** +** A conflict handler callback must return one of the following three values. +** +** <dl> +** <dt>SQLITE_CHANGESET_OMIT<dd> +** If a conflict handler returns this value no special action is taken. The +** change that caused the conflict is not applied. The session module +** continues to the next change in the changeset. +** +** <dt>SQLITE_CHANGESET_REPLACE<dd> +** This value may only be returned if the second argument to the conflict +** handler was SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this +** is not the case, any changes applied so far are rolled back and the +** call to sqlcipher_sqlite3changeset_apply() returns SQLITE_MISUSE. +** +** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_DATA conflict +** handler, then the conflicting row is either updated or deleted, depending +** on the type of change. +** +** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_CONFLICT conflict +** handler, then the conflicting row is removed from the database and a +** second attempt to apply the change is made. If this second attempt fails, +** the original row is restored to the database before continuing. +** +** <dt>SQLITE_CHANGESET_ABORT<dd> +** If this value is returned, any changes applied so far are rolled back +** and the call to sqlcipher_sqlite3changeset_apply() returns SQLITE_ABORT. +** </dl> +*/ +#define SQLITE_CHANGESET_OMIT 0 +#define SQLITE_CHANGESET_REPLACE 1 +#define SQLITE_CHANGESET_ABORT 2 + +/* +** CAPI3REF: Streaming Versions of API functions. +** +** The six streaming API xxx_strm() functions serve similar purposes to the +** corresponding non-streaming API functions: +** +** <table border=1 style="margin-left:8ex;margin-right:8ex"> +** <tr><th>Streaming function<th>Non-streaming equivalent</th> +** <tr><td>sqlcipher_sqlite3changeset_apply_str<td>[sqlcipher_sqlite3changeset_apply] +** <tr><td>sqlcipher_sqlite3changeset_concat_str<td>[sqlcipher_sqlite3changeset_concat] +** <tr><td>sqlcipher_sqlite3changeset_invert_str<td>[sqlcipher_sqlite3changeset_invert] +** <tr><td>sqlcipher_sqlite3changeset_start_str<td>[sqlcipher_sqlite3changeset_start] +** <tr><td>sqlcipher_sqlite3session_changeset_str<td>[sqlcipher_sqlite3session_changeset] +** <tr><td>sqlcipher_sqlite3session_patchset_str<td>[sqlcipher_sqlite3session_patchset] +** </table> +** +** Non-streaming functions that accept changesets (or patchsets) as input +** require that the entire changeset be stored in a single buffer in memory. +** Similarly, those that return a changeset or patchset do so by returning +** a pointer to a single large buffer allocated using sqlcipher_sqlite3_malloc(). +** Normally this is convenient. However, if an application running in a +** low-memory environment is required to handle very large changesets, the +** large contiguous memory allocations required can become onerous. +** +** In order to avoid this problem, instead of a single large buffer, input +** is passed to a streaming API functions by way of a callback function that +** the sessions module invokes to incrementally request input data as it is +** required. In all cases, a pair of API function parameters such as +** +** <pre> +** int nChangeset, +** void *pChangeset, +** </pre> +** +** Is replaced by: +** +** <pre> +** int (*xInput)(void *pIn, void *pData, int *pnData), +** void *pIn, +** </pre> +** +** Each time the xInput callback is invoked by the sessions module, the first +** argument passed is a copy of the supplied pIn context pointer. The second +** argument, pData, points to a buffer (*pnData) bytes in size. Assuming no +** error occurs the xInput method should copy up to (*pnData) bytes of data +** into the buffer and set (*pnData) to the actual number of bytes copied +** before returning SQLITE_OK. If the input is completely exhausted, (*pnData) +** should be set to zero to indicate this. Or, if an error occurs, an SQLite +** error code should be returned. In all cases, if an xInput callback returns +** an error, all processing is abandoned and the streaming API function +** returns a copy of the error code to the caller. +** +** In the case of sqlcipher_sqlite3changeset_start_strm(), the xInput callback may be +** invoked by the sessions module at any point during the lifetime of the +** iterator. If such an xInput callback returns an error, the iterator enters +** an error state, whereby all subsequent calls to iterator functions +** immediately fail with the same error code as returned by xInput. +** +** Similarly, streaming API functions that return changesets (or patchsets) +** return them in chunks by way of a callback function instead of via a +** pointer to a single large buffer. In this case, a pair of parameters such +** as: +** +** <pre> +** int *pnChangeset, +** void **ppChangeset, +** </pre> +** +** Is replaced by: +** +** <pre> +** int (*xOutput)(void *pOut, const void *pData, int nData), +** void *pOut +** </pre> +** +** The xOutput callback is invoked zero or more times to return data to +** the application. The first parameter passed to each call is a copy of the +** pOut pointer supplied by the application. The second parameter, pData, +** points to a buffer nData bytes in size containing the chunk of output +** data being returned. If the xOutput callback successfully processes the +** supplied data, it should return SQLITE_OK to indicate success. Otherwise, +** it should return some other SQLite error code. In this case processing +** is immediately abandoned and the streaming API function returns a copy +** of the xOutput error code to the application. +** +** The sessions module never invokes an xOutput callback with the third +** parameter set to a value less than or equal to zero. Other than this, +** no guarantees are made as to the size of the chunks of data returned. +*/ +SQLITE_API int sqlcipher_sqlite3changeset_apply_strm( + sqlcipher_sqlite3 *db, /* Apply change to "main" db of this handle */ + int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */ + void *pIn, /* First arg for xInput */ + int(*xFilter)( + void *pCtx, /* Copy of sixth arg to _apply() */ + const char *zTab /* Table name */ + ), + int(*xConflict)( + void *pCtx, /* Copy of sixth arg to _apply() */ + int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */ + sqlcipher_sqlite3_changeset_iter *p /* Handle describing change and conflict */ + ), + void *pCtx /* First argument passed to xConflict */ +); +SQLITE_API int sqlcipher_sqlite3changeset_concat_strm( + int (*xInputA)(void *pIn, void *pData, int *pnData), + void *pInA, + int (*xInputB)(void *pIn, void *pData, int *pnData), + void *pInB, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); +SQLITE_API int sqlcipher_sqlite3changeset_invert_strm( + int (*xInput)(void *pIn, void *pData, int *pnData), + void *pIn, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); +SQLITE_API int sqlcipher_sqlite3changeset_start_strm( + sqlcipher_sqlite3_changeset_iter **pp, + int (*xInput)(void *pIn, void *pData, int *pnData), + void *pIn +); +SQLITE_API int sqlcipher_sqlite3session_changeset_strm( + sqlcipher_sqlite3_session *pSession, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); +SQLITE_API int sqlcipher_sqlite3session_patchset_strm( + sqlcipher_sqlite3_session *pSession, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); +SQLITE_API int sqlcipher_sqlite3changegroup_add_strm(sqlcipher_sqlite3_changegroup*, + int (*xInput)(void *pIn, void *pData, int *pnData), + void *pIn +); +SQLITE_API int sqlcipher_sqlite3changegroup_output_strm(sqlcipher_sqlite3_changegroup*, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); + + +/* +** Make sure we can call this stuff from C++. +*/ +#ifdef __cplusplus +} +#endif + +#endif /* !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION) */ + +/******** End of sqlcipher_sqlite3session.h *********/ +/******** Begin file fts5.h *********/ /* ** 2014 May 31 ** @@ -8252,11 +10256,13 @@ struct Fts5PhraseIter { ** ... FROM ftstable WHERE ftstable MATCH $p ORDER BY rowid ** ** with $p set to a phrase equivalent to the phrase iPhrase of the -** current query is executed. For each row visited, the callback function -** passed as the fourth argument is invoked. The context and API objects -** passed to the callback function may be used to access the properties of -** each matched row. Invoking Api.xUserData() returns a copy of the pointer -** passed as the third argument to pUserData. +** current query is executed. Any column filter that applies to +** phrase iPhrase of the current query is included in $p. For each +** row visited, the callback function passed as the fourth argument +** is invoked. The context and API objects passed to the callback +** function may be used to access the properties of each matched row. +** Invoking Api.xUserData() returns a copy of the pointer passed as +** the third argument to pUserData. ** ** If the callback function returns any value other than SQLITE_OK, the ** query is abandoned and the xQueryPhrase function returns immediately. @@ -8425,7 +10431,7 @@ struct Fts5ExtensionApi { ** behaviour. The structure methods are expected to function as follows: ** ** xCreate: -** This function is used to allocate and inititalize a tokenizer instance. +** This function is used to allocate and initialize a tokenizer instance. ** A tokenizer instance is required to actually tokenize text. ** ** The first argument passed to this function is a copy of the (void*) @@ -8685,5 +10691,5 @@ struct fts5_api { #endif /* _FTS5_H */ - +/******** End of fts5.h *********/ |