@ -1,7 +1,3 @@
/** @file
* @ brief sqlite3 interface
*/
/*
* * 2001 - 09 - 15
* *
@ -47,7 +43,30 @@ extern "C" {
/*
* * Provide the ability to override linkage features of the interface .
* * Facilitate override of interface linkage and calling conventions .
* * Be aware that these macros may not be used within this particular
* * translation of the amalgamation and its associated header file .
* *
* * The SQLITE_EXTERN and SQLITE_API macros are used to instruct the
* * compiler that the target identifier should have external linkage .
* *
* * The SQLITE_CDECL macro is used to set the calling convention for
* * public functions that accept a variable number of arguments .
* *
* * The SQLITE_APICALL macro is used to set the calling convention for
* * public functions that accept a fixed number of arguments .
* *
* * The SQLITE_STDCALL macro is no longer used and is now deprecated .
* *
* * The SQLITE_CALLBACK macro is used to set the calling convention for
* * function pointers .
* *
* * The SQLITE_SYSAPI macro is used to set the calling convention for
* * functions provided by the operating system .
* *
* * Currently , the SQLITE_CDECL , SQLITE_APICALL , SQLITE_CALLBACK , and
* * SQLITE_SYSAPI macros are used only when building for environments
* * that require non - default calling conventions .
*/
# ifndef SQLITE_EXTERN
# define SQLITE_EXTERN extern
@ -127,9 +146,9 @@ extern "C" {
* * [ sqlite3_libversion_number ( ) ] , [ sqlite3_sourceid ( ) ] ,
* * [ sqlite_version ( ) ] and [ sqlite_source_id ( ) ] .
*/
# define SQLITE_VERSION "3.3 6.0 "
# define SQLITE_VERSION_NUMBER 303 6000
# define SQLITE_SOURCE_ID "202 1-06-18 18:36:39 5c9a6c06871cb9fe42814af9c039eb6da5427a6ec28f187af7ebfb62eafa66e5 "
# define SQLITE_VERSION "3.3 9.4 "
# define SQLITE_VERSION_NUMBER 303 9004
# define SQLITE_SOURCE_ID "202 2-09-29 15:55:41 a29f9949895322123f7c38fbe94c649a9d6e6c9cd0c3b41c96d694552f26b309 "
/*
* * CAPI3REF : Run - Time Library Version Numbers
@ -541,12 +560,13 @@ SQLITE_API int sqlite3_exec(
# define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT | (9<<8))
# define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT |(10<<8))
# define SQLITE_CONSTRAINT_PINNED (SQLITE_CONSTRAINT |(11<<8))
# define SQLITE_CONSTRAINT_DATATYPE (SQLITE_CONSTRAINT |(12<<8))
# define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1<<8))
# define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8))
# define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8))
# define SQLITE_AUTH_USER (SQLITE_AUTH | (1<<8))
# define SQLITE_OK_LOAD_PERMANENTLY (SQLITE_OK | (1<<8))
# define SQLITE_OK_SYMLINK (SQLITE_OK | (2<<8))
# define SQLITE_OK_SYMLINK (SQLITE_OK | (2<<8)) /* internal use only */
/*
* * CAPI3REF : Flags For File Open Operations
@ -554,6 +574,19 @@ SQLITE_API int sqlite3_exec(
* * These bit values are intended for use in the
* * 3 rd parameter to the [ sqlite3_open_v2 ( ) ] interface and
* * in the 4 th parameter to the [ sqlite3_vfs . xOpen ] method .
* *
* * Only those flags marked as " Ok for sqlite3_open_v2() " may be
* * used as the third argument to the [ sqlite3_open_v2 ( ) ] interface .
* * The other flags have historically been ignored by sqlite3_open_v2 ( ) ,
* * though future versions of SQLite might change so that an error is
* * raised if any of the disallowed bits are passed into sqlite3_open_v2 ( ) .
* * Applications should not depend on the historical behavior .
* *
* * Note in particular that passing the SQLITE_OPEN_EXCLUSIVE flag into
* * [ sqlite3_open_v2 ( ) ] does * not * cause the underlying database file
* * to be opened using O_EXCL . Passing SQLITE_OPEN_EXCLUSIVE into
* * [ sqlite3_open_v2 ( ) ] has historically be a no - op and might become an
* * error in future versions of SQLite .
*/
# define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */
# define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */
@ -576,6 +609,7 @@ SQLITE_API int sqlite3_exec(
# define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */
# define SQLITE_OPEN_WAL 0x00080000 /* VFS only */
# define SQLITE_OPEN_NOFOLLOW 0x01000000 /* Ok for sqlite3_open_v2() */
# define SQLITE_OPEN_EXRESCODE 0x02000000 /* Extended result codes */
/* Reserved: 0x00F00000 */
/* Legacy compatibility: */
@ -2468,11 +2502,14 @@ SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
* * CAPI3REF : Count The Number Of Rows Modified
* * METHOD : sqlite3
* *
* * ^ Th is function returns the number of rows modified , inserted or
* * ^ Th ese functions return the number of rows modified , inserted or
* * deleted by the most recently completed INSERT , UPDATE or DELETE
* * statement on the database connection specified by the only parameter .
* * ^ Executing any other type of SQL statement does not modify the value
* * returned by this function .
* * The two functions are identical except for the type of the return value
* * and that if the number of rows modified by the most recent INSERT , UPDATE
* * or DELETE is greater than the maximum value supported by type " int " , then
* * the return value of sqlite3_changes ( ) is undefined . ^ Executing any other
* * type of SQL statement does not modify the value returned by these functions .
* *
* * ^ Only changes made directly by the INSERT , UPDATE or DELETE statement are
* * considered - auxiliary changes caused by [ CREATE TRIGGER | triggers ] ,
@ -2521,16 +2558,21 @@ SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
* * < / ul >
*/
SQLITE_API int sqlite3_changes ( sqlite3 * ) ;
SQLITE_API sqlite3_int64 sqlite3_changes64 ( sqlite3 * ) ;
/*
* * CAPI3REF : Total Number Of Rows Modified
* * METHOD : sqlite3
* *
* * ^ Th is function returns the total number of rows inserted , modified or
* * ^ Th ese functions return the total number of rows inserted , modified or
* * deleted by all [ INSERT ] , [ UPDATE ] or [ DELETE ] statements completed
* * since the database connection was opened , including those executed as
* * part of trigger programs . ^ Executing any other type of SQL statement
* * does not affect the value returned by sqlite3_total_changes ( ) .
* * part of trigger programs . The two functions are identical except for the
* * type of the return value and that if the number of rows modified by the
* * connection exceeds the maximum value supported by type " int " , then
* * the return value of sqlite3_total_changes ( ) is undefined . ^ Executing
* * any other type of SQL statement does not affect the value returned by
* * sqlite3_total_changes ( ) .
* *
* * ^ Changes made as part of [ foreign key actions ] are included in the
* * count , but those made as part of REPLACE constraint resolution are
@ -2558,6 +2600,7 @@ SQLITE_API int sqlite3_changes(sqlite3*);
* * < / ul >
*/
SQLITE_API int sqlite3_total_changes ( sqlite3 * ) ;
SQLITE_API sqlite3_int64 sqlite3_total_changes64 ( sqlite3 * ) ;
/*
* * CAPI3REF : Interrupt A Long - Running Query
@ -3387,6 +3430,14 @@ SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
* * the default shared cache setting provided by
* * [ sqlite3_enable_shared_cache ( ) ] . ) ^
* *
* * [ [ OPEN_EXRESCODE ] ] ^ ( < dt > [ SQLITE_OPEN_EXRESCODE ] < / dt >
* * < dd > The database connection comes up in " extended result code mode " .
* * In other words , the database behaves has if
* * [ sqlite3_extended_result_codes ( db , 1 ) ] where called on the database
* * connection as soon as the connection is created . In addition to setting
* * the extended result code mode , this flag also causes [ sqlite3_open_v2 ( ) ]
* * to return an extended result code . < / dd >
* *
* * [ [ OPEN_NOFOLLOW ] ] ^ ( < dt > [ SQLITE_OPEN_NOFOLLOW ] < / dt >
* * < dd > The database filename is not allowed to be a symbolic link < / dd >
* * < / dl > ) ^
@ -3394,7 +3445,15 @@ SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
* * If the 3 rd parameter to sqlite3_open_v2 ( ) is not one of the
* * required combinations shown above optionally combined with other
* * [ SQLITE_OPEN_READONLY | SQLITE_OPEN_ * bits ]
* * then the behavior is undefined .
* * then the behavior is undefined . Historic versions of SQLite
* * have silently ignored surplus bits in the flags parameter to
* * sqlite3_open_v2 ( ) , however that behavior might not be carried through
* * into future versions of SQLite and so applications should not rely
* * upon it . Note in particular that the SQLITE_OPEN_EXCLUSIVE flag is a no - op
* * for sqlite3_open_v2 ( ) . The SQLITE_OPEN_EXCLUSIVE does * not * cause
* * the open to fail if the database already exists . The SQLITE_OPEN_EXCLUSIVE
* * flag is intended for use by the [ sqlite3_vfs | VFS interface ] only , and not
* * by sqlite3_open_v2 ( ) .
* *
* * ^ The fourth parameter to sqlite3_open_v2 ( ) is the name of the
* * [ sqlite3_vfs ] object that defines the operating system interface that
@ -3765,13 +3824,14 @@ SQLITE_API void sqlite3_free_filename(char*);
* * sqlite3_extended_errcode ( ) might change with each API call .
* * Except , there are some interfaces that are guaranteed to never
* * change the value of the error code . The error - code preserving
* * interfaces are :
* * interfaces include the following :
* *
* * < ul >
* * < li > sqlite3_errcode ( )
* * < li > sqlite3_extended_errcode ( )
* * < li > sqlite3_errmsg ( )
* * < li > sqlite3_errmsg16 ( )
* * < li > sqlite3_error_offset ( )
* * < / ul >
* *
* * ^ The sqlite3_errmsg ( ) and sqlite3_errmsg16 ( ) return English - language
@ -3786,6 +3846,13 @@ SQLITE_API void sqlite3_free_filename(char*);
* * ^ ( Memory to hold the error message string is managed internally
* * and must not be freed by the application ) ^ .
* *
* * ^ If the most recent error references a specific token in the input
* * SQL , the sqlite3_error_offset ( ) interface returns the byte offset
* * of the start of that token . ^ The byte offset returned by
* * sqlite3_error_offset ( ) assumes that the input SQL is UTF8 .
* * ^ If the most recent error does not reference a specific token in the input
* * SQL , then the sqlite3_error_offset ( ) function returns - 1.
* *
* * When the serialized [ threading mode ] is in use , it might be the
* * case that a second error occurs on a separate thread in between
* * the time of the first error and the call to these interfaces .
@ -3805,6 +3872,7 @@ 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 ) ;
SQLITE_API int sqlite3_error_offset ( sqlite3 * db ) ;
/*
* * CAPI3REF : Prepared Statement Object
@ -4162,12 +4230,17 @@ SQLITE_API int sqlite3_prepare16_v3(
* * are managed by SQLite and are 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
* * is obtained from [ sqlite3_malloc ( ) ] and must be free d by the application
* * by passing it to [ sqlite3_free ( ) ] .
* *
* * ^ The sqlite3_normalized_sql ( ) interface is only available if
* * the [ SQLITE_ENABLE_NORMALIZE ] compile - time option is defined .
*/
SQLITE_API const char * sqlite3_sql ( sqlite3_stmt * pStmt ) ;
SQLITE_API char * sqlite3_expanded_sql ( sqlite3_stmt * pStmt ) ;
# ifdef SQLITE_ENABLE_NORMALIZE
SQLITE_API const char * sqlite3_normalized_sql ( sqlite3_stmt * pStmt ) ;
# endif
/*
* * CAPI3REF : Determine If An SQL Statement Writes The Database
@ -4211,6 +4284,10 @@ SQLITE_API const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt);
* * be false . ^ Similarly , a CREATE TABLE IF NOT EXISTS statement is a
* * read - only no - op if the table already exists , but
* * sqlite3_stmt_readonly ( ) still returns false for such a statement .
* *
* * ^ If prepared statement X is an [ EXPLAIN ] or [ EXPLAIN QUERY PLAN ]
* * statement , then sqlite3_stmt_readonly ( X ) returns the same value as
* * if the EXPLAIN or EXPLAIN QUERY PLAN prefix were omitted .
*/
SQLITE_API int sqlite3_stmt_readonly ( sqlite3_stmt * pStmt ) ;
@ -4279,6 +4356,8 @@ SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*);
* *
* * ^ The sqlite3_value objects that are passed as parameters into the
* * implementation of [ application - defined SQL functions ] are protected .
* * ^ The sqlite3_value objects returned by [ sqlite3_vtab_rhs_value ( ) ]
* * are protected .
* * ^ The sqlite3_value object returned by
* * [ sqlite3_column_value ( ) ] is unprotected .
* * Unprotected sqlite3_value objects may only be used as arguments
@ -4900,6 +4979,10 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
* * even empty strings , are always zero - terminated . ^ The return
* * value from sqlite3_column_blob ( ) for a zero - length BLOB is a NULL pointer .
* *
* * ^ Strings returned by sqlite3_column_text16 ( ) always have the endianness
* * which is native to the platform , regardless of the text encoding set
* * for the database .
* *
* * < b > Warning : < / b > ^ The object returned by [ sqlite3_column_value ( ) ] is an
* * [ unprotected sqlite3_value ] object . In a multithreaded environment ,
* * an unprotected sqlite3_value object may only be used safely with
@ -4913,7 +4996,7 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
* * [ application - defined SQL functions ] or [ virtual tables ] , not within
* * top - level application code .
* *
* * The the se routines may attempt to convert the datatype of the result .
* * The se routines may attempt to convert the datatype of the result .
* * ^ For example , if the internal representation is FLOAT and a text result
* * is requested , [ sqlite3_snprintf ( ) ] is used internally to perform the
* * conversion automatically . ^ ( The following table details the conversions
@ -4938,7 +5021,7 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
* * < tr > < td > TEXT < td > BLOB < td > No change
* * < tr > < td > BLOB < td > INTEGER < td > [ CAST ] to INTEGER
* * < tr > < td > BLOB < td > FLOAT < td > [ CAST ] to REAL
* * < tr > < td > BLOB < td > TEXT < td > Add a zero terminator if needed
* * < tr > < td > BLOB < td > TEXT < td > [ CAST ] to TEXT , ensure zero terminator
* * < / table >
* * < / blockquote > ) ^
* *
@ -5510,7 +5593,8 @@ SQLITE_API unsigned int sqlite3_value_subtype(sqlite3_value*);
* * object D and returns a pointer to that copy . ^ The [ sqlite3_value ] returned
* * is a [ protected sqlite3_value ] object even if the input is not .
* * ^ The sqlite3_value_dup ( V ) interface returns NULL if V is NULL or if a
* * memory allocation fails .
* * memory allocation fails . ^ If V is a [ pointer value ] , then the result
* * of sqlite3_value_dup ( V ) is a NULL value .
* *
* * ^ The sqlite3_value_free ( V ) interface frees an [ sqlite3_value ] object
* * previously obtained from [ sqlite3_value_dup ( ) ] . ^ If V is a NULL pointer
@ -6192,6 +6276,28 @@ SQLITE_API int sqlite3_get_autocommit(sqlite3*);
*/
SQLITE_API sqlite3 * sqlite3_db_handle ( sqlite3_stmt * ) ;
/*
* * CAPI3REF : Return The Schema Name For A Database Connection
* * METHOD : sqlite3
* *
* * ^ The sqlite3_db_name ( D , N ) interface returns a pointer to the schema name
* * for the N - th database on database connection D , or a NULL pointer of N is
* * out of range . An N value of 0 means the main database file . An N of 1 is
* * the " temp " schema . Larger values of N correspond to various ATTACH - ed
* * databases .
* *
* * Space to hold the string that is returned by sqlite3_db_name ( ) is managed
* * by SQLite itself . The string might be deallocated by any operation that
* * changes the schema , including [ ATTACH ] or [ DETACH ] or calls to
* * [ sqlite3_serialize ( ) ] or [ sqlite3_deserialize ( ) ] , even operations that
* * occur on a different thread . Applications that need to
* * remember the string long - term should make their own copy . Applications that
* * are accessing the same database connection simultaneously on multiple
* * threads should mutex - protect calls to this API and should make their own
* * private copy of the result prior to releasing the mutex .
*/
SQLITE_API const char * sqlite3_db_name ( sqlite3 * db , int N ) ;
/*
* * CAPI3REF : Return The Filename For A Database Connection
* * METHOD : sqlite3
@ -6351,6 +6457,72 @@ SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
SQLITE_API void * sqlite3_commit_hook ( sqlite3 * , int ( * ) ( void * ) , void * ) ;
SQLITE_API void * sqlite3_rollback_hook ( sqlite3 * , void ( * ) ( void * ) , void * ) ;
/*
* * CAPI3REF : Autovacuum Compaction Amount Callback
* * METHOD : sqlite3
* *
* * ^ The sqlite3_autovacuum_pages ( D , C , P , X ) interface registers a callback
* * function C that is invoked prior to each autovacuum of the database
* * file . ^ The callback is passed a copy of the generic data pointer ( P ) ,
* * the schema - name of the attached database that is being autovacuumed ,
* * the the size of the database file in pages , the number of free pages ,
* * and the number of bytes per page , respectively . The callback should
* * return the number of free pages that should be removed by the
* * autovacuum . ^ If the callback returns zero , then no autovacuum happens .
* * ^ If the value returned is greater than or equal to the number of
* * free pages , then a complete autovacuum happens .
* *
* * < p > ^ If there are multiple ATTACH - ed database files that are being
* * modified as part of a transaction commit , then the autovacuum pages
* * callback is invoked separately for each file .
* *
* * < p > < b > The callback is not reentrant . < / b > The callback function should
* * not attempt to invoke any other SQLite interface . If it does , bad
* * things may happen , including segmentation faults and corrupt database
* * files . The callback function should be a simple function that
* * does some arithmetic on its input parameters and returns a result .
* *
* * ^ The X parameter to sqlite3_autovacuum_pages ( D , C , P , X ) is an optional
* * destructor for the P parameter . ^ If X is not NULL , then X ( P ) is
* * invoked whenever the database connection closes or when the callback
* * is overwritten by another invocation of sqlite3_autovacuum_pages ( ) .
* *
* * < p > ^ There is only one autovacuum pages callback per database connection .
* * ^ Each call to the sqlite3_autovacuum_pages ( ) interface overrides all
* * previous invocations for that database connection . ^ If the callback
* * argument ( C ) to sqlite3_autovacuum_pages ( D , C , P , X ) is a NULL pointer ,
* * then the autovacuum steps callback is cancelled . The return value
* * from sqlite3_autovacuum_pages ( ) is normally SQLITE_OK , but might
* * be some other error code if something goes wrong . The current
* * implementation will only return SQLITE_OK or SQLITE_MISUSE , but other
* * return codes might be added in future releases .
* *
* * < p > If no autovacuum pages callback is specified ( the usual case ) or
* * a NULL pointer is provided for the callback ,
* * then the default behavior is to vacuum all free pages . So , in other
* * words , the default behavior is the same as if the callback function
* * were something like this :
* *
* * < blockquote > < pre >
* * & nbsp ; unsigned int demonstration_autovac_pages_callback (
* * & nbsp ; void * pClientData ,
* * & nbsp ; const char * zSchema ,
* * & nbsp ; unsigned int nDbPage ,
* * & nbsp ; unsigned int nFreePage ,
* * & nbsp ; unsigned int nBytePerPage
* * & nbsp ; ) {
* * & nbsp ; return nFreePage ;
* * & nbsp ; }
* * < / pre > < / blockquote >
*/
SQLITE_API int sqlite3_autovacuum_pages (
sqlite3 * db ,
unsigned int ( * ) ( void * , const char * , unsigned int , unsigned int , unsigned int ) ,
void * ,
void ( * ) ( void * )
) ;
/*
* * CAPI3REF : Data Change Notification Callbacks
* * METHOD : sqlite3
@ -6992,24 +7164,56 @@ struct sqlite3_index_info {
* *
* * These macros define the allowed values for the
* * [ sqlite3_index_info ] . aConstraint [ ] . op field . Each value represents
* * an operator that is part of a constraint term in the w HERE clause of
* * an operator that is part of a constraint term in the W HERE clause of
* * a query that uses a [ virtual table ] .
*/
# define SQLITE_INDEX_CONSTRAINT_EQ 2
# define SQLITE_INDEX_CONSTRAINT_GT 4
# define SQLITE_INDEX_CONSTRAINT_LE 8
# define SQLITE_INDEX_CONSTRAINT_LT 16
# define SQLITE_INDEX_CONSTRAINT_GE 32
# define SQLITE_INDEX_CONSTRAINT_MATCH 64
# define SQLITE_INDEX_CONSTRAINT_LIKE 65
# define SQLITE_INDEX_CONSTRAINT_GLOB 66
# define SQLITE_INDEX_CONSTRAINT_REGEXP 67
# define SQLITE_INDEX_CONSTRAINT_NE 68
# define SQLITE_INDEX_CONSTRAINT_ISNOT 69
# define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70
# define SQLITE_INDEX_CONSTRAINT_ISNULL 71
# define SQLITE_INDEX_CONSTRAINT_IS 72
# define SQLITE_INDEX_CONSTRAINT_FUNCTION 150
* *
* * ^ The left - hand operand of the operator is given by the corresponding
* * aConstraint [ ] . iColumn field . ^ An iColumn of - 1 indicates the left - hand
* * operand is the rowid .
* * The SQLITE_INDEX_CONSTRAINT_LIMIT and SQLITE_INDEX_CONSTRAINT_OFFSET
* * operators have no left - hand operand , and so for those operators the
* * corresponding aConstraint [ ] . iColumn is meaningless and should not be
* * used .
* *
* * All operator values from SQLITE_INDEX_CONSTRAINT_FUNCTION through
* * value 255 are reserved to represent functions that are overloaded
* * by the [ xFindFunction | xFindFunction method ] of the virtual table
* * implementation .
* *
* * The right - hand operands for each constraint might be accessible using
* * the [ sqlite3_vtab_rhs_value ( ) ] interface . Usually the right - hand
* * operand is only available if it appears as a single constant literal
* * in the input SQL . If the right - hand operand is another column or an
* * expression ( even a constant expression ) or a parameter , then the
* * sqlite3_vtab_rhs_value ( ) probably will not be able to extract it .
* * ^ The SQLITE_INDEX_CONSTRAINT_ISNULL and
* * SQLITE_INDEX_CONSTRAINT_ISNOTNULL operators have no right - hand operand
* * and hence calls to sqlite3_vtab_rhs_value ( ) for those operators will
* * always return SQLITE_NOTFOUND .
* *
* * The collating sequence to be used for comparison can be found using
* * the [ sqlite3_vtab_collation ( ) ] interface . For most real - world virtual
* * tables , the collating sequence of constraints does not matter ( for example
* * because the constraints are numeric ) and so the sqlite3_vtab_collation ( )
* * interface is no commonly needed .
*/
# define SQLITE_INDEX_CONSTRAINT_EQ 2
# define SQLITE_INDEX_CONSTRAINT_GT 4
# define SQLITE_INDEX_CONSTRAINT_LE 8
# define SQLITE_INDEX_CONSTRAINT_LT 16
# define SQLITE_INDEX_CONSTRAINT_GE 32
# define SQLITE_INDEX_CONSTRAINT_MATCH 64
# define SQLITE_INDEX_CONSTRAINT_LIKE 65
# define SQLITE_INDEX_CONSTRAINT_GLOB 66
# define SQLITE_INDEX_CONSTRAINT_REGEXP 67
# define SQLITE_INDEX_CONSTRAINT_NE 68
# define SQLITE_INDEX_CONSTRAINT_ISNOT 69
# define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70
# define SQLITE_INDEX_CONSTRAINT_ISNULL 71
# define SQLITE_INDEX_CONSTRAINT_IS 72
# define SQLITE_INDEX_CONSTRAINT_LIMIT 73
# define SQLITE_INDEX_CONSTRAINT_OFFSET 74
# define SQLITE_INDEX_CONSTRAINT_FUNCTION 150
/*
* * CAPI3REF : Register A Virtual Table Implementation
@ -7038,7 +7242,7 @@ struct sqlite3_index_info {
* * destructor .
* *
* * ^ If the third parameter ( the pointer to the sqlite3_module object ) is
* * NULL then no new module is create and any existing modules with the
* * NULL then no new module is create d and any existing modules with the
* * same name are dropped .
* *
* * See also : [ sqlite3_drop_modules ( ) ]
@ -7814,7 +8018,8 @@ SQLITE_API int sqlite3_test_control(int op, ...);
# define SQLITE_TESTCTRL_SEEK_COUNT 30
# define SQLITE_TESTCTRL_TRACEFLAGS 31
# define SQLITE_TESTCTRL_TUNE 32
# define SQLITE_TESTCTRL_LAST 32 /* Largest TESTCTRL */
# define SQLITE_TESTCTRL_LOGEST 33
# define SQLITE_TESTCTRL_LAST 33 /* Largest TESTCTRL */
/*
* * CAPI3REF : SQL Keyword Checking
@ -8337,6 +8542,16 @@ SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
* * The counter is incremented on the first [ sqlite3_step ( ) ] call of each
* * cycle .
* *
* * [ [ SQLITE_STMTSTATUS_FILTER_MISS ] ]
* * [ [ SQLITE_STMTSTATUS_FILTER HIT ] ]
* * < dt > SQLITE_STMTSTATUS_FILTER_HIT < br >
* * SQLITE_STMTSTATUS_FILTER_MISS < / dt >
* * < dd > ^ SQLITE_STMTSTATUS_FILTER_HIT is the number of times that a join
* * step was bypassed because a Bloom filter returned not - found . The
* * corresponding SQLITE_STMTSTATUS_FILTER_MISS value is the number of
* * times that the Bloom filter returned a find , and thus the join step
* * had to be processed as normal .
* *
* * [ [ SQLITE_STMTSTATUS_MEMUSED ] ] < dt > SQLITE_STMTSTATUS_MEMUSED < / dt >
* * < dd > ^ This is the approximate number of bytes of heap memory
* * used to store the prepared statement . ^ This value is not actually
@ -8351,6 +8566,8 @@ SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
# define SQLITE_STMTSTATUS_VM_STEP 4
# define SQLITE_STMTSTATUS_REPREPARE 5
# define SQLITE_STMTSTATUS_RUN 6
# define SQLITE_STMTSTATUS_FILTER_MISS 7
# define SQLITE_STMTSTATUS_FILTER_HIT 8
# define SQLITE_STMTSTATUS_MEMUSED 99
/*
@ -9014,8 +9231,9 @@ SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
* *
* * A single database handle may have at most a single write - ahead log callback
* * registered at one time . ^ Calling [ sqlite3_wal_hook ( ) ] replaces any
* * previously registered write - ahead log callback . ^ Note that the
* * [ sqlite3_wal_autocheckpoint ( ) ] interface and the
* * previously registered write - ahead log callback . ^ The return value is
* * a copy of the third parameter from the previous call , if any , or 0.
* * ^ Note that the [ sqlite3_wal_autocheckpoint ( ) ] interface and the
* * [ wal_autocheckpoint pragma ] both invoke [ sqlite3_wal_hook ( ) ] and will
* * overwrite any prior [ sqlite3_wal_hook ( ) ] settings .
*/
@ -9318,19 +9536,276 @@ SQLITE_API int sqlite3_vtab_nochange(sqlite3_context*);
/*
* * CAPI3REF : Determine The Collation For a Virtual Table Constraint
* * METHOD : sqlite3_index_info
* *
* * This function may only be called from within a call to the [ xBestIndex ]
* * method of a [ virtual table ] .
* * method of a [ virtual table ] . This function returns a pointer to a string
* * that is the name of the appropriate collation sequence to use for text
* * comparisons on the constraint identified by its arguments .
* *
* * The first argument must be the pointer to the [ sqlite3_index_info ] object
* * that is the first parameter to the xBestIndex ( ) method . The second argument
* * must be an index into the aConstraint [ ] array belonging to the
* * sqlite3_index_info structure passed to xBestIndex .
* *
* * The first argument must be the sqlite3_index_info object that is the
* * first parameter to the xBestIndex ( ) method . The second argument must be
* * an index into the aConstraint [ ] array belonging to the sqlite3_index_info
* * structure passed to xBestIndex . This function returns a pointer to a buffer
* * containing the name of the collation sequence for the corresponding
* * constraint .
* * Important :
* * The first parameter must be the same pointer that is passed into the
* * xBestMethod ( ) method . The first parameter may not be a pointer to a
* * different [ sqlite3_index_info ] object , even an exact copy .
* *
* * The return value is computed as follows :
* *
* * < ol >
* * < li > < p > If the constraint comes from a WHERE clause expression that contains
* * a [ COLLATE operator ] , then the name of the collation specified by
* * that COLLATE operator is returned .
* * < li > < p > If there is no COLLATE operator , but the column that is the subject
* * of the constraint specifies an alternative collating sequence via
* * a [ COLLATE clause ] on the column definition within the CREATE TABLE
* * statement that was passed into [ sqlite3_declare_vtab ( ) ] , then the
* * name of that alternative collating sequence is returned .
* * < li > < p > Otherwise , " BINARY " is returned .
* * < / ol >
*/
SQLITE_API SQLITE_EXPERIMENTAL const char * sqlite3_vtab_collation ( sqlite3_index_info * , int ) ;
/*
* * CAPI3REF : Determine if a virtual table query is DISTINCT
* * METHOD : sqlite3_index_info
* *
* * This API may only be used from within an [ xBestIndex | xBestIndex method ]
* * of a [ virtual table ] implementation . The result of calling this
* * interface from outside of xBestIndex ( ) is undefined and probably harmful .
* *
* * ^ The sqlite3_vtab_distinct ( ) interface returns an integer between 0 and
* * 3. The integer returned by sqlite3_vtab_distinct ( )
* * gives the virtual table additional information about how the query
* * planner wants the output to be ordered . As long as the virtual table
* * can meet the ordering requirements of the query planner , it may set
* * the " orderByConsumed " flag .
* *
* * < ol > < li value = " 0 " > < p >
* * ^ If the sqlite3_vtab_distinct ( ) interface returns 0 , that means
* * that the query planner needs the virtual table to return all rows in the
* * sort order defined by the " nOrderBy " and " aOrderBy " fields of the
* * [ sqlite3_index_info ] object . This is the default expectation . If the
* * virtual table outputs all rows in sorted order , then it is always safe for
* * the xBestIndex method to set the " orderByConsumed " flag , regardless of
* * the return value from sqlite3_vtab_distinct ( ) .
* * < li value = " 1 " > < p >
* * ^ ( If the sqlite3_vtab_distinct ( ) interface returns 1 , that means
* * that the query planner does not need the rows to be returned in sorted order
* * as long as all rows with the same values in all columns identified by the
* * " aOrderBy " field are adjacent . ) ^ This mode is used when the query planner
* * is doing a GROUP BY .
* * < li value = " 2 " > < p >
* * ^ ( If the sqlite3_vtab_distinct ( ) interface returns 2 , that means
* * that the query planner does not need the rows returned in any particular
* * order , as long as rows with the same values in all " aOrderBy " columns
* * are adjacent . ) ^ ^ ( Furthermore , only a single row for each particular
* * combination of values in the columns identified by the " aOrderBy " field
* * needs to be returned . ) ^ ^ It is always ok for two or more rows with the same
* * values in all " aOrderBy " columns to be returned , as long as all such rows
* * are adjacent . ^ The virtual table may , if it chooses , omit extra rows
* * that have the same value for all columns identified by " aOrderBy " .
* * ^ However omitting the extra rows is optional .
* * This mode is used for a DISTINCT query .
* * < li value = " 3 " > < p >
* * ^ ( If the sqlite3_vtab_distinct ( ) interface returns 3 , that means
* * that the query planner needs only distinct rows but it does need the
* * rows to be sorted . ) ^ ^ The virtual table implementation is free to omit
* * rows that are identical in all aOrderBy columns , if it wants to , but
* * it is not required to omit any rows . This mode is used for queries
* * that have both DISTINCT and ORDER BY clauses .
* * < / ol >
* *
* * ^ For the purposes of comparing virtual table output values to see if the
* * values are same value for sorting purposes , two NULL values are considered
* * to be the same . In other words , the comparison operator is " IS "
* * ( or " IS NOT DISTINCT FROM " ) and not " == " .
* *
* * If a virtual table implementation is unable to meet the requirements
* * specified above , then it must not set the " orderByConsumed " flag in the
* * [ sqlite3_index_info ] object or an incorrect answer may result .
* *
* * ^ A virtual table implementation is always free to return rows in any order
* * it wants , as long as the " orderByConsumed " flag is not set . ^ When the
* * the " orderByConsumed " flag is unset , the query planner will add extra
* * [ bytecode ] to ensure that the final results returned by the SQL query are
* * ordered correctly . The use of the " orderByConsumed " flag and the
* * sqlite3_vtab_distinct ( ) interface is merely an optimization . ^ Careful
* * use of the sqlite3_vtab_distinct ( ) interface and the " orderByConsumed "
* * flag might help queries against a virtual table to run faster . Being
* * overly aggressive and setting the " orderByConsumed " flag when it is not
* * valid to do so , on the other hand , might cause SQLite to return incorrect
* * results .
*/
SQLITE_API int sqlite3_vtab_distinct ( sqlite3_index_info * ) ;
/*
* * CAPI3REF : Identify and handle IN constraints in xBestIndex
* *
* * This interface may only be used from within an
* * [ xBestIndex | xBestIndex ( ) method ] of a [ virtual table ] implementation .
* * The result of invoking this interface from any other context is
* * undefined and probably harmful .
* *
* * ^ ( A constraint on a virtual table of the form
* * " [IN operator|column IN (...)] " is
* * communicated to the xBestIndex method as a
* * [ SQLITE_INDEX_CONSTRAINT_EQ ] constraint . ) ^ If xBestIndex wants to use
* * this constraint , it must set the corresponding
* * aConstraintUsage [ ] . argvIndex to a postive integer . ^ ( Then , under
* * the usual mode of handling IN operators , SQLite generates [ bytecode ]
* * that invokes the [ xFilter | xFilter ( ) method ] once for each value
* * on the right - hand side of the IN operator . ) ^ Thus the virtual table
* * only sees a single value from the right - hand side of the IN operator
* * at a time .
* *
* * In some cases , however , it would be advantageous for the virtual
* * table to see all values on the right - hand of the IN operator all at
* * once . The sqlite3_vtab_in ( ) interfaces facilitates this in two ways :
* *
* * < ol >
* * < li > < p >
* * ^ A call to sqlite3_vtab_in ( P , N , - 1 ) will return true ( non - zero )
* * if and only if the [ sqlite3_index_info | P - > aConstraint ] [ N ] constraint
* * is an [ IN operator ] that can be processed all at once . ^ In other words ,
* * sqlite3_vtab_in ( ) with - 1 in the third argument is a mechanism
* * by which the virtual table can ask SQLite if all - at - once processing
* * of the IN operator is even possible .
* *
* * < li > < p >
* * ^ A call to sqlite3_vtab_in ( P , N , F ) with F = = 1 or F = = 0 indicates
* * to SQLite that the virtual table does or does not want to process
* * the IN operator all - at - once , respectively . ^ Thus when the third
* * parameter ( F ) is non - negative , this interface is the mechanism by
* * which the virtual table tells SQLite how it wants to process the
* * IN operator .
* * < / ol >
* *
* * ^ The sqlite3_vtab_in ( P , N , F ) interface can be invoked multiple times
* * within the same xBestIndex method call . ^ For any given P , N pair ,
* * the return value from sqlite3_vtab_in ( P , N , F ) will always be the same
* * within the same xBestIndex call . ^ If the interface returns true
* * ( non - zero ) , that means that the constraint is an IN operator
* * that can be processed all - at - once . ^ If the constraint is not an IN
* * operator or cannot be processed all - at - once , then the interface returns
* * false .
* *
* * ^ ( All - at - once processing of the IN operator is selected if both of the
* * following conditions are met :
* *
* * < ol >
* * < li > < p > The P - > aConstraintUsage [ N ] . argvIndex value is set to a positive
* * integer . This is how the virtual table tells SQLite that it wants to
* * use the N - th constraint .
* *
* * < li > < p > The last call to sqlite3_vtab_in ( P , N , F ) for which F was
* * non - negative had F > = 1.
* * < / ol > ) ^
* *
* * ^ If either or both of the conditions above are false , then SQLite uses
* * the traditional one - at - a - time processing strategy for the IN constraint .
* * ^ If both conditions are true , then the argvIndex - th parameter to the
* * xFilter method will be an [ sqlite3_value ] that appears to be NULL ,
* * but which can be passed to [ sqlite3_vtab_in_first ( ) ] and
* * [ sqlite3_vtab_in_next ( ) ] to find all values on the right - hand side
* * of the IN constraint .
*/
SQLITE_API int sqlite3_vtab_in ( sqlite3_index_info * , int iCons , int bHandle ) ;
/*
* * CAPI3REF : Find all elements on the right - hand side of an IN constraint .
* *
* * These interfaces are only useful from within the
* * [ xFilter | xFilter ( ) method ] of a [ virtual table ] implementation .
* * The result of invoking these interfaces from any other context
* * is undefined and probably harmful .
* *
* * The X parameter in a call to sqlite3_vtab_in_first ( X , P ) or
* * sqlite3_vtab_in_next ( X , P ) must be one of the parameters to the
* * xFilter method which invokes these routines , and specifically
* * a parameter that was previously selected for all - at - once IN constraint
* * processing use the [ sqlite3_vtab_in ( ) ] interface in the
* * [ xBestIndex | xBestIndex method ] . ^ ( If the X parameter is not
* * an xFilter argument that was selected for all - at - once IN constraint
* * processing , then these routines return [ SQLITE_MISUSE ] ) ^ or perhaps
* * exhibit some other undefined or harmful behavior .
* *
* * ^ ( Use these routines to access all values on the right - hand side
* * of the IN constraint using code like the following :
* *
* * < blockquote > < pre >
* * & nbsp ; for ( rc = sqlite3_vtab_in_first ( pList , & pVal ) ;
* * & nbsp ; rc = = SQLITE_OK & & pVal
* * & nbsp ; rc = sqlite3_vtab_in_next ( pList , & pVal )
* * & nbsp ; ) {
* * & nbsp ; // do something with pVal
* * & nbsp ; }
* * & nbsp ; if ( rc ! = SQLITE_OK ) {
* * & nbsp ; // an error has occurred
* * & nbsp ; }
* * < / pre > < / blockquote > ) ^
* *
* * ^ On success , the sqlite3_vtab_in_first ( X , P ) and sqlite3_vtab_in_next ( X , P )
* * routines return SQLITE_OK and set * P to point to the first or next value
* * on the RHS of the IN constraint . ^ If there are no more values on the
* * right hand side of the IN constraint , then * P is set to NULL and these
* * routines return [ SQLITE_DONE ] . ^ The return value might be
* * some other value , such as SQLITE_NOMEM , in the event of a malfunction .
* *
* * The * ppOut values returned by these routines are only valid until the
* * next call to either of these routines or until the end of the xFilter
* * method from which these routines were called . If the virtual table
* * implementation needs to retain the * ppOut values for longer , it must make
* * copies . The * ppOut values are [ protected sqlite3_value | protected ] .
*/
SQLITE_API int sqlite3_vtab_in_first ( sqlite3_value * pVal , sqlite3_value * * ppOut ) ;
SQLITE_API int sqlite3_vtab_in_next ( sqlite3_value * pVal , sqlite3_value * * ppOut ) ;
/*
* * CAPI3REF : Constraint values in xBestIndex ( )
* * METHOD : sqlite3_index_info
* *
* * This API may only be used from within the [ xBestIndex | xBestIndex method ]
* * of a [ virtual table ] implementation . The result of calling this interface
* * from outside of an xBestIndex method are undefined and probably harmful .
* *
* * ^ When the sqlite3_vtab_rhs_value ( P , J , V ) interface is invoked from within
* * the [ xBestIndex ] method of a [ virtual table ] implementation , with P being
* * a copy of the [ sqlite3_index_info ] object pointer passed into xBestIndex and
* * J being a 0 - based index into P - > aConstraint [ ] , then this routine
* * attempts to set * V to the value of the right - hand operand of
* * that constraint if the right - hand operand is known . ^ If the
* * right - hand operand is not known , then * V is set to a NULL pointer .
* * ^ The sqlite3_vtab_rhs_value ( P , J , V ) interface returns SQLITE_OK if
* * and only if * V is set to a value . ^ The sqlite3_vtab_rhs_value ( P , J , V )
* * inteface returns SQLITE_NOTFOUND if the right - hand side of the J - th
* * constraint is not available . ^ The sqlite3_vtab_rhs_value ( ) interface
* * can return an result code other than SQLITE_OK or SQLITE_NOTFOUND if
* * something goes wrong .
* *
* * The sqlite3_vtab_rhs_value ( ) interface is usually only successful if
* * the right - hand operand of a constraint is a literal value in the original
* * SQL statement . If the right - hand operand is an expression or a reference
* * to some other column or a [ host parameter ] , then sqlite3_vtab_rhs_value ( )
* * will probably return [ SQLITE_NOTFOUND ] .
* *
* * ^ ( Some constraints , such as [ SQLITE_INDEX_CONSTRAINT_ISNULL ] and
* * [ SQLITE_INDEX_CONSTRAINT_ISNOTNULL ] , have no right - hand operand . For such
* * constraints , sqlite3_vtab_rhs_value ( ) always returns SQLITE_NOTFOUND . ) ^
* *
* * ^ The [ sqlite3_value ] object returned in * V is a protected sqlite3_value
* * and remains valid for the duration of the xBestIndex method call .
* * ^ When xBestIndex returns , the sqlite3_value object returned by
* * sqlite3_vtab_rhs_value ( ) is automatically deallocated .
* *
* * The " _rhs_ " in the name of this routine is an abbreviation for
* * " Right-Hand Side " .
*/
SQLITE_API int sqlite3_vtab_rhs_value ( sqlite3_index_info * , int , sqlite3_value * * ppVal ) ;
/*
* * CAPI3REF : Conflict resolution modes
* * KEYWORDS : { conflict resolution mode }
@ -9882,6 +10357,10 @@ SQLITE_API unsigned char *sqlite3_serialize(
* * database is currently in a read transaction or is involved in a backup
* * operation .
* *
* * It is not possible to deserialized into the TEMP database . If the
* * S argument to sqlite3_deserialize ( D , S , P , N , M , F ) is " temp " then the
* * function returns SQLITE_ERROR .
* *
* * If sqlite3_deserialize ( D , S , P , N , M , F ) fails for any reason and if the
* * SQLITE_DESERIALIZE_FREEONCLOSE bit is set in argument F , then
* * [ sqlite3_free ( ) ] is invoked on argument P prior to returning .
Sascha Bacardit
3 months ago