Index: third_party/sqlite/amalgamation/sqlite3.h |
diff --git a/third_party/sqlite/amalgamation/sqlite3.h b/third_party/sqlite/amalgamation/sqlite3.h |
index 7ca339843a62f59e7cc26d6d2b6d9d362e532e6f..8e4e11e0ce71253e95234134aa974d2bbb7be210 100644 |
--- a/third_party/sqlite/amalgamation/sqlite3.h |
+++ b/third_party/sqlite/amalgamation/sqlite3.h |
@@ -30,8 +30,8 @@ |
** the version number) and changes its name to "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,7 +108,8 @@ 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 |
@@ -111,13 +121,13 @@ extern "C" { |
** [sqlite3_libversion_number()], [sqlite3_sourceid()], |
** [sqlite_version()] and [sqlite_source_id()]. |
*/ |
-#define SQLITE_VERSION "3.10.2" |
-#define SQLITE_VERSION_NUMBER 3010002 |
-#define SQLITE_SOURCE_ID "2016-01-20 15:27:19 17efb4209f97fb4971656086b138599a91a75ff9" |
+#define SQLITE_VERSION "3.17.0" |
+#define SQLITE_VERSION_NUMBER 3017000 |
+#define SQLITE_SOURCE_ID "2017-02-13 16:02:40 ada05cfa86ad7f5645450ac7a2a21c9aa6e57d2c" |
/* |
** CAPI3REF: Run-Time Library Version Numbers |
-** KEYWORDS: sqlite3_version, sqlite3_sourceid |
+** KEYWORDS: sqlite3_version 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 sqlite3_version[]; |
-SQLITE_API const char *SQLITE_STDCALL sqlite3_libversion(void); |
-SQLITE_API const char *SQLITE_STDCALL sqlite3_sourceid(void); |
-SQLITE_API int SQLITE_STDCALL sqlite3_libversion_number(void); |
+SQLITE_API const char *sqlite3_libversion(void); |
+SQLITE_API const char *sqlite3_sourceid(void); |
+SQLITE_API int sqlite3_libversion_number(void); |
/* |
** CAPI3REF: Run-Time Library Compilation Options Diagnostics |
@@ -173,8 +183,8 @@ SQLITE_API int SQLITE_STDCALL sqlite3_libversion_number(void); |
** [sqlite_compileoption_get()] and the [compile_options pragma]. |
*/ |
#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS |
-SQLITE_API int SQLITE_STDCALL sqlite3_compileoption_used(const char *zOptName); |
-SQLITE_API const char *SQLITE_STDCALL sqlite3_compileoption_get(int N); |
+SQLITE_API int sqlite3_compileoption_used(const char *zOptName); |
+SQLITE_API const char *sqlite3_compileoption_get(int N); |
#endif |
/* |
@@ -213,7 +223,7 @@ SQLITE_API const char *SQLITE_STDCALL sqlite3_compileoption_get(int N); |
** |
** See the [threading mode] documentation for additional information. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_threadsafe(void); |
+SQLITE_API int sqlite3_threadsafe(void); |
/* |
** CAPI3REF: Database Connection Handle |
@@ -249,7 +259,11 @@ typedef struct sqlite3 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 sqlite3_uint64; |
** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer |
** argument is a harmless no-op. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_close(sqlite3*); |
-SQLITE_API int SQLITE_STDCALL sqlite3_close_v2(sqlite3*); |
+SQLITE_API int sqlite3_close(sqlite3*); |
+SQLITE_API int sqlite3_close_v2(sqlite3*); |
/* |
** The type for a callback function. |
@@ -347,7 +361,7 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**); |
** from [sqlite3_malloc()] and passed back through the 5th parameter. |
** To avoid memory leaks, the application should invoke [sqlite3_free()] |
** on error message strings returned through the 5th parameter of |
-** of sqlite3_exec() after the error message string is no longer needed. |
+** sqlite3_exec() after the error message string is no longer needed. |
** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors |
** occur, then sqlite3_exec() sets the pointer in its 5th parameter to |
** NULL before returning. |
@@ -382,7 +396,7 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**); |
** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running. |
** </ul> |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_exec( |
+SQLITE_API int sqlite3_exec( |
sqlite3*, /* An open database */ |
const char *sql, /* SQL to be evaluated */ |
int (*callback)(void*,int,char**,char**), /* Callback function */ |
@@ -443,7 +457,8 @@ SQLITE_API int SQLITE_STDCALL 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 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 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 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 |
@@ -966,6 +985,12 @@ struct 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 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 sqlite3_io_methods { |
typedef struct sqlite3_mutex sqlite3_mutex; |
/* |
+** CAPI3REF: Loadable Extension Thunk |
+** |
+** A pointer to the opaque 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 sqlite3_api_routines sqlite3_api_routines; |
+ |
+/* |
** CAPI3REF: OS Interface Object |
** |
** An instance of the sqlite3_vfs object defines the interface between |
@@ -1228,7 +1265,7 @@ struct sqlite3_vfs { |
const char *(*xNextSystemCall)(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 sqlite3_vfs { |
** must return [SQLITE_OK] on success and some other [error code] upon |
** failure. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_initialize(void); |
-SQLITE_API int SQLITE_STDCALL sqlite3_shutdown(void); |
-SQLITE_API int SQLITE_STDCALL sqlite3_os_init(void); |
-SQLITE_API int SQLITE_STDCALL sqlite3_os_end(void); |
+SQLITE_API int sqlite3_initialize(void); |
+SQLITE_API int sqlite3_shutdown(void); |
+SQLITE_API int sqlite3_os_init(void); |
+SQLITE_API int sqlite3_os_end(void); |
/* |
** CAPI3REF: Configuring The SQLite Library |
@@ -1406,7 +1443,7 @@ SQLITE_API int SQLITE_STDCALL 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 sqlite3_config(int, ...); |
+SQLITE_API int sqlite3_config(int, ...); |
/* |
** CAPI3REF: Configure database connections |
@@ -1425,7 +1462,7 @@ SQLITE_API int SQLITE_CDECL sqlite3_config(int, ...); |
** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if |
** the call is considered successful. |
*/ |
-SQLITE_API int SQLITE_CDECL sqlite3_db_config(sqlite3*, int op, ...); |
+SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...); |
/* |
** CAPI3REF: Memory Allocation Routines |
@@ -1820,6 +1857,20 @@ struct 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 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,66 @@ struct 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 [sqlite3_load_extension()] |
+** interface independently of the [load_extension()] SQL function. |
+** The [sqlite3_enable_load_extension()] API enables or disables both the |
+** C-API [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 [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> |
+** |
** </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* */ |
/* |
@@ -1919,7 +2026,7 @@ struct 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 sqlite3_extended_result_codes(sqlite3*, int onoff); |
+SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff); |
/* |
** CAPI3REF: Last Insert Rowid |
@@ -1971,7 +2078,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_extended_result_codes(sqlite3*, int onoff) |
** unpredictable and might not equal either the old or the new |
** last insert [rowid]. |
*/ |
-SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_last_insert_rowid(sqlite3*); |
+SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); |
/* |
** CAPI3REF: Count The Number Of Rows Modified |
@@ -2024,7 +2131,7 @@ SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_last_insert_rowid(sqlite3*); |
** while [sqlite3_changes()] is running then the value returned |
** is unpredictable and not meaningful. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_changes(sqlite3*); |
+SQLITE_API int sqlite3_changes(sqlite3*); |
/* |
** CAPI3REF: Total Number Of Rows Modified |
@@ -2048,7 +2155,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_changes(sqlite3*); |
** while [sqlite3_total_changes()] is running then the value |
** returned is unpredictable and not meaningful. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_total_changes(sqlite3*); |
+SQLITE_API int sqlite3_total_changes(sqlite3*); |
/* |
** CAPI3REF: Interrupt A Long-Running Query |
@@ -2088,7 +2195,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_total_changes(sqlite3*); |
** If the database connection closes while [sqlite3_interrupt()] |
** is running then bad things will likely happen. |
*/ |
-SQLITE_API void SQLITE_STDCALL sqlite3_interrupt(sqlite3*); |
+SQLITE_API void sqlite3_interrupt(sqlite3*); |
/* |
** CAPI3REF: Determine If An SQL Statement Is Complete |
@@ -2123,8 +2230,8 @@ SQLITE_API void SQLITE_STDCALL sqlite3_interrupt(sqlite3*); |
** The input to [sqlite3_complete16()] must be a zero-terminated |
** UTF-16 string in native byte order. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_complete(const char *sql); |
-SQLITE_API int SQLITE_STDCALL sqlite3_complete16(const void *sql); |
+SQLITE_API int sqlite3_complete(const char *sql); |
+SQLITE_API int sqlite3_complete16(const void *sql); |
/* |
** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors |
@@ -2185,7 +2292,7 @@ SQLITE_API int SQLITE_STDCALL 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 sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); |
+SQLITE_API int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*); |
/* |
** CAPI3REF: Set A Busy Timeout |
@@ -2208,7 +2315,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_busy_handler(sqlite3*, int(*)(void*,int), |
** |
** See also: [PRAGMA busy_timeout] |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_busy_timeout(sqlite3*, int ms); |
+SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms); |
/* |
** CAPI3REF: Convenience Routines For Running Queries |
@@ -2283,7 +2390,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_busy_timeout(sqlite3*, int ms); |
** reflected in subsequent calls to [sqlite3_errcode()] or |
** [sqlite3_errmsg()]. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_get_table( |
+SQLITE_API int sqlite3_get_table( |
sqlite3 *db, /* An open database */ |
const char *zSql, /* SQL to be evaluated */ |
char ***pazResult, /* Results of the query */ |
@@ -2291,7 +2398,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_get_table( |
int *pnColumn, /* Number of result columns written here */ |
char **pzErrmsg /* Error msg written here */ |
); |
-SQLITE_API void SQLITE_STDCALL sqlite3_free_table(char **result); |
+SQLITE_API void sqlite3_free_table(char **result); |
/* |
** CAPI3REF: Formatted String Printing Functions |
@@ -2397,10 +2504,10 @@ SQLITE_API void SQLITE_STDCALL sqlite3_free_table(char **result); |
** addition that after the string has been read and copied into |
** the result, [sqlite3_free()] is called on the input string.)^ |
*/ |
-SQLITE_API char *SQLITE_CDECL sqlite3_mprintf(const char*,...); |
-SQLITE_API char *SQLITE_STDCALL sqlite3_vmprintf(const char*, va_list); |
-SQLITE_API char *SQLITE_CDECL sqlite3_snprintf(int,char*,const char*, ...); |
-SQLITE_API char *SQLITE_STDCALL sqlite3_vsnprintf(int,char*,const char*, va_list); |
+SQLITE_API char *sqlite3_mprintf(const char*,...); |
+SQLITE_API char *sqlite3_vmprintf(const char*, va_list); |
+SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...); |
+SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list); |
/* |
** CAPI3REF: Memory Allocation Subsystem |
@@ -2490,12 +2597,12 @@ SQLITE_API char *SQLITE_STDCALL sqlite3_vsnprintf(int,char*,const char*, va_list |
** a block of memory after it has been released using |
** [sqlite3_free()] or [sqlite3_realloc()]. |
*/ |
-SQLITE_API void *SQLITE_STDCALL sqlite3_malloc(int); |
-SQLITE_API void *SQLITE_STDCALL sqlite3_malloc64(sqlite3_uint64); |
-SQLITE_API void *SQLITE_STDCALL sqlite3_realloc(void*, int); |
-SQLITE_API void *SQLITE_STDCALL sqlite3_realloc64(void*, sqlite3_uint64); |
-SQLITE_API void SQLITE_STDCALL sqlite3_free(void*); |
-SQLITE_API sqlite3_uint64 SQLITE_STDCALL sqlite3_msize(void*); |
+SQLITE_API void *sqlite3_malloc(int); |
+SQLITE_API void *sqlite3_malloc64(sqlite3_uint64); |
+SQLITE_API void *sqlite3_realloc(void*, int); |
+SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64); |
+SQLITE_API void sqlite3_free(void*); |
+SQLITE_API sqlite3_uint64 sqlite3_msize(void*); |
/* |
** CAPI3REF: Memory Allocator Statistics |
@@ -2520,8 +2627,8 @@ SQLITE_API sqlite3_uint64 SQLITE_STDCALL sqlite3_msize(void*); |
** by [sqlite3_memory_highwater(1)] is the high-water mark |
** prior to the reset. |
*/ |
-SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_memory_used(void); |
-SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_memory_highwater(int resetFlag); |
+SQLITE_API sqlite3_int64 sqlite3_memory_used(void); |
+SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag); |
/* |
** CAPI3REF: Pseudo-Random Number Generator |
@@ -2544,7 +2651,7 @@ SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_memory_highwater(int resetFlag); |
** internally and without recourse to the [sqlite3_vfs] xRandomness |
** method. |
*/ |
-SQLITE_API void SQLITE_STDCALL sqlite3_randomness(int N, void *P); |
+SQLITE_API void sqlite3_randomness(int N, void *P); |
/* |
** CAPI3REF: Compile-Time Authorization Callbacks |
@@ -2627,7 +2734,7 @@ SQLITE_API void SQLITE_STDCALL sqlite3_randomness(int N, void *P); |
** as stated in the previous paragraph, sqlite3_step() invokes |
** sqlite3_prepare_v2() to reprepare a statement after a schema change. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_set_authorizer( |
+SQLITE_API int sqlite3_set_authorizer( |
sqlite3*, |
int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), |
void *pUserData |
@@ -2707,6 +2814,9 @@ SQLITE_API int SQLITE_STDCALL sqlite3_set_authorizer( |
** CAPI3REF: Tracing And Profiling Functions |
** METHOD: sqlite3 |
** |
+** These routines are deprecated. Use the [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 +2842,105 @@ SQLITE_API int SQLITE_STDCALL sqlite3_set_authorizer( |
** sqlite3_profile() function is considered experimental and is |
** subject to change in future versions of SQLite. |
*/ |
-SQLITE_API void *SQLITE_STDCALL sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); |
-SQLITE_API SQLITE_EXPERIMENTAL void *SQLITE_STDCALL sqlite3_profile(sqlite3*, |
+SQLITE_API SQLITE_DEPRECATED void *sqlite3_trace(sqlite3*, |
+ void(*xTrace)(void*,const char*), void*); |
+SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*, |
void(*xProfile)(void*,const char*,sqlite3_uint64), void*); |
/* |
+** CAPI3REF: SQL Trace Event Codes |
+** KEYWORDS: SQLITE_TRACE |
+** |
+** These constants identify classes of events that can be monitored |
+** using the [sqlite3_trace_v2()] tracing logic. The third argument |
+** to [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 [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 [sqlite3_trace()] |
+** interface by using the X argument when X begins with "--" and invoking |
+** [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 [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: sqlite3 |
+** |
+** ^The 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 sqlite3_trace() or sqlite3_trace_v2() overrides |
+** (cancels) any prior calls to sqlite3_trace() or 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 sqlite3_trace_v2() interface is intended to replace the legacy |
+** interfaces [sqlite3_trace()] and [sqlite3_profile()], both of which |
+** are deprecated. |
+*/ |
+SQLITE_API int sqlite3_trace_v2( |
+ sqlite3*, |
+ unsigned uMask, |
+ int(*xCallback)(unsigned,void*,void*,void*), |
+ void *pCtx |
+); |
+ |
+/* |
** CAPI3REF: Query Progress Callbacks |
** METHOD: sqlite3 |
** |
@@ -2768,7 +2972,7 @@ SQLITE_API SQLITE_EXPERIMENTAL void *SQLITE_STDCALL sqlite3_profile(sqlite3*, |
** database connections for the meaning of "modify" in this paragraph. |
** |
*/ |
-SQLITE_API void SQLITE_STDCALL sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); |
+SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); |
/* |
** CAPI3REF: Opening A New Database Connection |
@@ -2997,15 +3201,15 @@ SQLITE_API void SQLITE_STDCALL sqlite3_progress_handler(sqlite3*, int, int(*)(vo |
** |
** See also: [sqlite3_temp_directory] |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_open( |
+SQLITE_API int sqlite3_open( |
const char *filename, /* Database filename (UTF-8) */ |
sqlite3 **ppDb /* OUT: SQLite db handle */ |
); |
-SQLITE_API int SQLITE_STDCALL sqlite3_open16( |
+SQLITE_API int sqlite3_open16( |
const void *filename, /* Database filename (UTF-16) */ |
sqlite3 **ppDb /* OUT: SQLite db handle */ |
); |
-SQLITE_API int SQLITE_STDCALL sqlite3_open_v2( |
+SQLITE_API int sqlite3_open_v2( |
const char *filename, /* Database filename (UTF-8) */ |
sqlite3 **ppDb, /* OUT: SQLite db handle */ |
int flags, /* Flags */ |
@@ -3051,9 +3255,9 @@ SQLITE_API int SQLITE_STDCALL sqlite3_open_v2( |
** VFS method, then the behavior of this routine is undefined and probably |
** undesirable. |
*/ |
-SQLITE_API const char *SQLITE_STDCALL sqlite3_uri_parameter(const char *zFilename, const char *zParam); |
-SQLITE_API int SQLITE_STDCALL sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault); |
-SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_uri_int64(const char*, const char*, sqlite3_int64); |
+SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam); |
+SQLITE_API int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault); |
+SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int64); |
/* |
@@ -3097,11 +3301,11 @@ SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_uri_int64(const char*, const cha |
** 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 sqlite3_errcode(sqlite3 *db); |
-SQLITE_API int SQLITE_STDCALL sqlite3_extended_errcode(sqlite3 *db); |
-SQLITE_API const char *SQLITE_STDCALL sqlite3_errmsg(sqlite3*); |
-SQLITE_API const void *SQLITE_STDCALL sqlite3_errmsg16(sqlite3*); |
-SQLITE_API const char *SQLITE_STDCALL sqlite3_errstr(int); |
+SQLITE_API int sqlite3_errcode(sqlite3 *db); |
+SQLITE_API int sqlite3_extended_errcode(sqlite3 *db); |
+SQLITE_API const char *sqlite3_errmsg(sqlite3*); |
+SQLITE_API const void *sqlite3_errmsg16(sqlite3*); |
+SQLITE_API const char *sqlite3_errstr(int); |
/* |
** CAPI3REF: Prepared Statement Object |
@@ -3169,7 +3373,7 @@ typedef struct sqlite3_stmt sqlite3_stmt; |
** |
** New run-time limit categories may be added in future releases. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_limit(sqlite3*, int id, int newVal); |
+SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal); |
/* |
** CAPI3REF: Run-Time Limit Categories |
@@ -3321,28 +3525,28 @@ SQLITE_API int SQLITE_STDCALL sqlite3_limit(sqlite3*, int id, int newVal); |
** </li> |
** </ol> |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_prepare( |
+SQLITE_API int sqlite3_prepare( |
sqlite3 *db, /* Database handle */ |
const char *zSql, /* SQL statement, UTF-8 encoded */ |
int nByte, /* Maximum length of zSql in bytes. */ |
sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
const char **pzTail /* OUT: Pointer to unused portion of zSql */ |
); |
-SQLITE_API int SQLITE_STDCALL sqlite3_prepare_v2( |
+SQLITE_API int sqlite3_prepare_v2( |
sqlite3 *db, /* Database handle */ |
const char *zSql, /* SQL statement, UTF-8 encoded */ |
int nByte, /* Maximum length of zSql in bytes. */ |
sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
const char **pzTail /* OUT: Pointer to unused portion of zSql */ |
); |
-SQLITE_API int SQLITE_STDCALL sqlite3_prepare16( |
+SQLITE_API int sqlite3_prepare16( |
sqlite3 *db, /* Database handle */ |
const void *zSql, /* SQL statement, UTF-16 encoded */ |
int nByte, /* Maximum length of zSql in bytes. */ |
sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
const void **pzTail /* OUT: Pointer to unused portion of zSql */ |
); |
-SQLITE_API int SQLITE_STDCALL sqlite3_prepare16_v2( |
+SQLITE_API int sqlite3_prepare16_v2( |
sqlite3 *db, /* Database handle */ |
const void *zSql, /* SQL statement, UTF-16 encoded */ |
int nByte, /* Maximum length of zSql in bytes. */ |
@@ -3354,11 +3558,35 @@ SQLITE_API int SQLITE_STDCALL sqlite3_prepare16_v2( |
** CAPI3REF: Retrieving Statement SQL |
** METHOD: 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 [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()]. |
+** ^The 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 either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()]. |
+** ^The 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 sqlite3_sql() will return |
+** the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql() |
+** will return "SELECT 2345,NULL".)^ |
+** |
+** ^The 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 sqlite3_expanded_sql() to always return NULL. |
+** |
+** ^The string returned by sqlite3_sql(P) is managed by SQLite and is |
+** automatically freed when the prepared statement is finalized. |
+** ^The string returned by sqlite3_expanded_sql(P), on the other hand, |
+** is obtained from [sqlite3_malloc()] and must be free by the application |
+** by passing it to [sqlite3_free()]. |
*/ |
-SQLITE_API const char *SQLITE_STDCALL sqlite3_sql(sqlite3_stmt *pStmt); |
+SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt); |
+SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt); |
/* |
** CAPI3REF: Determine If An SQL Statement Writes The Database |
@@ -3389,8 +3617,12 @@ SQLITE_API const char *SQLITE_STDCALL sqlite3_sql(sqlite3_stmt *pStmt); |
** 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 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 |
+** sqlite3_stmt_readonly() returns false for those commands. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_stmt_readonly(sqlite3_stmt *pStmt); |
+SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt); |
/* |
** CAPI3REF: Determine If A Prepared Statement Has Been Reset |
@@ -3411,7 +3643,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_stmt_readonly(sqlite3_stmt *pStmt); |
** for example, in diagnostic routines to search for prepared |
** statements that are holding a transaction open. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_stmt_busy(sqlite3_stmt*); |
+SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*); |
/* |
** CAPI3REF: Dynamically Typed Value Object |
@@ -3575,20 +3807,20 @@ typedef struct sqlite3_context sqlite3_context; |
** See also: [sqlite3_bind_parameter_count()], |
** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()]. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); |
-SQLITE_API int SQLITE_STDCALL sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64, |
+SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); |
+SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64, |
void(*)(void*)); |
-SQLITE_API int SQLITE_STDCALL sqlite3_bind_double(sqlite3_stmt*, int, double); |
-SQLITE_API int SQLITE_STDCALL sqlite3_bind_int(sqlite3_stmt*, int, int); |
-SQLITE_API int SQLITE_STDCALL sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); |
-SQLITE_API int SQLITE_STDCALL sqlite3_bind_null(sqlite3_stmt*, int); |
-SQLITE_API int SQLITE_STDCALL sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*)); |
-SQLITE_API int SQLITE_STDCALL sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); |
-SQLITE_API int SQLITE_STDCALL sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64, |
+SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double); |
+SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int); |
+SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); |
+SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int); |
+SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*)); |
+SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); |
+SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64, |
void(*)(void*), unsigned char encoding); |
-SQLITE_API int SQLITE_STDCALL sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); |
-SQLITE_API int SQLITE_STDCALL sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); |
-SQLITE_API int SQLITE_STDCALL sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64); |
+SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); |
+SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); |
+SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64); |
/* |
** CAPI3REF: Number Of SQL Parameters |
@@ -3609,7 +3841,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite |
** [sqlite3_bind_parameter_name()], and |
** [sqlite3_bind_parameter_index()]. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_bind_parameter_count(sqlite3_stmt*); |
+SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*); |
/* |
** CAPI3REF: Name Of A Host Parameter |
@@ -3637,7 +3869,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_bind_parameter_count(sqlite3_stmt*); |
** [sqlite3_bind_parameter_count()], and |
** [sqlite3_bind_parameter_index()]. |
*/ |
-SQLITE_API const char *SQLITE_STDCALL sqlite3_bind_parameter_name(sqlite3_stmt*, int); |
+SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); |
/* |
** CAPI3REF: Index Of A Parameter With A Given Name |
@@ -3654,7 +3886,7 @@ SQLITE_API const char *SQLITE_STDCALL sqlite3_bind_parameter_name(sqlite3_stmt*, |
** [sqlite3_bind_parameter_count()], and |
** [sqlite3_bind_parameter_name()]. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); |
+SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); |
/* |
** CAPI3REF: Reset All Bindings On A Prepared Statement |
@@ -3664,19 +3896,23 @@ SQLITE_API int SQLITE_STDCALL sqlite3_bind_parameter_index(sqlite3_stmt*, const |
** the [sqlite3_bind_blob | bindings] on a [prepared statement]. |
** ^Use this routine to reset all host parameters to NULL. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_clear_bindings(sqlite3_stmt*); |
+SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*); |
/* |
** CAPI3REF: Number Of Columns In A Result Set |
** METHOD: 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 sqlite3_column_count() but depending on the |
+** WHERE clause constraints and the table content, it might return no rows. |
** |
** See also: [sqlite3_data_count()] |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_column_count(sqlite3_stmt *pStmt); |
+SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt); |
/* |
** CAPI3REF: Column Names In A Result Set |
@@ -3705,8 +3941,8 @@ SQLITE_API int SQLITE_STDCALL sqlite3_column_count(sqlite3_stmt *pStmt); |
** 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 sqlite3_column_name(sqlite3_stmt*, int N); |
-SQLITE_API const void *SQLITE_STDCALL sqlite3_column_name16(sqlite3_stmt*, int N); |
+SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N); |
+SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N); |
/* |
** CAPI3REF: Source Of Data In A Query Result |
@@ -3754,12 +3990,12 @@ SQLITE_API const void *SQLITE_STDCALL sqlite3_column_name16(sqlite3_stmt*, int N |
** for the same [prepared statement] and result column |
** at the same time then the results are undefined. |
*/ |
-SQLITE_API const char *SQLITE_STDCALL sqlite3_column_database_name(sqlite3_stmt*,int); |
-SQLITE_API const void *SQLITE_STDCALL sqlite3_column_database_name16(sqlite3_stmt*,int); |
-SQLITE_API const char *SQLITE_STDCALL sqlite3_column_table_name(sqlite3_stmt*,int); |
-SQLITE_API const void *SQLITE_STDCALL sqlite3_column_table_name16(sqlite3_stmt*,int); |
-SQLITE_API const char *SQLITE_STDCALL sqlite3_column_origin_name(sqlite3_stmt*,int); |
-SQLITE_API const void *SQLITE_STDCALL sqlite3_column_origin_name16(sqlite3_stmt*,int); |
+SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int); |
+SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int); |
+SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int); |
+SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int); |
+SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int); |
+SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); |
/* |
** CAPI3REF: Declared Datatype Of A Query Result |
@@ -3791,8 +4027,8 @@ SQLITE_API const void *SQLITE_STDCALL sqlite3_column_origin_name16(sqlite3_stmt* |
** is associated with individual values, not with the containers |
** used to hold those values. |
*/ |
-SQLITE_API const char *SQLITE_STDCALL sqlite3_column_decltype(sqlite3_stmt*,int); |
-SQLITE_API const void *SQLITE_STDCALL sqlite3_column_decltype16(sqlite3_stmt*,int); |
+SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int); |
+SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int); |
/* |
** CAPI3REF: Evaluate An SQL Statement |
@@ -3853,7 +4089,8 @@ SQLITE_API const void *SQLITE_STDCALL sqlite3_column_decltype16(sqlite3_stmt*,in |
** other than [SQLITE_ROW] before any subsequent invocation of |
** sqlite3_step(). Failure to reset the prepared statement using |
** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from |
-** sqlite3_step(). But after version 3.6.23.1, sqlite3_step() began |
+** sqlite3_step(). But after [version 3.6.23.1] ([dateof:3.6.23.1], |
+** sqlite3_step() began |
** calling [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 |
@@ -3872,7 +4109,7 @@ SQLITE_API const void *SQLITE_STDCALL sqlite3_column_decltype16(sqlite3_stmt*,in |
** then the more specific [error codes] are returned directly |
** by sqlite3_step(). The use of the "v2" interface is recommended. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_step(sqlite3_stmt*); |
+SQLITE_API int sqlite3_step(sqlite3_stmt*); |
/* |
** CAPI3REF: Number of columns in a result set |
@@ -3893,7 +4130,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_step(sqlite3_stmt*); |
** |
** See also: [sqlite3_column_count()] |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_data_count(sqlite3_stmt *pStmt); |
+SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt); |
/* |
** CAPI3REF: Fundamental Datatypes |
@@ -4083,16 +4320,16 @@ SQLITE_API int SQLITE_STDCALL sqlite3_data_count(sqlite3_stmt *pStmt); |
** pointer. Subsequent calls to [sqlite3_errcode()] will return |
** [SQLITE_NOMEM].)^ |
*/ |
-SQLITE_API const void *SQLITE_STDCALL sqlite3_column_blob(sqlite3_stmt*, int iCol); |
-SQLITE_API int SQLITE_STDCALL sqlite3_column_bytes(sqlite3_stmt*, int iCol); |
-SQLITE_API int SQLITE_STDCALL sqlite3_column_bytes16(sqlite3_stmt*, int iCol); |
-SQLITE_API double SQLITE_STDCALL sqlite3_column_double(sqlite3_stmt*, int iCol); |
-SQLITE_API int SQLITE_STDCALL sqlite3_column_int(sqlite3_stmt*, int iCol); |
-SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_column_int64(sqlite3_stmt*, int iCol); |
-SQLITE_API const unsigned char *SQLITE_STDCALL sqlite3_column_text(sqlite3_stmt*, int iCol); |
-SQLITE_API const void *SQLITE_STDCALL sqlite3_column_text16(sqlite3_stmt*, int iCol); |
-SQLITE_API int SQLITE_STDCALL sqlite3_column_type(sqlite3_stmt*, int iCol); |
-SQLITE_API sqlite3_value *SQLITE_STDCALL sqlite3_column_value(sqlite3_stmt*, int iCol); |
+SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); |
+SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol); |
+SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); |
+SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol); |
+SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol); |
+SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); |
+SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); |
+SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); |
+SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol); |
+SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); |
/* |
** CAPI3REF: Destroy A Prepared Statement Object |
@@ -4120,7 +4357,7 @@ SQLITE_API sqlite3_value *SQLITE_STDCALL sqlite3_column_value(sqlite3_stmt*, int |
** statement after it has been finalized can result in undefined and |
** undesirable behavior such as segfaults and heap corruption. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_finalize(sqlite3_stmt *pStmt); |
+SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt); |
/* |
** CAPI3REF: Reset A Prepared Statement Object |
@@ -4147,7 +4384,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_finalize(sqlite3_stmt *pStmt); |
** ^The [sqlite3_reset(S)] interface does not change the values |
** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_reset(sqlite3_stmt *pStmt); |
+SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt); |
/* |
** CAPI3REF: Create Or Redefine SQL Functions |
@@ -4247,7 +4484,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_reset(sqlite3_stmt *pStmt); |
** close the database connection nor finalize or reset the prepared |
** statement in which the function is running. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_create_function( |
+SQLITE_API int sqlite3_create_function( |
sqlite3 *db, |
const char *zFunctionName, |
int nArg, |
@@ -4257,7 +4494,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_create_function( |
void (*xStep)(sqlite3_context*,int,sqlite3_value**), |
void (*xFinal)(sqlite3_context*) |
); |
-SQLITE_API int SQLITE_STDCALL sqlite3_create_function16( |
+SQLITE_API int sqlite3_create_function16( |
sqlite3 *db, |
const void *zFunctionName, |
int nArg, |
@@ -4267,7 +4504,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_create_function16( |
void (*xStep)(sqlite3_context*,int,sqlite3_value**), |
void (*xFinal)(sqlite3_context*) |
); |
-SQLITE_API int SQLITE_STDCALL sqlite3_create_function_v2( |
+SQLITE_API int sqlite3_create_function_v2( |
sqlite3 *db, |
const char *zFunctionName, |
int nArg, |
@@ -4313,12 +4550,12 @@ SQLITE_API int SQLITE_STDCALL sqlite3_create_function_v2( |
** these functions, we will not explain what they do. |
*/ |
#ifndef SQLITE_OMIT_DEPRECATED |
-SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_aggregate_count(sqlite3_context*); |
-SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_expired(sqlite3_stmt*); |
-SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); |
-SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_global_recover(void); |
-SQLITE_API SQLITE_DEPRECATED void SQLITE_STDCALL sqlite3_thread_cleanup(void); |
-SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int), |
+SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*); |
+SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*); |
+SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); |
+SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void); |
+SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void); |
+SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int), |
void*,sqlite3_int64); |
#endif |
@@ -4368,18 +4605,18 @@ SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_memory_alarm(void(*)(voi |
** These routines must be called from the same thread as |
** the SQL function that supplied the [sqlite3_value*] parameters. |
*/ |
-SQLITE_API const void *SQLITE_STDCALL sqlite3_value_blob(sqlite3_value*); |
-SQLITE_API int SQLITE_STDCALL sqlite3_value_bytes(sqlite3_value*); |
-SQLITE_API int SQLITE_STDCALL sqlite3_value_bytes16(sqlite3_value*); |
-SQLITE_API double SQLITE_STDCALL sqlite3_value_double(sqlite3_value*); |
-SQLITE_API int SQLITE_STDCALL sqlite3_value_int(sqlite3_value*); |
-SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_value_int64(sqlite3_value*); |
-SQLITE_API const unsigned char *SQLITE_STDCALL sqlite3_value_text(sqlite3_value*); |
-SQLITE_API const void *SQLITE_STDCALL sqlite3_value_text16(sqlite3_value*); |
-SQLITE_API const void *SQLITE_STDCALL sqlite3_value_text16le(sqlite3_value*); |
-SQLITE_API const void *SQLITE_STDCALL sqlite3_value_text16be(sqlite3_value*); |
-SQLITE_API int SQLITE_STDCALL sqlite3_value_type(sqlite3_value*); |
-SQLITE_API int SQLITE_STDCALL sqlite3_value_numeric_type(sqlite3_value*); |
+SQLITE_API const void *sqlite3_value_blob(sqlite3_value*); |
+SQLITE_API int sqlite3_value_bytes(sqlite3_value*); |
+SQLITE_API int sqlite3_value_bytes16(sqlite3_value*); |
+SQLITE_API double sqlite3_value_double(sqlite3_value*); |
+SQLITE_API int sqlite3_value_int(sqlite3_value*); |
+SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*); |
+SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*); |
+SQLITE_API const void *sqlite3_value_text16(sqlite3_value*); |
+SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*); |
+SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*); |
+SQLITE_API int sqlite3_value_type(sqlite3_value*); |
+SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*); |
/* |
** CAPI3REF: Finding The Subtype Of SQL Values |
@@ -4395,7 +4632,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_value_numeric_type(sqlite3_value*); |
** from the result of one [application-defined SQL function] into the |
** input of another. |
*/ |
-SQLITE_API unsigned int SQLITE_STDCALL sqlite3_value_subtype(sqlite3_value*); |
+SQLITE_API unsigned int sqlite3_value_subtype(sqlite3_value*); |
/* |
** CAPI3REF: Copy And Free SQL Values |
@@ -4411,8 +4648,8 @@ SQLITE_API unsigned int SQLITE_STDCALL sqlite3_value_subtype(sqlite3_value*); |
** previously obtained from [sqlite3_value_dup()]. ^If V is a NULL pointer |
** then sqlite3_value_free(V) is a harmless no-op. |
*/ |
-SQLITE_API sqlite3_value *SQLITE_STDCALL sqlite3_value_dup(const sqlite3_value*); |
-SQLITE_API void SQLITE_STDCALL sqlite3_value_free(sqlite3_value*); |
+SQLITE_API sqlite3_value *sqlite3_value_dup(const sqlite3_value*); |
+SQLITE_API void sqlite3_value_free(sqlite3_value*); |
/* |
** CAPI3REF: Obtain Aggregate Function Context |
@@ -4457,7 +4694,7 @@ SQLITE_API void SQLITE_STDCALL sqlite3_value_free(sqlite3_value*); |
** This routine must be called from the same thread in which |
** the aggregate SQL function is running. |
*/ |
-SQLITE_API void *SQLITE_STDCALL sqlite3_aggregate_context(sqlite3_context*, int nBytes); |
+SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); |
/* |
** CAPI3REF: User Data For Functions |
@@ -4472,7 +4709,7 @@ SQLITE_API void *SQLITE_STDCALL sqlite3_aggregate_context(sqlite3_context*, int |
** This routine must be called from the same thread in which |
** the application-defined function is running. |
*/ |
-SQLITE_API void *SQLITE_STDCALL sqlite3_user_data(sqlite3_context*); |
+SQLITE_API void *sqlite3_user_data(sqlite3_context*); |
/* |
** CAPI3REF: Database Connection For Functions |
@@ -4484,7 +4721,7 @@ SQLITE_API void *SQLITE_STDCALL sqlite3_user_data(sqlite3_context*); |
** and [sqlite3_create_function16()] routines that originally |
** registered the application defined function. |
*/ |
-SQLITE_API sqlite3 *SQLITE_STDCALL sqlite3_context_db_handle(sqlite3_context*); |
+SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*); |
/* |
** CAPI3REF: Function Auxiliary Data |
@@ -4516,12 +4753,13 @@ SQLITE_API sqlite3 *SQLITE_STDCALL sqlite3_context_db_handle(sqlite3_context*); |
** 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 [sqlite3_reset()] or [sqlite3_finalize()] is called for the |
-** SQL statement, or |
-** <li> when sqlite3_set_auxdata() is invoked again on the same parameter, or |
-** <li> during the original sqlite3_set_auxdata() call when a memory |
-** allocation error occurs. </ul>)^ |
+** <li> ^(when the corresponding function parameter changes)^, or |
+** <li> ^(when [sqlite3_reset()] or [sqlite3_finalize()] is called for the |
+** SQL statement)^, or |
+** <li> ^(when sqlite3_set_auxdata() is invoked again on the same |
+** parameter)^, or |
+** <li> ^(during the original sqlite3_set_auxdata() call when a memory |
+** allocation error occurs.)^ </ul> |
** |
** Note the last bullet in particular. The destructor X in |
** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the |
@@ -4537,8 +4775,8 @@ SQLITE_API sqlite3 *SQLITE_STDCALL sqlite3_context_db_handle(sqlite3_context*); |
** These routines must be called from the same thread in which |
** the SQL function is running. |
*/ |
-SQLITE_API void *SQLITE_STDCALL sqlite3_get_auxdata(sqlite3_context*, int N); |
-SQLITE_API void SQLITE_STDCALL sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*)); |
+SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N); |
+SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*)); |
/* |
@@ -4674,27 +4912,27 @@ typedef void (*sqlite3_destructor_type)(void*); |
** than the one containing the application-defined function that received |
** the [sqlite3_context] pointer, the results are undefined. |
*/ |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_blob64(sqlite3_context*,const void*, |
+SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); |
+SQLITE_API void sqlite3_result_blob64(sqlite3_context*,const void*, |
sqlite3_uint64,void(*)(void*)); |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_double(sqlite3_context*, double); |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_error(sqlite3_context*, const char*, int); |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_error16(sqlite3_context*, const void*, int); |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_error_toobig(sqlite3_context*); |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_error_nomem(sqlite3_context*); |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_error_code(sqlite3_context*, int); |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_int(sqlite3_context*, int); |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_int64(sqlite3_context*, sqlite3_int64); |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_null(sqlite3_context*); |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64, |
+SQLITE_API void sqlite3_result_double(sqlite3_context*, double); |
+SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int); |
+SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int); |
+SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*); |
+SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*); |
+SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int); |
+SQLITE_API void sqlite3_result_int(sqlite3_context*, int); |
+SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64); |
+SQLITE_API void sqlite3_result_null(sqlite3_context*); |
+SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); |
+SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64, |
void(*)(void*), unsigned char encoding); |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_value(sqlite3_context*, sqlite3_value*); |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_zeroblob(sqlite3_context*, int n); |
-SQLITE_API int SQLITE_STDCALL sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n); |
+SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); |
+SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); |
+SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); |
+SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*); |
+SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n); |
+SQLITE_API int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n); |
/* |
@@ -4709,7 +4947,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_result_zeroblob64(sqlite3_context*, sqlite |
** The number of subtype bytes preserved by SQLite might increase |
** in future releases of SQLite. |
*/ |
-SQLITE_API void SQLITE_STDCALL sqlite3_result_subtype(sqlite3_context*,unsigned int); |
+SQLITE_API void sqlite3_result_subtype(sqlite3_context*,unsigned int); |
/* |
** CAPI3REF: Define New Collating Sequences |
@@ -4791,14 +5029,14 @@ SQLITE_API void SQLITE_STDCALL sqlite3_result_subtype(sqlite3_context*,unsigned |
** |
** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()]. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_create_collation( |
+SQLITE_API int sqlite3_create_collation( |
sqlite3*, |
const char *zName, |
int eTextRep, |
void *pArg, |
int(*xCompare)(void*,int,const void*,int,const void*) |
); |
-SQLITE_API int SQLITE_STDCALL sqlite3_create_collation_v2( |
+SQLITE_API int sqlite3_create_collation_v2( |
sqlite3*, |
const char *zName, |
int eTextRep, |
@@ -4806,7 +5044,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_create_collation_v2( |
int(*xCompare)(void*,int,const void*,int,const void*), |
void(*xDestroy)(void*) |
); |
-SQLITE_API int SQLITE_STDCALL sqlite3_create_collation16( |
+SQLITE_API int sqlite3_create_collation16( |
sqlite3*, |
const void *zName, |
int eTextRep, |
@@ -4841,12 +5079,12 @@ SQLITE_API int SQLITE_STDCALL sqlite3_create_collation16( |
** [sqlite3_create_collation()], [sqlite3_create_collation16()], or |
** [sqlite3_create_collation_v2()]. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_collation_needed( |
+SQLITE_API int sqlite3_collation_needed( |
sqlite3*, |
void*, |
void(*)(void*,sqlite3*,int eTextRep,const char*) |
); |
-SQLITE_API int SQLITE_STDCALL sqlite3_collation_needed16( |
+SQLITE_API int sqlite3_collation_needed16( |
sqlite3*, |
void*, |
void(*)(void*,sqlite3*,int eTextRep,const void*) |
@@ -4860,11 +5098,11 @@ SQLITE_API int SQLITE_STDCALL sqlite3_collation_needed16( |
** The code to implement this API is not available in the public release |
** of SQLite. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_key( |
+SQLITE_API int sqlite3_key( |
sqlite3 *db, /* Database to be rekeyed */ |
const void *pKey, int nKey /* The key */ |
); |
-SQLITE_API int SQLITE_STDCALL sqlite3_key_v2( |
+SQLITE_API int sqlite3_key_v2( |
sqlite3 *db, /* Database to be rekeyed */ |
const char *zDbName, /* Name of the database */ |
const void *pKey, int nKey /* The key */ |
@@ -4878,11 +5116,11 @@ SQLITE_API int SQLITE_STDCALL sqlite3_key_v2( |
** The code to implement this API is not available in the public release |
** of SQLite. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_rekey( |
+SQLITE_API int sqlite3_rekey( |
sqlite3 *db, /* Database to be rekeyed */ |
const void *pKey, int nKey /* The new key */ |
); |
-SQLITE_API int SQLITE_STDCALL sqlite3_rekey_v2( |
+SQLITE_API int sqlite3_rekey_v2( |
sqlite3 *db, /* Database to be rekeyed */ |
const char *zDbName, /* Name of the database */ |
const void *pKey, int nKey /* The new key */ |
@@ -4892,7 +5130,7 @@ SQLITE_API int SQLITE_STDCALL 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 sqlite3_activate_see( |
+SQLITE_API void sqlite3_activate_see( |
const char *zPassPhrase /* Activation phrase */ |
); |
#endif |
@@ -4902,7 +5140,7 @@ SQLITE_API void SQLITE_STDCALL 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 sqlite3_activate_cerod( |
+SQLITE_API void sqlite3_activate_cerod( |
const char *zPassPhrase /* Activation phrase */ |
); |
#endif |
@@ -4924,7 +5162,7 @@ SQLITE_API void SQLITE_STDCALL sqlite3_activate_cerod( |
** all, then the behavior of sqlite3_sleep() may deviate from the description |
** in the previous paragraphs. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_sleep(int); |
+SQLITE_API int sqlite3_sleep(int); |
/* |
** CAPI3REF: Name Of The Folder Holding Temporary Files |
@@ -5043,7 +5281,7 @@ SQLITE_API SQLITE_EXTERN char *sqlite3_data_directory; |
** connection while this routine is running, then the return value |
** is undefined. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_get_autocommit(sqlite3*); |
+SQLITE_API int sqlite3_get_autocommit(sqlite3*); |
/* |
** CAPI3REF: Find The Database Handle Of A Prepared Statement |
@@ -5056,7 +5294,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_get_autocommit(sqlite3*); |
** to the [sqlite3_prepare_v2()] call (or its variants) that was used to |
** create the statement in the first place. |
*/ |
-SQLITE_API sqlite3 *SQLITE_STDCALL sqlite3_db_handle(sqlite3_stmt*); |
+SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*); |
/* |
** CAPI3REF: Return The Filename For A Database Connection |
@@ -5073,7 +5311,7 @@ SQLITE_API sqlite3 *SQLITE_STDCALL sqlite3_db_handle(sqlite3_stmt*); |
** 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 sqlite3_db_filename(sqlite3 *db, const char *zDbName); |
+SQLITE_API const char *sqlite3_db_filename(sqlite3 *db, const char *zDbName); |
/* |
** CAPI3REF: Determine if a database is read-only |
@@ -5083,7 +5321,7 @@ SQLITE_API const char *SQLITE_STDCALL sqlite3_db_filename(sqlite3 *db, const cha |
** 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 sqlite3_db_readonly(sqlite3 *db, const char *zDbName); |
+SQLITE_API int sqlite3_db_readonly(sqlite3 *db, const char *zDbName); |
/* |
** CAPI3REF: Find the next prepared statement |
@@ -5099,7 +5337,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_db_readonly(sqlite3 *db, const char *zDbNa |
** [sqlite3_next_stmt(D,S)] must refer to an open database |
** connection and in particular must not be a NULL pointer. |
*/ |
-SQLITE_API sqlite3_stmt *SQLITE_STDCALL sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt); |
+SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt); |
/* |
** CAPI3REF: Commit And Rollback Notification Callbacks |
@@ -5148,8 +5386,8 @@ SQLITE_API sqlite3_stmt *SQLITE_STDCALL sqlite3_next_stmt(sqlite3 *pDb, sqlite3_ |
** |
** See also the [sqlite3_update_hook()] interface. |
*/ |
-SQLITE_API void *SQLITE_STDCALL sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); |
-SQLITE_API void *SQLITE_STDCALL sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); |
+SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); |
+SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); |
/* |
** CAPI3REF: Data Change Notification Callbacks |
@@ -5158,7 +5396,7 @@ SQLITE_API void *SQLITE_STDCALL sqlite3_rollback_hook(sqlite3*, void(*)(void *), |
** ^The 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 +5417,7 @@ SQLITE_API void *SQLITE_STDCALL sqlite3_rollback_hook(sqlite3*, void(*)(void *), |
** ^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 +5435,10 @@ SQLITE_API void *SQLITE_STDCALL sqlite3_rollback_hook(sqlite3*, void(*)(void *), |
** on the same [database connection] D, or NULL for |
** the first call on D. |
** |
-** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()] |
-** interfaces. |
+** See also the [sqlite3_commit_hook()], [sqlite3_rollback_hook()], |
+** and [sqlite3_preupdate_hook()] interfaces. |
*/ |
-SQLITE_API void *SQLITE_STDCALL sqlite3_update_hook( |
+SQLITE_API void *sqlite3_update_hook( |
sqlite3*, |
void(*)(void *,int ,char const *,char const *,sqlite3_int64), |
void* |
@@ -5215,7 +5453,8 @@ SQLITE_API void *SQLITE_STDCALL 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 +5479,7 @@ SQLITE_API void *SQLITE_STDCALL sqlite3_update_hook( |
** |
** See Also: [SQLite Shared-Cache Mode] |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_enable_shared_cache(int); |
+SQLITE_API int sqlite3_enable_shared_cache(int); |
/* |
** CAPI3REF: Attempt To Free Heap Memory |
@@ -5256,7 +5495,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_enable_shared_cache(int); |
** |
** See also: [sqlite3_db_release_memory()] |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_release_memory(int); |
+SQLITE_API int sqlite3_release_memory(int); |
/* |
** CAPI3REF: Free Memory Used By A Database Connection |
@@ -5270,7 +5509,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_release_memory(int); |
** |
** See also: [sqlite3_release_memory()] |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_db_release_memory(sqlite3*); |
+SQLITE_API int sqlite3_db_release_memory(sqlite3*); |
/* |
** CAPI3REF: Impose A Limit On Heap Size |
@@ -5309,7 +5548,8 @@ SQLITE_API int SQLITE_STDCALL sqlite3_db_release_memory(sqlite3*); |
** 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 +5562,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_db_release_memory(sqlite3*); |
** The circumstances under which SQLite will enforce the soft heap limit may |
** changes in future releases of SQLite. |
*/ |
-SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_soft_heap_limit64(sqlite3_int64 N); |
+SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N); |
/* |
** CAPI3REF: Deprecated Soft Heap Limit Interface |
@@ -5333,7 +5573,7 @@ SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_soft_heap_limit64(sqlite3_int64 |
** only. All new applications should use the |
** [sqlite3_soft_heap_limit64()] interface rather than this one. |
*/ |
-SQLITE_API SQLITE_DEPRECATED void SQLITE_STDCALL sqlite3_soft_heap_limit(int N); |
+SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N); |
/* |
@@ -5348,7 +5588,7 @@ SQLITE_API SQLITE_DEPRECATED void SQLITE_STDCALL sqlite3_soft_heap_limit(int N); |
** column exists. ^The sqlite3_table_column_metadata() interface returns |
** SQLITE_ERROR and if the specified column does not exist. |
** ^If the column-name parameter to 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. |
** |
@@ -5403,7 +5643,7 @@ SQLITE_API SQLITE_DEPRECATED void SQLITE_STDCALL sqlite3_soft_heap_limit(int N); |
** 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 sqlite3_table_column_metadata( |
+SQLITE_API int sqlite3_table_column_metadata( |
sqlite3 *db, /* Connection handle */ |
const char *zDbName, /* Database name or NULL */ |
const char *zTableName, /* Table name */ |
@@ -5445,12 +5685,21 @@ SQLITE_API int SQLITE_STDCALL sqlite3_table_column_metadata( |
** should free this memory by calling [sqlite3_free()]. |
** |
** ^Extension loading must be enabled using |
-** [sqlite3_enable_load_extension()] prior to calling this API, |
+** [sqlite3_enable_load_extension()] or |
+** [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 [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 sqlite3_load_extension( |
+SQLITE_API int sqlite3_load_extension( |
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 +5719,19 @@ SQLITE_API int SQLITE_STDCALL sqlite3_load_extension( |
** ^Call the 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 |
+** [sqlite3_load_extension()] and the SQL function [load_extension()]. |
+** ^(Use [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 sqlite3_enable_load_extension(sqlite3 *db, int onoff); |
+SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff); |
/* |
** CAPI3REF: Automatically Load Statically Linked Extensions |
@@ -5483,7 +5743,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_enable_load_extension(sqlite3 *db, int ono |
** |
** ^(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 +5769,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_enable_load_extension(sqlite3 *db, int ono |
** See also: [sqlite3_reset_auto_extension()] |
** and [sqlite3_cancel_auto_extension()] |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_auto_extension(void (*xEntryPoint)(void)); |
+SQLITE_API int sqlite3_auto_extension(void(*xEntryPoint)(void)); |
/* |
** CAPI3REF: Cancel Automatic Extension Loading |
@@ -5521,7 +5781,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_auto_extension(void (*xEntryPoint)(void)); |
** unregistered and it returns 0 if X was not on the list of initialization |
** routines. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_cancel_auto_extension(void (*xEntryPoint)(void)); |
+SQLITE_API int sqlite3_cancel_auto_extension(void(*xEntryPoint)(void)); |
/* |
** CAPI3REF: Reset Automatic Extension Loading |
@@ -5529,7 +5789,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_cancel_auto_extension(void (*xEntryPoint)( |
** ^This interface disables all automatic extensions previously |
** registered using [sqlite3_auto_extension()]. |
*/ |
-SQLITE_API void SQLITE_STDCALL sqlite3_reset_auto_extension(void); |
+SQLITE_API void sqlite3_reset_auto_extension(void); |
/* |
** The interface to the virtual-table mechanism is currently considered |
@@ -5683,13 +5943,15 @@ struct sqlite3_module { |
** the xUpdate method are automatically rolled back by SQLite. |
** |
** IMPORTANT: The estimatedRows field was added to the 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 [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 |
** sqlite3_libversion_number() returns a value greater than or equal to |
** 3009000. |
*/ |
@@ -5697,7 +5959,7 @@ struct sqlite3_index_info { |
/* Inputs */ |
int nConstraint; /* Number of entries in aConstraint */ |
struct sqlite3_index_constraint { |
- int iColumn; /* Column on left-hand side of constraint */ |
+ int iColumn; /* Column constrained. -1 for ROWID */ |
unsigned char op; /* Constraint operator */ |
unsigned char usable; /* True if this constraint is usable */ |
int iTermOffset; /* Used internally - xBestIndex should ignore */ |
@@ -5774,13 +6036,13 @@ struct sqlite3_index_info { |
** interface is equivalent to sqlite3_create_module_v2() with a NULL |
** destructor. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_create_module( |
+SQLITE_API int sqlite3_create_module( |
sqlite3 *db, /* SQLite connection to register module with */ |
const char *zName, /* Name of the module */ |
const sqlite3_module *p, /* Methods for the module */ |
void *pClientData /* Client data for xCreate/xConnect */ |
); |
-SQLITE_API int SQLITE_STDCALL sqlite3_create_module_v2( |
+SQLITE_API int sqlite3_create_module_v2( |
sqlite3 *db, /* SQLite connection to register module with */ |
const char *zName, /* Name of the module */ |
const sqlite3_module *p, /* Methods for the module */ |
@@ -5843,7 +6105,7 @@ struct 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 sqlite3_declare_vtab(sqlite3*, const char *zSQL); |
+SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL); |
/* |
** CAPI3REF: Overload A Function For A Virtual Table |
@@ -5862,7 +6124,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_declare_vtab(sqlite3*, const char *zSQL); |
** purpose is to be a placeholder function that can be overloaded |
** by a [virtual table]. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); |
+SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); |
/* |
** The interface to the virtual-table mechanism defined above (back up |
@@ -5937,6 +6199,12 @@ typedef struct sqlite3_blob sqlite3_blob; |
** [database connection] error code and message accessible via |
** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions. |
** |
+** A BLOB referenced by sqlite3_blob_open() may be read using the |
+** [sqlite3_blob_read()] interface and modified by using |
+** [sqlite3_blob_write()]. The [BLOB handle] can be moved to a |
+** different row of the same table using the [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 +6228,12 @@ typedef struct sqlite3_blob sqlite3_blob; |
** |
** To avoid a resource leak, every open [BLOB handle] should eventually |
** be released by a call to [sqlite3_blob_close()]. |
+** |
+** See also: [sqlite3_blob_close()], |
+** [sqlite3_blob_reopen()], [sqlite3_blob_read()], |
+** [sqlite3_blob_bytes()], [sqlite3_blob_write()]. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_blob_open( |
+SQLITE_API int sqlite3_blob_open( |
sqlite3*, |
const char *zDb, |
const char *zTable, |
@@ -5975,11 +6247,11 @@ SQLITE_API int SQLITE_STDCALL sqlite3_blob_open( |
** CAPI3REF: Move a BLOB Handle to a New Row |
** METHOD: 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 [sqlite3_blob_open()] - |
@@ -5994,7 +6266,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_blob_open( |
** |
** ^This function sets the database handle error code and message. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64); |
+SQLITE_API int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64); |
/* |
** CAPI3REF: Close A BLOB Handle |
@@ -6017,7 +6289,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64) |
** is passed a valid open blob handle, the values returned by the |
** sqlite3_errcode() and sqlite3_errmsg() functions are set before returning. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_blob_close(sqlite3_blob *); |
+SQLITE_API int sqlite3_blob_close(sqlite3_blob *); |
/* |
** CAPI3REF: Return The Size Of An Open BLOB |
@@ -6033,7 +6305,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_blob_close(sqlite3_blob *); |
** been closed by [sqlite3_blob_close()]. Passing any other pointer in |
** to this routine results in undefined and probably undesirable behavior. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_blob_bytes(sqlite3_blob *); |
+SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *); |
/* |
** CAPI3REF: Read Data From A BLOB Incrementally |
@@ -6062,7 +6334,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_blob_bytes(sqlite3_blob *); |
** |
** See also: [sqlite3_blob_write()]. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset); |
+SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset); |
/* |
** CAPI3REF: Write Data Into A BLOB Incrementally |
@@ -6104,7 +6376,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_blob_read(sqlite3_blob *, void *Z, int N, |
** |
** See also: [sqlite3_blob_read()]. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); |
+SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); |
/* |
** CAPI3REF: Virtual File System Objects |
@@ -6135,9 +6407,9 @@ SQLITE_API int SQLITE_STDCALL sqlite3_blob_write(sqlite3_blob *, const void *z, |
** ^(If the default VFS is unregistered, another VFS is chosen as |
** the default. The choice for the new VFS is arbitrary.)^ |
*/ |
-SQLITE_API sqlite3_vfs *SQLITE_STDCALL sqlite3_vfs_find(const char *zVfsName); |
-SQLITE_API int SQLITE_STDCALL sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); |
-SQLITE_API int SQLITE_STDCALL sqlite3_vfs_unregister(sqlite3_vfs*); |
+SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); |
+SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); |
+SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*); |
/* |
** CAPI3REF: Mutexes |
@@ -6253,11 +6525,11 @@ SQLITE_API int SQLITE_STDCALL sqlite3_vfs_unregister(sqlite3_vfs*); |
** |
** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()]. |
*/ |
-SQLITE_API sqlite3_mutex *SQLITE_STDCALL sqlite3_mutex_alloc(int); |
-SQLITE_API void SQLITE_STDCALL sqlite3_mutex_free(sqlite3_mutex*); |
-SQLITE_API void SQLITE_STDCALL sqlite3_mutex_enter(sqlite3_mutex*); |
-SQLITE_API int SQLITE_STDCALL sqlite3_mutex_try(sqlite3_mutex*); |
-SQLITE_API void SQLITE_STDCALL sqlite3_mutex_leave(sqlite3_mutex*); |
+SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int); |
+SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*); |
+SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*); |
+SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*); |
+SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*); |
/* |
** CAPI3REF: Mutex Methods Object |
@@ -6367,8 +6639,8 @@ struct sqlite3_mutex_methods { |
** interface should also return 1 when given a NULL pointer. |
*/ |
#ifndef NDEBUG |
-SQLITE_API int SQLITE_STDCALL sqlite3_mutex_held(sqlite3_mutex*); |
-SQLITE_API int SQLITE_STDCALL sqlite3_mutex_notheld(sqlite3_mutex*); |
+SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*); |
+SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*); |
#endif |
/* |
@@ -6387,7 +6659,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_mutex_notheld(sqlite3_mutex*); |
#define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ |
#define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */ |
#define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */ |
-#define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */ |
+#define SQLITE_MUTEX_STATIC_PRNG 5 /* 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 /* sqlite3PageMalloc() */ |
@@ -6408,7 +6680,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_mutex_notheld(sqlite3_mutex*); |
** ^If the [threading mode] is Single-thread or Multi-thread then this |
** routine returns a NULL pointer. |
*/ |
-SQLITE_API sqlite3_mutex *SQLITE_STDCALL sqlite3_db_mutex(sqlite3*); |
+SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*); |
/* |
** CAPI3REF: Low-Level Control Of Database Files |
@@ -6443,7 +6715,7 @@ SQLITE_API sqlite3_mutex *SQLITE_STDCALL sqlite3_db_mutex(sqlite3*); |
** |
** See also: [SQLITE_FCNTL_LOCKSTATE] |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); |
+SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); |
/* |
** CAPI3REF: Testing Interface |
@@ -6462,7 +6734,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_file_control(sqlite3*, const char *zDbName |
** 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 sqlite3_test_control(int op, ...); |
+SQLITE_API int sqlite3_test_control(int op, ...); |
/* |
** CAPI3REF: Testing Interface Operation Codes |
@@ -6491,6 +6763,7 @@ SQLITE_API int SQLITE_CDECL 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 +6798,8 @@ SQLITE_API int SQLITE_CDECL sqlite3_test_control(int op, ...); |
** |
** See also: [sqlite3_db_status()] |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag); |
-SQLITE_API int SQLITE_STDCALL sqlite3_status64( |
+SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag); |
+SQLITE_API int sqlite3_status64( |
int op, |
sqlite3_int64 *pCurrent, |
sqlite3_int64 *pHighwater, |
@@ -6651,7 +6924,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_status64( |
** |
** See also: [sqlite3_status()] and [sqlite3_stmt_status()]. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg); |
+SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg); |
/* |
** CAPI3REF: Status Parameters for database connections |
@@ -6697,6 +6970,18 @@ SQLITE_API int SQLITE_STDCALL sqlite3_db_status(sqlite3*, int op, int *pCur, int |
** 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 +7039,8 @@ SQLITE_API int SQLITE_STDCALL sqlite3_db_status(sqlite3*, int op, int *pCur, int |
#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 +7067,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_db_status(sqlite3*, int op, int *pCur, int |
** |
** See also: [sqlite3_status()] and [sqlite3_db_status()]. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg); |
+SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg); |
/* |
** CAPI3REF: Status Parameters for prepared statements |
@@ -7108,7 +7394,7 @@ typedef struct sqlite3_backup sqlite3_backup; |
** must be different or else sqlite3_backup_init(D,N,S,M) will fail with |
** an error. |
** |
-** ^A call to sqlite3_backup_init() will fail, returning SQLITE_ERROR, if |
+** ^A call to sqlite3_backup_init() will fail, returning NULL, if |
** there is already a read or read-write transaction open on the |
** destination database. |
** |
@@ -7250,16 +7536,16 @@ typedef struct sqlite3_backup sqlite3_backup; |
** same time as another thread is invoking sqlite3_backup_step() it is |
** possible that they return invalid values. |
*/ |
-SQLITE_API sqlite3_backup *SQLITE_STDCALL sqlite3_backup_init( |
+SQLITE_API sqlite3_backup *sqlite3_backup_init( |
sqlite3 *pDest, /* Destination database handle */ |
const char *zDestName, /* Destination database name */ |
sqlite3 *pSource, /* Source database handle */ |
const char *zSourceName /* Source database name */ |
); |
-SQLITE_API int SQLITE_STDCALL sqlite3_backup_step(sqlite3_backup *p, int nPage); |
-SQLITE_API int SQLITE_STDCALL sqlite3_backup_finish(sqlite3_backup *p); |
-SQLITE_API int SQLITE_STDCALL sqlite3_backup_remaining(sqlite3_backup *p); |
-SQLITE_API int SQLITE_STDCALL sqlite3_backup_pagecount(sqlite3_backup *p); |
+SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage); |
+SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p); |
+SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p); |
+SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p); |
/* |
** CAPI3REF: Unlock Notification |
@@ -7376,7 +7662,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_backup_pagecount(sqlite3_backup *p); |
** the special "DROP TABLE/INDEX" case, the extended error code is just |
** SQLITE_LOCKED.)^ |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_unlock_notify( |
+SQLITE_API int sqlite3_unlock_notify( |
sqlite3 *pBlocked, /* Waiting connection */ |
void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */ |
void *pNotifyArg /* Argument to pass to xNotify */ |
@@ -7391,8 +7677,8 @@ SQLITE_API int SQLITE_STDCALL 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 sqlite3_stricmp(const char *, const char *); |
-SQLITE_API int SQLITE_STDCALL sqlite3_strnicmp(const char *, const char *, int); |
+SQLITE_API int sqlite3_stricmp(const char *, const char *); |
+SQLITE_API int sqlite3_strnicmp(const char *, const char *, int); |
/* |
** CAPI3REF: String Globbing |
@@ -7409,7 +7695,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_strnicmp(const char *, const char *, int); |
** |
** See also: [sqlite3_strlike()]. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_strglob(const char *zGlob, const char *zStr); |
+SQLITE_API int sqlite3_strglob(const char *zGlob, const char *zStr); |
/* Begin WebDatabase patch for Chromium */ |
/* Expose some SQLite internals for the WebDatabase vfs. |
@@ -7455,7 +7741,7 @@ int chromium_sqlite3_fill_in_unix_sqlite3_file(sqlite3_vfs* pVfs, |
** |
** See also: [sqlite3_strglob()]. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int cEsc); |
+SQLITE_API int sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int cEsc); |
/* |
** CAPI3REF: Error Logging Interface |
@@ -7478,7 +7764,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_strlike(const char *zGlob, const char *zSt |
** a few hundred characters, it will be truncated to the length of the |
** buffer. |
*/ |
-SQLITE_API void SQLITE_CDECL sqlite3_log(int iErrCode, const char *zFormat, ...); |
+SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...); |
/* |
** CAPI3REF: Write-Ahead Log Commit Hook |
@@ -7512,9 +7798,9 @@ SQLITE_API void SQLITE_CDECL sqlite3_log(int iErrCode, const char *zFormat, ...) |
** previously registered write-ahead log callback. ^Note that the |
** [sqlite3_wal_autocheckpoint()] interface and the |
** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will |
-** those overwrite any prior [sqlite3_wal_hook()] settings. |
+** overwrite any prior [sqlite3_wal_hook()] settings. |
*/ |
-SQLITE_API void *SQLITE_STDCALL sqlite3_wal_hook( |
+SQLITE_API void *sqlite3_wal_hook( |
sqlite3*, |
int(*)(void *,sqlite3*,const char*,int), |
void* |
@@ -7549,7 +7835,7 @@ SQLITE_API void *SQLITE_STDCALL sqlite3_wal_hook( |
** is only necessary if the default setting is found to be suboptimal |
** for a particular application. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_wal_autocheckpoint(sqlite3 *db, int N); |
+SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N); |
/* |
** CAPI3REF: Checkpoint a database |
@@ -7571,7 +7857,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_wal_autocheckpoint(sqlite3 *db, int N); |
** start a callback but which do not need the full power (and corresponding |
** complication) of [sqlite3_wal_checkpoint_v2()]. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb); |
+SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb); |
/* |
** CAPI3REF: Checkpoint a database |
@@ -7665,7 +7951,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_wal_checkpoint(sqlite3 *db, const char *zD |
** ^The [PRAGMA wal_checkpoint] command can be used to invoke this interface |
** from SQL. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_wal_checkpoint_v2( |
+SQLITE_API int sqlite3_wal_checkpoint_v2( |
sqlite3 *db, /* Database handle */ |
const char *zDb, /* Name of attached database (or NULL) */ |
int eMode, /* SQLITE_CHECKPOINT_* value */ |
@@ -7701,7 +7987,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_wal_checkpoint_v2( |
** this function. (See [SQLITE_VTAB_CONSTRAINT_SUPPORT].) Further options |
** may be added in the future. |
*/ |
-SQLITE_API int SQLITE_CDECL sqlite3_vtab_config(sqlite3*, int op, ...); |
+SQLITE_API int sqlite3_vtab_config(sqlite3*, int op, ...); |
/* |
** CAPI3REF: Virtual Table Configuration Options |
@@ -7754,7 +8040,7 @@ SQLITE_API int SQLITE_CDECL sqlite3_vtab_config(sqlite3*, int op, ...); |
** of the SQL statement that triggered the call to the [xUpdate] method of the |
** [virtual table]. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_vtab_on_conflict(sqlite3 *); |
+SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *); |
/* |
** CAPI3REF: Conflict resolution modes |
@@ -7859,7 +8145,7 @@ SQLITE_API int SQLITE_STDCALL sqlite3_vtab_on_conflict(sqlite3 *); |
** |
** See also: [sqlite3_stmt_scanstatus_reset()] |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_stmt_scanstatus( |
+SQLITE_API int sqlite3_stmt_scanstatus( |
sqlite3_stmt *pStmt, /* Prepared statement for which info desired */ |
int idx, /* Index of loop to report on */ |
int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */ |
@@ -7875,7 +8161,7 @@ SQLITE_API int SQLITE_STDCALL 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 sqlite3_stmt_scanstatus_reset(sqlite3_stmt*); |
+SQLITE_API void sqlite3_stmt_scanstatus_reset(sqlite3_stmt*); |
/* |
** CAPI3REF: Flush caches to disk mid-transaction |
@@ -7907,11 +8193,125 @@ SQLITE_API void SQLITE_STDCALL sqlite3_stmt_scanstatus_reset(sqlite3_stmt*); |
** ^This function does not set the database handle error code or message |
** returned by the [sqlite3_errcode()] and [sqlite3_errmsg()] functions. |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_db_cacheflush(sqlite3*); |
+SQLITE_API int sqlite3_db_cacheflush(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 [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 [sqlite3_preupdate_hook()] overrides |
+** the previous setting. |
+** ^The preupdate hook is disabled by invoking [sqlite3_preupdate_hook()] |
+** with a NULL pointer as the second parameter. |
+** ^The third parameter to [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 [sqlite3_preupdate_old()], [sqlite3_preupdate_new()], |
+** [sqlite3_preupdate_count()], and [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 [sqlite3_preupdate_count(D)] interface returns the number of columns |
+** in the row that is being inserted, updated, or deleted. |
+** |
+** ^The [sqlite3_preupdate_old(D,N,P)] interface writes into P a pointer to |
+** a [protected 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 [sqlite3_value] that P points to |
+** will be destroyed when the preupdate callback returns. |
+** |
+** ^The [sqlite3_preupdate_new(D,N,P)] interface writes into P a pointer to |
+** a [protected 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 [sqlite3_value] that P points to |
+** will be destroyed when the preupdate callback returns. |
+** |
+** ^The [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: [sqlite3_update_hook()] |
+*/ |
+#if defined(SQLITE_ENABLE_PREUPDATE_HOOK) |
+SQLITE_API void *sqlite3_preupdate_hook( |
+ sqlite3 *db, |
+ void(*xPreUpdate)( |
+ void *pCtx, /* Copy of third arg to preupdate_hook() */ |
+ sqlite3 *db, /* Database handle */ |
+ int op, /* SQLITE_UPDATE, DELETE or INSERT */ |
+ char const *zDb, /* Database name */ |
+ char const *zName, /* Table name */ |
+ sqlite3_int64 iKey1, /* Rowid of row about to be deleted/updated */ |
+ sqlite3_int64 iKey2 /* New rowid value (for a rowid UPDATE) */ |
+ ), |
+ void* |
+); |
+SQLITE_API int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **); |
+SQLITE_API int sqlite3_preupdate_count(sqlite3 *); |
+SQLITE_API int sqlite3_preupdate_depth(sqlite3 *); |
+SQLITE_API int sqlite3_preupdate_new(sqlite3 *, int, 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 |
+** [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 sqlite3_system_errno(sqlite3*); |
/* |
** CAPI3REF: Database Snapshot |
-** KEYWORDS: {snapshot} |
+** KEYWORDS: {snapshot} {sqlite3_snapshot} |
** EXPERIMENTAL |
** |
** An instance of the snapshot object records the state of a [WAL mode] |
@@ -7935,7 +8335,9 @@ SQLITE_API int SQLITE_STDCALL sqlite3_db_cacheflush(sqlite3*); |
** to an historical snapshot (if possible). The destructor for |
** sqlite3_snapshot objects is [sqlite3_snapshot_free()]. |
*/ |
-typedef struct sqlite3_snapshot sqlite3_snapshot; |
+typedef struct sqlite3_snapshot { |
+ unsigned char hidden[48]; |
+} sqlite3_snapshot; |
/* |
** CAPI3REF: Record A Database Snapshot |
@@ -7946,9 +8348,32 @@ typedef struct sqlite3_snapshot sqlite3_snapshot; |
** schema S in database connection D. ^On success, the |
** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly |
** created [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 [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 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 [sqlite3_snapshot] object returned from a successful call to |
** [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()] |
@@ -7957,7 +8382,7 @@ typedef struct sqlite3_snapshot sqlite3_snapshot; |
** The [sqlite3_snapshot_get()] interface is only available when the |
** SQLITE_ENABLE_SNAPSHOT compile-time option is used. |
*/ |
-SQLITE_API SQLITE_EXPERIMENTAL int SQLITE_STDCALL sqlite3_snapshot_get( |
+SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_get( |
sqlite3 *db, |
const char *zSchema, |
sqlite3_snapshot **ppSnapshot |
@@ -7967,22 +8392,35 @@ SQLITE_API SQLITE_EXPERIMENTAL int SQLITE_STDCALL sqlite3_snapshot_get( |
** CAPI3REF: Start a read transaction on an historical snapshot |
** EXPERIMENTAL |
** |
-** ^The [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 [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 [sqlite3_snapshot_open()] interface returns SQLITE_OK on success |
** or an appropriate [error code] if it fails. |
** |
** ^In order to succeed, a call to [sqlite3_snapshot_open(D,S,P)] must be |
-** the first operation, apart from other 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 [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 [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 [sqlite3_snapshot_open()] interface is only available when the |
** SQLITE_ENABLE_SNAPSHOT compile-time option is used. |
*/ |
-SQLITE_API SQLITE_EXPERIMENTAL int SQLITE_STDCALL sqlite3_snapshot_open( |
+SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_open( |
sqlite3 *db, |
const char *zSchema, |
sqlite3_snapshot *pSnapshot |
@@ -7999,7 +8437,56 @@ SQLITE_API SQLITE_EXPERIMENTAL int SQLITE_STDCALL sqlite3_snapshot_open( |
** The [sqlite3_snapshot_free()] interface is only available when the |
** SQLITE_ENABLE_SNAPSHOT compile-time option is used. |
*/ |
-SQLITE_API SQLITE_EXPERIMENTAL void SQLITE_STDCALL sqlite3_snapshot_free(sqlite3_snapshot*); |
+SQLITE_API SQLITE_EXPERIMENTAL void sqlite3_snapshot_free(sqlite3_snapshot*); |
+ |
+/* |
+** CAPI3REF: Compare the ages of two snapshot handles. |
+** EXPERIMENTAL |
+** |
+** The 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 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 sqlite3_snapshot_cmp( |
+ sqlite3_snapshot *p1, |
+ 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 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 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 |
+** 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 sqlite3_snapshot_recover(sqlite3 *db, const char *zDb); |
/* |
** Undo the hack that converts floating point types to integer for |
@@ -8012,8 +8499,9 @@ SQLITE_API SQLITE_EXPERIMENTAL void SQLITE_STDCALL sqlite3_snapshot_free(sqlite3 |
#ifdef __cplusplus |
} /* End of the 'extern "C"' block */ |
#endif |
-#endif /* _SQLITE3_H_ */ |
+#endif /* SQLITE3_H */ |
+/******** Begin file sqlite3rtree.h *********/ |
/* |
** 2010 August 30 |
** |
@@ -8053,7 +8541,7 @@ typedef struct sqlite3_rtree_query_info sqlite3_rtree_query_info; |
** |
** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...) |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_rtree_geometry_callback( |
+SQLITE_API int sqlite3_rtree_geometry_callback( |
sqlite3 *db, |
const char *zGeom, |
int (*xGeom)(sqlite3_rtree_geometry*, int, sqlite3_rtree_dbl*,int*), |
@@ -8079,7 +8567,7 @@ struct sqlite3_rtree_geometry { |
** |
** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zQueryFunc(... params ...) |
*/ |
-SQLITE_API int SQLITE_STDCALL sqlite3_rtree_query_callback( |
+SQLITE_API int sqlite3_rtree_query_callback( |
sqlite3 *db, |
const char *zQueryFunc, |
int (*xQueryFunc)(sqlite3_rtree_query_info*), |
@@ -8131,6 +8619,1298 @@ struct sqlite3_rtree_query_info { |
#endif /* ifndef _SQLITE3RTREE_H_ */ |
+/******** End of sqlite3rtree.h *********/ |
+/******** Begin file 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 sqlite3_session sqlite3_session; |
+ |
+/* |
+** CAPI3REF: Changeset Iterator Handle |
+*/ |
+typedef struct sqlite3_changeset_iter 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 |
+** [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 [sqlite3session_delete()] on the session object |
+** are undefined. |
+** |
+** Because the session module uses the [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 sqlite3session_create( |
+ sqlite3 *db, /* Database handle */ |
+ const char *zDb, /* Name of db (e.g. "main") */ |
+ sqlite3_session **ppSession /* OUT: New session object */ |
+); |
+ |
+/* |
+** CAPI3REF: Delete A Session Object |
+** |
+** Delete a session object previously allocated using |
+** [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 |
+** [sqlite3session_create()] for details. |
+*/ |
+SQLITE_API void sqlite3session_delete(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 [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 sqlite3session_enable(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 sqlite3session_indirect(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 [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 sqlite3session_attach( |
+ 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 sqlite3session_table_filter( |
+ 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 [sqlite3changeset_start()] API. A changeset may be applied to |
+** a database with a compatible schema using the [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 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 |
+** [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 [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 sqlite3session_changeset( |
+ 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 |
+** [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 [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 |
+** sqlite3_free(). |
+*/ |
+SQLITE_API int sqlite3session_diff( |
+ 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 |
+** sqlite3changeset_xxx API functions except for sqlite3changeset_invert(), |
+** which returns SQLITE_CORRUPT if it is passed a patchset. Similarly, |
+** attempting to use a patchset blob with old versions of the |
+** 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 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 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 sqlite3session_patchset( |
+ 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 |
+** [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 sqlite3session_changeset() will return a |
+** changeset containing zero changes. |
+*/ |
+SQLITE_API int sqlite3session_isempty(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> [sqlite3changeset_next()] |
+** <li> [sqlite3changeset_op()] |
+** <li> [sqlite3changeset_new()] |
+** <li> [sqlite3changeset_old()] |
+** </ul> |
+** |
+** It is the responsibility of the caller to eventually destroy the iterator |
+** by passing it to [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 |
+** [sqlite3session_changeset()], [sqlite3changeset_concat()] or |
+** [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 sqlite3changeset_start( |
+ 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 |
+** [sqlite3changeset_start()]. If it is called on an iterator passed to |
+** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE |
+** is returned and the call has no effect. |
+** |
+** Immediately after an iterator is created by 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 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 sqlite3changeset_next(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 [sqlite3changeset_apply()], or an iterator |
+** created by [sqlite3changeset_start()]. In the latter case, the most recent |
+** call to [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 |
+** 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 |
+** [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 sqlite3changeset_op( |
+ 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 sqlite3changeset_pk( |
+ 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 [sqlite3changeset_apply()], or an iterator |
+** created by [sqlite3changeset_start()]. In the latter case, the most recent |
+** call to [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 |
+** 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 sqlite3changeset_old( |
+ sqlite3_changeset_iter *pIter, /* Changeset iterator */ |
+ int iVal, /* Column number */ |
+ 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 [sqlite3changeset_apply()], or an iterator |
+** created by [sqlite3changeset_start()]. In the latter case, the most recent |
+** call to [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 |
+** 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 sqlite3changeset_new( |
+ sqlite3_changeset_iter *pIter, /* Changeset iterator */ |
+ int iVal, /* Column number */ |
+ 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 [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 |
+** 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 sqlite3changeset_conflict( |
+ sqlite3_changeset_iter *pIter, /* Changeset iterator */ |
+ int iVal, /* Column number */ |
+ 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 sqlite3changeset_fk_conflicts( |
+ 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 |
+** [sqlite3changeset_start()]. |
+** |
+** This function should only be called on iterators created using the |
+** [sqlite3changeset_start()] function. If an application calls this |
+** function with an iterator passed to a conflict-handler by |
+** [sqlite3changeset_apply()], [SQLITE_MISUSE] is immediately returned and the |
+** call has no effect. |
+** |
+** If an error was encountered within a call to an sqlite3changeset_xxx() |
+** function (for example an [SQLITE_CORRUPT] in [sqlite3changeset_next()] or an |
+** [SQLITE_NOMEM] in [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): |
+** |
+** sqlite3changeset_start(); |
+** while( SQLITE_ROW==sqlite3changeset_next() ){ |
+** // Do something with change. |
+** } |
+** rc = sqlite3changeset_finalize(); |
+** if( rc!=SQLITE_OK ){ |
+** // An error has occurred |
+** } |
+*/ |
+SQLITE_API int sqlite3changeset_finalize(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 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 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 |
+** sqlite3_changegroup object. Calling it produces similar results as the |
+** following code fragment: |
+** |
+** sqlite3_changegroup *pGrp; |
+** rc = sqlite3_changegroup_new(&pGrp); |
+** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nA, pA); |
+** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nB, pB); |
+** if( rc==SQLITE_OK ){ |
+** rc = sqlite3changegroup_output(pGrp, pnOut, ppOut); |
+** }else{ |
+** *ppOut = 0; |
+** *pnOut = 0; |
+** } |
+** |
+** Refer to the sqlite3_changegroup documentation below for details. |
+*/ |
+SQLITE_API int 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 sqlite3_changegroup sqlite3_changegroup; |
+ |
+/* |
+** CAPI3REF: Create A New Changegroup Object |
+** |
+** An 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 sqlite3_changegroup object before returning. The caller |
+** should eventually free the returned object using a call to |
+** 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 sqlite3_changegroup object is as follows: |
+** |
+** <ul> |
+** <li> It is created using a call to sqlite3changegroup_new(). |
+** |
+** <li> Zero or more changesets (or patchsets) are added to the object |
+** by calling sqlite3changegroup_add(). |
+** |
+** <li> The result of combining all input changesets together is obtained |
+** by the application via a call to sqlite3changegroup_output(). |
+** |
+** <li> The object is deleted using a call to 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 sqlite3changegroup_add() and |
+** sqlite3changegroup_output() functions, also available are the streaming |
+** versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm(). |
+*/ |
+int sqlite3changegroup_new(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. |
+*/ |
+int sqlite3changegroup_add(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 sqlite3session_changeset() and |
+** 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 sqlite3_free(). |
+*/ |
+int sqlite3changegroup_output( |
+ sqlite3_changegroup*, |
+ int *pnData, /* OUT: Size of output buffer in bytes */ |
+ void **ppData /* OUT: Pointer to output buffer */ |
+); |
+ |
+/* |
+** CAPI3REF: Delete A Changegroup Object |
+*/ |
+void sqlite3changegroup_delete(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 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 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 sqlite3changeset_apply() returns SQLITE_MISUSE. Different |
+** actions are taken by 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 sqlite3changeset_apply( |
+ 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 */ |
+ 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 |
+** 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 sqlite3_changeset_iter handle |
+** is 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 |
+** 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 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 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>sqlite3changeset_apply_str<td>[sqlite3changeset_apply] |
+** <tr><td>sqlite3changeset_concat_str<td>[sqlite3changeset_concat] |
+** <tr><td>sqlite3changeset_invert_str<td>[sqlite3changeset_invert] |
+** <tr><td>sqlite3changeset_start_str<td>[sqlite3changeset_start] |
+** <tr><td>sqlite3session_changeset_str<td>[sqlite3session_changeset] |
+** <tr><td>sqlite3session_patchset_str<td>[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 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 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 sqlite3changeset_apply_strm( |
+ 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 */ |
+ sqlite3_changeset_iter *p /* Handle describing change and conflict */ |
+ ), |
+ void *pCtx /* First argument passed to xConflict */ |
+); |
+SQLITE_API int 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 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 sqlite3changeset_start_strm( |
+ sqlite3_changeset_iter **pp, |
+ int (*xInput)(void *pIn, void *pData, int *pnData), |
+ void *pIn |
+); |
+SQLITE_API int sqlite3session_changeset_strm( |
+ sqlite3_session *pSession, |
+ int (*xOutput)(void *pOut, const void *pData, int nData), |
+ void *pOut |
+); |
+SQLITE_API int sqlite3session_patchset_strm( |
+ sqlite3_session *pSession, |
+ int (*xOutput)(void *pOut, const void *pData, int nData), |
+ void *pOut |
+); |
+int sqlite3changegroup_add_strm(sqlite3_changegroup*, |
+ int (*xInput)(void *pIn, void *pData, int *pnData), |
+ void *pIn |
+); |
+int sqlite3changegroup_output_strm(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 sqlite3session.h *********/ |
+/******** Begin file fts5.h *********/ |
/* |
** 2014 May 31 |
** |
@@ -8216,6 +9996,9 @@ struct Fts5PhraseIter { |
** an OOM condition or IO error), an appropriate SQLite error code is |
** returned. |
** |
+** This function may be quite inefficient if used with an FTS5 table |
+** created with the "columnsize=0" option. |
+** |
** xColumnText: |
** This function attempts to retrieve the text of column iCol of the |
** current document. If successful, (*pz) is set to point to a buffer |
@@ -8236,15 +10019,29 @@ struct Fts5PhraseIter { |
** the query within the current row. Return SQLITE_OK if successful, or |
** an error code (i.e. SQLITE_NOMEM) if an error occurs. |
** |
+** This API can be quite slow if used with an FTS5 table created with the |
+** "detail=none" or "detail=column" option. If the FTS5 table is created |
+** with either "detail=none" or "detail=column" and "content=" option |
+** (i.e. if it is a contentless table), then this API always returns 0. |
+** |
** xInst: |
** Query for the details of phrase match iIdx within the current row. |
** Phrase matches are numbered starting from zero, so the iIdx argument |
** should be greater than or equal to zero and smaller than the value |
** output by xInstCount(). |
** |
+** Usually, output parameter *piPhrase is set to the phrase number, *piCol |
+** to the column in which it occurs and *piOff the token offset of the |
+** first token of the phrase. The exception is if the table was created |
+** with the offsets=0 option specified. In this case *piOff is always |
+** set to -1. |
+** |
** Returns SQLITE_OK if successful, or an error code (i.e. SQLITE_NOMEM) |
** if an error occurs. |
** |
+** This API can be quite slow if used with an FTS5 table created with the |
+** "detail=none" or "detail=column" option. |
+** |
** xRowid: |
** Returns the rowid of the current row. |
** |
@@ -8258,11 +10055,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. |
@@ -8328,7 +10127,7 @@ struct Fts5PhraseIter { |
** Fts5PhraseIter iter; |
** int iCol, iOff; |
** for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff); |
-** iOff>=0; |
+** iCol>=0; |
** pApi->xPhraseNext(pFts, &iter, &iCol, &iOff) |
** ){ |
** // An instance of phrase iPhrase at offset iOff of column iCol |
@@ -8336,13 +10135,51 @@ struct Fts5PhraseIter { |
** |
** The Fts5PhraseIter structure is defined above. Applications should not |
** modify this structure directly - it should only be used as shown above |
-** with the xPhraseFirst() and xPhraseNext() API methods. |
+** with the xPhraseFirst() and xPhraseNext() API methods (and by |
+** xPhraseFirstColumn() and xPhraseNextColumn() as illustrated below). |
+** |
+** This API can be quite slow if used with an FTS5 table created with the |
+** "detail=none" or "detail=column" option. If the FTS5 table is created |
+** with either "detail=none" or "detail=column" and "content=" option |
+** (i.e. if it is a contentless table), then this API always iterates |
+** through an empty set (all calls to xPhraseFirst() set iCol to -1). |
** |
** xPhraseNext() |
** See xPhraseFirst above. |
+** |
+** xPhraseFirstColumn() |
+** This function and xPhraseNextColumn() are similar to the xPhraseFirst() |
+** and xPhraseNext() APIs described above. The difference is that instead |
+** of iterating through all instances of a phrase in the current row, these |
+** APIs are used to iterate through the set of columns in the current row |
+** that contain one or more instances of a specified phrase. For example: |
+** |
+** Fts5PhraseIter iter; |
+** int iCol; |
+** for(pApi->xPhraseFirstColumn(pFts, iPhrase, &iter, &iCol); |
+** iCol>=0; |
+** pApi->xPhraseNextColumn(pFts, &iter, &iCol) |
+** ){ |
+** // Column iCol contains at least one instance of phrase iPhrase |
+** } |
+** |
+** This API can be quite slow if used with an FTS5 table created with the |
+** "detail=none" option. If the FTS5 table is created with either |
+** "detail=none" "content=" option (i.e. if it is a contentless table), |
+** then this API always iterates through an empty set (all calls to |
+** xPhraseFirstColumn() set iCol to -1). |
+** |
+** The information accessed using this API and its companion |
+** xPhraseFirstColumn() may also be obtained using xPhraseFirst/xPhraseNext |
+** (or xInst/xInstCount). The chief advantage of this API is that it is |
+** significantly more efficient than those alternatives when used with |
+** "detail=column" tables. |
+** |
+** xPhraseNextColumn() |
+** See xPhraseFirstColumn above. |
*/ |
struct Fts5ExtensionApi { |
- int iVersion; /* Currently always set to 1 */ |
+ int iVersion; /* Currently always set to 3 */ |
void *(*xUserData)(Fts5Context*); |
@@ -8372,8 +10209,11 @@ struct Fts5ExtensionApi { |
int (*xSetAuxdata)(Fts5Context*, void *pAux, void(*xDelete)(void*)); |
void *(*xGetAuxdata)(Fts5Context*, int bClear); |
- void (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*); |
+ int (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*); |
void (*xPhraseNext)(Fts5Context*, Fts5PhraseIter*, int *piCol, int *piOff); |
+ |
+ int (*xPhraseFirstColumn)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*); |
+ void (*xPhraseNextColumn)(Fts5Context*, Fts5PhraseIter*, int *piCol); |
}; |
/* |
@@ -8390,7 +10230,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*) |
@@ -8650,4 +10490,4 @@ struct fts5_api { |
#endif /* _FTS5_H */ |
- |
+/******** End of fts5.h *********/ |