diff options
Diffstat (limited to 'Plugins/DbSqliteWx/wxsqlite3.h')
| -rw-r--r-- | Plugins/DbSqliteWx/wxsqlite3.h | 1205 |
1 files changed, 986 insertions, 219 deletions
diff --git a/Plugins/DbSqliteWx/wxsqlite3.h b/Plugins/DbSqliteWx/wxsqlite3.h index 170bfc1..35784e9 100644 --- a/Plugins/DbSqliteWx/wxsqlite3.h +++ b/Plugins/DbSqliteWx/wxsqlite3.h @@ -3,13 +3,45 @@ ** Purpose: Header file for SQLite3 Multiple Ciphers support ** Author: Ulrich Telle ** Created: 2020-03-01 -** Copyright: (c) 2019-2020 Ulrich Telle +** Copyright: (c) 2019-2022 Ulrich Telle ** License: MIT */ #ifndef SQLITE3MC_H_ #define SQLITE3MC_H_ +/* +** Define SQLite3 Multiple Ciphers version information +*/ +/* #include "wx_sqlite3mc_version.h" */ +/*** Begin of #include "wx_sqlite3mc_version.h" ***/ +/* +** Name: wx_sqlite3mc_version.h +** Purpose: SQLite3 Multiple Ciphers version numbers +** Author: Ulrich Telle +** Created: 2020-08-05 +** Copyright: (c) 2020-2023 Ulrich Telle +** License: MIT +*/ + +/// \file wx_sqlite3mc_version.h Version information for the SQLite3 Multiple Ciphers library + +#ifndef SQLITE3MC_VERSION_H_ +#define SQLITE3MC_VERSION_H_ + +#define SQLITE3MC_VERSION_MAJOR 1 +#define SQLITE3MC_VERSION_MINOR 6 +#define SQLITE3MC_VERSION_RELEASE 2 +#define SQLITE3MC_VERSION_SUBRELEASE 0 +#define SQLITE3MC_VERSION_STRING "SQLite3 Multiple Ciphers 1.6.2" + +#endif /* SQLITE3MC_VERSION_H_ */ +/*** End of #include "wx_sqlite3mc_version.h" ***/ + + +/* +** Define SQLite3 API +*/ /* #include "wx_sqlite3.h" */ /*** Begin of #include "wx_sqlite3.h" ***/ /* @@ -57,7 +89,30 @@ extern "C" { /* -** Provide the ability to override linkage features of the interface. +** Facilitate override of interface linkage and calling conventions. +** Be aware that these macros may not be used within this particular +** translation of the amalgamation and its associated header file. +** +** The SQLITE_EXTERN and SQLITE_API macros are used to instruct the +** compiler that the target identifier should have external linkage. +** +** The SQLITE_CDECL macro is used to set the calling convention for +** public functions that accept a variable number of arguments. +** +** The SQLITE_APICALL macro is used to set the calling convention for +** public functions that accept a fixed number of arguments. +** +** The SQLITE_STDCALL macro is no longer used and is now deprecated. +** +** The SQLITE_CALLBACK macro is used to set the calling convention for +** function pointers. +** +** The SQLITE_SYSAPI macro is used to set the calling convention for +** functions provided by the operating system. +** +** Currently, the SQLITE_CDECL, SQLITE_APICALL, SQLITE_CALLBACK, and +** SQLITE_SYSAPI macros are used only when building for environments +** that require non-default calling conventions. */ #ifndef SQLITE_EXTERN # define SQLITE_EXTERN extern @@ -137,9 +192,9 @@ extern "C" { ** [wx_sqlite3_libversion_number()], [wx_sqlite3_sourceid()], ** [sqlite_version()] and [sqlite_source_id()]. */ -#define SQLITE_VERSION "3.35.4" -#define SQLITE_VERSION_NUMBER 3035004 -#define SQLITE_SOURCE_ID "2021-04-02 15:20:15 5d4c65779dab868b285519b19e4cf9d451d50c6048f06f653aa701ec212df45e" +#define SQLITE_VERSION "3.41.2" +#define SQLITE_VERSION_NUMBER 3041002 +#define SQLITE_SOURCE_ID "2023-03-22 11:56:21 0d1fc92f94cb6b76bffe3ec34d69cffde2924203304e8ffc4155597af0c191da" /* ** CAPI3REF: Run-Time Library Version Numbers @@ -551,12 +606,14 @@ SQLITE_API int wx_sqlite3_exec( #define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT | (9<<8)) #define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT |(10<<8)) #define SQLITE_CONSTRAINT_PINNED (SQLITE_CONSTRAINT |(11<<8)) +#define SQLITE_CONSTRAINT_DATATYPE (SQLITE_CONSTRAINT |(12<<8)) #define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1<<8)) #define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8)) +#define SQLITE_NOTICE_RBU (SQLITE_NOTICE | (3<<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)) -#define SQLITE_OK_SYMLINK (SQLITE_OK | (2<<8)) +#define SQLITE_OK_SYMLINK (SQLITE_OK | (2<<8)) /* internal use only */ /* ** CAPI3REF: Flags For File Open Operations @@ -564,6 +621,19 @@ SQLITE_API int wx_sqlite3_exec( ** These bit values are intended for use in the ** 3rd parameter to the [wx_sqlite3_open_v2()] interface and ** in the 4th parameter to the [wx_sqlite3_vfs.xOpen] method. +** +** Only those flags marked as "Ok for wx_sqlite3_open_v2()" may be +** used as the third argument to the [wx_sqlite3_open_v2()] interface. +** The other flags have historically been ignored by wx_sqlite3_open_v2(), +** though future versions of SQLite might change so that an error is +** raised if any of the disallowed bits are passed into wx_sqlite3_open_v2(). +** Applications should not depend on the historical behavior. +** +** Note in particular that passing the SQLITE_OPEN_EXCLUSIVE flag into +** [wx_sqlite3_open_v2()] does *not* cause the underlying database file +** to be opened using O_EXCL. Passing SQLITE_OPEN_EXCLUSIVE into +** [wx_sqlite3_open_v2()] has historically be a no-op and might become an +** error in future versions of SQLite. */ #define SQLITE_OPEN_READONLY 0x00000001 /* Ok for wx_sqlite3_open_v2() */ #define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for wx_sqlite3_open_v2() */ @@ -586,6 +656,7 @@ SQLITE_API int wx_sqlite3_exec( #define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for wx_sqlite3_open_v2() */ #define SQLITE_OPEN_WAL 0x00080000 /* VFS only */ #define SQLITE_OPEN_NOFOLLOW 0x01000000 /* Ok for wx_sqlite3_open_v2() */ +#define SQLITE_OPEN_EXRESCODE 0x02000000 /* Extended result codes */ /* Reserved: 0x00F00000 */ /* Legacy compatibility: */ @@ -646,13 +717,17 @@ SQLITE_API int wx_sqlite3_exec( ** ** SQLite uses one of these integer values as the second ** argument to calls it makes to the xLock() and xUnlock() methods -** of an [wx_sqlite3_io_methods] object. +** of an [wx_sqlite3_io_methods] object. These values are ordered from +** lest restrictive to most restrictive. +** +** The argument to xLock() is always SHARED or higher. The argument to +** xUnlock is either SHARED or NONE. */ -#define SQLITE_LOCK_NONE 0 -#define SQLITE_LOCK_SHARED 1 -#define SQLITE_LOCK_RESERVED 2 -#define SQLITE_LOCK_PENDING 3 -#define SQLITE_LOCK_EXCLUSIVE 4 +#define SQLITE_LOCK_NONE 0 /* xUnlock() only */ +#define SQLITE_LOCK_SHARED 1 /* xLock() or xUnlock() */ +#define SQLITE_LOCK_RESERVED 2 /* xLock() only */ +#define SQLITE_LOCK_PENDING 3 /* xLock() only */ +#define SQLITE_LOCK_EXCLUSIVE 4 /* xLock() only */ /* ** CAPI3REF: Synchronization Type Flags @@ -730,7 +805,14 @@ struct wx_sqlite3_file { ** <li> [SQLITE_LOCK_PENDING], or ** <li> [SQLITE_LOCK_EXCLUSIVE]. ** </ul> -** xLock() increases the lock. xUnlock() decreases the lock. +** xLock() upgrades the database file lock. In other words, xLock() moves the +** database file lock in the direction NONE toward EXCLUSIVE. The argument to +** xLock() is always on of SHARED, RESERVED, PENDING, or EXCLUSIVE, never +** SQLITE_LOCK_NONE. If the database file lock is already at or above the +** requested lock, then the call to xLock() is a no-op. +** xUnlock() downgrades the database file lock to either SHARED or NONE. +* If the lock is already at or below the requested lock state, then the call +** to xUnlock() is a no-op. ** The xCheckReservedLock() method checks whether any database connection, ** either in this process or in some other process, is holding a RESERVED, ** PENDING, or EXCLUSIVE lock on the file. It returns true @@ -835,9 +917,8 @@ struct wx_sqlite3_io_methods { ** opcode causes the xFileControl method to write the current state of ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED], ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE]) -** into an integer that the pArg argument points to. This capability -** is used during testing and is only available when the SQLITE_TEST -** compile-time option is used. +** into an integer that the pArg argument points to. +** This capability is only available if SQLite is compiled with [SQLITE_DEBUG]. ** ** <li>[[SQLITE_FCNTL_SIZE_HINT]] ** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS @@ -1141,6 +1222,28 @@ struct wx_sqlite3_io_methods { ** in wal mode after the client has finished copying pages from the wal ** file to the database file, but before the *-shm file is updated to ** record the fact that the pages have been checkpointed. +** +** <li>[[SQLITE_FCNTL_EXTERNAL_READER]] +** The EXPERIMENTAL [SQLITE_FCNTL_EXTERNAL_READER] opcode is used to detect +** whether or not there is a database client in another process with a wal-mode +** transaction open on the database or not. It is only available on unix.The +** (void*) argument passed with this file-control should be a pointer to a +** value of type (int). The integer value is set to 1 if the database is a wal +** mode database and there exists at least one client in another process that +** currently has an SQL transaction open on the database. It is set to 0 if +** the database is not a wal-mode db, or if there is no such connection in any +** other process. This opcode cannot be used to detect transactions opened +** by clients within the current process, only within other processes. +** +** <li>[[SQLITE_FCNTL_CKSM_FILE]] +** The [SQLITE_FCNTL_CKSM_FILE] opcode is for use interally by the +** [checksum VFS shim] only. +** +** <li>[[SQLITE_FCNTL_RESET_CACHE]] +** If there is currently no transaction open on the database, and the +** database is not a temp db, then the [SQLITE_FCNTL_RESET_CACHE] file-control +** purges the contents of the in-memory page cache. If there is an open +** transaction, or if the db is a temp-db, this opcode is a no-op, not an error. ** </ul> */ #define SQLITE_FCNTL_LOCKSTATE 1 @@ -1181,6 +1284,9 @@ struct wx_sqlite3_io_methods { #define SQLITE_FCNTL_CKPT_DONE 37 #define SQLITE_FCNTL_RESERVE_BYTES 38 #define SQLITE_FCNTL_CKPT_START 39 +#define SQLITE_FCNTL_EXTERNAL_READER 40 +#define SQLITE_FCNTL_CKSM_FILE 41 +#define SQLITE_FCNTL_RESET_CACHE 42 /* deprecated names */ #define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE @@ -1211,6 +1317,26 @@ typedef struct wx_sqlite3_mutex wx_sqlite3_mutex; typedef struct wx_sqlite3_api_routines wx_sqlite3_api_routines; /* +** CAPI3REF: File Name +** +** Type [wx_sqlite3_filename] is used by SQLite to pass filenames to the +** xOpen method of a [VFS]. It may be cast to (const char*) and treated +** as a normal, nul-terminated, UTF-8 buffer containing the filename, but +** may also be passed to special APIs such as: +** +** <ul> +** <li> wx_sqlite3_filename_database() +** <li> wx_sqlite3_filename_journal() +** <li> wx_sqlite3_filename_wal() +** <li> wx_sqlite3_uri_parameter() +** <li> wx_sqlite3_uri_boolean() +** <li> wx_sqlite3_uri_int64() +** <li> wx_sqlite3_uri_key() +** </ul> +*/ +typedef const char *wx_sqlite3_filename; + +/* ** CAPI3REF: OS Interface Object ** ** An instance of the wx_sqlite3_vfs object defines the interface between @@ -1388,7 +1514,7 @@ struct wx_sqlite3_vfs { wx_sqlite3_vfs *pNext; /* Next registered VFS */ const char *zName; /* Name of this virtual file system */ void *pAppData; /* Pointer to application-specific data */ - int (*xOpen)(wx_sqlite3_vfs*, const char *zName, wx_sqlite3_file*, + int (*xOpen)(wx_sqlite3_vfs*, wx_sqlite3_filename zName, wx_sqlite3_file*, int flags, int *pOutFlags); int (*xDelete)(wx_sqlite3_vfs*, const char *zName, int syncDir); int (*xAccess)(wx_sqlite3_vfs*, const char *zName, int flags, int *pResOut); @@ -2104,7 +2230,7 @@ struct wx_sqlite3_mem_methods { ** configuration for a database connection can only be changed when that ** connection is not currently using lookaside memory, or in other words ** when the "current value" returned by -** [wx_sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero. +** [wx_sqlite3_db_status](D,[SQLITE_DBSTATUS_LOOKASIDE_USED],...) is zero. ** Any attempt to change the lookaside memory configuration when lookaside ** memory is in use leaves the configuration unchanged and returns ** [SQLITE_BUSY].)^</dd> @@ -2254,8 +2380,12 @@ struct wx_sqlite3_mem_methods { ** <li> wx_sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0); ** </ol> ** Because resetting a database is destructive and irreversible, the -** process requires the use of this obscure API and multiple steps to help -** ensure that it does not happen by accident. +** process requires the use of this obscure API and multiple steps to +** help ensure that it does not happen by accident. Because this +** feature must be capable of resetting corrupt databases, and +** shutting down virtual tables may require access to that corrupt +** storage, the library must abandon any installed virtual tables +** without calling their xDestroy() methods. ** ** [[SQLITE_DBCONFIG_DEFENSIVE]] <dt>SQLITE_DBCONFIG_DEFENSIVE</dt> ** <dd>The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the @@ -2266,6 +2396,7 @@ struct wx_sqlite3_mem_methods { ** <ul> ** <li> The [PRAGMA writable_schema=ON] statement. ** <li> The [PRAGMA journal_mode=OFF] statement. +** <li> The [PRAGMA schema_version=N] statement. ** <li> Writes to the [sqlite_dbpage] virtual table. ** <li> Direct writes to [shadow tables]. ** </ul> @@ -2459,11 +2590,14 @@ SQLITE_API void wx_sqlite3_set_last_insert_rowid(wx_sqlite3*,wx_sqlite3_int64); ** CAPI3REF: Count The Number Of Rows Modified ** METHOD: wx_sqlite3 ** -** ^This function returns the number of rows modified, inserted or +** ^These functions return the number of rows modified, inserted or ** deleted by the most recently completed INSERT, UPDATE or DELETE ** statement on the database connection specified by the only parameter. -** ^Executing any other type of SQL statement does not modify the value -** returned by this function. +** The two functions are identical except for the type of the return value +** and that if the number of rows modified by the most recent INSERT, UPDATE +** or DELETE is greater than the maximum value supported by type "int", then +** the return value of wx_sqlite3_changes() is undefined. ^Executing any other +** type of SQL statement does not modify the value returned by these functions. ** ** ^Only changes made directly by the INSERT, UPDATE or DELETE statement are ** considered - auxiliary changes caused by [CREATE TRIGGER | triggers], @@ -2512,16 +2646,21 @@ SQLITE_API void wx_sqlite3_set_last_insert_rowid(wx_sqlite3*,wx_sqlite3_int64); ** </ul> */ SQLITE_API int wx_sqlite3_changes(wx_sqlite3*); +SQLITE_API wx_sqlite3_int64 wx_sqlite3_changes64(wx_sqlite3*); /* ** CAPI3REF: Total Number Of Rows Modified ** METHOD: wx_sqlite3 ** -** ^This function returns the total number of rows inserted, modified or +** ^These functions return the total number of rows inserted, modified or ** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed ** since the database connection was opened, including those executed as -** part of trigger programs. ^Executing any other type of SQL statement -** does not affect the value returned by wx_sqlite3_total_changes(). +** part of trigger programs. The two functions are identical except for the +** type of the return value and that if the number of rows modified by the +** connection exceeds the maximum value supported by type "int", then +** the return value of wx_sqlite3_total_changes() is undefined. ^Executing +** any other type of SQL statement does not affect the value returned by +** wx_sqlite3_total_changes(). ** ** ^Changes made as part of [foreign key actions] are included in the ** count, but those made as part of REPLACE constraint resolution are @@ -2549,6 +2688,7 @@ SQLITE_API int wx_sqlite3_changes(wx_sqlite3*); ** </ul> */ SQLITE_API int wx_sqlite3_total_changes(wx_sqlite3*); +SQLITE_API wx_sqlite3_int64 wx_sqlite3_total_changes64(wx_sqlite3*); /* ** CAPI3REF: Interrupt A Long-Running Query @@ -2584,8 +2724,12 @@ SQLITE_API int wx_sqlite3_total_changes(wx_sqlite3*); ** ^A call to wx_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 wx_sqlite3_interrupt() call returns. +** +** ^The [wx_sqlite3_is_interrupted(D)] interface can be used to determine whether +** or not an interrupt is currently in effect for [database connection] D. */ SQLITE_API void wx_sqlite3_interrupt(wx_sqlite3*); +SQLITE_API int wx_sqlite3_is_interrupted(wx_sqlite3*); /* ** CAPI3REF: Determine If An SQL Statement Is Complete @@ -3203,8 +3347,8 @@ SQLITE_API SQLITE_DEPRECATED void *wx_sqlite3_profile(wx_sqlite3*, ** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same ** information as is provided by the [wx_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. +** X argument points to a 64-bit integer which is approximately +** the number of nanoseconds 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> @@ -3267,7 +3411,7 @@ SQLITE_API int wx_sqlite3_trace_v2( ** ** ^The wx_sqlite3_progress_handler(D,N,X,P) interface causes the callback ** function X to be invoked periodically during long running calls to -** [wx_sqlite3_exec()], [wx_sqlite3_step()] and [wx_sqlite3_get_table()] for +** [wx_sqlite3_step()] and [wx_sqlite3_prepare()] and similar for ** database connection D. An example use for this ** interface is to keep a GUI updated during a large query. ** @@ -3292,6 +3436,13 @@ SQLITE_API int wx_sqlite3_trace_v2( ** Note that [wx_sqlite3_prepare_v2()] and [wx_sqlite3_step()] both modify their ** database connections for the meaning of "modify" in this paragraph. ** +** The progress handler callback would originally only be invoked from the +** bytecode engine. It still might be invoked during [wx_sqlite3_prepare()] +** and similar because those routines might force a reparse of the schema +** which involves running the bytecode engine. However, beginning with +** SQLite version 3.41.0, the progress handler callback might also be +** invoked directly from [wx_sqlite3_prepare()] while analyzing and generating +** code for complex queries. */ SQLITE_API void wx_sqlite3_progress_handler(wx_sqlite3*, int, int(*)(void*), void*); @@ -3328,13 +3479,18 @@ SQLITE_API void wx_sqlite3_progress_handler(wx_sqlite3*, int, int(*)(void*), voi ** ** <dl> ** ^(<dt>[SQLITE_OPEN_READONLY]</dt> -** <dd>The database is opened in read-only mode. If the database does not -** already exist, an error is returned.</dd>)^ +** <dd>The database is opened in read-only mode. If the database does +** not already exist, an error is returned.</dd>)^ ** ** ^(<dt>[SQLITE_OPEN_READWRITE]</dt> -** <dd>The database is opened for reading and writing if possible, or reading -** only if the file is write protected by the operating system. In either -** case the database must already exist, otherwise an error is returned.</dd>)^ +** <dd>The database is opened for reading and writing if possible, or +** reading only if the file is write protected by the operating +** system. In either case the database must already exist, otherwise +** an error is returned. For historical reasons, if opening in +** read-write mode fails due to OS-level permissions, an attempt is +** made to open it in read-only mode. [wx_sqlite3_db_readonly()] can be +** used to determine whether the database is actually +** read-write.</dd>)^ ** ** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt> ** <dd>The database is opened for reading and writing, and is created if @@ -3372,20 +3528,39 @@ SQLITE_API void wx_sqlite3_progress_handler(wx_sqlite3*, int, int(*)(void*), voi ** <dd>The database is opened [shared cache] enabled, overriding ** the default shared cache setting provided by ** [wx_sqlite3_enable_shared_cache()].)^ +** The [use of shared cache mode is discouraged] and hence shared cache +** capabilities may be omitted from many builds of SQLite. In such cases, +** this option is a no-op. ** ** ^(<dt>[SQLITE_OPEN_PRIVATECACHE]</dt> ** <dd>The database is opened [shared cache] disabled, overriding ** the default shared cache setting provided by ** [wx_sqlite3_enable_shared_cache()].)^ ** +** [[OPEN_EXRESCODE]] ^(<dt>[SQLITE_OPEN_EXRESCODE]</dt> +** <dd>The database connection comes up in "extended result code mode". +** In other words, the database behaves has if +** [wx_sqlite3_extended_result_codes(db,1)] where called on the database +** connection as soon as the connection is created. In addition to setting +** the extended result code mode, this flag also causes [wx_sqlite3_open_v2()] +** to return an extended result code.</dd> +** ** [[OPEN_NOFOLLOW]] ^(<dt>[SQLITE_OPEN_NOFOLLOW]</dt> -** <dd>The database filename is not allowed to be a symbolic link</dd> +** <dd>The database filename is not allowed to contain a symbolic link</dd> ** </dl>)^ ** ** If the 3rd parameter to wx_sqlite3_open_v2() is not one of the ** required combinations shown above optionally combined with other ** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits] -** then the behavior is undefined. +** then the behavior is undefined. Historic versions of SQLite +** have silently ignored surplus bits in the flags parameter to +** wx_sqlite3_open_v2(), however that behavior might not be carried through +** into future versions of SQLite and so applications should not rely +** upon it. Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no-op +** for wx_sqlite3_open_v2(). The SQLITE_OPEN_EXCLUSIVE does *not* cause +** the open to fail if the database already exists. The SQLITE_OPEN_EXCLUSIVE +** flag is intended for use by the [wx_sqlite3_vfs|VFS interface] only, and not +** by wx_sqlite3_open_v2(). ** ** ^The fourth parameter to wx_sqlite3_open_v2() is the name of the ** [wx_sqlite3_vfs] object that defines the operating system interface that @@ -3630,10 +3805,10 @@ SQLITE_API int wx_sqlite3_open_v2( ** ** See the [URI filename] documentation for additional information. */ -SQLITE_API const char *wx_sqlite3_uri_parameter(const char *zFilename, const char *zParam); -SQLITE_API int wx_sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault); -SQLITE_API wx_sqlite3_int64 wx_sqlite3_uri_int64(const char*, const char*, wx_sqlite3_int64); -SQLITE_API const char *wx_sqlite3_uri_key(const char *zFilename, int N); +SQLITE_API const char *wx_sqlite3_uri_parameter(wx_sqlite3_filename z, const char *zParam); +SQLITE_API int wx_sqlite3_uri_boolean(wx_sqlite3_filename z, const char *zParam, int bDefault); +SQLITE_API wx_sqlite3_int64 wx_sqlite3_uri_int64(wx_sqlite3_filename, const char*, wx_sqlite3_int64); +SQLITE_API const char *wx_sqlite3_uri_key(wx_sqlite3_filename z, int N); /* ** CAPI3REF: Translate filenames @@ -3662,9 +3837,9 @@ SQLITE_API const char *wx_sqlite3_uri_key(const char *zFilename, int N); ** return value from [wx_sqlite3_db_filename()], then the result is ** undefined and is likely a memory access violation. */ -SQLITE_API const char *wx_sqlite3_filename_database(const char*); -SQLITE_API const char *wx_sqlite3_filename_journal(const char*); -SQLITE_API const char *wx_sqlite3_filename_wal(const char*); +SQLITE_API const char *wx_sqlite3_filename_database(wx_sqlite3_filename); +SQLITE_API const char *wx_sqlite3_filename_journal(wx_sqlite3_filename); +SQLITE_API const char *wx_sqlite3_filename_wal(wx_sqlite3_filename); /* ** CAPI3REF: Database File Corresponding To A Journal @@ -3730,14 +3905,14 @@ SQLITE_API wx_sqlite3_file *wx_sqlite3_database_file_object(const char*); ** then the corresponding [wx_sqlite3_module.xClose() method should also be ** invoked prior to calling wx_sqlite3_free_filename(Y). */ -SQLITE_API char *wx_sqlite3_create_filename( +SQLITE_API wx_sqlite3_filename wx_sqlite3_create_filename( const char *zDatabase, const char *zJournal, const char *zWal, int nParam, const char **azParam ); -SQLITE_API void wx_sqlite3_free_filename(char*); +SQLITE_API void wx_sqlite3_free_filename(wx_sqlite3_filename); /* ** CAPI3REF: Error Codes And Messages @@ -3756,13 +3931,14 @@ SQLITE_API void wx_sqlite3_free_filename(char*); ** wx_sqlite3_extended_errcode() might change with each API call. ** Except, there are some interfaces that are guaranteed to never ** change the value of the error code. The error-code preserving -** interfaces are: +** interfaces include the following: ** ** <ul> ** <li> wx_sqlite3_errcode() ** <li> wx_sqlite3_extended_errcode() ** <li> wx_sqlite3_errmsg() ** <li> wx_sqlite3_errmsg16() +** <li> wx_sqlite3_error_offset() ** </ul> ** ** ^The wx_sqlite3_errmsg() and wx_sqlite3_errmsg16() return English-language @@ -3777,6 +3953,13 @@ SQLITE_API void wx_sqlite3_free_filename(char*); ** ^(Memory to hold the error message string is managed internally ** and must not be freed by the application)^. ** +** ^If the most recent error references a specific token in the input +** SQL, the wx_sqlite3_error_offset() interface returns the byte offset +** of the start of that token. ^The byte offset returned by +** wx_sqlite3_error_offset() assumes that the input SQL is UTF8. +** ^If the most recent error does not reference a specific token in the input +** SQL, then the wx_sqlite3_error_offset() function returns -1. +** ** When the serialized [threading mode] is in use, it might be the ** case that a second error occurs on a separate thread in between ** the time of the first error and the call to these interfaces. @@ -3796,6 +3979,7 @@ SQLITE_API int wx_sqlite3_extended_errcode(wx_sqlite3 *db); SQLITE_API const char *wx_sqlite3_errmsg(wx_sqlite3*); SQLITE_API const void *wx_sqlite3_errmsg16(wx_sqlite3*); SQLITE_API const char *wx_sqlite3_errstr(int); +SQLITE_API int wx_sqlite3_error_offset(wx_sqlite3 *db); /* ** CAPI3REF: Prepared Statement Object @@ -4153,12 +4337,17 @@ SQLITE_API int wx_sqlite3_prepare16_v3( ** are managed by SQLite and are automatically freed when the prepared ** statement is finalized. ** ^The string returned by wx_sqlite3_expanded_sql(P), on the other hand, -** is obtained from [wx_sqlite3_malloc()] and must be free by the application +** is obtained from [wx_sqlite3_malloc()] and must be freed by the application ** by passing it to [wx_sqlite3_free()]. +** +** ^The wx_sqlite3_normalized_sql() interface is only available if +** the [SQLITE_ENABLE_NORMALIZE] compile-time option is defined. */ SQLITE_API const char *wx_sqlite3_sql(wx_sqlite3_stmt *pStmt); SQLITE_API char *wx_sqlite3_expanded_sql(wx_sqlite3_stmt *pStmt); +#ifdef SQLITE_ENABLE_NORMALIZE SQLITE_API const char *wx_sqlite3_normalized_sql(wx_sqlite3_stmt *pStmt); +#endif /* ** CAPI3REF: Determine If An SQL Statement Writes The Database @@ -4193,6 +4382,19 @@ SQLITE_API const char *wx_sqlite3_normalized_sql(wx_sqlite3_stmt *pStmt); ** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and ** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so ** wx_sqlite3_stmt_readonly() returns false for those commands. +** +** ^This routine returns false if there is any possibility that the +** statement might change the database file. ^A false return does +** not guarantee that the statement will change the database file. +** ^For example, an UPDATE statement might have a WHERE clause that +** makes it a no-op, but the wx_sqlite3_stmt_readonly() result would still +** be false. ^Similarly, a CREATE TABLE IF NOT EXISTS statement is a +** read-only no-op if the table already exists, but +** wx_sqlite3_stmt_readonly() still returns false for such a statement. +** +** ^If prepared statement X is an [EXPLAIN] or [EXPLAIN QUERY PLAN] +** statement, then wx_sqlite3_stmt_readonly(X) returns the same value as +** if the EXPLAIN or EXPLAIN QUERY PLAN prefix were omitted. */ SQLITE_API int wx_sqlite3_stmt_readonly(wx_sqlite3_stmt *pStmt); @@ -4261,6 +4463,8 @@ SQLITE_API int wx_sqlite3_stmt_busy(wx_sqlite3_stmt*); ** ** ^The wx_sqlite3_value objects that are passed as parameters into the ** implementation of [application-defined SQL functions] are protected. +** ^The wx_sqlite3_value objects returned by [wx_sqlite3_vtab_rhs_value()] +** are protected. ** ^The wx_sqlite3_value object returned by ** [wx_sqlite3_column_value()] is unprotected. ** Unprotected wx_sqlite3_value objects may only be used as arguments @@ -4362,18 +4566,22 @@ typedef struct wx_sqlite3_context wx_sqlite3_context; ** contain embedded NULs. The result of expressions involving strings ** with embedded NULs is undefined. ** -** ^The fifth argument to the BLOB and string binding interfaces -** is a destructor used to dispose of the BLOB or -** string after SQLite has finished with it. ^The destructor is called -** to dispose of the BLOB or string even if the call to the bind API fails, -** except the destructor is not called if the third parameter is a NULL -** pointer or the fourth parameter is negative. -** ^If the fifth argument is -** the special value [SQLITE_STATIC], then SQLite assumes that the -** information is in static, unmanaged space and does not need to be freed. -** ^If the fifth argument has the value [SQLITE_TRANSIENT], then -** SQLite makes its own private copy of the data immediately, before -** the wx_sqlite3_bind_*() routine returns. +** ^The fifth argument to the BLOB and string binding interfaces controls +** or indicates the lifetime of the object referenced by the third parameter. +** These three options exist: +** ^ (1) A destructor to dispose of the BLOB or string after SQLite has finished +** with it may be passed. ^It is called to dispose of the BLOB or string even +** if the call to the bind API fails, except the destructor is not called if +** the third parameter is a NULL pointer or the fourth parameter is negative. +** ^ (2) The special constant, [SQLITE_STATIC], may be passsed to indicate that +** the application remains responsible for disposing of the object. ^In this +** case, the object and the provided pointer to it must remain valid until +** either the prepared statement is finalized or the same SQL parameter is +** bound to something else, whichever occurs sooner. +** ^ (3) The constant, [SQLITE_TRANSIENT], may be passed to indicate that the +** object is to be copied prior to the return from wx_sqlite3_bind_*(). ^The +** object and pointer to it must remain valid until then. ^SQLite will then +** manage the lifetime of its private copy. ** ** ^The sixth argument to wx_sqlite3_bind_text64() must be one of ** [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE] @@ -4878,6 +5086,10 @@ SQLITE_API int wx_sqlite3_data_count(wx_sqlite3_stmt *pStmt); ** even empty strings, are always zero-terminated. ^The return ** value from wx_sqlite3_column_blob() for a zero-length BLOB is a NULL pointer. ** +** ^Strings returned by wx_sqlite3_column_text16() always have the endianness +** which is native to the platform, regardless of the text encoding set +** for the database. +** ** <b>Warning:</b> ^The object returned by [wx_sqlite3_column_value()] is an ** [unprotected wx_sqlite3_value] object. In a multithreaded environment, ** an unprotected wx_sqlite3_value object may only be used safely with @@ -4891,7 +5103,7 @@ SQLITE_API int wx_sqlite3_data_count(wx_sqlite3_stmt *pStmt); ** [application-defined SQL functions] or [virtual tables], not within ** top-level application code. ** -** The these routines may attempt to convert the datatype of the result. +** 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, [wx_sqlite3_snprintf()] is used internally to perform the ** conversion automatically. ^(The following table details the conversions @@ -4916,7 +5128,7 @@ SQLITE_API int wx_sqlite3_data_count(wx_sqlite3_stmt *pStmt); ** <tr><td> TEXT <td> BLOB <td> No change ** <tr><td> BLOB <td> INTEGER <td> [CAST] to INTEGER ** <tr><td> BLOB <td> FLOAT <td> [CAST] to REAL -** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed +** <tr><td> BLOB <td> TEXT <td> [CAST] to TEXT, ensure zero terminator ** </table> ** </blockquote>)^ ** @@ -5115,7 +5327,6 @@ SQLITE_API int wx_sqlite3_reset(wx_sqlite3_stmt *pStmt); ** within VIEWs, TRIGGERs, CHECK constraints, generated column expressions, ** index expressions, or the WHERE clause of partial indexes. ** -** <span style="background-color:#ffff90;"> ** For best security, the [SQLITE_DIRECTONLY] flag is recommended for ** all application-defined SQL functions that do not need to be ** used inside of triggers, view, CHECK constraints, or other elements of @@ -5125,7 +5336,6 @@ SQLITE_API int wx_sqlite3_reset(wx_sqlite3_stmt *pStmt); ** a database file to include invocations of the function with parameters ** chosen by the attacker, which the application will then execute when ** the database file is opened and read. -** </span> ** ** ^(The fifth parameter is an arbitrary pointer. The implementation of the ** function can gain access to this pointer using [wx_sqlite3_user_data()].)^ @@ -5261,10 +5471,21 @@ SQLITE_API int wx_sqlite3_create_window_function( ** from top-level SQL, and cannot be used in VIEWs or TRIGGERs nor in ** schema structures such as [CHECK constraints], [DEFAULT clauses], ** [expression indexes], [partial indexes], or [generated columns]. -** The SQLITE_DIRECTONLY flags is a security feature which is recommended -** for all [application-defined SQL functions], and especially for functions -** that have side-effects or that could potentially leak sensitive -** information. +** <p> +** The SQLITE_DIRECTONLY flag is recommended for any +** [application-defined SQL function] +** that has side-effects or that could potentially leak sensitive information. +** This will prevent attacks in which an application is tricked +** into using a database file that has had its schema surreptiously +** modified to invoke the application-defined function in ways that are +** harmful. +** <p> +** Some people say it is good practice to set SQLITE_DIRECTONLY on all +** [application-defined SQL functions], regardless of whether or not they +** are security sensitive, as doing so prevents those functions from being used +** inside of the database schema, and thus ensures that the database +** can be inspected and modified using generic tools (such as the [CLI]) +** that do not have access to the application-defined functions. ** </dd> ** ** [[SQLITE_INNOCUOUS]] <dt>SQLITE_INNOCUOUS</dt><dd> @@ -5471,6 +5692,28 @@ SQLITE_API int wx_sqlite3_value_nochange(wx_sqlite3_value*); SQLITE_API int wx_sqlite3_value_frombind(wx_sqlite3_value*); /* +** CAPI3REF: Report the internal text encoding state of an wx_sqlite3_value object +** METHOD: wx_sqlite3_value +** +** ^(The wx_sqlite3_value_encoding(X) interface returns one of [SQLITE_UTF8], +** [SQLITE_UTF16BE], or [SQLITE_UTF16LE] according to the current text encoding +** of the value X, assuming that X has type TEXT.)^ If wx_sqlite3_value_type(X) +** returns something other than SQLITE_TEXT, then the return value from +** wx_sqlite3_value_encoding(X) is meaningless. ^Calls to +** [wx_sqlite3_value_text(X)], [wx_sqlite3_value_text16(X)], [wx_sqlite3_value_text16be(X)], +** [wx_sqlite3_value_text16le(X)], [wx_sqlite3_value_bytes(X)], or +** [wx_sqlite3_value_bytes16(X)] might change the encoding of the value X and +** thus change the return from subsequent calls to wx_sqlite3_value_encoding(X). +** +** This routine is intended for used by applications that test and validate +** the SQLite implementation. This routine is inquiring about the opaque +** internal state of an [wx_sqlite3_value] object. Ordinary applications should +** not need to know what the internal state of an wx_sqlite3_value object is and +** hence should not need to use this interface. +*/ +SQLITE_API int wx_sqlite3_value_encoding(wx_sqlite3_value*); + +/* ** CAPI3REF: Finding The Subtype Of SQL Values ** METHOD: wx_sqlite3_value ** @@ -5490,7 +5733,8 @@ SQLITE_API unsigned int wx_sqlite3_value_subtype(wx_sqlite3_value*); ** object D and returns a pointer to that copy. ^The [wx_sqlite3_value] returned ** is a [protected wx_sqlite3_value] object even if the input is not. ** ^The wx_sqlite3_value_dup(V) interface returns NULL if V is NULL or if a -** memory allocation fails. +** memory allocation fails. ^If V is a [pointer value], then the result +** of wx_sqlite3_value_dup(V) is a NULL value. ** ** ^The wx_sqlite3_value_free(V) interface frees an [wx_sqlite3_value] object ** previously obtained from [wx_sqlite3_value_dup()]. ^If V is a NULL pointer @@ -5521,7 +5765,7 @@ SQLITE_API void wx_sqlite3_value_free(wx_sqlite3_value*); ** ** ^The wx_sqlite3_aggregate_context(C,N) routine returns a NULL pointer ** when first called if N is less than or equal to zero or if a memory -** allocate error occurs. +** allocation error occurs. ** ** ^(The amount of space allocated by wx_sqlite3_aggregate_context(C,N) is ** determined by the N parameter on first successful call. Changing the @@ -5726,9 +5970,10 @@ typedef void (*wx_sqlite3_destructor_type)(void*); ** of [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE]. ** ^SQLite takes the text result from the application from ** the 2nd parameter of the wx_sqlite3_result_text* interfaces. -** ^If the 3rd parameter to the wx_sqlite3_result_text* interfaces -** is negative, then SQLite takes result text from the 2nd parameter -** through the first zero character. +** ^If the 3rd parameter to any of the wx_sqlite3_result_text* interfaces +** other than wx_sqlite3_result_text64() is negative, then SQLite computes +** the string length itself by searching the 2nd parameter for the first +** zero character. ** ^If the 3rd parameter to the wx_sqlite3_result_text* interfaces ** is non-negative, then as many bytes (not characters) of the text ** pointed to by the 2nd parameter are taken as the application-defined @@ -6173,6 +6418,28 @@ SQLITE_API int wx_sqlite3_get_autocommit(wx_sqlite3*); SQLITE_API wx_sqlite3 *wx_sqlite3_db_handle(wx_sqlite3_stmt*); /* +** CAPI3REF: Return The Schema Name For A Database Connection +** METHOD: wx_sqlite3 +** +** ^The wx_sqlite3_db_name(D,N) interface returns a pointer to the schema name +** for the N-th database on database connection D, or a NULL pointer of N is +** out of range. An N value of 0 means the main database file. An N of 1 is +** the "temp" schema. Larger values of N correspond to various ATTACH-ed +** databases. +** +** Space to hold the string that is returned by wx_sqlite3_db_name() is managed +** by SQLite itself. The string might be deallocated by any operation that +** changes the schema, including [ATTACH] or [DETACH] or calls to +** [wx_sqlite3_serialize()] or [wx_sqlite3_deserialize()], even operations that +** occur on a different thread. Applications that need to +** remember the string long-term should make their own copy. Applications that +** are accessing the same database connection simultaneously on multiple +** threads should mutex-protect calls to this API and should make their own +** private copy of the result prior to releasing the mutex. +*/ +SQLITE_API const char *wx_sqlite3_db_name(wx_sqlite3 *db, int N); + +/* ** CAPI3REF: Return The Filename For A Database Connection ** METHOD: wx_sqlite3 ** @@ -6202,7 +6469,7 @@ SQLITE_API wx_sqlite3 *wx_sqlite3_db_handle(wx_sqlite3_stmt*); ** <li> [wx_sqlite3_filename_wal()] ** </ul> */ -SQLITE_API const char *wx_sqlite3_db_filename(wx_sqlite3 *db, const char *zDbName); +SQLITE_API wx_sqlite3_filename wx_sqlite3_db_filename(wx_sqlite3 *db, const char *zDbName); /* ** CAPI3REF: Determine if a database is read-only @@ -6332,6 +6599,72 @@ SQLITE_API void *wx_sqlite3_commit_hook(wx_sqlite3*, int(*)(void*), void*); SQLITE_API void *wx_sqlite3_rollback_hook(wx_sqlite3*, void(*)(void *), void*); /* +** CAPI3REF: Autovacuum Compaction Amount Callback +** METHOD: wx_sqlite3 +** +** ^The wx_sqlite3_autovacuum_pages(D,C,P,X) interface registers a callback +** function C that is invoked prior to each autovacuum of the database +** file. ^The callback is passed a copy of the generic data pointer (P), +** the schema-name of the attached database that is being autovacuumed, +** the size of the database file in pages, the number of free pages, +** and the number of bytes per page, respectively. The callback should +** return the number of free pages that should be removed by the +** autovacuum. ^If the callback returns zero, then no autovacuum happens. +** ^If the value returned is greater than or equal to the number of +** free pages, then a complete autovacuum happens. +** +** <p>^If there are multiple ATTACH-ed database files that are being +** modified as part of a transaction commit, then the autovacuum pages +** callback is invoked separately for each file. +** +** <p><b>The callback is not reentrant.</b> The callback function should +** not attempt to invoke any other SQLite interface. If it does, bad +** things may happen, including segmentation faults and corrupt database +** files. The callback function should be a simple function that +** does some arithmetic on its input parameters and returns a result. +** +** ^The X parameter to wx_sqlite3_autovacuum_pages(D,C,P,X) is an optional +** destructor for the P parameter. ^If X is not NULL, then X(P) is +** invoked whenever the database connection closes or when the callback +** is overwritten by another invocation of wx_sqlite3_autovacuum_pages(). +** +** <p>^There is only one autovacuum pages callback per database connection. +** ^Each call to the wx_sqlite3_autovacuum_pages() interface overrides all +** previous invocations for that database connection. ^If the callback +** argument (C) to wx_sqlite3_autovacuum_pages(D,C,P,X) is a NULL pointer, +** then the autovacuum steps callback is cancelled. The return value +** from wx_sqlite3_autovacuum_pages() is normally SQLITE_OK, but might +** be some other error code if something goes wrong. The current +** implementation will only return SQLITE_OK or SQLITE_MISUSE, but other +** return codes might be added in future releases. +** +** <p>If no autovacuum pages callback is specified (the usual case) or +** a NULL pointer is provided for the callback, +** then the default behavior is to vacuum all free pages. So, in other +** words, the default behavior is the same as if the callback function +** were something like this: +** +** <blockquote><pre> +** unsigned int demonstration_autovac_pages_callback( +** void *pClientData, +** const char *zSchema, +** unsigned int nDbPage, +** unsigned int nFreePage, +** unsigned int nBytePerPage +** ){ +** return nFreePage; +** } +** </pre></blockquote> +*/ +SQLITE_API int wx_sqlite3_autovacuum_pages( + wx_sqlite3 *db, + unsigned int(*)(void*,const char*,unsigned int,unsigned int,unsigned int), + void*, + void(*)(void*) +); + + +/* ** CAPI3REF: Data Change Notification Callbacks ** METHOD: wx_sqlite3 ** @@ -6394,6 +6727,11 @@ SQLITE_API void *wx_sqlite3_update_hook( ** to the same database. Sharing is enabled if the argument is true ** and disabled if the argument is false.)^ ** +** This interface is omitted if SQLite is compiled with +** [-DSQLITE_OMIT_SHARED_CACHE]. The [-DSQLITE_OMIT_SHARED_CACHE] +** compile-time option is recommended because the +** [use of shared cache mode is discouraged]. +** ** ^Cache sharing is enabled and disabled for an entire process. ** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]). ** In prior versions of SQLite, @@ -6492,7 +6830,7 @@ SQLITE_API int wx_sqlite3_db_release_memory(wx_sqlite3*); ** ^The soft heap limit may not be greater than the hard heap limit. ** ^If the hard heap limit is enabled and if wx_sqlite3_soft_heap_limit(N) ** is invoked with a value of N that is greater than the hard heap limit, -** the the soft heap limit is set to the value of the hard heap limit. +** the soft heap limit is set to the value of the hard heap limit. ** ^The soft heap limit is automatically enabled whenever the hard heap ** limit is enabled. ^When wx_sqlite3_hard_heap_limit64(N) is invoked and ** the soft heap limit is outside the range of 1..N, then the soft heap @@ -6754,15 +7092,6 @@ SQLITE_API int wx_sqlite3_cancel_auto_extension(void(*xEntryPoint)(void)); SQLITE_API void wx_sqlite3_reset_auto_extension(void); /* -** The interface to the virtual-table mechanism is currently considered -** to be experimental. The interface might change in incompatible ways. -** If this is a problem for you, do not use the interface at this time. -** -** When the virtual-table mechanism stabilizes, we will declare the -** interface fixed, support it indefinitely, and remove this comment. -*/ - -/* ** Structures used by the virtual table interface */ typedef struct wx_sqlite3_vtab wx_sqlite3_vtab; @@ -6880,10 +7209,10 @@ struct wx_sqlite3_module { ** when the omit flag is true there is no guarantee that the constraint will ** not be checked again using byte code.)^ ** -** ^The idxNum and idxPtr values are recorded and passed into the +** ^The idxNum and idxStr values are recorded and passed into the ** [xFilter] method. -** ^[wx_sqlite3_free()] is used to free idxPtr if and only if -** needToFreeIdxPtr is true. +** ^[wx_sqlite3_free()] is used to free idxStr if and only if +** needToFreeIdxStr is true. ** ** ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in ** the correct order to satisfy the ORDER BY clause so that no separate @@ -6972,24 +7301,56 @@ struct wx_sqlite3_index_info { ** ** These macros define the allowed values for the ** [wx_sqlite3_index_info].aConstraint[].op field. Each value represents -** an operator that is part of a constraint term in the wHERE clause of +** an operator that is part of a constraint term in the WHERE clause of ** a query that uses a [virtual table]. -*/ -#define SQLITE_INDEX_CONSTRAINT_EQ 2 -#define SQLITE_INDEX_CONSTRAINT_GT 4 -#define SQLITE_INDEX_CONSTRAINT_LE 8 -#define SQLITE_INDEX_CONSTRAINT_LT 16 -#define SQLITE_INDEX_CONSTRAINT_GE 32 -#define SQLITE_INDEX_CONSTRAINT_MATCH 64 -#define SQLITE_INDEX_CONSTRAINT_LIKE 65 -#define SQLITE_INDEX_CONSTRAINT_GLOB 66 -#define SQLITE_INDEX_CONSTRAINT_REGEXP 67 -#define SQLITE_INDEX_CONSTRAINT_NE 68 -#define SQLITE_INDEX_CONSTRAINT_ISNOT 69 -#define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70 -#define SQLITE_INDEX_CONSTRAINT_ISNULL 71 -#define SQLITE_INDEX_CONSTRAINT_IS 72 -#define SQLITE_INDEX_CONSTRAINT_FUNCTION 150 +** +** ^The left-hand operand of the operator is given by the corresponding +** aConstraint[].iColumn field. ^An iColumn of -1 indicates the left-hand +** operand is the rowid. +** The SQLITE_INDEX_CONSTRAINT_LIMIT and SQLITE_INDEX_CONSTRAINT_OFFSET +** operators have no left-hand operand, and so for those operators the +** corresponding aConstraint[].iColumn is meaningless and should not be +** used. +** +** All operator values from SQLITE_INDEX_CONSTRAINT_FUNCTION through +** value 255 are reserved to represent functions that are overloaded +** by the [xFindFunction|xFindFunction method] of the virtual table +** implementation. +** +** The right-hand operands for each constraint might be accessible using +** the [wx_sqlite3_vtab_rhs_value()] interface. Usually the right-hand +** operand is only available if it appears as a single constant literal +** in the input SQL. If the right-hand operand is another column or an +** expression (even a constant expression) or a parameter, then the +** wx_sqlite3_vtab_rhs_value() probably will not be able to extract it. +** ^The SQLITE_INDEX_CONSTRAINT_ISNULL and +** SQLITE_INDEX_CONSTRAINT_ISNOTNULL operators have no right-hand operand +** and hence calls to wx_sqlite3_vtab_rhs_value() for those operators will +** always return SQLITE_NOTFOUND. +** +** The collating sequence to be used for comparison can be found using +** the [wx_sqlite3_vtab_collation()] interface. For most real-world virtual +** tables, the collating sequence of constraints does not matter (for example +** because the constraints are numeric) and so the wx_sqlite3_vtab_collation() +** interface is not commonly needed. +*/ +#define SQLITE_INDEX_CONSTRAINT_EQ 2 +#define SQLITE_INDEX_CONSTRAINT_GT 4 +#define SQLITE_INDEX_CONSTRAINT_LE 8 +#define SQLITE_INDEX_CONSTRAINT_LT 16 +#define SQLITE_INDEX_CONSTRAINT_GE 32 +#define SQLITE_INDEX_CONSTRAINT_MATCH 64 +#define SQLITE_INDEX_CONSTRAINT_LIKE 65 +#define SQLITE_INDEX_CONSTRAINT_GLOB 66 +#define SQLITE_INDEX_CONSTRAINT_REGEXP 67 +#define SQLITE_INDEX_CONSTRAINT_NE 68 +#define SQLITE_INDEX_CONSTRAINT_ISNOT 69 +#define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70 +#define SQLITE_INDEX_CONSTRAINT_ISNULL 71 +#define SQLITE_INDEX_CONSTRAINT_IS 72 +#define SQLITE_INDEX_CONSTRAINT_LIMIT 73 +#define SQLITE_INDEX_CONSTRAINT_OFFSET 74 +#define SQLITE_INDEX_CONSTRAINT_FUNCTION 150 /* ** CAPI3REF: Register A Virtual Table Implementation @@ -7018,7 +7379,7 @@ struct wx_sqlite3_index_info { ** destructor. ** ** ^If the third parameter (the pointer to the wx_sqlite3_module object) is -** NULL then no new module is create and any existing modules with the +** NULL then no new module is created and any existing modules with the ** same name are dropped. ** ** See also: [wx_sqlite3_drop_modules()] @@ -7131,16 +7492,6 @@ SQLITE_API int wx_sqlite3_declare_vtab(wx_sqlite3*, const char *zSQL); SQLITE_API int wx_sqlite3_overload_function(wx_sqlite3*, const char *zFuncName, int nArg); /* -** The interface to the virtual-table mechanism defined above (back up -** to a comment remarkably similar to this one) is currently considered -** to be experimental. The interface might change in incompatible ways. -** If this is a problem for you, do not use the interface at this time. -** -** When the virtual-table mechanism stabilizes, we will declare the -** interface fixed, support it indefinitely, and remove this comment. -*/ - -/* ** CAPI3REF: A Handle To An Open BLOB ** KEYWORDS: {BLOB handle} {BLOB handles} ** @@ -7793,7 +8144,9 @@ SQLITE_API int wx_sqlite3_test_control(int op, ...); #define SQLITE_TESTCTRL_EXTRA_SCHEMA_CHECKS 29 #define SQLITE_TESTCTRL_SEEK_COUNT 30 #define SQLITE_TESTCTRL_TRACEFLAGS 31 -#define SQLITE_TESTCTRL_LAST 31 /* Largest TESTCTRL */ +#define SQLITE_TESTCTRL_TUNE 32 +#define SQLITE_TESTCTRL_LOGEST 33 +#define SQLITE_TESTCTRL_LAST 33 /* Largest TESTCTRL */ /* ** CAPI3REF: SQL Keyword Checking @@ -8316,6 +8669,16 @@ SQLITE_API int wx_sqlite3_stmt_status(wx_sqlite3_stmt*, int op,int resetFlg); ** The counter is incremented on the first [wx_sqlite3_step()] call of each ** cycle. ** +** [[SQLITE_STMTSTATUS_FILTER_MISS]] +** [[SQLITE_STMTSTATUS_FILTER HIT]] +** <dt>SQLITE_STMTSTATUS_FILTER_HIT<br> +** SQLITE_STMTSTATUS_FILTER_MISS</dt> +** <dd>^SQLITE_STMTSTATUS_FILTER_HIT is the number of times that a join +** step was bypassed because a Bloom filter returned not-found. The +** corresponding SQLITE_STMTSTATUS_FILTER_MISS value is the number of +** times that the Bloom filter returned a find, and thus the join step +** had to be processed as normal. +** ** [[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 @@ -8330,6 +8693,8 @@ SQLITE_API int wx_sqlite3_stmt_status(wx_sqlite3_stmt*, int op,int resetFlg); #define SQLITE_STMTSTATUS_VM_STEP 4 #define SQLITE_STMTSTATUS_REPREPARE 5 #define SQLITE_STMTSTATUS_RUN 6 +#define SQLITE_STMTSTATUS_FILTER_MISS 7 +#define SQLITE_STMTSTATUS_FILTER_HIT 8 #define SQLITE_STMTSTATUS_MEMUSED 99 /* @@ -8741,7 +9106,7 @@ typedef struct wx_sqlite3_backup wx_sqlite3_backup; ** if the application incorrectly accesses the destination [database connection] ** and so no error code is reported, but the operations may malfunction ** nevertheless. Use of the destination database connection while a -** backup is in progress might also also cause a mutex deadlock. +** backup is in progress might also cause a mutex deadlock. ** ** If running in [shared cache mode], the application must ** guarantee that the shared cache used by the destination database @@ -8993,8 +9358,9 @@ SQLITE_API void wx_sqlite3_log(int iErrCode, const char *zFormat, ...); ** ** A single database handle may have at most a single write-ahead log callback ** registered at one time. ^Calling [wx_sqlite3_wal_hook()] replaces any -** previously registered write-ahead log callback. ^Note that the -** [wx_sqlite3_wal_autocheckpoint()] interface and the +** previously registered write-ahead log callback. ^The return value is +** a copy of the third parameter from the previous call, if any, or 0. +** ^Note that the [wx_sqlite3_wal_autocheckpoint()] interface and the ** [wal_autocheckpoint pragma] both invoke [wx_sqlite3_wal_hook()] and will ** overwrite any prior [wx_sqlite3_wal_hook()] settings. */ @@ -9168,7 +9534,7 @@ SQLITE_API int wx_sqlite3_wal_checkpoint_v2( */ #define SQLITE_CHECKPOINT_PASSIVE 0 /* Do as much as possible w/o blocking */ #define SQLITE_CHECKPOINT_FULL 1 /* Wait for writers, then checkpoint */ -#define SQLITE_CHECKPOINT_RESTART 2 /* Like FULL but wait for for readers */ +#define SQLITE_CHECKPOINT_RESTART 2 /* Like FULL but wait for readers */ #define SQLITE_CHECKPOINT_TRUNCATE 3 /* Like RESTART but also truncate WAL */ /* @@ -9297,18 +9663,274 @@ SQLITE_API int wx_sqlite3_vtab_nochange(wx_sqlite3_context*); /* ** CAPI3REF: Determine The Collation For a Virtual Table Constraint +** METHOD: wx_sqlite3_index_info ** ** This function may only be called from within a call to the [xBestIndex] -** method of a [virtual table]. +** method of a [virtual table]. This function returns a pointer to a string +** that is the name of the appropriate collation sequence to use for text +** comparisons on the constraint identified by its arguments. +** +** The first argument must be the pointer to the [wx_sqlite3_index_info] object +** that is the first parameter to the xBestIndex() method. The second argument +** must be an index into the aConstraint[] array belonging to the +** wx_sqlite3_index_info structure passed to xBestIndex. ** -** The first argument must be the wx_sqlite3_index_info object that is the -** first parameter to the xBestIndex() method. The second argument must be -** an index into the aConstraint[] array belonging to the wx_sqlite3_index_info -** structure passed to xBestIndex. This function returns a pointer to a buffer -** containing the name of the collation sequence for the corresponding -** constraint. +** Important: +** The first parameter must be the same pointer that is passed into the +** xBestMethod() method. The first parameter may not be a pointer to a +** different [wx_sqlite3_index_info] object, even an exact copy. +** +** The return value is computed as follows: +** +** <ol> +** <li><p> If the constraint comes from a WHERE clause expression that contains +** a [COLLATE operator], then the name of the collation specified by +** that COLLATE operator is returned. +** <li><p> If there is no COLLATE operator, but the column that is the subject +** of the constraint specifies an alternative collating sequence via +** a [COLLATE clause] on the column definition within the CREATE TABLE +** statement that was passed into [wx_sqlite3_declare_vtab()], then the +** name of that alternative collating sequence is returned. +** <li><p> Otherwise, "BINARY" is returned. +** </ol> */ -SQLITE_API SQLITE_EXPERIMENTAL const char *wx_sqlite3_vtab_collation(wx_sqlite3_index_info*,int); +SQLITE_API const char *wx_sqlite3_vtab_collation(wx_sqlite3_index_info*,int); + +/* +** CAPI3REF: Determine if a virtual table query is DISTINCT +** METHOD: wx_sqlite3_index_info +** +** This API may only be used from within an [xBestIndex|xBestIndex method] +** of a [virtual table] implementation. The result of calling this +** interface from outside of xBestIndex() is undefined and probably harmful. +** +** ^The wx_sqlite3_vtab_distinct() interface returns an integer between 0 and +** 3. The integer returned by wx_sqlite3_vtab_distinct() +** gives the virtual table additional information about how the query +** planner wants the output to be ordered. As long as the virtual table +** can meet the ordering requirements of the query planner, it may set +** the "orderByConsumed" flag. +** +** <ol><li value="0"><p> +** ^If the wx_sqlite3_vtab_distinct() interface returns 0, that means +** that the query planner needs the virtual table to return all rows in the +** sort order defined by the "nOrderBy" and "aOrderBy" fields of the +** [wx_sqlite3_index_info] object. This is the default expectation. If the +** virtual table outputs all rows in sorted order, then it is always safe for +** the xBestIndex method to set the "orderByConsumed" flag, regardless of +** the return value from wx_sqlite3_vtab_distinct(). +** <li value="1"><p> +** ^(If the wx_sqlite3_vtab_distinct() interface returns 1, that means +** that the query planner does not need the rows to be returned in sorted order +** as long as all rows with the same values in all columns identified by the +** "aOrderBy" field are adjacent.)^ This mode is used when the query planner +** is doing a GROUP BY. +** <li value="2"><p> +** ^(If the wx_sqlite3_vtab_distinct() interface returns 2, that means +** that the query planner does not need the rows returned in any particular +** order, as long as rows with the same values in all "aOrderBy" columns +** are adjacent.)^ ^(Furthermore, only a single row for each particular +** combination of values in the columns identified by the "aOrderBy" field +** needs to be returned.)^ ^It is always ok for two or more rows with the same +** values in all "aOrderBy" columns to be returned, as long as all such rows +** are adjacent. ^The virtual table may, if it chooses, omit extra rows +** that have the same value for all columns identified by "aOrderBy". +** ^However omitting the extra rows is optional. +** This mode is used for a DISTINCT query. +** <li value="3"><p> +** ^(If the wx_sqlite3_vtab_distinct() interface returns 3, that means +** that the query planner needs only distinct rows but it does need the +** rows to be sorted.)^ ^The virtual table implementation is free to omit +** rows that are identical in all aOrderBy columns, if it wants to, but +** it is not required to omit any rows. This mode is used for queries +** that have both DISTINCT and ORDER BY clauses. +** </ol> +** +** ^For the purposes of comparing virtual table output values to see if the +** values are same value for sorting purposes, two NULL values are considered +** to be the same. In other words, the comparison operator is "IS" +** (or "IS NOT DISTINCT FROM") and not "==". +** +** If a virtual table implementation is unable to meet the requirements +** specified above, then it must not set the "orderByConsumed" flag in the +** [wx_sqlite3_index_info] object or an incorrect answer may result. +** +** ^A virtual table implementation is always free to return rows in any order +** it wants, as long as the "orderByConsumed" flag is not set. ^When the +** the "orderByConsumed" flag is unset, the query planner will add extra +** [bytecode] to ensure that the final results returned by the SQL query are +** ordered correctly. The use of the "orderByConsumed" flag and the +** wx_sqlite3_vtab_distinct() interface is merely an optimization. ^Careful +** use of the wx_sqlite3_vtab_distinct() interface and the "orderByConsumed" +** flag might help queries against a virtual table to run faster. Being +** overly aggressive and setting the "orderByConsumed" flag when it is not +** valid to do so, on the other hand, might cause SQLite to return incorrect +** results. +*/ +SQLITE_API int wx_sqlite3_vtab_distinct(wx_sqlite3_index_info*); + +/* +** CAPI3REF: Identify and handle IN constraints in xBestIndex +** +** This interface may only be used from within an +** [xBestIndex|xBestIndex() method] of a [virtual table] implementation. +** The result of invoking this interface from any other context is +** undefined and probably harmful. +** +** ^(A constraint on a virtual table of the form +** "[IN operator|column IN (...)]" is +** communicated to the xBestIndex method as a +** [SQLITE_INDEX_CONSTRAINT_EQ] constraint.)^ If xBestIndex wants to use +** this constraint, it must set the corresponding +** aConstraintUsage[].argvIndex to a postive integer. ^(Then, under +** the usual mode of handling IN operators, SQLite generates [bytecode] +** that invokes the [xFilter|xFilter() method] once for each value +** on the right-hand side of the IN operator.)^ Thus the virtual table +** only sees a single value from the right-hand side of the IN operator +** at a time. +** +** In some cases, however, it would be advantageous for the virtual +** table to see all values on the right-hand of the IN operator all at +** once. The wx_sqlite3_vtab_in() interfaces facilitates this in two ways: +** +** <ol> +** <li><p> +** ^A call to wx_sqlite3_vtab_in(P,N,-1) will return true (non-zero) +** if and only if the [wx_sqlite3_index_info|P->aConstraint][N] constraint +** is an [IN operator] that can be processed all at once. ^In other words, +** wx_sqlite3_vtab_in() with -1 in the third argument is a mechanism +** by which the virtual table can ask SQLite if all-at-once processing +** of the IN operator is even possible. +** +** <li><p> +** ^A call to wx_sqlite3_vtab_in(P,N,F) with F==1 or F==0 indicates +** to SQLite that the virtual table does or does not want to process +** the IN operator all-at-once, respectively. ^Thus when the third +** parameter (F) is non-negative, this interface is the mechanism by +** which the virtual table tells SQLite how it wants to process the +** IN operator. +** </ol> +** +** ^The wx_sqlite3_vtab_in(P,N,F) interface can be invoked multiple times +** within the same xBestIndex method call. ^For any given P,N pair, +** the return value from wx_sqlite3_vtab_in(P,N,F) will always be the same +** within the same xBestIndex call. ^If the interface returns true +** (non-zero), that means that the constraint is an IN operator +** that can be processed all-at-once. ^If the constraint is not an IN +** operator or cannot be processed all-at-once, then the interface returns +** false. +** +** ^(All-at-once processing of the IN operator is selected if both of the +** following conditions are met: +** +** <ol> +** <li><p> The P->aConstraintUsage[N].argvIndex value is set to a positive +** integer. This is how the virtual table tells SQLite that it wants to +** use the N-th constraint. +** +** <li><p> The last call to wx_sqlite3_vtab_in(P,N,F) for which F was +** non-negative had F>=1. +** </ol>)^ +** +** ^If either or both of the conditions above are false, then SQLite uses +** the traditional one-at-a-time processing strategy for the IN constraint. +** ^If both conditions are true, then the argvIndex-th parameter to the +** xFilter method will be an [wx_sqlite3_value] that appears to be NULL, +** but which can be passed to [wx_sqlite3_vtab_in_first()] and +** [wx_sqlite3_vtab_in_next()] to find all values on the right-hand side +** of the IN constraint. +*/ +SQLITE_API int wx_sqlite3_vtab_in(wx_sqlite3_index_info*, int iCons, int bHandle); + +/* +** CAPI3REF: Find all elements on the right-hand side of an IN constraint. +** +** These interfaces are only useful from within the +** [xFilter|xFilter() method] of a [virtual table] implementation. +** The result of invoking these interfaces from any other context +** is undefined and probably harmful. +** +** The X parameter in a call to wx_sqlite3_vtab_in_first(X,P) or +** wx_sqlite3_vtab_in_next(X,P) should be one of the parameters to the +** xFilter method which invokes these routines, and specifically +** a parameter that was previously selected for all-at-once IN constraint +** processing use the [wx_sqlite3_vtab_in()] interface in the +** [xBestIndex|xBestIndex method]. ^(If the X parameter is not +** an xFilter argument that was selected for all-at-once IN constraint +** processing, then these routines return [SQLITE_ERROR].)^ +** +** ^(Use these routines to access all values on the right-hand side +** of the IN constraint using code like the following: +** +** <blockquote><pre> +** for(rc=wx_sqlite3_vtab_in_first(pList, &pVal); +** rc==SQLITE_OK && pVal; +** rc=wx_sqlite3_vtab_in_next(pList, &pVal) +** ){ +** // do something with pVal +** } +** if( rc!=SQLITE_OK ){ +** // an error has occurred +** } +** </pre></blockquote>)^ +** +** ^On success, the wx_sqlite3_vtab_in_first(X,P) and wx_sqlite3_vtab_in_next(X,P) +** routines return SQLITE_OK and set *P to point to the first or next value +** on the RHS of the IN constraint. ^If there are no more values on the +** right hand side of the IN constraint, then *P is set to NULL and these +** routines return [SQLITE_DONE]. ^The return value might be +** some other value, such as SQLITE_NOMEM, in the event of a malfunction. +** +** The *ppOut values returned by these routines are only valid until the +** next call to either of these routines or until the end of the xFilter +** method from which these routines were called. If the virtual table +** implementation needs to retain the *ppOut values for longer, it must make +** copies. The *ppOut values are [protected wx_sqlite3_value|protected]. +*/ +SQLITE_API int wx_sqlite3_vtab_in_first(wx_sqlite3_value *pVal, wx_sqlite3_value **ppOut); +SQLITE_API int wx_sqlite3_vtab_in_next(wx_sqlite3_value *pVal, wx_sqlite3_value **ppOut); + +/* +** CAPI3REF: Constraint values in xBestIndex() +** METHOD: wx_sqlite3_index_info +** +** This API may only be used from within the [xBestIndex|xBestIndex method] +** of a [virtual table] implementation. The result of calling this interface +** from outside of an xBestIndex method are undefined and probably harmful. +** +** ^When the wx_sqlite3_vtab_rhs_value(P,J,V) interface is invoked from within +** the [xBestIndex] method of a [virtual table] implementation, with P being +** a copy of the [wx_sqlite3_index_info] object pointer passed into xBestIndex and +** J being a 0-based index into P->aConstraint[], then this routine +** attempts to set *V to the value of the right-hand operand of +** that constraint if the right-hand operand is known. ^If the +** right-hand operand is not known, then *V is set to a NULL pointer. +** ^The wx_sqlite3_vtab_rhs_value(P,J,V) interface returns SQLITE_OK if +** and only if *V is set to a value. ^The wx_sqlite3_vtab_rhs_value(P,J,V) +** inteface returns SQLITE_NOTFOUND if the right-hand side of the J-th +** constraint is not available. ^The wx_sqlite3_vtab_rhs_value() interface +** can return an result code other than SQLITE_OK or SQLITE_NOTFOUND if +** something goes wrong. +** +** The wx_sqlite3_vtab_rhs_value() interface is usually only successful if +** the right-hand operand of a constraint is a literal value in the original +** SQL statement. If the right-hand operand is an expression or a reference +** to some other column or a [host parameter], then wx_sqlite3_vtab_rhs_value() +** will probably return [SQLITE_NOTFOUND]. +** +** ^(Some constraints, such as [SQLITE_INDEX_CONSTRAINT_ISNULL] and +** [SQLITE_INDEX_CONSTRAINT_ISNOTNULL], have no right-hand operand. For such +** constraints, wx_sqlite3_vtab_rhs_value() always returns SQLITE_NOTFOUND.)^ +** +** ^The [wx_sqlite3_value] object returned in *V is a protected wx_sqlite3_value +** and remains valid for the duration of the xBestIndex method call. +** ^When xBestIndex returns, the wx_sqlite3_value object returned by +** wx_sqlite3_vtab_rhs_value() is automatically deallocated. +** +** The "_rhs_" in the name of this routine is an abbreviation for +** "Right-Hand Side". +*/ +SQLITE_API int wx_sqlite3_vtab_rhs_value(wx_sqlite3_index_info*, int, wx_sqlite3_value **ppVal); /* ** CAPI3REF: Conflict resolution modes @@ -9340,6 +9962,10 @@ SQLITE_API SQLITE_EXPERIMENTAL const char *wx_sqlite3_vtab_collation(wx_sqlite3_ ** managed by the prepared statement S and will be automatically freed when ** S is finalized. ** +** Not all values are available for all query elements. When a value is +** not available, the output variable is set to -1 if the value is numeric, +** or to NULL if it is a string (SQLITE_SCANSTAT_NAME). +** ** <dl> ** [[SQLITE_SCANSTAT_NLOOP]] <dt>SQLITE_SCANSTAT_NLOOP</dt> ** <dd>^The [wx_sqlite3_int64] variable pointed to by the V parameter will be @@ -9367,12 +9993,24 @@ SQLITE_API SQLITE_EXPERIMENTAL const char *wx_sqlite3_vtab_collation(wx_sqlite3_ ** to a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN] ** description for the X-th loop. ** -** [[SQLITE_SCANSTAT_SELECTID]] <dt>SQLITE_SCANSTAT_SELECT</dt> +** [[SQLITE_SCANSTAT_SELECTID]] <dt>SQLITE_SCANSTAT_SELECTID</dt> ** <dd>^The "int" variable pointed to by the V parameter will be set to the -** "select-id" for the X-th loop. The select-id identifies which query or -** subquery the loop is part of. The main query has a select-id of zero. -** The select-id is the same value as is output in the first column -** of an [EXPLAIN QUERY PLAN] query. +** id for the X-th query plan element. The id value is unique within the +** statement. The select-id is the same value as is output in the first +** column of an [EXPLAIN QUERY PLAN] query. +** +** [[SQLITE_SCANSTAT_PARENTID]] <dt>SQLITE_SCANSTAT_PARENTID</dt> +** <dd>The "int" variable pointed to by the V parameter will be set to the +** the id of the parent of the current query element, if applicable, or +** to zero if the query element has no parent. This is the same value as +** returned in the second column of an [EXPLAIN QUERY PLAN] query. +** +** [[SQLITE_SCANSTAT_NCYCLE]] <dt>SQLITE_SCANSTAT_NCYCLE</dt> +** <dd>The wx_sqlite3_int64 output value is set to the number of cycles, +** according to the processor time-stamp counter, that elapsed while the +** query element was being processed. This value is not available for +** all query elements - if it is unavailable the output variable is +** set to -1. ** </dl> */ #define SQLITE_SCANSTAT_NLOOP 0 @@ -9381,12 +10019,14 @@ SQLITE_API SQLITE_EXPERIMENTAL const char *wx_sqlite3_vtab_collation(wx_sqlite3_ #define SQLITE_SCANSTAT_NAME 3 #define SQLITE_SCANSTAT_EXPLAIN 4 #define SQLITE_SCANSTAT_SELECTID 5 +#define SQLITE_SCANSTAT_PARENTID 6 +#define SQLITE_SCANSTAT_NCYCLE 7 /* ** CAPI3REF: Prepared Statement Scan Status ** METHOD: wx_sqlite3_stmt ** -** This interface returns information about the predicted and measured +** These interfaces return information about the predicted and measured ** performance for pStmt. Advanced applications can use this ** interface to compare the predicted and the measured performance and ** issue warnings and/or rerun [ANALYZE] if discrepancies are found. @@ -9397,19 +10037,25 @@ SQLITE_API SQLITE_EXPERIMENTAL const char *wx_sqlite3_vtab_collation(wx_sqlite3_ ** ** The "iScanStatusOp" parameter determines which status information to return. ** The "iScanStatusOp" must be one of the [scanstatus options] or the behavior -** of this interface is undefined. -** ^The requested measurement is written into a variable pointed to by -** the "pOut" parameter. -** Parameter "idx" identifies the specific loop to retrieve statistics for. -** Loops are numbered starting from zero. ^If idx is out of range - less than -** zero or greater than or equal to the total number of loops used to implement -** the statement - a non-zero value is returned and the variable that pOut -** points to is unchanged. -** -** ^Statistics might not be available for all loops in all statements. ^In cases -** where there exist loops with no available statistics, this function behaves -** as if the loop did not exist - it returns non-zero and leave the variable -** that pOut points to unchanged. +** of this interface is undefined. ^The requested measurement is written into +** a variable pointed to by the "pOut" parameter. +** +** The "flags" parameter must be passed a mask of flags. At present only +** one flag is defined - SQLITE_SCANSTAT_COMPLEX. If SQLITE_SCANSTAT_COMPLEX +** is specified, then status information is available for all elements +** of a query plan that are reported by "EXPLAIN QUERY PLAN" output. If +** SQLITE_SCANSTAT_COMPLEX is not specified, then only query plan elements +** that correspond to query loops (the "SCAN..." and "SEARCH..." elements of +** the EXPLAIN QUERY PLAN output) are available. Invoking API +** wx_sqlite3_stmt_scanstatus() is equivalent to calling +** wx_sqlite3_stmt_scanstatus_v2() with a zeroed flags parameter. +** +** Parameter "idx" identifies the specific query element to retrieve statistics +** for. Query elements are numbered starting from zero. A value of -1 may be +** to query for statistics regarding the entire query. ^If idx is out of range +** - less than -1 or greater than or equal to the total number of query +** elements used to implement the statement - a non-zero value is returned and +** the variable that pOut points to is unchanged. ** ** See also: [wx_sqlite3_stmt_scanstatus_reset()] */ @@ -9419,6 +10065,19 @@ SQLITE_API int wx_sqlite3_stmt_scanstatus( int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */ void *pOut /* Result written here */ ); +SQLITE_API int wx_sqlite3_stmt_scanstatus_v2( + wx_sqlite3_stmt *pStmt, /* Prepared statement for which info desired */ + int idx, /* Index of loop to report on */ + int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */ + int flags, /* Mask of flags defined below */ + void *pOut /* Result written here */ +); + +/* +** CAPI3REF: Prepared Statement Scan Status +** KEYWORDS: {scan status flags} +*/ +#define SQLITE_SCANSTAT_COMPLEX 0x0001 /* ** CAPI3REF: Zero Scan-Status Counters @@ -9509,6 +10168,10 @@ SQLITE_API int wx_sqlite3_db_cacheflush(wx_sqlite3*); ** function is not defined for operations on WITHOUT ROWID tables, or for ** DELETE operations on rowid tables. ** +** ^The wx_sqlite3_preupdate_hook(D,C,P) function returns the P argument from +** the previous call on the same [database connection] D, or NULL for +** the first call on D. +** ** The [wx_sqlite3_preupdate_old()], [wx_sqlite3_preupdate_new()], ** [wx_sqlite3_preupdate_count()], and [wx_sqlite3_preupdate_depth()] interfaces ** provide additional information about a preupdate event. These routines @@ -9545,6 +10208,15 @@ SQLITE_API int wx_sqlite3_db_cacheflush(wx_sqlite3*); ** triggers; or 2 for changes resulting from triggers called by top-level ** triggers; and so forth. ** +** When the [wx_sqlite3_blob_write()] API is used to update a blob column, +** the pre-update hook is invoked with SQLITE_DELETE. This is because the +** in this case the new values are not available. In this case, when a +** callback made with op==SQLITE_DELETE is actuall a write using the +** wx_sqlite3_blob_write() API, the [wx_sqlite3_preupdate_blobwrite()] returns +** the index of the column being written. In other cases, where the +** pre-update hook is being invoked for some other reason, including a +** regular DELETE, wx_sqlite3_preupdate_blobwrite() returns -1. +** ** See also: [wx_sqlite3_update_hook()] */ #if defined(SQLITE_ENABLE_PREUPDATE_HOOK) @@ -9565,6 +10237,7 @@ SQLITE_API int wx_sqlite3_preupdate_old(wx_sqlite3 *, int, wx_sqlite3_value **); SQLITE_API int wx_sqlite3_preupdate_count(wx_sqlite3 *); SQLITE_API int wx_sqlite3_preupdate_depth(wx_sqlite3 *); SQLITE_API int wx_sqlite3_preupdate_new(wx_sqlite3 *, int, wx_sqlite3_value **); +SQLITE_API int wx_sqlite3_preupdate_blobwrite(wx_sqlite3 *); #endif /* @@ -9803,8 +10476,8 @@ SQLITE_API SQLITE_EXPERIMENTAL int wx_sqlite3_snapshot_recover(wx_sqlite3 *db, c ** SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory ** allocation error occurs. ** -** This interface is only available if SQLite is compiled with the -** [SQLITE_ENABLE_DESERIALIZE] option. +** This interface is omitted if SQLite is compiled with the +** [SQLITE_OMIT_DESERIALIZE] option. */ SQLITE_API unsigned char *wx_sqlite3_serialize( wx_sqlite3 *db, /* The database connection */ @@ -9851,12 +10524,16 @@ SQLITE_API unsigned char *wx_sqlite3_serialize( ** database is currently in a read transaction or is involved in a backup ** operation. ** +** It is not possible to deserialized into the TEMP database. If the +** S argument to wx_sqlite3_deserialize(D,S,P,N,M,F) is "temp" then the +** function returns SQLITE_ERROR. +** ** If wx_sqlite3_deserialize(D,S,P,N,M,F) fails for any reason and if the ** SQLITE_DESERIALIZE_FREEONCLOSE bit is set in argument F, then ** [wx_sqlite3_free()] is invoked on argument P prior to returning. ** -** This interface is only available if SQLite is compiled with the -** [SQLITE_ENABLE_DESERIALIZE] option. +** This interface is omitted if SQLite is compiled with the +** [SQLITE_OMIT_DESERIALIZE] option. */ SQLITE_API int wx_sqlite3_deserialize( wx_sqlite3 *db, /* The database connection */ @@ -9900,6 +10577,19 @@ SQLITE_API int wx_sqlite3_deserialize( # undef double #endif +#if defined(__wasi__) +# undef SQLITE_WASI +# define SQLITE_WASI 1 +# undef SQLITE_OMIT_WAL +# define SQLITE_OMIT_WAL 1/* because it requires shared memory APIs */ +# ifndef SQLITE_OMIT_LOAD_EXTENSION +# define SQLITE_OMIT_LOAD_EXTENSION +# endif +# ifndef SQLITE_THREADSAFE +# define SQLITE_THREADSAFE 0 +# endif +#endif + #ifdef __cplusplus } /* End of the 'extern "C"' block */ #endif @@ -10105,6 +10795,38 @@ SQLITE_API int wx_sqlite3session_create( */ SQLITE_API void wx_sqlite3session_delete(wx_sqlite3_session *pSession); +/* +** CAPIREF: Conigure a Session Object +** METHOD: wx_sqlite3_session +** +** This method is used to configure a session object after it has been +** created. At present the only valid value for the second parameter is +** [SQLITE_SESSION_OBJCONFIG_SIZE]. +** +** Arguments for wx_sqlite3session_object_config() +** +** The following values may passed as the the 4th parameter to +** wx_sqlite3session_object_config(). +** +** <dt>SQLITE_SESSION_OBJCONFIG_SIZE <dd> +** This option is used to set, clear or query the flag that enables +** the [wx_sqlite3session_changeset_size()] API. Because it imposes some +** computational overhead, this API is disabled by default. Argument +** pArg must point to a value of type (int). If the value is initially +** 0, then the wx_sqlite3session_changeset_size() API is disabled. If it +** is greater than 0, then the same API is enabled. Or, if the initial +** value is less than zero, no change is made. In all cases the (int) +** variable is set to 1 if the wx_sqlite3session_changeset_size() API is +** enabled following the current call, or 0 otherwise. +** +** It is an error (SQLITE_MISUSE) to attempt to modify this setting after +** the first table has been attached to the session object. +*/ +SQLITE_API int wx_sqlite3session_object_config(wx_sqlite3_session*, int op, void *pArg); + +/* +*/ +#define SQLITE_SESSION_OBJCONFIG_SIZE 1 /* ** CAPI3REF: Enable Or Disable A Session Object @@ -10350,6 +11072,22 @@ SQLITE_API int wx_sqlite3session_changeset( ); /* +** CAPI3REF: Return An Upper-limit For The Size Of The Changeset +** METHOD: wx_sqlite3_session +** +** By default, this function always returns 0. For it to return +** a useful result, the wx_sqlite3_session object must have been configured +** to enable this API using wx_sqlite3session_object_config() with the +** SQLITE_SESSION_OBJCONFIG_SIZE verb. +** +** When enabled, this function returns an upper limit, in bytes, for the size +** of the changeset that might be produced if wx_sqlite3session_changeset() were +** called. The final changeset size might be equal to or smaller than the +** size in bytes returned by this function. +*/ +SQLITE_API wx_sqlite3_int64 wx_sqlite3session_changeset_size(wx_sqlite3_session *pSession); + +/* ** CAPI3REF: Load The Difference Between Tables Into A Session ** METHOD: wx_sqlite3_session ** @@ -12385,74 +13123,13 @@ int wx_sqlite3_user_delete( /* ** Symbols for ciphers */ -#define CODEC_TYPE_UNKNOWN 0 -#define CODEC_TYPE_AES128 1 -#define CODEC_TYPE_AES256 2 -#define CODEC_TYPE_CHACHA20 3 -#define CODEC_TYPE_SQLCIPHER 4 -#define CODEC_TYPE_RC4 5 -#define CODEC_TYPE_MAX 5 - -/* -** Definitions of supported ciphers -*/ - -/* -** Compatibility with wxSQLite3 -*/ -#ifdef WXSQLITE3_HAVE_CIPHER_AES_128_CBC -#define HAVE_CIPHER_AES_128_CBC WXSQLITE3_HAVE_CIPHER_AES_128_CBC -#endif - -#ifdef WXSQLITE3_HAVE_CIPHER_AES_256_CBC -#define HAVE_CIPHER_AES_256_CBC WXSQLITE3_HAVE_CIPHER_AES_256_CBC -#endif - -#ifdef WXSQLITE3_HAVE_CIPHER_CHACHA20 -#define HAVE_CIPHER_CHACHA20 WXSQLITE3_HAVE_CIPHER_CHACHA20 -#endif - -#ifdef WXSQLITE3_HAVE_CIPHER_SQLCIPHER -#define HAVE_CIPHER_SQLCIPHER WXSQLITE3_HAVE_CIPHER_SQLCIPHER -#endif - -#ifdef WXSQLITE3_HAVE_CIPHER_RC4 -#define HAVE_CIPHER_RC4 WXSQLITE3_HAVE_CIPHER_RC4 -#endif - -/* -** Actual definitions of supported ciphers -*/ -#ifndef HAVE_CIPHER_AES_128_CBC -#define HAVE_CIPHER_AES_128_CBC 1 -#endif - -#ifndef HAVE_CIPHER_AES_256_CBC -#define HAVE_CIPHER_AES_256_CBC 1 -#endif - -#ifndef HAVE_CIPHER_CHACHA20 -#define HAVE_CIPHER_CHACHA20 1 -#endif - -#ifndef HAVE_CIPHER_SQLCIPHER -#define HAVE_CIPHER_SQLCIPHER 1 -#endif - -#ifndef HAVE_CIPHER_RC4 -#define HAVE_CIPHER_RC4 1 -#endif - -/* -** Check that at least one cipher is be supported -*/ -#if HAVE_CIPHER_AES_128_CBC == 0 && \ - HAVE_CIPHER_AES_256_CBC == 0 && \ - HAVE_CIPHER_CHACHA20 == 0 && \ - HAVE_CIPHER_SQLCIPHER == 0 && \ - HAVE_CIPHER_RC4 == 0 -#error Enable at least one cipher scheme! -#endif +#define CODEC_TYPE_UNKNOWN 0 +#define CODEC_TYPE_AES128 1 +#define CODEC_TYPE_AES256 2 +#define CODEC_TYPE_CHACHA20 3 +#define CODEC_TYPE_SQLCIPHER 4 +#define CODEC_TYPE_RC4 5 +#define CODEC_TYPE_MAX_BUILTIN 5 /* ** Definition of API functions @@ -12521,6 +13198,9 @@ SQLITE_API void wx_sqlite3_activate_see(const char* zPassPhrase); /* ** Define functions for the configuration of the wxSQLite3 encryption extension */ +SQLITE_API int wx_sqlite3mc_cipher_count(); +SQLITE_API int wx_sqlite3mc_cipher_index(const char* cipherName); +SQLITE_API const char* wx_sqlite3mc_cipher_name(int cipherIndex); SQLITE_API int wx_sqlite3mc_config(wx_sqlite3* db, const char* paramName, int newValue); SQLITE_API int wx_sqlite3mc_config_cipher(wx_sqlite3* db, const char* cipherName, const char* paramName, int newValue); SQLITE_API unsigned char* wx_sqlite3mc_codec_data(wx_sqlite3* db, const char* zDbName, const char* paramName); @@ -12532,6 +13212,88 @@ SQLITE_API int wxwx_sqlite3_config_cipher(wx_sqlite3* db, const char* cipherName SQLITE_API unsigned char* wxwx_sqlite3_codec_data(wx_sqlite3* db, const char* zDbName, const char* paramName); #endif +/* +** Structures and functions to dynamically register a cipher +*/ + +/* +** Structure for a single cipher configuration parameter +** +** Components: +** m_name - name of parameter (1st char = alpha, rest = alphanumeric or underscore, max 63 characters) +** m_value - current/transient parameter value +** m_default - default parameter value +** m_minValue - minimum valid parameter value +** m_maxValue - maximum valid parameter value +*/ +typedef struct _CipherParams +{ + char* m_name; + int m_value; + int m_default; + int m_minValue; + int m_maxValue; +} CipherParams; + +/* +** Structure for a cipher API +** +** Components: +** m_name - name of cipher (1st char = alpha, rest = alphanumeric or underscore, max 63 characters) +** m_allocateCipher - Function pointer for function AllocateCipher +** m_freeCipher - Function pointer for function FreeCipher +** m_cloneCipher - Function pointer for function CloneCipher +** m_getLegacy - Function pointer for function GetLegacy +** m_getPageSize - Function pointer for function GetPageSize +** m_getReserved - Function pointer for function GetReserved +** m_getSalt - Function pointer for function GetSalt +** m_generateKey - Function pointer for function GenerateKey +** m_encryptPage - Function pointer for function EncryptPage +** m_decryptPage - Function pointer for function DecryptPage +*/ + +typedef struct BtShared BtSharedMC; + +typedef void* (*AllocateCipher_t)(wx_sqlite3* db); +typedef void (*FreeCipher_t)(void* cipher); +typedef void (*CloneCipher_t)(void* cipherTo, void* cipherFrom); +typedef int (*GetLegacy_t)(void* cipher); +typedef int (*GetPageSize_t)(void* cipher); +typedef int (*GetReserved_t)(void* cipher); +typedef unsigned char* (*GetSalt_t)(void* cipher); +typedef void (*GenerateKey_t)(void* cipher, BtSharedMC* pBt, char* userPassword, int passwordLength, int rekey, unsigned char* cipherSalt); +typedef int (*EncryptPage_t)(void* cipher, int page, unsigned char* data, int len, int reserved); +typedef int (*DecryptPage_t)(void* cipher, int page, unsigned char* data, int len, int reserved, int hmacCheck); + +typedef struct _CipherDescriptor +{ + char* m_name; + AllocateCipher_t m_allocateCipher; + FreeCipher_t m_freeCipher; + CloneCipher_t m_cloneCipher; + GetLegacy_t m_getLegacy; + GetPageSize_t m_getPageSize; + GetReserved_t m_getReserved; + GetSalt_t m_getSalt; + GenerateKey_t m_generateKey; + EncryptPage_t m_encryptPage; + DecryptPage_t m_decryptPage; +} CipherDescriptor; + +/* +** Register a cipher +** +** Arguments: +** desc - Cipher descriptor structure +** params - Cipher configuration parameter table +** makeDefault - flag whether to make the cipher the default cipher +** +** Returns: +** SQLITE_OK - the cipher could be registered successfully +** SQLITE_ERROR - the cipher could not be registered +*/ +SQLITE_API int wx_sqlite3mc_register_cipher(const CipherDescriptor* desc, const CipherParams* params, int makeDefault); + #ifdef __cplusplus } #endif @@ -12546,7 +13308,7 @@ SQLITE_API unsigned char* wxwx_sqlite3_codec_data(wx_sqlite3* db, const char* zD ** Purpose: Header file for VFS of SQLite3 Multiple Ciphers support ** Author: Ulrich Telle ** Created: 2020-03-01 -** Copyright: (c) 2020 Ulrich Telle +** Copyright: (c) 2020-2023 Ulrich Telle ** License: MIT */ @@ -12556,6 +13318,11 @@ SQLITE_API unsigned char* wxwx_sqlite3_codec_data(wx_sqlite3* db, const char* zD extern "C" { #endif +#ifndef SQLITE_PRIVATE +#define SQLITE_PRIVATE +#endif +SQLITE_PRIVATE int wx_sqlite3mcCheckVfs(const char* zVfs); + SQLITE_API int wx_sqlite3mc_vfs_create(const char* zVfsReal, int makeDefault); SQLITE_API void wx_sqlite3mc_vfs_destroy(const char* zName); SQLITE_API void wx_sqlite3mc_vfs_shutdown(); |