| Index: third_party/sqlite/amalgamation/sqlite3.h
|
| diff --git a/third_party/sqlite/amalgamation/sqlite3.h b/third_party/sqlite/amalgamation/sqlite3.h
|
| index 78a3ea3c0d2792f431710616a7b65301c83d23ff..d69310141ddfed883a7c014fd6cd044939d6054f 100644
|
| --- a/third_party/sqlite/amalgamation/sqlite3.h
|
| +++ b/third_party/sqlite/amalgamation/sqlite3.h
|
| @@ -23,7 +23,7 @@
|
| **
|
| ** The official C-language API documentation for SQLite is derived
|
| ** from comments in this file. This file is the authoritative source
|
| -** on how SQLite interfaces are suppose to operate.
|
| +** on how SQLite interfaces are supposed to operate.
|
| **
|
| ** The name of this file under configuration management is "sqlite.h.in".
|
| ** The makefile makes some minor changes to this file (such as inserting
|
| @@ -43,21 +43,25 @@ extern "C" {
|
|
|
|
|
| /*
|
| -** Add the ability to override 'extern'
|
| +** Provide the ability to override linkage features of the interface.
|
| */
|
| #ifndef SQLITE_EXTERN
|
| # define SQLITE_EXTERN extern
|
| #endif
|
| -
|
| #ifndef SQLITE_API
|
| # define SQLITE_API
|
| #endif
|
| -
|
| +#ifndef SQLITE_CDECL
|
| +# define SQLITE_CDECL
|
| +#endif
|
| +#ifndef SQLITE_STDCALL
|
| +# define SQLITE_STDCALL
|
| +#endif
|
|
|
| /*
|
| ** These no-op macros are used in front of interfaces to mark those
|
| ** interfaces as either deprecated or experimental. New applications
|
| -** should not use deprecated interfaces - they are support for backwards
|
| +** should not use deprecated interfaces - they are supported for backwards
|
| ** compatibility only. Application writers should be aware that
|
| ** experimental interfaces are subject to change in point releases.
|
| **
|
| @@ -107,9 +111,9 @@ extern "C" {
|
| ** [sqlite3_libversion_number()], [sqlite3_sourceid()],
|
| ** [sqlite_version()] and [sqlite_source_id()].
|
| */
|
| -#define SQLITE_VERSION "3.8.7.4"
|
| -#define SQLITE_VERSION_NUMBER 3008007
|
| -#define SQLITE_SOURCE_ID "2014-12-09 01:34:36 f66f7a17b78ba617acde90fc810107f34f1a1f2e"
|
| +#define SQLITE_VERSION "3.10.2"
|
| +#define SQLITE_VERSION_NUMBER 3010002
|
| +#define SQLITE_SOURCE_ID "2016-01-20 15:27:19 17efb4209f97fb4971656086b138599a91a75ff9"
|
|
|
| /*
|
| ** CAPI3REF: Run-Time Library Version Numbers
|
| @@ -120,7 +124,7 @@ extern "C" {
|
| ** but are associated with the library instead of the header file. ^(Cautious
|
| ** programmers might include assert() statements in their application to
|
| ** verify that values returned by these interfaces match the macros in
|
| -** the header, and thus insure that the application is
|
| +** the header, and thus ensure that the application is
|
| ** compiled with matching library and header files.
|
| **
|
| ** <blockquote><pre>
|
| @@ -142,9 +146,9 @@ extern "C" {
|
| ** See also: [sqlite_version()] and [sqlite_source_id()].
|
| */
|
| SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
|
| -SQLITE_API const char *sqlite3_libversion(void);
|
| -SQLITE_API const char *sqlite3_sourceid(void);
|
| -SQLITE_API int sqlite3_libversion_number(void);
|
| +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);
|
|
|
| /*
|
| ** CAPI3REF: Run-Time Library Compilation Options Diagnostics
|
| @@ -169,8 +173,8 @@ SQLITE_API int sqlite3_libversion_number(void);
|
| ** [sqlite_compileoption_get()] and the [compile_options pragma].
|
| */
|
| #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
|
| -SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
|
| -SQLITE_API const char *sqlite3_compileoption_get(int N);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_compileoption_used(const char *zOptName);
|
| +SQLITE_API const char *SQLITE_STDCALL sqlite3_compileoption_get(int N);
|
| #endif
|
|
|
| /*
|
| @@ -201,7 +205,7 @@ SQLITE_API const char *sqlite3_compileoption_get(int N);
|
| ** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
|
| ** can be fully or partially disabled using a call to [sqlite3_config()]
|
| ** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
|
| -** or [SQLITE_CONFIG_MUTEX]. ^(The return value of the
|
| +** or [SQLITE_CONFIG_SERIALIZED]. ^(The return value of the
|
| ** sqlite3_threadsafe() function shows only the compile-time setting of
|
| ** thread safety, not any run-time changes to that setting made by
|
| ** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
|
| @@ -209,7 +213,7 @@ SQLITE_API const char *sqlite3_compileoption_get(int N);
|
| **
|
| ** See the [threading mode] documentation for additional information.
|
| */
|
| -SQLITE_API int sqlite3_threadsafe(void);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_threadsafe(void);
|
|
|
| /*
|
| ** CAPI3REF: Database Connection Handle
|
| @@ -266,6 +270,7 @@ typedef sqlite_uint64 sqlite3_uint64;
|
|
|
| /*
|
| ** CAPI3REF: Closing A Database Connection
|
| +** DESTRUCTOR: sqlite3
|
| **
|
| ** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
|
| ** for the [sqlite3] object.
|
| @@ -305,8 +310,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 sqlite3_close(sqlite3*);
|
| -SQLITE_API int sqlite3_close_v2(sqlite3*);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_close(sqlite3*);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_close_v2(sqlite3*);
|
|
|
| /*
|
| ** The type for a callback function.
|
| @@ -317,6 +322,7 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**);
|
|
|
| /*
|
| ** CAPI3REF: One-Step Query Execution Interface
|
| +** METHOD: sqlite3
|
| **
|
| ** The sqlite3_exec() interface is a convenience wrapper around
|
| ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
|
| @@ -368,7 +374,7 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**);
|
| ** Restrictions:
|
| **
|
| ** <ul>
|
| -** <li> The application must insure that the 1st parameter to sqlite3_exec()
|
| +** <li> The application must ensure that the 1st parameter to sqlite3_exec()
|
| ** is a valid and open [database connection].
|
| ** <li> The application must not close the [database connection] specified by
|
| ** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
|
| @@ -376,7 +382,7 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**);
|
| ** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
|
| ** </ul>
|
| */
|
| -SQLITE_API int sqlite3_exec(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_exec(
|
| sqlite3*, /* An open database */
|
| const char *sql, /* SQL to be evaluated */
|
| int (*callback)(void*,int,char**,char**), /* Callback function */
|
| @@ -471,6 +477,8 @@ SQLITE_API int sqlite3_exec(
|
| #define SQLITE_IOERR_MMAP (SQLITE_IOERR | (24<<8))
|
| #define SQLITE_IOERR_GETTEMPPATH (SQLITE_IOERR | (25<<8))
|
| #define SQLITE_IOERR_CONVPATH (SQLITE_IOERR | (26<<8))
|
| +#define SQLITE_IOERR_VNODE (SQLITE_IOERR | (27<<8))
|
| +#define SQLITE_IOERR_AUTH (SQLITE_IOERR | (28<<8))
|
| #define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8))
|
| #define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8))
|
| #define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8))
|
| @@ -756,14 +764,16 @@ struct sqlite3_io_methods {
|
| ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
|
| ** interface.
|
| **
|
| +** <ul>
|
| +** <li>[[SQLITE_FCNTL_LOCKSTATE]]
|
| ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
|
| ** opcode causes the xFileControl method to write the current state of
|
| ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
|
| ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
|
| ** into an integer that the pArg argument points to. This capability
|
| -** is used during testing and only needs to be supported when SQLITE_TEST
|
| -** is defined.
|
| -** <ul>
|
| +** is used during testing and is only available when the SQLITE_TEST
|
| +** compile-time option is used.
|
| +**
|
| ** <li>[[SQLITE_FCNTL_SIZE_HINT]]
|
| ** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
|
| ** layer a hint of how large the database file will grow to be during the
|
| @@ -784,8 +794,13 @@ struct sqlite3_io_methods {
|
| ** <li>[[SQLITE_FCNTL_FILE_POINTER]]
|
| ** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
|
| ** to the [sqlite3_file] object associated with a particular database
|
| -** connection. See the [sqlite3_file_control()] documentation for
|
| -** additional information.
|
| +** connection. See also [SQLITE_FCNTL_JOURNAL_POINTER].
|
| +**
|
| +** <li>[[SQLITE_FCNTL_JOURNAL_POINTER]]
|
| +** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer
|
| +** to the [sqlite3_file] object associated with the journal file (either
|
| +** the [rollback journal] or the [write-ahead log]) for a particular database
|
| +** connection. See also [SQLITE_FCNTL_FILE_POINTER].
|
| **
|
| ** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]
|
| ** No longer in use.
|
| @@ -872,6 +887,15 @@ struct sqlite3_io_methods {
|
| ** pointer in case this file-control is not implemented. This file-control
|
| ** is intended for diagnostic use only.
|
| **
|
| +** <li>[[SQLITE_FCNTL_VFS_POINTER]]
|
| +** ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level
|
| +** [VFSes] currently in use. ^(The argument X in
|
| +** sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be
|
| +** of type "[sqlite3_vfs] **". This opcodes will set *X
|
| +** to a pointer to the top-level VFS.)^
|
| +** ^When there are multiple VFS shims in the stack, this opcode finds the
|
| +** upper-most shim only.
|
| +**
|
| ** <li>[[SQLITE_FCNTL_PRAGMA]]
|
| ** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA]
|
| ** file control is sent to the open [sqlite3_file] object corresponding
|
| @@ -888,7 +912,9 @@ struct sqlite3_io_methods {
|
| ** [PRAGMA] processing continues. ^If the [SQLITE_FCNTL_PRAGMA]
|
| ** file control returns [SQLITE_OK], then the parser assumes that the
|
| ** VFS has handled the PRAGMA itself and the parser generates a no-op
|
| -** prepared statement. ^If the [SQLITE_FCNTL_PRAGMA] file control returns
|
| +** prepared statement if result string is NULL, or that returns a copy
|
| +** of the result string if the string is non-NULL.
|
| +** ^If the [SQLITE_FCNTL_PRAGMA] file control returns
|
| ** any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means
|
| ** that the VFS encountered an error while handling the [PRAGMA] and the
|
| ** compilation of the PRAGMA fails with an error. ^The [SQLITE_FCNTL_PRAGMA]
|
| @@ -946,12 +972,27 @@ struct sqlite3_io_methods {
|
| ** pointed to by the pArg argument. This capability is used during testing
|
| ** and only needs to be supported when SQLITE_TEST is defined.
|
| **
|
| +** <li>[[SQLITE_FCNTL_WAL_BLOCK]]
|
| +** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might
|
| +** be advantageous to block on the next WAL lock if the lock is not immediately
|
| +** available. The WAL subsystem issues this signal during rare
|
| +** circumstances in order to fix a problem with priority inversion.
|
| +** Applications should <em>not</em> use this file-control.
|
| +**
|
| +** <li>[[SQLITE_FCNTL_ZIPVFS]]
|
| +** The [SQLITE_FCNTL_ZIPVFS] opcode is implemented by zipvfs only. All other
|
| +** VFS should return SQLITE_NOTFOUND for this opcode.
|
| +**
|
| +** <li>[[SQLITE_FCNTL_RBU]]
|
| +** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by
|
| +** the RBU extension only. All other VFS should return SQLITE_NOTFOUND for
|
| +** this opcode.
|
| ** </ul>
|
| */
|
| #define SQLITE_FCNTL_LOCKSTATE 1
|
| -#define SQLITE_GET_LOCKPROXYFILE 2
|
| -#define SQLITE_SET_LOCKPROXYFILE 3
|
| -#define SQLITE_LAST_ERRNO 4
|
| +#define SQLITE_FCNTL_GET_LOCKPROXYFILE 2
|
| +#define SQLITE_FCNTL_SET_LOCKPROXYFILE 3
|
| +#define SQLITE_FCNTL_LAST_ERRNO 4
|
| #define SQLITE_FCNTL_SIZE_HINT 5
|
| #define SQLITE_FCNTL_CHUNK_SIZE 6
|
| #define SQLITE_FCNTL_FILE_POINTER 7
|
| @@ -970,6 +1011,17 @@ struct sqlite3_io_methods {
|
| #define SQLITE_FCNTL_SYNC 21
|
| #define SQLITE_FCNTL_COMMIT_PHASETWO 22
|
| #define SQLITE_FCNTL_WIN32_SET_HANDLE 23
|
| +#define SQLITE_FCNTL_WAL_BLOCK 24
|
| +#define SQLITE_FCNTL_ZIPVFS 25
|
| +#define SQLITE_FCNTL_RBU 26
|
| +#define SQLITE_FCNTL_VFS_POINTER 27
|
| +#define SQLITE_FCNTL_JOURNAL_POINTER 28
|
| +
|
| +/* deprecated names */
|
| +#define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE
|
| +#define SQLITE_SET_LOCKPROXYFILE SQLITE_FCNTL_SET_LOCKPROXYFILE
|
| +#define SQLITE_LAST_ERRNO SQLITE_FCNTL_LAST_ERRNO
|
| +
|
|
|
| /*
|
| ** CAPI3REF: Mutex Handle
|
| @@ -1221,7 +1273,7 @@ struct sqlite3_vfs {
|
| ** </ul>
|
| **
|
| ** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
|
| -** was given no the corresponding lock.
|
| +** was given on the corresponding lock.
|
| **
|
| ** The xShmLock method can transition between unlocked and SHARED or
|
| ** between unlocked and EXCLUSIVE. It cannot transition between SHARED
|
| @@ -1318,10 +1370,10 @@ struct sqlite3_vfs {
|
| ** must return [SQLITE_OK] on success and some other [error code] upon
|
| ** failure.
|
| */
|
| -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);
|
| +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);
|
|
|
| /*
|
| ** CAPI3REF: Configuring The SQLite Library
|
| @@ -1332,9 +1384,11 @@ SQLITE_API int sqlite3_os_end(void);
|
| ** applications and so this routine is usually not necessary. It is
|
| ** provided to support rare applications with unusual needs.
|
| **
|
| -** The sqlite3_config() interface is not threadsafe. The application
|
| -** must insure that no other SQLite interfaces are invoked by other
|
| -** threads while sqlite3_config() is running. Furthermore, sqlite3_config()
|
| +** <b>The sqlite3_config() interface is not threadsafe. The application
|
| +** must ensure that no other SQLite interfaces are invoked by other
|
| +** threads while sqlite3_config() is running.</b>
|
| +**
|
| +** The sqlite3_config() interface
|
| ** may only be invoked prior to library initialization using
|
| ** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
|
| ** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
|
| @@ -1352,10 +1406,11 @@ SQLITE_API int 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 sqlite3_config(int, ...);
|
| +SQLITE_API int SQLITE_CDECL sqlite3_config(int, ...);
|
|
|
| /*
|
| ** CAPI3REF: Configure database connections
|
| +** METHOD: sqlite3
|
| **
|
| ** The sqlite3_db_config() interface is used to make configuration
|
| ** changes to a [database connection]. The interface is similar to
|
| @@ -1370,7 +1425,7 @@ SQLITE_API int sqlite3_config(int, ...);
|
| ** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
|
| ** the call is considered successful.
|
| */
|
| -SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
|
| +SQLITE_API int SQLITE_CDECL sqlite3_db_config(sqlite3*, int op, ...);
|
|
|
| /*
|
| ** CAPI3REF: Memory Allocation Routines
|
| @@ -1504,31 +1559,33 @@ struct sqlite3_mem_methods {
|
| ** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
|
| **
|
| ** [[SQLITE_CONFIG_MALLOC]] <dt>SQLITE_CONFIG_MALLOC</dt>
|
| -** <dd> ^(This option takes a single argument which is a pointer to an
|
| -** instance of the [sqlite3_mem_methods] structure. The argument specifies
|
| +** <dd> ^(The SQLITE_CONFIG_MALLOC option takes a single argument which is
|
| +** a pointer to an instance of the [sqlite3_mem_methods] structure.
|
| +** The argument specifies
|
| ** alternative low-level memory allocation routines to be used in place of
|
| ** the memory allocation routines built into SQLite.)^ ^SQLite makes
|
| ** its own private copy of the content of the [sqlite3_mem_methods] structure
|
| ** before the [sqlite3_config()] call returns.</dd>
|
| **
|
| ** [[SQLITE_CONFIG_GETMALLOC]] <dt>SQLITE_CONFIG_GETMALLOC</dt>
|
| -** <dd> ^(This option takes a single argument which is a pointer to an
|
| -** instance of the [sqlite3_mem_methods] structure. The [sqlite3_mem_methods]
|
| +** <dd> ^(The SQLITE_CONFIG_GETMALLOC option takes a single argument which
|
| +** is a pointer to an instance of the [sqlite3_mem_methods] structure.
|
| +** The [sqlite3_mem_methods]
|
| ** structure is filled with the currently defined memory allocation routines.)^
|
| ** This option can be used to overload the default memory allocation
|
| ** routines with a wrapper that simulations memory allocation failure or
|
| ** tracks memory usage, for example. </dd>
|
| **
|
| ** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
|
| -** <dd> ^This option takes single argument of type int, interpreted as a
|
| -** boolean, which enables or disables the collection of memory allocation
|
| -** statistics. ^(When memory allocation statistics are disabled, the
|
| -** following SQLite interfaces become non-operational:
|
| +** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
|
| +** interpreted as a boolean, which enables or disables the collection of
|
| +** memory allocation statistics. ^(When memory allocation statistics are
|
| +** disabled, the following SQLite interfaces become non-operational:
|
| ** <ul>
|
| ** <li> [sqlite3_memory_used()]
|
| ** <li> [sqlite3_memory_highwater()]
|
| ** <li> [sqlite3_soft_heap_limit64()]
|
| -** <li> [sqlite3_status()]
|
| +** <li> [sqlite3_status64()]
|
| ** </ul>)^
|
| ** ^Memory allocation statistics are enabled by default unless SQLite is
|
| ** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
|
| @@ -1536,53 +1593,72 @@ struct sqlite3_mem_methods {
|
| ** </dd>
|
| **
|
| ** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>
|
| -** <dd> ^This option specifies a static memory buffer that SQLite can use for
|
| -** scratch memory. There are three arguments: A pointer an 8-byte
|
| +** <dd> ^The SQLITE_CONFIG_SCRATCH option specifies a static memory buffer
|
| +** that SQLite can use for scratch memory. ^(There are three arguments
|
| +** to SQLITE_CONFIG_SCRATCH: A pointer an 8-byte
|
| ** aligned memory buffer from which the scratch allocations will be
|
| ** drawn, the size of each scratch allocation (sz),
|
| -** and the maximum number of scratch allocations (N). The sz
|
| -** argument must be a multiple of 16.
|
| +** and the maximum number of scratch allocations (N).)^
|
| ** The first argument must be a pointer to an 8-byte aligned buffer
|
| ** of at least sz*N bytes of memory.
|
| -** ^SQLite will use no more than two scratch buffers per thread. So
|
| -** N should be set to twice the expected maximum number of threads.
|
| -** ^SQLite will never require a scratch buffer that is more than 6
|
| -** times the database page size. ^If SQLite needs needs additional
|
| +** ^SQLite will not use more than one scratch buffers per thread.
|
| +** ^SQLite will never request a scratch buffer that is more than 6
|
| +** times the database page size.
|
| +** ^If SQLite needs needs additional
|
| ** scratch memory beyond what is provided by this configuration option, then
|
| -** [sqlite3_malloc()] will be used to obtain the memory needed.</dd>
|
| +** [sqlite3_malloc()] will be used to obtain the memory needed.<p>
|
| +** ^When the application provides any amount of scratch memory using
|
| +** SQLITE_CONFIG_SCRATCH, SQLite avoids unnecessary large
|
| +** [sqlite3_malloc|heap allocations].
|
| +** This can help [Robson proof|prevent memory allocation failures] due to heap
|
| +** fragmentation in low-memory embedded systems.
|
| +** </dd>
|
| **
|
| ** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
|
| -** <dd> ^This option specifies a static memory buffer that SQLite can use for
|
| -** the database page cache with the default page cache implementation.
|
| -** This configuration should not be used if an application-define page
|
| -** cache implementation is loaded using the SQLITE_CONFIG_PCACHE2 option.
|
| -** There are three arguments to this option: A pointer to 8-byte aligned
|
| -** memory, the size of each page buffer (sz), and the number of pages (N).
|
| +** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
|
| +** that SQLite can use for the database page cache with the default page
|
| +** cache implementation.
|
| +** This configuration option is a no-op if an application-define page
|
| +** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2].
|
| +** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
|
| +** 8-byte aligned memory (pMem), the size of each page cache line (sz),
|
| +** and the number of cache lines (N).
|
| ** The sz argument should be the size of the largest database page
|
| -** (a power of two between 512 and 32768) plus a little extra for each
|
| -** page header. ^The page header size is 20 to 40 bytes depending on
|
| -** the host architecture. ^It is harmless, apart from the wasted memory,
|
| -** to make sz a little too large. The first
|
| -** argument should point to an allocation of at least sz*N bytes of memory.
|
| -** ^SQLite will use the memory provided by the first argument to satisfy its
|
| -** memory needs for the first N pages that it adds to cache. ^If additional
|
| -** page cache memory is needed beyond what is provided by this option, then
|
| -** SQLite goes to [sqlite3_malloc()] for the additional storage space.
|
| -** The pointer in the first argument must
|
| -** be aligned to an 8-byte boundary or subsequent behavior of SQLite
|
| -** will be undefined.</dd>
|
| +** (a power of two between 512 and 65536) plus some extra bytes for each
|
| +** page header. ^The number of extra bytes needed by the page header
|
| +** can be determined using [SQLITE_CONFIG_PCACHE_HDRSZ].
|
| +** ^It is harmless, apart from the wasted memory,
|
| +** for the sz parameter to be larger than necessary. The pMem
|
| +** argument must be either a NULL pointer or a pointer to an 8-byte
|
| +** aligned block of memory of at least sz*N bytes, otherwise
|
| +** subsequent behavior is undefined.
|
| +** ^When pMem is not NULL, SQLite will strive to use the memory provided
|
| +** to satisfy page cache needs, falling back to [sqlite3_malloc()] if
|
| +** a page cache line is larger than sz bytes or if all of the pMem buffer
|
| +** is exhausted.
|
| +** ^If pMem is NULL and N is non-zero, then each database connection
|
| +** does an initial bulk allocation for page cache memory
|
| +** from [sqlite3_malloc()] sufficient for N cache lines if N is positive or
|
| +** of -1024*N bytes if N is negative, . ^If additional
|
| +** page cache memory is needed beyond what is provided by the initial
|
| +** allocation, then SQLite goes to [sqlite3_malloc()] separately for each
|
| +** additional cache line. </dd>
|
| **
|
| ** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
|
| -** <dd> ^This option specifies a static memory buffer that SQLite will use
|
| -** for all of its dynamic memory allocation needs beyond those provided
|
| -** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE].
|
| -** There are three arguments: An 8-byte aligned pointer to the memory,
|
| +** <dd> ^The SQLITE_CONFIG_HEAP option specifies a static memory buffer
|
| +** that SQLite will use for all of its dynamic memory allocation needs
|
| +** beyond those provided for by [SQLITE_CONFIG_SCRATCH] and
|
| +** [SQLITE_CONFIG_PAGECACHE].
|
| +** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
|
| +** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns
|
| +** [SQLITE_ERROR] if invoked otherwise.
|
| +** ^There are three arguments to SQLITE_CONFIG_HEAP:
|
| +** An 8-byte aligned pointer to the memory,
|
| ** the number of bytes in the memory buffer, and the minimum allocation size.
|
| ** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
|
| ** to using its default memory allocator (the system malloc() implementation),
|
| ** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. ^If the
|
| -** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or
|
| -** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory
|
| +** memory pointer is not NULL then the alternative memory
|
| ** allocator is engaged to handle all of SQLites memory allocation needs.
|
| ** The first pointer (the memory pointer) must be aligned to an 8-byte
|
| ** boundary or subsequent behavior of SQLite will be undefined.
|
| @@ -1590,11 +1666,11 @@ struct sqlite3_mem_methods {
|
| ** for the minimum allocation size are 2**5 through 2**8.</dd>
|
| **
|
| ** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>
|
| -** <dd> ^(This option takes a single argument which is a pointer to an
|
| -** instance of the [sqlite3_mutex_methods] structure. The argument specifies
|
| -** alternative low-level mutex routines to be used in place
|
| -** the mutex routines built into SQLite.)^ ^SQLite makes a copy of the
|
| -** content of the [sqlite3_mutex_methods] structure before the call to
|
| +** <dd> ^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a
|
| +** pointer to an instance of the [sqlite3_mutex_methods] structure.
|
| +** The argument specifies alternative low-level mutex routines to be used
|
| +** in place the mutex routines built into SQLite.)^ ^SQLite makes a copy of
|
| +** the content of the [sqlite3_mutex_methods] structure before the call to
|
| ** [sqlite3_config()] returns. ^If SQLite is compiled with
|
| ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
|
| ** the entire mutexing subsystem is omitted from the build and hence calls to
|
| @@ -1602,8 +1678,8 @@ struct sqlite3_mem_methods {
|
| ** return [SQLITE_ERROR].</dd>
|
| **
|
| ** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>
|
| -** <dd> ^(This option takes a single argument which is a pointer to an
|
| -** instance of the [sqlite3_mutex_methods] structure. The
|
| +** <dd> ^(The SQLITE_CONFIG_GETMUTEX option takes a single argument which
|
| +** is a pointer to an instance of the [sqlite3_mutex_methods] structure. The
|
| ** [sqlite3_mutex_methods]
|
| ** structure is filled with the currently defined mutex routines.)^
|
| ** This option can be used to overload the default mutex allocation
|
| @@ -1615,25 +1691,25 @@ struct sqlite3_mem_methods {
|
| ** return [SQLITE_ERROR].</dd>
|
| **
|
| ** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt>
|
| -** <dd> ^(This option takes two arguments that determine the default
|
| -** memory allocation for the lookaside memory allocator on each
|
| -** [database connection]. The first argument is the
|
| +** <dd> ^(The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine
|
| +** the default size of lookaside memory on each [database connection].
|
| +** The first argument is the
|
| ** size of each lookaside buffer slot and the second is the number of
|
| -** slots allocated to each database connection.)^ ^(This option sets the
|
| -** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
|
| -** verb to [sqlite3_db_config()] can be used to change the lookaside
|
| +** slots allocated to each database connection.)^ ^(SQLITE_CONFIG_LOOKASIDE
|
| +** sets the <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
|
| +** option to [sqlite3_db_config()] can be used to change the lookaside
|
| ** configuration on individual connections.)^ </dd>
|
| **
|
| ** [[SQLITE_CONFIG_PCACHE2]] <dt>SQLITE_CONFIG_PCACHE2</dt>
|
| -** <dd> ^(This option takes a single argument which is a pointer to
|
| -** an [sqlite3_pcache_methods2] object. This object specifies the interface
|
| -** to a custom page cache implementation.)^ ^SQLite makes a copy of the
|
| -** object and uses it for page cache memory allocations.</dd>
|
| +** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
|
| +** a pointer to an [sqlite3_pcache_methods2] object. This object specifies
|
| +** the interface to a custom page cache implementation.)^
|
| +** ^SQLite makes a copy of the [sqlite3_pcache_methods2] object.</dd>
|
| **
|
| ** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>
|
| -** <dd> ^(This option takes a single argument which is a pointer to an
|
| -** [sqlite3_pcache_methods2] object. SQLite copies of the current
|
| -** page cache implementation into that object.)^ </dd>
|
| +** <dd> ^(The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
|
| +** is a pointer to an [sqlite3_pcache_methods2] object. SQLite copies of
|
| +** the current page cache implementation into that object.)^ </dd>
|
| **
|
| ** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
|
| ** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
|
| @@ -1656,10 +1732,11 @@ struct sqlite3_mem_methods {
|
| ** function must be threadsafe. </dd>
|
| **
|
| ** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
|
| -** <dd>^(This option takes a single argument of type int. If non-zero, then
|
| -** URI handling is globally enabled. If the parameter is zero, then URI handling
|
| -** is globally disabled.)^ ^If URI handling is globally enabled, all filenames
|
| -** passed to [sqlite3_open()], [sqlite3_open_v2()], [sqlite3_open16()] or
|
| +** <dd>^(The SQLITE_CONFIG_URI option takes a single argument of type int.
|
| +** If non-zero, then URI handling is globally enabled. If the parameter is zero,
|
| +** then URI handling is globally disabled.)^ ^If URI handling is globally
|
| +** enabled, all filenames passed to [sqlite3_open()], [sqlite3_open_v2()],
|
| +** [sqlite3_open16()] or
|
| ** specified as part of [ATTACH] commands are interpreted as URIs, regardless
|
| ** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
|
| ** connection is opened. ^If it is globally disabled, filenames are
|
| @@ -1669,9 +1746,10 @@ struct sqlite3_mem_methods {
|
| ** [SQLITE_USE_URI] symbol defined.)^
|
| **
|
| ** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
|
| -** <dd>^This option takes a single integer argument which is interpreted as
|
| -** a boolean in order to enable or disable the use of covering indices for
|
| -** full table scans in the query optimizer. ^The default setting is determined
|
| +** <dd>^The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer
|
| +** argument which is interpreted as a boolean in order to enable or disable
|
| +** the use of covering indices for full table scans in the query optimizer.
|
| +** ^The default setting is determined
|
| ** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
|
| ** if that compile-time option is omitted.
|
| ** The ability to disable the use of covering indices for full table scans
|
| @@ -1711,18 +1789,37 @@ struct sqlite3_mem_methods {
|
| ** ^The default setting can be overridden by each database connection using
|
| ** either the [PRAGMA mmap_size] command, or by using the
|
| ** [SQLITE_FCNTL_MMAP_SIZE] file control. ^(The maximum allowed mmap size
|
| -** cannot be changed at run-time. Nor may the maximum allowed mmap size
|
| -** exceed the compile-time maximum mmap size set by the
|
| +** will be silently truncated if necessary so that it does not exceed the
|
| +** compile-time maximum mmap size set by the
|
| ** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
|
| ** ^If either argument to this option is negative, then that argument is
|
| ** changed to its compile-time default.
|
| **
|
| ** [[SQLITE_CONFIG_WIN32_HEAPSIZE]]
|
| ** <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
|
| -** <dd>^This option is only available if SQLite is compiled for Windows
|
| -** with the [SQLITE_WIN32_MALLOC] pre-processor macro defined.
|
| -** SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
|
| +** <dd>^The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
|
| +** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro
|
| +** defined. ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
|
| ** that specifies the maximum size of the created heap.
|
| +**
|
| +** [[SQLITE_CONFIG_PCACHE_HDRSZ]]
|
| +** <dt>SQLITE_CONFIG_PCACHE_HDRSZ
|
| +** <dd>^The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
|
| +** is a pointer to an integer and writes into that integer the number of extra
|
| +** bytes per page required for each page in [SQLITE_CONFIG_PAGECACHE].
|
| +** The amount of extra space required can change depending on the compiler,
|
| +** target platform, and SQLite version.
|
| +**
|
| +** [[SQLITE_CONFIG_PMASZ]]
|
| +** <dt>SQLITE_CONFIG_PMASZ
|
| +** <dd>^The SQLITE_CONFIG_PMASZ option takes a single parameter which
|
| +** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
|
| +** sorter to that integer. The default minimum PMA Size is set by the
|
| +** [SQLITE_SORTER_PMASZ] compile-time option. New threads are launched
|
| +** to help with sort operations when multithreaded sorting
|
| +** 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.
|
| ** </dl>
|
| */
|
| #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
|
| @@ -1748,6 +1845,8 @@ struct sqlite3_mem_methods {
|
| #define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */
|
| #define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */
|
| #define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */
|
| +#define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */
|
| +#define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */
|
|
|
| /*
|
| ** CAPI3REF: Database Connection Configuration Options
|
| @@ -1814,15 +1913,17 @@ struct sqlite3_mem_methods {
|
|
|
| /*
|
| ** CAPI3REF: Enable Or Disable Extended Result Codes
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The sqlite3_extended_result_codes() routine enables or disables the
|
| ** [extended result codes] feature of SQLite. ^The extended result
|
| ** codes are disabled by default for historical compatibility.
|
| */
|
| -SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_extended_result_codes(sqlite3*, int onoff);
|
|
|
| /*
|
| ** CAPI3REF: Last Insert Rowid
|
| +** METHOD: sqlite3
|
| **
|
| ** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables)
|
| ** has a unique 64-bit signed
|
| @@ -1870,52 +1971,51 @@ SQLITE_API int 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 sqlite3_last_insert_rowid(sqlite3*);
|
| +SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_last_insert_rowid(sqlite3*);
|
|
|
| /*
|
| ** CAPI3REF: Count The Number Of Rows Modified
|
| +** METHOD: sqlite3
|
| **
|
| -** ^This function returns the number of database rows that were changed
|
| -** or inserted or deleted by the most recently completed SQL statement
|
| -** on the [database connection] specified by the first parameter.
|
| -** ^(Only changes that are directly specified by the [INSERT], [UPDATE],
|
| -** or [DELETE] statement are counted. Auxiliary changes caused by
|
| -** triggers or [foreign key actions] are not counted.)^ Use the
|
| -** [sqlite3_total_changes()] function to find the total number of changes
|
| -** including changes caused by triggers and foreign key actions.
|
| -**
|
| -** ^Changes to a view that are simulated by an [INSTEAD OF trigger]
|
| -** are not counted. Only real table changes are counted.
|
| -**
|
| -** ^(A "row change" is a change to a single row of a single table
|
| -** caused by an INSERT, DELETE, or UPDATE statement. Rows that
|
| -** are changed as side effects of [REPLACE] constraint resolution,
|
| -** rollback, ABORT processing, [DROP TABLE], or by any other
|
| -** mechanisms do not count as direct row changes.)^
|
| -**
|
| -** A "trigger context" is a scope of execution that begins and
|
| -** ends with the script of a [CREATE TRIGGER | trigger].
|
| -** Most SQL statements are
|
| -** evaluated outside of any trigger. This is the "top level"
|
| -** trigger context. If a trigger fires from the top level, a
|
| -** new trigger context is entered for the duration of that one
|
| -** trigger. Subtriggers create subcontexts for their duration.
|
| -**
|
| -** ^Calling [sqlite3_exec()] or [sqlite3_step()] recursively does
|
| -** not create a new trigger context.
|
| -**
|
| -** ^This function returns the number of direct row changes in the
|
| -** most recent INSERT, UPDATE, or DELETE statement within the same
|
| -** trigger context.
|
| -**
|
| -** ^Thus, when called from the top level, this function returns the
|
| -** number of changes in the most recent INSERT, UPDATE, or DELETE
|
| -** that also occurred at the top level. ^(Within the body of a trigger,
|
| -** the sqlite3_changes() interface can be called to find the number of
|
| -** changes in the most recently completed INSERT, UPDATE, or DELETE
|
| -** statement within the body of the same trigger.
|
| -** However, the number returned does not include changes
|
| -** caused by subtriggers since those have their own context.)^
|
| +** ^This function returns 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.
|
| +**
|
| +** ^Only changes made directly by the INSERT, UPDATE or DELETE statement are
|
| +** considered - auxiliary changes caused by [CREATE TRIGGER | triggers],
|
| +** [foreign key actions] or [REPLACE] constraint resolution are not counted.
|
| +**
|
| +** Changes to a view that are intercepted by
|
| +** [INSTEAD OF trigger | INSTEAD OF triggers] are not counted. ^The value
|
| +** returned by sqlite3_changes() immediately after an INSERT, UPDATE or
|
| +** DELETE statement run on a view is always zero. Only changes made to real
|
| +** tables are counted.
|
| +**
|
| +** Things are more complicated if the sqlite3_changes() function is
|
| +** executed while a trigger program is running. This may happen if the
|
| +** program uses the [changes() SQL function], or if some other callback
|
| +** function invokes sqlite3_changes() directly. Essentially:
|
| +**
|
| +** <ul>
|
| +** <li> ^(Before entering a trigger program the value returned by
|
| +** sqlite3_changes() function is saved. After the trigger program
|
| +** has finished, the original value is restored.)^
|
| +**
|
| +** <li> ^(Within a trigger program each INSERT, UPDATE and DELETE
|
| +** statement sets the value returned by sqlite3_changes()
|
| +** upon completion as normal. Of course, this value will not include
|
| +** any changes performed by sub-triggers, as the sqlite3_changes()
|
| +** value will be saved and restored after each sub-trigger has run.)^
|
| +** </ul>
|
| +**
|
| +** ^This means that if the changes() SQL function (or similar) is used
|
| +** by the first INSERT, UPDATE or DELETE statement within a trigger, it
|
| +** returns the value as set when the calling statement began executing.
|
| +** ^If it is used by the second or subsequent such statement within a trigger
|
| +** program, the value returned reflects the number of rows modified by the
|
| +** previous INSERT, UPDATE or DELETE statement within the same trigger.
|
| **
|
| ** See also the [sqlite3_total_changes()] interface, the
|
| ** [count_changes pragma], and the [changes() SQL function].
|
| @@ -1924,25 +2024,23 @@ SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
|
| ** while [sqlite3_changes()] is running then the value returned
|
| ** is unpredictable and not meaningful.
|
| */
|
| -SQLITE_API int sqlite3_changes(sqlite3*);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_changes(sqlite3*);
|
|
|
| /*
|
| ** CAPI3REF: Total Number Of Rows Modified
|
| +** METHOD: sqlite3
|
| **
|
| -** ^This function returns the number of row changes caused by [INSERT],
|
| -** [UPDATE] or [DELETE] statements since the [database connection] was opened.
|
| -** ^(The count returned by sqlite3_total_changes() includes all changes
|
| -** from all [CREATE TRIGGER | trigger] contexts and changes made by
|
| -** [foreign key actions]. However,
|
| -** the count does not include changes used to implement [REPLACE] constraints,
|
| -** do rollbacks or ABORT processing, or [DROP TABLE] processing. The
|
| -** count does not include rows of views that fire an [INSTEAD OF trigger],
|
| -** though if the INSTEAD OF trigger makes changes of its own, those changes
|
| -** are counted.)^
|
| -** ^The sqlite3_total_changes() function counts the changes as soon as
|
| -** the statement that makes them is completed (when the statement handle
|
| -** is passed to [sqlite3_reset()] or [sqlite3_finalize()]).
|
| -**
|
| +** ^This function returns 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().
|
| +**
|
| +** ^Changes made as part of [foreign key actions] are included in the
|
| +** count, but those made as part of REPLACE constraint resolution are
|
| +** not. ^Changes to a view that are intercepted by INSTEAD OF triggers
|
| +** are not counted.
|
| +**
|
| ** See also the [sqlite3_changes()] interface, the
|
| ** [count_changes pragma], and the [total_changes() SQL function].
|
| **
|
| @@ -1950,10 +2048,11 @@ SQLITE_API int sqlite3_changes(sqlite3*);
|
| ** while [sqlite3_total_changes()] is running then the value
|
| ** returned is unpredictable and not meaningful.
|
| */
|
| -SQLITE_API int sqlite3_total_changes(sqlite3*);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_total_changes(sqlite3*);
|
|
|
| /*
|
| ** CAPI3REF: Interrupt A Long-Running Query
|
| +** METHOD: sqlite3
|
| **
|
| ** ^This function causes any pending database operation to abort and
|
| ** return at its earliest opportunity. This routine is typically
|
| @@ -1989,7 +2088,7 @@ SQLITE_API int sqlite3_total_changes(sqlite3*);
|
| ** If the database connection closes while [sqlite3_interrupt()]
|
| ** is running then bad things will likely happen.
|
| */
|
| -SQLITE_API void sqlite3_interrupt(sqlite3*);
|
| +SQLITE_API void SQLITE_STDCALL sqlite3_interrupt(sqlite3*);
|
|
|
| /*
|
| ** CAPI3REF: Determine If An SQL Statement Is Complete
|
| @@ -2024,11 +2123,13 @@ SQLITE_API void sqlite3_interrupt(sqlite3*);
|
| ** The input to [sqlite3_complete16()] must be a zero-terminated
|
| ** UTF-16 string in native byte order.
|
| */
|
| -SQLITE_API int sqlite3_complete(const char *sql);
|
| -SQLITE_API int sqlite3_complete16(const void *sql);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_complete(const char *sql);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_complete16(const void *sql);
|
|
|
| /*
|
| ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
|
| +** KEYWORDS: {busy-handler callback} {busy handler}
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
|
| ** that might be invoked with argument P whenever
|
| @@ -2045,7 +2146,7 @@ SQLITE_API int sqlite3_complete16(const void *sql);
|
| ** ^The first argument to the busy handler is a copy of the void* pointer which
|
| ** is the third argument to sqlite3_busy_handler(). ^The second argument to
|
| ** the busy handler callback is the number of times that the busy handler has
|
| -** been invoked for the same locking event. ^If the
|
| +** been invoked previously for the same locking event. ^If the
|
| ** busy callback returns 0, then no additional attempts are made to
|
| ** access the database and [SQLITE_BUSY] is returned
|
| ** to the application.
|
| @@ -2084,10 +2185,11 @@ SQLITE_API int 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 sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
|
|
|
| /*
|
| ** CAPI3REF: Set A Busy Timeout
|
| +** METHOD: sqlite3
|
| **
|
| ** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
|
| ** for a specified amount of time when a table is locked. ^The handler
|
| @@ -2106,10 +2208,11 @@ SQLITE_API int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
|
| **
|
| ** See also: [PRAGMA busy_timeout]
|
| */
|
| -SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_busy_timeout(sqlite3*, int ms);
|
|
|
| /*
|
| ** CAPI3REF: Convenience Routines For Running Queries
|
| +** METHOD: sqlite3
|
| **
|
| ** This is a legacy interface that is preserved for backwards compatibility.
|
| ** Use of this interface is not recommended.
|
| @@ -2180,7 +2283,7 @@ SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
|
| ** reflected in subsequent calls to [sqlite3_errcode()] or
|
| ** [sqlite3_errmsg()].
|
| */
|
| -SQLITE_API int sqlite3_get_table(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_get_table(
|
| sqlite3 *db, /* An open database */
|
| const char *zSql, /* SQL to be evaluated */
|
| char ***pazResult, /* Results of the query */
|
| @@ -2188,13 +2291,17 @@ SQLITE_API int sqlite3_get_table(
|
| int *pnColumn, /* Number of result columns written here */
|
| char **pzErrmsg /* Error msg written here */
|
| );
|
| -SQLITE_API void sqlite3_free_table(char **result);
|
| +SQLITE_API void SQLITE_STDCALL sqlite3_free_table(char **result);
|
|
|
| /*
|
| ** CAPI3REF: Formatted String Printing Functions
|
| **
|
| ** These routines are work-alikes of the "printf()" family of functions
|
| ** from the standard C library.
|
| +** These routines understand most of the common K&R formatting options,
|
| +** plus some additional non-standard formats, detailed below.
|
| +** Note that some of the more obscure formatting options from recent
|
| +** C-library standards are omitted from this implementation.
|
| **
|
| ** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
|
| ** results into memory obtained from [sqlite3_malloc()].
|
| @@ -2227,7 +2334,7 @@ SQLITE_API void sqlite3_free_table(char **result);
|
| ** These routines all implement some additional formatting
|
| ** options that are useful for constructing SQL statements.
|
| ** All of the usual printf() formatting options apply. In addition, there
|
| -** is are "%q", "%Q", and "%z" options.
|
| +** is are "%q", "%Q", "%w" and "%z" options.
|
| **
|
| ** ^(The %q option works like %s in that it substitutes a nul-terminated
|
| ** string from the argument list. But %q also doubles every '\'' character.
|
| @@ -2280,14 +2387,20 @@ SQLITE_API void sqlite3_free_table(char **result);
|
| ** The code above will render a correct SQL statement in the zSQL
|
| ** variable even if the zText variable is a NULL pointer.
|
| **
|
| +** ^(The "%w" formatting option is like "%q" except that it expects to
|
| +** be contained within double-quotes instead of single quotes, and it
|
| +** escapes the double-quote character instead of the single-quote
|
| +** character.)^ The "%w" formatting option is intended for safely inserting
|
| +** table and column names into a constructed SQL statement.
|
| +**
|
| ** ^(The "%z" formatting option works like "%s" but with the
|
| ** addition that after the string has been read and copied into
|
| ** the result, [sqlite3_free()] is called on the input string.)^
|
| */
|
| -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);
|
| +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);
|
|
|
| /*
|
| ** CAPI3REF: Memory Allocation Subsystem
|
| @@ -2377,12 +2490,12 @@ SQLITE_API char *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 *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*);
|
| +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*);
|
|
|
| /*
|
| ** CAPI3REF: Memory Allocator Statistics
|
| @@ -2407,8 +2520,8 @@ SQLITE_API sqlite3_uint64 sqlite3_msize(void*);
|
| ** by [sqlite3_memory_highwater(1)] is the high-water mark
|
| ** prior to the reset.
|
| */
|
| -SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
|
| -SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
|
| +SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_memory_used(void);
|
| +SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_memory_highwater(int resetFlag);
|
|
|
| /*
|
| ** CAPI3REF: Pseudo-Random Number Generator
|
| @@ -2420,20 +2533,22 @@ SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
|
| ** applications to access the same PRNG for other purposes.
|
| **
|
| ** ^A call to this routine stores N bytes of randomness into buffer P.
|
| -** ^If N is less than one, then P can be a NULL pointer.
|
| +** ^The P parameter can be a NULL pointer.
|
| **
|
| ** ^If this routine has not been previously called or if the previous
|
| -** call had N less than one, then the PRNG is seeded using randomness
|
| -** obtained from the xRandomness method of the default [sqlite3_vfs] object.
|
| -** ^If the previous call to this routine had an N of 1 or more then
|
| -** the pseudo-randomness is generated
|
| +** call had N less than one or a NULL pointer for P, then the PRNG is
|
| +** seeded using randomness obtained from the xRandomness method of
|
| +** the default [sqlite3_vfs] object.
|
| +** ^If the previous call to this routine had an N of 1 or more and a
|
| +** non-NULL P then the pseudo-randomness is generated
|
| ** internally and without recourse to the [sqlite3_vfs] xRandomness
|
| ** method.
|
| */
|
| -SQLITE_API void sqlite3_randomness(int N, void *P);
|
| +SQLITE_API void SQLITE_STDCALL sqlite3_randomness(int N, void *P);
|
|
|
| /*
|
| ** CAPI3REF: Compile-Time Authorization Callbacks
|
| +** METHOD: sqlite3
|
| **
|
| ** ^This routine registers an authorizer callback with a particular
|
| ** [database connection], supplied in the first argument.
|
| @@ -2512,7 +2627,7 @@ SQLITE_API void 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 sqlite3_set_authorizer(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_set_authorizer(
|
| sqlite3*,
|
| int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
|
| void *pUserData
|
| @@ -2590,6 +2705,7 @@ SQLITE_API int sqlite3_set_authorizer(
|
|
|
| /*
|
| ** CAPI3REF: Tracing And Profiling Functions
|
| +** METHOD: sqlite3
|
| **
|
| ** These routines register callback functions that can be used for
|
| ** tracing and profiling the execution of SQL statements.
|
| @@ -2616,12 +2732,13 @@ SQLITE_API int sqlite3_set_authorizer(
|
| ** sqlite3_profile() function is considered experimental and is
|
| ** subject to change in future versions of SQLite.
|
| */
|
| -SQLITE_API void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
|
| -SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
|
| +SQLITE_API void *SQLITE_STDCALL sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
|
| +SQLITE_API SQLITE_EXPERIMENTAL void *SQLITE_STDCALL sqlite3_profile(sqlite3*,
|
| void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
|
|
|
| /*
|
| ** CAPI3REF: Query Progress Callbacks
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
|
| ** function X to be invoked periodically during long running calls to
|
| @@ -2651,10 +2768,11 @@ SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
|
| ** database connections for the meaning of "modify" in this paragraph.
|
| **
|
| */
|
| -SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
|
| +SQLITE_API void SQLITE_STDCALL sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
|
|
|
| /*
|
| ** CAPI3REF: Opening A New Database Connection
|
| +** CONSTRUCTOR: sqlite3
|
| **
|
| ** ^These routines open an SQLite database file as specified by the
|
| ** filename argument. ^The filename argument is interpreted as UTF-8 for
|
| @@ -2879,15 +2997,15 @@ SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
|
| **
|
| ** See also: [sqlite3_temp_directory]
|
| */
|
| -SQLITE_API int sqlite3_open(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_open(
|
| const char *filename, /* Database filename (UTF-8) */
|
| sqlite3 **ppDb /* OUT: SQLite db handle */
|
| );
|
| -SQLITE_API int sqlite3_open16(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_open16(
|
| const void *filename, /* Database filename (UTF-16) */
|
| sqlite3 **ppDb /* OUT: SQLite db handle */
|
| );
|
| -SQLITE_API int sqlite3_open_v2(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_open_v2(
|
| const char *filename, /* Database filename (UTF-8) */
|
| sqlite3 **ppDb, /* OUT: SQLite db handle */
|
| int flags, /* Flags */
|
| @@ -2933,19 +3051,22 @@ SQLITE_API int sqlite3_open_v2(
|
| ** VFS method, then the behavior of this routine is undefined and probably
|
| ** undesirable.
|
| */
|
| -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);
|
| +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);
|
|
|
|
|
| /*
|
| ** CAPI3REF: Error Codes And Messages
|
| -**
|
| -** ^The sqlite3_errcode() interface returns the numeric [result code] or
|
| -** [extended result code] for the most recent failed sqlite3_* API call
|
| -** associated with a [database connection]. If a prior API call failed
|
| -** but the most recent API call succeeded, the return value from
|
| -** sqlite3_errcode() is undefined. ^The sqlite3_extended_errcode()
|
| +** METHOD: sqlite3
|
| +**
|
| +** ^If the most recent sqlite3_* API call associated with
|
| +** [database connection] D failed, then the sqlite3_errcode(D) interface
|
| +** returns the numeric [result code] or [extended result code] for that
|
| +** API call.
|
| +** If the most recent API call was successful,
|
| +** then the return value from sqlite3_errcode() is undefined.
|
| +** ^The sqlite3_extended_errcode()
|
| ** interface is the same except that it always returns the
|
| ** [extended result code] even when extended result codes are
|
| ** disabled.
|
| @@ -2976,40 +3097,41 @@ SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int
|
| ** was invoked incorrectly by the application. In that case, the
|
| ** error code and message may or may not be set.
|
| */
|
| -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);
|
| +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);
|
|
|
| /*
|
| -** CAPI3REF: SQL Statement Object
|
| +** CAPI3REF: Prepared Statement Object
|
| ** KEYWORDS: {prepared statement} {prepared statements}
|
| **
|
| -** An instance of this object represents a single SQL statement.
|
| -** This object is variously known as a "prepared statement" or a
|
| -** "compiled SQL statement" or simply as a "statement".
|
| +** An instance of this object represents a single SQL statement that
|
| +** has been compiled into binary form and is ready to be evaluated.
|
| +**
|
| +** Think of each SQL statement as a separate computer program. The
|
| +** original SQL text is source code. A prepared statement object
|
| +** is the compiled object code. All SQL must be converted into a
|
| +** prepared statement before it can be run.
|
| **
|
| -** The life of a statement object goes something like this:
|
| +** The life-cycle of a prepared statement object usually goes like this:
|
| **
|
| ** <ol>
|
| -** <li> Create the object using [sqlite3_prepare_v2()] or a related
|
| -** function.
|
| -** <li> Bind values to [host parameters] using the sqlite3_bind_*()
|
| +** <li> Create the prepared statement object using [sqlite3_prepare_v2()].
|
| +** <li> Bind values to [parameters] using the sqlite3_bind_*()
|
| ** interfaces.
|
| ** <li> Run the SQL by calling [sqlite3_step()] one or more times.
|
| -** <li> Reset the statement using [sqlite3_reset()] then go back
|
| +** <li> Reset the prepared statement using [sqlite3_reset()] then go back
|
| ** to step 2. Do this zero or more times.
|
| ** <li> Destroy the object using [sqlite3_finalize()].
|
| ** </ol>
|
| -**
|
| -** Refer to documentation on individual methods above for additional
|
| -** information.
|
| */
|
| typedef struct sqlite3_stmt sqlite3_stmt;
|
|
|
| /*
|
| ** CAPI3REF: Run-time Limits
|
| +** METHOD: sqlite3
|
| **
|
| ** ^(This interface allows the size of various constructs to be limited
|
| ** on a connection by connection basis. The first parameter is the
|
| @@ -3047,7 +3169,7 @@ typedef struct sqlite3_stmt sqlite3_stmt;
|
| **
|
| ** New run-time limit categories may be added in future releases.
|
| */
|
| -SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_limit(sqlite3*, int id, int newVal);
|
|
|
| /*
|
| ** CAPI3REF: Run-Time Limit Categories
|
| @@ -3121,6 +3243,8 @@ SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
|
| /*
|
| ** CAPI3REF: Compiling An SQL Statement
|
| ** KEYWORDS: {SQL statement compiler}
|
| +** METHOD: sqlite3
|
| +** CONSTRUCTOR: sqlite3_stmt
|
| **
|
| ** To execute an SQL query, it must first be compiled into a byte-code
|
| ** program using one of these routines.
|
| @@ -3134,16 +3258,14 @@ SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
|
| ** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()
|
| ** use UTF-16.
|
| **
|
| -** ^If the nByte argument is less than zero, then zSql is read up to the
|
| -** first zero terminator. ^If nByte is non-negative, then it is the maximum
|
| -** number of bytes read from zSql. ^When nByte is non-negative, the
|
| -** zSql string ends at either the first '\000' or '\u0000' character or
|
| -** the nByte-th byte, whichever comes first. If the caller knows
|
| -** that the supplied string is nul-terminated, then there is a small
|
| -** performance advantage to be gained by passing an nByte parameter that
|
| -** is equal to the number of bytes in the input string <i>including</i>
|
| -** the nul-terminator bytes as this saves SQLite from having to
|
| -** make a copy of the input string.
|
| +** ^If the nByte argument is negative, then zSql is read up to the
|
| +** first zero terminator. ^If nByte is positive, then it is the
|
| +** number of bytes read from zSql. ^If nByte is zero, then no prepared
|
| +** statement is generated.
|
| +** If the caller knows that the supplied string is nul-terminated, then
|
| +** there is a small performance advantage to passing an nByte parameter that
|
| +** is the number of bytes in the input string <i>including</i>
|
| +** the nul-terminator.
|
| **
|
| ** ^If pzTail is not NULL then *pzTail is made to point to the first byte
|
| ** past the end of the first SQL statement in zSql. These routines only
|
| @@ -3199,28 +3321,28 @@ SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
|
| ** </li>
|
| ** </ol>
|
| */
|
| -SQLITE_API int sqlite3_prepare(
|
| +SQLITE_API int SQLITE_STDCALL 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 sqlite3_prepare_v2(
|
| +SQLITE_API int SQLITE_STDCALL 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 sqlite3_prepare16(
|
| +SQLITE_API int SQLITE_STDCALL 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 sqlite3_prepare16_v2(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_prepare16_v2(
|
| sqlite3 *db, /* Database handle */
|
| const void *zSql, /* SQL statement, UTF-16 encoded */
|
| int nByte, /* Maximum length of zSql in bytes. */
|
| @@ -3230,15 +3352,17 @@ SQLITE_API int 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()].
|
| */
|
| -SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
|
| +SQLITE_API const char *SQLITE_STDCALL sqlite3_sql(sqlite3_stmt *pStmt);
|
|
|
| /*
|
| ** CAPI3REF: Determine If An SQL Statement Writes The Database
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
|
| ** and only if the [prepared statement] X makes no direct changes to
|
| @@ -3266,14 +3390,16 @@ SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
|
| ** change the configuration of a database connection, they do not make
|
| ** changes to the content of the database files on disk.
|
| */
|
| -SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
|
|
|
| /*
|
| ** CAPI3REF: Determine If A Prepared Statement Has Been Reset
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
|
| ** [prepared statement] S has been stepped at least once using
|
| -** [sqlite3_step(S)] but has not run to completion and/or has not
|
| +** [sqlite3_step(S)] but has neither run to completion (returned
|
| +** [SQLITE_DONE] from [sqlite3_step(S)]) nor
|
| ** been reset using [sqlite3_reset(S)]. ^The sqlite3_stmt_busy(S)
|
| ** interface returns false if S is a NULL pointer. If S is not a
|
| ** NULL pointer and is not a pointer to a valid [prepared statement]
|
| @@ -3285,7 +3411,7 @@ SQLITE_API int 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 sqlite3_stmt_busy(sqlite3_stmt*);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_stmt_busy(sqlite3_stmt*);
|
|
|
| /*
|
| ** CAPI3REF: Dynamically Typed Value Object
|
| @@ -3300,7 +3426,9 @@ SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*);
|
| ** Some interfaces require a protected sqlite3_value. Other interfaces
|
| ** will accept either a protected or an unprotected sqlite3_value.
|
| ** Every interface that accepts sqlite3_value arguments specifies
|
| -** whether or not it requires a protected sqlite3_value.
|
| +** whether or not it requires a protected sqlite3_value. The
|
| +** [sqlite3_value_dup()] interface can be used to construct a new
|
| +** protected sqlite3_value from an unprotected sqlite3_value.
|
| **
|
| ** The terms "protected" and "unprotected" refer to whether or not
|
| ** a mutex is held. An internal mutex is held for a protected
|
| @@ -3344,6 +3472,7 @@ typedef struct sqlite3_context sqlite3_context;
|
| ** CAPI3REF: Binding Values To Prepared Statements
|
| ** KEYWORDS: {host parameter} {host parameters} {host parameter name}
|
| ** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
|
| ** literals may be replaced by a [parameter] that matches one of following
|
| @@ -3446,22 +3575,24 @@ typedef struct sqlite3_context sqlite3_context;
|
| ** See also: [sqlite3_bind_parameter_count()],
|
| ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
|
| */
|
| -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,
|
| +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,
|
| void(*)(void*));
|
| -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,
|
| +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,
|
| void(*)(void*), unsigned char encoding);
|
| -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 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);
|
|
|
| /*
|
| ** CAPI3REF: Number Of SQL Parameters
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^This routine can be used to find the number of [SQL parameters]
|
| ** in a [prepared statement]. SQL parameters are tokens of the
|
| @@ -3478,10 +3609,11 @@ SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
|
| ** [sqlite3_bind_parameter_name()], and
|
| ** [sqlite3_bind_parameter_index()].
|
| */
|
| -SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_bind_parameter_count(sqlite3_stmt*);
|
|
|
| /*
|
| ** CAPI3REF: Name Of A Host Parameter
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^The sqlite3_bind_parameter_name(P,N) interface returns
|
| ** the name of the N-th [SQL parameter] in the [prepared statement] P.
|
| @@ -3505,10 +3637,11 @@ SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
|
| ** [sqlite3_bind_parameter_count()], and
|
| ** [sqlite3_bind_parameter_index()].
|
| */
|
| -SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
|
| +SQLITE_API const char *SQLITE_STDCALL sqlite3_bind_parameter_name(sqlite3_stmt*, int);
|
|
|
| /*
|
| ** CAPI3REF: Index Of A Parameter With A Given Name
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^Return the index of an SQL parameter given its name. ^The
|
| ** index value returned is suitable for use as the second
|
| @@ -3519,21 +3652,23 @@ SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
|
| **
|
| ** See also: [sqlite3_bind_blob|sqlite3_bind()],
|
| ** [sqlite3_bind_parameter_count()], and
|
| -** [sqlite3_bind_parameter_index()].
|
| +** [sqlite3_bind_parameter_name()].
|
| */
|
| -SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
|
|
|
| /*
|
| ** CAPI3REF: Reset All Bindings On A Prepared Statement
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
|
| ** the [sqlite3_bind_blob | bindings] on a [prepared statement].
|
| ** ^Use this routine to reset all host parameters to NULL.
|
| */
|
| -SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
|
| +SQLITE_API int SQLITE_STDCALL 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
|
| @@ -3541,10 +3676,11 @@ SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
|
| **
|
| ** See also: [sqlite3_data_count()]
|
| */
|
| -SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_column_count(sqlite3_stmt *pStmt);
|
|
|
| /*
|
| ** CAPI3REF: Column Names In A Result Set
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^These routines return the name assigned to a particular column
|
| ** in the result set of a [SELECT] statement. ^The sqlite3_column_name()
|
| @@ -3569,11 +3705,12 @@ SQLITE_API int 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 *sqlite3_column_name(sqlite3_stmt*, int N);
|
| -SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);
|
| +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);
|
|
|
| /*
|
| ** CAPI3REF: Source Of Data In A Query Result
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^These routines provide a means to determine the database, table, and
|
| ** table column that is the origin of a particular result column in
|
| @@ -3617,15 +3754,16 @@ SQLITE_API const void *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 *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);
|
| +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);
|
|
|
| /*
|
| ** CAPI3REF: Declared Datatype Of A Query Result
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^(The first parameter is a [prepared statement].
|
| ** If this statement is a [SELECT] statement and the Nth column of the
|
| @@ -3653,11 +3791,12 @@ SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
|
| ** is associated with individual values, not with the containers
|
| ** used to hold those values.
|
| */
|
| -SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);
|
| -SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
|
| +SQLITE_API const char *SQLITE_STDCALL sqlite3_column_decltype(sqlite3_stmt*,int);
|
| +SQLITE_API const void *SQLITE_STDCALL sqlite3_column_decltype16(sqlite3_stmt*,int);
|
|
|
| /*
|
| ** CAPI3REF: Evaluate An SQL Statement
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** After a [prepared statement] has been prepared using either
|
| ** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy
|
| @@ -3733,10 +3872,11 @@ SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
|
| ** then the more specific [error codes] are returned directly
|
| ** by sqlite3_step(). The use of the "v2" interface is recommended.
|
| */
|
| -SQLITE_API int sqlite3_step(sqlite3_stmt*);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_step(sqlite3_stmt*);
|
|
|
| /*
|
| ** CAPI3REF: Number of columns in a result set
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^The sqlite3_data_count(P) interface returns the number of columns in the
|
| ** current row of the result set of [prepared statement] P.
|
| @@ -3753,7 +3893,7 @@ SQLITE_API int sqlite3_step(sqlite3_stmt*);
|
| **
|
| ** See also: [sqlite3_column_count()]
|
| */
|
| -SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_data_count(sqlite3_stmt *pStmt);
|
|
|
| /*
|
| ** CAPI3REF: Fundamental Datatypes
|
| @@ -3790,8 +3930,7 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
|
| /*
|
| ** CAPI3REF: Result Values From A Query
|
| ** KEYWORDS: {column access functions}
|
| -**
|
| -** These routines form the "result set" interface.
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^These routines return information about a single column of the current
|
| ** result row of a query. ^In every case the first argument is a pointer
|
| @@ -3852,13 +3991,14 @@ 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.
|
| **
|
| -** ^The object returned by [sqlite3_column_value()] is an
|
| -** [unprotected sqlite3_value] object. An unprotected sqlite3_value object
|
| -** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].
|
| +** <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
|
| +** [sqlite3_bind_value()] and [sqlite3_result_value()].
|
| ** If the [unprotected sqlite3_value] object returned by
|
| ** [sqlite3_column_value()] is used in any other way, including calls
|
| ** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
|
| -** or [sqlite3_value_bytes()], then the behavior is undefined.
|
| +** or [sqlite3_value_bytes()], the behavior is not threadsafe.
|
| **
|
| ** These routines attempt to convert the value where appropriate. ^For
|
| ** example, if the internal representation is FLOAT and a text result
|
| @@ -3889,12 +4029,6 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
|
| ** </table>
|
| ** </blockquote>)^
|
| **
|
| -** The table above makes reference to standard C library functions atoi()
|
| -** and atof(). SQLite does not really use these functions. It has its
|
| -** own equivalent internal routines. The atoi() and atof() names are
|
| -** used in the table for brevity and because they are familiar to most
|
| -** C programmers.
|
| -**
|
| ** Note that when type conversions occur, pointers returned by prior
|
| ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
|
| ** sqlite3_column_text16() may be invalidated.
|
| @@ -3919,7 +4053,7 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
|
| ** of conversion are done in place when it is possible, but sometimes they
|
| ** are not possible and in those cases prior pointers are invalidated.
|
| **
|
| -** The safest and easiest to remember policy is to invoke these routines
|
| +** The safest policy is to invoke these routines
|
| ** in one of the following ways:
|
| **
|
| ** <ul>
|
| @@ -3939,7 +4073,7 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
|
| ** ^The pointers returned are valid until a type conversion occurs as
|
| ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
|
| ** [sqlite3_finalize()] is called. ^The memory space used to hold strings
|
| -** and BLOBs is freed automatically. Do <b>not</b> pass the pointers returned
|
| +** and BLOBs is freed automatically. Do <em>not</em> pass the pointers returned
|
| ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
|
| ** [sqlite3_free()].
|
| **
|
| @@ -3949,19 +4083,20 @@ SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
|
| ** pointer. Subsequent calls to [sqlite3_errcode()] will return
|
| ** [SQLITE_NOMEM].)^
|
| */
|
| -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);
|
| +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);
|
|
|
| /*
|
| ** CAPI3REF: Destroy A Prepared Statement Object
|
| +** DESTRUCTOR: sqlite3_stmt
|
| **
|
| ** ^The sqlite3_finalize() function is called to delete a [prepared statement].
|
| ** ^If the most recent evaluation of the statement encountered no errors
|
| @@ -3985,10 +4120,11 @@ SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
|
| ** statement after it has been finalized can result in undefined and
|
| ** undesirable behavior such as segfaults and heap corruption.
|
| */
|
| -SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_finalize(sqlite3_stmt *pStmt);
|
|
|
| /*
|
| ** CAPI3REF: Reset A Prepared Statement Object
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** The sqlite3_reset() function is called to reset a [prepared statement]
|
| ** object back to its initial state, ready to be re-executed.
|
| @@ -4011,13 +4147,14 @@ SQLITE_API int 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 sqlite3_reset(sqlite3_stmt *pStmt);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_reset(sqlite3_stmt *pStmt);
|
|
|
| /*
|
| ** CAPI3REF: Create Or Redefine SQL Functions
|
| ** KEYWORDS: {function creation routines}
|
| ** KEYWORDS: {application-defined SQL function}
|
| ** KEYWORDS: {application-defined SQL functions}
|
| +** METHOD: sqlite3
|
| **
|
| ** ^These functions (collectively known as "function creation routines")
|
| ** are used to add SQL functions or aggregates or to redefine the behavior
|
| @@ -4110,7 +4247,7 @@ SQLITE_API int 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 sqlite3_create_function(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_create_function(
|
| sqlite3 *db,
|
| const char *zFunctionName,
|
| int nArg,
|
| @@ -4120,7 +4257,7 @@ SQLITE_API int sqlite3_create_function(
|
| void (*xStep)(sqlite3_context*,int,sqlite3_value**),
|
| void (*xFinal)(sqlite3_context*)
|
| );
|
| -SQLITE_API int sqlite3_create_function16(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_create_function16(
|
| sqlite3 *db,
|
| const void *zFunctionName,
|
| int nArg,
|
| @@ -4130,7 +4267,7 @@ SQLITE_API int sqlite3_create_function16(
|
| void (*xStep)(sqlite3_context*,int,sqlite3_value**),
|
| void (*xFinal)(sqlite3_context*)
|
| );
|
| -SQLITE_API int sqlite3_create_function_v2(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_create_function_v2(
|
| sqlite3 *db,
|
| const char *zFunctionName,
|
| int nArg,
|
| @@ -4148,9 +4285,9 @@ SQLITE_API int sqlite3_create_function_v2(
|
| ** These constant define integer codes that represent the various
|
| ** text encodings supported by SQLite.
|
| */
|
| -#define SQLITE_UTF8 1
|
| -#define SQLITE_UTF16LE 2
|
| -#define SQLITE_UTF16BE 3
|
| +#define SQLITE_UTF8 1 /* IMP: R-37514-35566 */
|
| +#define SQLITE_UTF16LE 2 /* IMP: R-03371-37637 */
|
| +#define SQLITE_UTF16BE 3 /* IMP: R-51971-34154 */
|
| #define SQLITE_UTF16 4 /* Use native byte order */
|
| #define SQLITE_ANY 5 /* Deprecated */
|
| #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
|
| @@ -4172,25 +4309,26 @@ SQLITE_API int sqlite3_create_function_v2(
|
| ** These functions are [deprecated]. In order to maintain
|
| ** backwards compatibility with older code, these functions continue
|
| ** to be supported. However, new applications should avoid
|
| -** the use of these functions. To help encourage people to avoid
|
| -** using these functions, we are not going to tell you what they do.
|
| +** the use of these functions. To encourage programmers to avoid
|
| +** these functions, we will not explain what they do.
|
| */
|
| #ifndef SQLITE_OMIT_DEPRECATED
|
| -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),
|
| +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),
|
| void*,sqlite3_int64);
|
| #endif
|
|
|
| /*
|
| -** CAPI3REF: Obtaining SQL Function Parameter Values
|
| +** CAPI3REF: Obtaining SQL Values
|
| +** METHOD: sqlite3_value
|
| **
|
| ** The C-language implementation of SQL functions and aggregates uses
|
| ** this set of interface routines to access the parameter values on
|
| -** the function or aggregate.
|
| +** the function or aggregate.
|
| **
|
| ** The xFunc (for scalar functions) or xStep (for aggregates) parameters
|
| ** to [sqlite3_create_function()] and [sqlite3_create_function16()]
|
| @@ -4230,21 +4368,55 @@ SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int6
|
| ** These routines must be called from the same thread as
|
| ** the SQL function that supplied the [sqlite3_value*] parameters.
|
| */
|
| -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*);
|
| +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*);
|
| +
|
| +/*
|
| +** CAPI3REF: Finding The Subtype Of SQL Values
|
| +** METHOD: sqlite3_value
|
| +**
|
| +** The sqlite3_value_subtype(V) function returns the subtype for
|
| +** an [application-defined SQL function] argument V. The subtype
|
| +** information can be used to pass a limited amount of context from
|
| +** one SQL function to another. Use the [sqlite3_result_subtype()]
|
| +** routine to set the subtype for the return value of an SQL function.
|
| +**
|
| +** SQLite makes no use of subtype itself. It merely passes the subtype
|
| +** from the result of one [application-defined SQL function] into the
|
| +** input of another.
|
| +*/
|
| +SQLITE_API unsigned int SQLITE_STDCALL sqlite3_value_subtype(sqlite3_value*);
|
| +
|
| +/*
|
| +** CAPI3REF: Copy And Free SQL Values
|
| +** METHOD: sqlite3_value
|
| +**
|
| +** ^The sqlite3_value_dup(V) interface makes a copy of the [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.
|
| +**
|
| +** ^The sqlite3_value_free(V) interface frees an [sqlite3_value] object
|
| +** 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*);
|
|
|
| /*
|
| ** CAPI3REF: Obtain Aggregate Function Context
|
| +** METHOD: sqlite3_context
|
| **
|
| ** Implementations of aggregate SQL functions use this
|
| ** routine to allocate memory for storing their state.
|
| @@ -4285,10 +4457,11 @@ SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
|
| ** This routine must be called from the same thread in which
|
| ** the aggregate SQL function is running.
|
| */
|
| -SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
|
| +SQLITE_API void *SQLITE_STDCALL sqlite3_aggregate_context(sqlite3_context*, int nBytes);
|
|
|
| /*
|
| ** CAPI3REF: User Data For Functions
|
| +** METHOD: sqlite3_context
|
| **
|
| ** ^The sqlite3_user_data() interface returns a copy of
|
| ** the pointer that was the pUserData parameter (the 5th parameter)
|
| @@ -4299,10 +4472,11 @@ SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
|
| ** This routine must be called from the same thread in which
|
| ** the application-defined function is running.
|
| */
|
| -SQLITE_API void *sqlite3_user_data(sqlite3_context*);
|
| +SQLITE_API void *SQLITE_STDCALL sqlite3_user_data(sqlite3_context*);
|
|
|
| /*
|
| ** CAPI3REF: Database Connection For Functions
|
| +** METHOD: sqlite3_context
|
| **
|
| ** ^The sqlite3_context_db_handle() interface returns a copy of
|
| ** the pointer to the [database connection] (the 1st parameter)
|
| @@ -4310,10 +4484,11 @@ SQLITE_API void *sqlite3_user_data(sqlite3_context*);
|
| ** and [sqlite3_create_function16()] routines that originally
|
| ** registered the application defined function.
|
| */
|
| -SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
|
| +SQLITE_API sqlite3 *SQLITE_STDCALL sqlite3_context_db_handle(sqlite3_context*);
|
|
|
| /*
|
| ** CAPI3REF: Function Auxiliary Data
|
| +** METHOD: sqlite3_context
|
| **
|
| ** These functions may be used by (non-aggregate) SQL functions to
|
| ** associate metadata with argument values. If the same value is passed to
|
| @@ -4362,8 +4537,8 @@ SQLITE_API sqlite3 *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 *sqlite3_get_auxdata(sqlite3_context*, int N);
|
| -SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
|
| +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*));
|
|
|
|
|
| /*
|
| @@ -4386,6 +4561,7 @@ typedef void (*sqlite3_destructor_type)(void*);
|
|
|
| /*
|
| ** CAPI3REF: Setting The Result Of An SQL Function
|
| +** METHOD: sqlite3_context
|
| **
|
| ** These routines are used by the xFunc or xFinal callbacks that
|
| ** implement SQL functions and aggregates. See
|
| @@ -4401,9 +4577,9 @@ typedef void (*sqlite3_destructor_type)(void*);
|
| ** to by the second parameter and which is N bytes long where N is the
|
| ** third parameter.
|
| **
|
| -** ^The sqlite3_result_zeroblob() interfaces set the result of
|
| -** the application-defined function to be a BLOB containing all zero
|
| -** bytes and N bytes in size, where N is the value of the 2nd parameter.
|
| +** ^The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N)
|
| +** interfaces set the result of the application-defined function to be
|
| +** a BLOB containing all zero bytes and N bytes in size.
|
| **
|
| ** ^The sqlite3_result_double() interface sets the result from
|
| ** an application-defined function to be a floating point value specified
|
| @@ -4485,7 +4661,7 @@ typedef void (*sqlite3_destructor_type)(void*);
|
| ** from [sqlite3_malloc()] before it returns.
|
| **
|
| ** ^The sqlite3_result_value() interface sets the result of
|
| -** the application-defined function to be a copy the
|
| +** the application-defined function to be a copy of the
|
| ** [unprotected sqlite3_value] object specified by the 2nd parameter. ^The
|
| ** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
|
| ** so that the [sqlite3_value] specified in the parameter may change or
|
| @@ -4498,28 +4674,46 @@ 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 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 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,
|
| +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*,
|
| + 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,
|
| void(*)(void*), unsigned char encoding);
|
| -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 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);
|
| +
|
| +
|
| +/*
|
| +** CAPI3REF: Setting The Subtype Of An SQL Function
|
| +** METHOD: sqlite3_context
|
| +**
|
| +** The sqlite3_result_subtype(C,T) function causes the subtype of
|
| +** the result from the [application-defined SQL function] with
|
| +** [sqlite3_context] C to be the value T. Only the lower 8 bits
|
| +** of the subtype T are preserved in current versions of SQLite;
|
| +** higher order bits are discarded.
|
| +** 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);
|
|
|
| /*
|
| ** CAPI3REF: Define New Collating Sequences
|
| +** METHOD: sqlite3
|
| **
|
| ** ^These functions add, remove, or modify a [collation] associated
|
| ** with the [database connection] specified as the first argument.
|
| @@ -4597,14 +4791,14 @@ SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
|
| **
|
| ** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
|
| */
|
| -SQLITE_API int sqlite3_create_collation(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_create_collation(
|
| sqlite3*,
|
| const char *zName,
|
| int eTextRep,
|
| void *pArg,
|
| int(*xCompare)(void*,int,const void*,int,const void*)
|
| );
|
| -SQLITE_API int sqlite3_create_collation_v2(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_create_collation_v2(
|
| sqlite3*,
|
| const char *zName,
|
| int eTextRep,
|
| @@ -4612,7 +4806,7 @@ SQLITE_API int sqlite3_create_collation_v2(
|
| int(*xCompare)(void*,int,const void*,int,const void*),
|
| void(*xDestroy)(void*)
|
| );
|
| -SQLITE_API int sqlite3_create_collation16(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_create_collation16(
|
| sqlite3*,
|
| const void *zName,
|
| int eTextRep,
|
| @@ -4622,6 +4816,7 @@ SQLITE_API int sqlite3_create_collation16(
|
|
|
| /*
|
| ** CAPI3REF: Collation Needed Callbacks
|
| +** METHOD: sqlite3
|
| **
|
| ** ^To avoid having to register all collation sequences before a database
|
| ** can be used, a single callback function may be registered with the
|
| @@ -4646,12 +4841,12 @@ SQLITE_API int sqlite3_create_collation16(
|
| ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
|
| ** [sqlite3_create_collation_v2()].
|
| */
|
| -SQLITE_API int sqlite3_collation_needed(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_collation_needed(
|
| sqlite3*,
|
| void*,
|
| void(*)(void*,sqlite3*,int eTextRep,const char*)
|
| );
|
| -SQLITE_API int sqlite3_collation_needed16(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_collation_needed16(
|
| sqlite3*,
|
| void*,
|
| void(*)(void*,sqlite3*,int eTextRep,const void*)
|
| @@ -4665,11 +4860,11 @@ SQLITE_API int sqlite3_collation_needed16(
|
| ** The code to implement this API is not available in the public release
|
| ** of SQLite.
|
| */
|
| -SQLITE_API int sqlite3_key(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_key(
|
| sqlite3 *db, /* Database to be rekeyed */
|
| const void *pKey, int nKey /* The key */
|
| );
|
| -SQLITE_API int sqlite3_key_v2(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_key_v2(
|
| sqlite3 *db, /* Database to be rekeyed */
|
| const char *zDbName, /* Name of the database */
|
| const void *pKey, int nKey /* The key */
|
| @@ -4683,11 +4878,11 @@ SQLITE_API int sqlite3_key_v2(
|
| ** The code to implement this API is not available in the public release
|
| ** of SQLite.
|
| */
|
| -SQLITE_API int sqlite3_rekey(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_rekey(
|
| sqlite3 *db, /* Database to be rekeyed */
|
| const void *pKey, int nKey /* The new key */
|
| );
|
| -SQLITE_API int sqlite3_rekey_v2(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_rekey_v2(
|
| sqlite3 *db, /* Database to be rekeyed */
|
| const char *zDbName, /* Name of the database */
|
| const void *pKey, int nKey /* The new key */
|
| @@ -4697,7 +4892,7 @@ SQLITE_API int sqlite3_rekey_v2(
|
| ** Specify the activation key for a SEE database. Unless
|
| ** activated, none of the SEE routines will work.
|
| */
|
| -SQLITE_API void sqlite3_activate_see(
|
| +SQLITE_API void SQLITE_STDCALL sqlite3_activate_see(
|
| const char *zPassPhrase /* Activation phrase */
|
| );
|
| #endif
|
| @@ -4707,7 +4902,7 @@ SQLITE_API void sqlite3_activate_see(
|
| ** Specify the activation key for a CEROD database. Unless
|
| ** activated, none of the CEROD routines will work.
|
| */
|
| -SQLITE_API void sqlite3_activate_cerod(
|
| +SQLITE_API void SQLITE_STDCALL sqlite3_activate_cerod(
|
| const char *zPassPhrase /* Activation phrase */
|
| );
|
| #endif
|
| @@ -4729,7 +4924,7 @@ SQLITE_API void sqlite3_activate_cerod(
|
| ** all, then the behavior of sqlite3_sleep() may deviate from the description
|
| ** in the previous paragraphs.
|
| */
|
| -SQLITE_API int sqlite3_sleep(int);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_sleep(int);
|
|
|
| /*
|
| ** CAPI3REF: Name Of The Folder Holding Temporary Files
|
| @@ -4829,6 +5024,7 @@ SQLITE_API SQLITE_EXTERN char *sqlite3_data_directory;
|
| /*
|
| ** CAPI3REF: Test For Auto-Commit Mode
|
| ** KEYWORDS: {autocommit mode}
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The sqlite3_get_autocommit() interface returns non-zero or
|
| ** zero if the given database connection is or is not in autocommit mode,
|
| @@ -4847,10 +5043,11 @@ SQLITE_API SQLITE_EXTERN char *sqlite3_data_directory;
|
| ** connection while this routine is running, then the return value
|
| ** is undefined.
|
| */
|
| -SQLITE_API int sqlite3_get_autocommit(sqlite3*);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_get_autocommit(sqlite3*);
|
|
|
| /*
|
| ** CAPI3REF: Find The Database Handle Of A Prepared Statement
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^The sqlite3_db_handle interface returns the [database connection] handle
|
| ** to which a [prepared statement] belongs. ^The [database connection]
|
| @@ -4859,10 +5056,11 @@ SQLITE_API int 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 *sqlite3_db_handle(sqlite3_stmt*);
|
| +SQLITE_API sqlite3 *SQLITE_STDCALL sqlite3_db_handle(sqlite3_stmt*);
|
|
|
| /*
|
| ** CAPI3REF: Return The Filename For A Database Connection
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The sqlite3_db_filename(D,N) interface returns a pointer to a filename
|
| ** associated with database N of connection D. ^The main database file
|
| @@ -4875,19 +5073,21 @@ SQLITE_API sqlite3 *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 *sqlite3_db_filename(sqlite3 *db, const char *zDbName);
|
| +SQLITE_API const char *SQLITE_STDCALL sqlite3_db_filename(sqlite3 *db, const char *zDbName);
|
|
|
| /*
|
| ** CAPI3REF: Determine if a database is read-only
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The sqlite3_db_readonly(D,N) interface returns 1 if the database N
|
| ** 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 sqlite3_db_readonly(sqlite3 *db, const char *zDbName);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_db_readonly(sqlite3 *db, const char *zDbName);
|
|
|
| /*
|
| ** CAPI3REF: Find the next prepared statement
|
| +** METHOD: sqlite3
|
| **
|
| ** ^This interface returns a pointer to the next [prepared statement] after
|
| ** pStmt associated with the [database connection] pDb. ^If pStmt is NULL
|
| @@ -4899,10 +5099,11 @@ SQLITE_API int sqlite3_db_readonly(sqlite3 *db, const char *zDbName);
|
| ** [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 *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
|
| +SQLITE_API sqlite3_stmt *SQLITE_STDCALL sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
|
|
|
| /*
|
| ** CAPI3REF: Commit And Rollback Notification Callbacks
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The sqlite3_commit_hook() interface registers a callback
|
| ** function to be invoked whenever a transaction is [COMMIT | committed].
|
| @@ -4947,11 +5148,12 @@ SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
|
| **
|
| ** See also the [sqlite3_update_hook()] interface.
|
| */
|
| -SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
|
| -SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
|
| +SQLITE_API void *SQLITE_STDCALL sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
|
| +SQLITE_API void *SQLITE_STDCALL sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
|
|
|
| /*
|
| ** CAPI3REF: Data Change Notification Callbacks
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The sqlite3_update_hook() interface registers a callback function
|
| ** with the [database connection] identified by the first argument
|
| @@ -4998,7 +5200,7 @@ SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
|
| ** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()]
|
| ** interfaces.
|
| */
|
| -SQLITE_API void *sqlite3_update_hook(
|
| +SQLITE_API void *SQLITE_STDCALL sqlite3_update_hook(
|
| sqlite3*,
|
| void(*)(void *,int ,char const *,char const *,sqlite3_int64),
|
| void*
|
| @@ -5028,12 +5230,17 @@ SQLITE_API void *sqlite3_update_hook(
|
| ** future releases of SQLite. Applications that care about shared
|
| ** cache setting should set it explicitly.
|
| **
|
| +** Note: This method is disabled on MacOS X 10.7 and iOS version 5.0
|
| +** and will always return SQLITE_MISUSE. On those systems,
|
| +** shared cache mode should be enabled per-database connection via
|
| +** [sqlite3_open_v2()] with [SQLITE_OPEN_SHAREDCACHE].
|
| +**
|
| ** This interface is threadsafe on processors where writing a
|
| ** 32-bit integer is atomic.
|
| **
|
| ** See Also: [SQLite Shared-Cache Mode]
|
| */
|
| -SQLITE_API int sqlite3_enable_shared_cache(int);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_enable_shared_cache(int);
|
|
|
| /*
|
| ** CAPI3REF: Attempt To Free Heap Memory
|
| @@ -5049,10 +5256,11 @@ SQLITE_API int sqlite3_enable_shared_cache(int);
|
| **
|
| ** See also: [sqlite3_db_release_memory()]
|
| */
|
| -SQLITE_API int sqlite3_release_memory(int);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_release_memory(int);
|
|
|
| /*
|
| ** CAPI3REF: Free Memory Used By A Database Connection
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The sqlite3_db_release_memory(D) interface attempts to free as much heap
|
| ** memory as possible from database connection D. Unlike the
|
| @@ -5062,7 +5270,7 @@ SQLITE_API int sqlite3_release_memory(int);
|
| **
|
| ** See also: [sqlite3_release_memory()]
|
| */
|
| -SQLITE_API int sqlite3_db_release_memory(sqlite3*);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_db_release_memory(sqlite3*);
|
|
|
| /*
|
| ** CAPI3REF: Impose A Limit On Heap Size
|
| @@ -5114,7 +5322,7 @@ SQLITE_API int 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 sqlite3_soft_heap_limit64(sqlite3_int64 N);
|
| +SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_soft_heap_limit64(sqlite3_int64 N);
|
|
|
| /*
|
| ** CAPI3REF: Deprecated Soft Heap Limit Interface
|
| @@ -5125,26 +5333,34 @@ SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);
|
| ** only. All new applications should use the
|
| ** [sqlite3_soft_heap_limit64()] interface rather than this one.
|
| */
|
| -SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N);
|
| +SQLITE_API SQLITE_DEPRECATED void SQLITE_STDCALL sqlite3_soft_heap_limit(int N);
|
|
|
|
|
| /*
|
| ** CAPI3REF: Extract Metadata About A Column Of A Table
|
| -**
|
| -** ^This routine returns metadata about a specific column of a specific
|
| -** database table accessible using the [database connection] handle
|
| -** passed as the first function argument.
|
| +** METHOD: sqlite3
|
| +**
|
| +** ^(The sqlite3_table_column_metadata(X,D,T,C,....) routine returns
|
| +** information about column C of table T in database D
|
| +** on [database connection] X.)^ ^The sqlite3_table_column_metadata()
|
| +** interface returns SQLITE_OK and fills in the non-NULL pointers in
|
| +** the final five arguments with appropriate values if the specified
|
| +** 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
|
| +** table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it
|
| +** does not.
|
| **
|
| ** ^The column is identified by the second, third and fourth parameters to
|
| -** this function. ^The second parameter is either the name of the database
|
| +** this function. ^(The second parameter is either the name of the database
|
| ** (i.e. "main", "temp", or an attached database) containing the specified
|
| -** table or NULL. ^If it is NULL, then all attached databases are searched
|
| +** table or NULL.)^ ^If it is NULL, then all attached databases are searched
|
| ** for the table using the same algorithm used by the database engine to
|
| ** resolve unqualified table references.
|
| **
|
| ** ^The third and fourth parameters to this function are the table and column
|
| -** name of the desired column, respectively. Neither of these parameters
|
| -** may be NULL.
|
| +** name of the desired column, respectively.
|
| **
|
| ** ^Metadata is returned by writing to the memory locations passed as the 5th
|
| ** and subsequent parameters to this function. ^Any of these arguments may be
|
| @@ -5163,16 +5379,17 @@ SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N);
|
| ** </blockquote>)^
|
| **
|
| ** ^The memory pointed to by the character pointers returned for the
|
| -** declaration type and collation sequence is valid only until the next
|
| +** declaration type and collation sequence is valid until the next
|
| ** call to any SQLite API function.
|
| **
|
| ** ^If the specified table is actually a view, an [error code] is returned.
|
| **
|
| -** ^If the specified column is "rowid", "oid" or "_rowid_" and an
|
| +** ^If the specified column is "rowid", "oid" or "_rowid_" and the table
|
| +** is not a [WITHOUT ROWID] table and an
|
| ** [INTEGER PRIMARY KEY] column has been explicitly declared, then the output
|
| ** parameters are set for the explicitly declared column. ^(If there is no
|
| -** explicitly declared [INTEGER PRIMARY KEY] column, then the output
|
| -** parameters are set as follows:
|
| +** [INTEGER PRIMARY KEY] column, then the outputs
|
| +** for the [rowid] are set as follows:
|
| **
|
| ** <pre>
|
| ** data type: "INTEGER"
|
| @@ -5182,15 +5399,11 @@ SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N);
|
| ** auto increment: 0
|
| ** </pre>)^
|
| **
|
| -** ^(This function may load one or more schemas from database files. If an
|
| -** error occurs during this process, or if the requested table or column
|
| -** cannot be found, an [error code] is returned and an error message left
|
| -** in the [database connection] (to be retrieved using sqlite3_errmsg()).)^
|
| -**
|
| -** ^This API is only available if the library was compiled with the
|
| -** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined.
|
| +** ^This function causes all database schemas to be read from disk and
|
| +** parsed, if that has not already been done, and returns an error if
|
| +** any errors are encountered while loading the schema.
|
| */
|
| -SQLITE_API int sqlite3_table_column_metadata(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_table_column_metadata(
|
| sqlite3 *db, /* Connection handle */
|
| const char *zDbName, /* Database name or NULL */
|
| const char *zTableName, /* Table name */
|
| @@ -5204,6 +5417,7 @@ SQLITE_API int sqlite3_table_column_metadata(
|
|
|
| /*
|
| ** CAPI3REF: Load An Extension
|
| +** METHOD: sqlite3
|
| **
|
| ** ^This interface loads an SQLite extension library from the named file.
|
| **
|
| @@ -5236,7 +5450,7 @@ SQLITE_API int sqlite3_table_column_metadata(
|
| **
|
| ** See also the [load_extension() SQL function].
|
| */
|
| -SQLITE_API int sqlite3_load_extension(
|
| +SQLITE_API int SQLITE_STDCALL 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 */
|
| @@ -5245,6 +5459,7 @@ SQLITE_API int sqlite3_load_extension(
|
|
|
| /*
|
| ** CAPI3REF: Enable Or Disable Extension Loading
|
| +** METHOD: sqlite3
|
| **
|
| ** ^So as not to open security holes in older applications that are
|
| ** unprepared to deal with [extension loading], and as a means of disabling
|
| @@ -5256,7 +5471,7 @@ SQLITE_API int sqlite3_load_extension(
|
| ** to turn extension loading on and call it with onoff==0 to turn
|
| ** it back off again.
|
| */
|
| -SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_enable_load_extension(sqlite3 *db, int onoff);
|
|
|
| /*
|
| ** CAPI3REF: Automatically Load Statically Linked Extensions
|
| @@ -5294,7 +5509,7 @@ SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
|
| ** See also: [sqlite3_reset_auto_extension()]
|
| ** and [sqlite3_cancel_auto_extension()]
|
| */
|
| -SQLITE_API int sqlite3_auto_extension(void (*xEntryPoint)(void));
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_auto_extension(void (*xEntryPoint)(void));
|
|
|
| /*
|
| ** CAPI3REF: Cancel Automatic Extension Loading
|
| @@ -5306,7 +5521,7 @@ SQLITE_API int sqlite3_auto_extension(void (*xEntryPoint)(void));
|
| ** unregistered and it returns 0 if X was not on the list of initialization
|
| ** routines.
|
| */
|
| -SQLITE_API int sqlite3_cancel_auto_extension(void (*xEntryPoint)(void));
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_cancel_auto_extension(void (*xEntryPoint)(void));
|
|
|
| /*
|
| ** CAPI3REF: Reset Automatic Extension Loading
|
| @@ -5314,7 +5529,7 @@ SQLITE_API int sqlite3_cancel_auto_extension(void (*xEntryPoint)(void));
|
| ** ^This interface disables all automatic extensions previously
|
| ** registered using [sqlite3_auto_extension()].
|
| */
|
| -SQLITE_API void sqlite3_reset_auto_extension(void);
|
| +SQLITE_API void SQLITE_STDCALL sqlite3_reset_auto_extension(void);
|
|
|
| /*
|
| ** The interface to the virtual-table mechanism is currently considered
|
| @@ -5416,6 +5631,17 @@ struct sqlite3_module {
|
| ** ^Information about the ORDER BY clause is stored in aOrderBy[].
|
| ** ^Each term of aOrderBy records a column of the ORDER BY clause.
|
| **
|
| +** The colUsed field indicates which columns of the virtual table may be
|
| +** required by the current scan. Virtual table columns are numbered from
|
| +** zero in the order in which they appear within the CREATE TABLE statement
|
| +** passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62),
|
| +** the corresponding bit is set within the colUsed mask if the column may be
|
| +** required by SQLite. If the table has at least 64 columns and any column
|
| +** to the right of the first 63 is required, then bit 63 of colUsed is also
|
| +** set. In other words, column iCol may be required if the expression
|
| +** (colUsed & ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to
|
| +** non-zero.
|
| +**
|
| ** The [xBestIndex] method must fill aConstraintUsage[] with information
|
| ** about what parameters to pass to xFilter. ^If argvIndex>0 then
|
| ** the right-hand side of the corresponding aConstraint[] is evaluated
|
| @@ -5441,13 +5667,31 @@ struct sqlite3_module {
|
| ** ^The estimatedRows value is an estimate of the number of rows that
|
| ** will be returned by the strategy.
|
| **
|
| +** The xBestIndex method may optionally populate the idxFlags field with a
|
| +** mask of SQLITE_INDEX_SCAN_* flags. Currently there is only one such flag -
|
| +** SQLITE_INDEX_SCAN_UNIQUE. If the xBestIndex method sets this flag, SQLite
|
| +** assumes that the strategy may visit at most one row.
|
| +**
|
| +** Additionally, if xBestIndex sets the SQLITE_INDEX_SCAN_UNIQUE flag, then
|
| +** SQLite also assumes that if a call to the xUpdate() method is made as
|
| +** part of the same statement to delete or update a virtual table row and the
|
| +** implementation returns SQLITE_CONSTRAINT, then there is no need to rollback
|
| +** any database changes. In other words, if the xUpdate() returns
|
| +** SQLITE_CONSTRAINT, the database contents must be exactly as they were
|
| +** before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not
|
| +** set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by
|
| +** 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
|
| ** 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.
|
| +** 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
|
| +** sqlite3_libversion_number() returns a value greater than or equal to
|
| +** 3009000.
|
| */
|
| struct sqlite3_index_info {
|
| /* Inputs */
|
| @@ -5475,9 +5719,18 @@ struct sqlite3_index_info {
|
| double estimatedCost; /* Estimated cost of using this index */
|
| /* Fields below are only available in SQLite 3.8.2 and later */
|
| sqlite3_int64 estimatedRows; /* Estimated number of rows returned */
|
| + /* Fields below are only available in SQLite 3.9.0 and later */
|
| + int idxFlags; /* Mask of SQLITE_INDEX_SCAN_* flags */
|
| + /* Fields below are only available in SQLite 3.10.0 and later */
|
| + sqlite3_uint64 colUsed; /* Input: Mask of columns used by statement */
|
| };
|
|
|
| /*
|
| +** CAPI3REF: Virtual Table Scan Flags
|
| +*/
|
| +#define SQLITE_INDEX_SCAN_UNIQUE 1 /* Scan visits at most 1 row */
|
| +
|
| +/*
|
| ** CAPI3REF: Virtual Table Constraint Operator Codes
|
| **
|
| ** These macros defined the allowed values for the
|
| @@ -5485,15 +5738,19 @@ struct sqlite3_index_info {
|
| ** an operator that is part of a constraint term in the wHERE clause of
|
| ** a query that uses a [virtual table].
|
| */
|
| -#define SQLITE_INDEX_CONSTRAINT_EQ 2
|
| -#define SQLITE_INDEX_CONSTRAINT_GT 4
|
| -#define SQLITE_INDEX_CONSTRAINT_LE 8
|
| -#define SQLITE_INDEX_CONSTRAINT_LT 16
|
| -#define SQLITE_INDEX_CONSTRAINT_GE 32
|
| -#define SQLITE_INDEX_CONSTRAINT_MATCH 64
|
| +#define SQLITE_INDEX_CONSTRAINT_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
|
|
|
| /*
|
| ** CAPI3REF: Register A Virtual Table Implementation
|
| +** METHOD: sqlite3
|
| **
|
| ** ^These routines are used to register a new [virtual table module] name.
|
| ** ^Module names must be registered before
|
| @@ -5517,13 +5774,13 @@ struct sqlite3_index_info {
|
| ** interface is equivalent to sqlite3_create_module_v2() with a NULL
|
| ** destructor.
|
| */
|
| -SQLITE_API int sqlite3_create_module(
|
| +SQLITE_API int SQLITE_STDCALL 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 sqlite3_create_module_v2(
|
| +SQLITE_API int SQLITE_STDCALL 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 */
|
| @@ -5551,7 +5808,7 @@ SQLITE_API int sqlite3_create_module_v2(
|
| */
|
| struct sqlite3_vtab {
|
| const sqlite3_module *pModule; /* The module for this virtual table */
|
| - int nRef; /* NO LONGER USED */
|
| + int nRef; /* Number of open cursors */
|
| char *zErrMsg; /* Error message from sqlite3_mprintf() */
|
| /* Virtual table implementations will typically add additional fields */
|
| };
|
| @@ -5586,10 +5843,11 @@ struct sqlite3_vtab_cursor {
|
| ** to declare the format (the names and datatypes of the columns) of
|
| ** the virtual tables they implement.
|
| */
|
| -SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_declare_vtab(sqlite3*, const char *zSQL);
|
|
|
| /*
|
| ** CAPI3REF: Overload A Function For A Virtual Table
|
| +** METHOD: sqlite3
|
| **
|
| ** ^(Virtual tables can provide alternative implementations of functions
|
| ** using the [xFindFunction] method of the [virtual table module].
|
| @@ -5604,7 +5862,7 @@ SQLITE_API int 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 sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
|
|
|
| /*
|
| ** The interface to the virtual-table mechanism defined above (back up
|
| @@ -5632,6 +5890,8 @@ typedef struct sqlite3_blob sqlite3_blob;
|
|
|
| /*
|
| ** CAPI3REF: Open A BLOB For Incremental I/O
|
| +** METHOD: sqlite3
|
| +** CONSTRUCTOR: sqlite3_blob
|
| **
|
| ** ^(This interfaces opens a [BLOB handle | handle] to the BLOB located
|
| ** in row iRow, column zColumn, table zTable in database zDb;
|
| @@ -5641,26 +5901,42 @@ typedef struct sqlite3_blob sqlite3_blob;
|
| ** SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow;
|
| ** </pre>)^
|
| **
|
| +** ^(Parameter zDb is not the filename that contains the database, but
|
| +** rather the symbolic name of the database. For attached databases, this is
|
| +** the name that appears after the AS keyword in the [ATTACH] statement.
|
| +** For the main database file, the database name is "main". For TEMP
|
| +** tables, the database name is "temp".)^
|
| +**
|
| ** ^If the flags parameter is non-zero, then the BLOB is opened for read
|
| -** and write access. ^If it is zero, the BLOB is opened for read access.
|
| -** ^It is not possible to open a column that is part of an index or primary
|
| -** key for writing. ^If [foreign key constraints] are enabled, it is
|
| -** not possible to open a column that is part of a [child key] for writing.
|
| -**
|
| -** ^Note that the database name is not the filename that contains
|
| -** the database but rather the symbolic name of the database that
|
| -** appears after the AS keyword when the database is connected using [ATTACH].
|
| -** ^For the main database file, the database name is "main".
|
| -** ^For TEMP tables, the database name is "temp".
|
| -**
|
| -** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is written
|
| -** to *ppBlob. Otherwise an [error code] is returned and *ppBlob is set
|
| -** to be a null pointer.)^
|
| -** ^This function sets the [database connection] error code and message
|
| -** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()] and related
|
| -** functions. ^Note that the *ppBlob variable is always initialized in a
|
| -** way that makes it safe to invoke [sqlite3_blob_close()] on *ppBlob
|
| -** regardless of the success or failure of this routine.
|
| +** and write access. ^If the flags parameter is zero, the BLOB is opened for
|
| +** read-only access.
|
| +**
|
| +** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is stored
|
| +** in *ppBlob. Otherwise an [error code] is returned and, unless the error
|
| +** code is SQLITE_MISUSE, *ppBlob is set to NULL.)^ ^This means that, provided
|
| +** the API is not misused, it is always safe to call [sqlite3_blob_close()]
|
| +** on *ppBlob after this function it returns.
|
| +**
|
| +** This function fails with SQLITE_ERROR if any of the following are true:
|
| +** <ul>
|
| +** <li> ^(Database zDb does not exist)^,
|
| +** <li> ^(Table zTable does not exist within database zDb)^,
|
| +** <li> ^(Table zTable is a WITHOUT ROWID table)^,
|
| +** <li> ^(Column zColumn does not exist)^,
|
| +** <li> ^(Row iRow is not present in the table)^,
|
| +** <li> ^(The specified column of row iRow contains a value that is not
|
| +** a TEXT or BLOB value)^,
|
| +** <li> ^(Column zColumn is part of an index, PRIMARY KEY or UNIQUE
|
| +** constraint and the blob is being opened for read/write access)^,
|
| +** <li> ^([foreign key constraints | Foreign key constraints] are enabled,
|
| +** column zColumn is part of a [child key] definition and the blob is
|
| +** being opened for read/write access)^.
|
| +** </ul>
|
| +**
|
| +** ^Unless it returns SQLITE_MISUSE, this function sets the
|
| +** [database connection] error code and message accessible via
|
| +** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions.
|
| +**
|
| **
|
| ** ^(If the row that a BLOB handle points to is modified by an
|
| ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
|
| @@ -5678,18 +5954,14 @@ typedef struct sqlite3_blob sqlite3_blob;
|
| ** interface. Use the [UPDATE] SQL command to change the size of a
|
| ** blob.
|
| **
|
| -** ^The [sqlite3_blob_open()] interface will fail for a [WITHOUT ROWID]
|
| -** table. Incremental BLOB I/O is not possible on [WITHOUT ROWID] tables.
|
| -**
|
| ** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
|
| -** and the built-in [zeroblob] SQL function can be used, if desired,
|
| -** to create an empty, zero-filled blob in which to read or write using
|
| -** this interface.
|
| +** and the built-in [zeroblob] SQL function may be used to create a
|
| +** zero-filled blob to read or write using the incremental-blob interface.
|
| **
|
| ** To avoid a resource leak, every open [BLOB handle] should eventually
|
| ** be released by a call to [sqlite3_blob_close()].
|
| */
|
| -SQLITE_API int sqlite3_blob_open(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_blob_open(
|
| sqlite3*,
|
| const char *zDb,
|
| const char *zTable,
|
| @@ -5701,6 +5973,7 @@ SQLITE_API int 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
|
| ** to a different row of the same database table. ^The new row is identified
|
| @@ -5721,34 +5994,34 @@ SQLITE_API int sqlite3_blob_open(
|
| **
|
| ** ^This function sets the database handle error code and message.
|
| */
|
| -SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);
|
|
|
| /*
|
| ** CAPI3REF: Close A BLOB Handle
|
| +** DESTRUCTOR: sqlite3_blob
|
| **
|
| -** ^Closes an open [BLOB handle].
|
| -**
|
| -** ^Closing a BLOB shall cause the current transaction to commit
|
| -** if there are no other BLOBs, no pending prepared statements, and the
|
| -** database connection is in [autocommit mode].
|
| -** ^If any writes were made to the BLOB, they might be held in cache
|
| -** until the close operation if they will fit.
|
| +** ^This function closes an open [BLOB handle]. ^(The BLOB handle is closed
|
| +** unconditionally. Even if this routine returns an error code, the
|
| +** handle is still closed.)^
|
| **
|
| -** ^(Closing the BLOB often forces the changes
|
| -** out to disk and so if any I/O errors occur, they will likely occur
|
| -** at the time when the BLOB is closed. Any errors that occur during
|
| -** closing are reported as a non-zero return value.)^
|
| +** ^If the blob handle being closed was opened for read-write access, and if
|
| +** the database is in auto-commit mode and there are no other open read-write
|
| +** blob handles or active write statements, the current transaction is
|
| +** committed. ^If an error occurs while committing the transaction, an error
|
| +** code is returned and the transaction rolled back.
|
| **
|
| -** ^(The BLOB is closed unconditionally. Even if this routine returns
|
| -** an error code, the BLOB is still closed.)^
|
| -**
|
| -** ^Calling this routine with a null pointer (such as would be returned
|
| -** by a failed call to [sqlite3_blob_open()]) is a harmless no-op.
|
| +** Calling this function with an argument that is not a NULL pointer or an
|
| +** open blob handle results in undefined behaviour. ^Calling this routine
|
| +** with a null pointer (such as would be returned by a failed call to
|
| +** [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function
|
| +** 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 sqlite3_blob_close(sqlite3_blob *);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_blob_close(sqlite3_blob *);
|
|
|
| /*
|
| ** CAPI3REF: Return The Size Of An Open BLOB
|
| +** METHOD: sqlite3_blob
|
| **
|
| ** ^Returns the size in bytes of the BLOB accessible via the
|
| ** successfully opened [BLOB handle] in its only argument. ^The
|
| @@ -5760,10 +6033,11 @@ SQLITE_API int 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 sqlite3_blob_bytes(sqlite3_blob *);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_blob_bytes(sqlite3_blob *);
|
|
|
| /*
|
| ** CAPI3REF: Read Data From A BLOB Incrementally
|
| +** METHOD: sqlite3_blob
|
| **
|
| ** ^(This function is used to read data from an open [BLOB handle] into a
|
| ** caller-supplied buffer. N bytes of data are copied into buffer Z
|
| @@ -5788,26 +6062,33 @@ SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *);
|
| **
|
| ** See also: [sqlite3_blob_write()].
|
| */
|
| -SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
|
|
|
| /*
|
| ** CAPI3REF: Write Data Into A BLOB Incrementally
|
| +** METHOD: sqlite3_blob
|
| **
|
| -** ^This function is used to write data into an open [BLOB handle] from a
|
| -** caller-supplied buffer. ^N bytes of data are copied from the buffer Z
|
| -** into the open BLOB, starting at offset iOffset.
|
| +** ^(This function is used to write data into an open [BLOB handle] from a
|
| +** caller-supplied buffer. N bytes of data are copied from the buffer Z
|
| +** into the open BLOB, starting at offset iOffset.)^
|
| +**
|
| +** ^(On success, sqlite3_blob_write() returns SQLITE_OK.
|
| +** Otherwise, an [error code] or an [extended error code] is returned.)^
|
| +** ^Unless SQLITE_MISUSE is returned, this function sets the
|
| +** [database connection] error code and message accessible via
|
| +** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions.
|
| **
|
| ** ^If the [BLOB handle] passed as the first argument was not opened for
|
| ** writing (the flags parameter to [sqlite3_blob_open()] was zero),
|
| ** this function returns [SQLITE_READONLY].
|
| **
|
| -** ^This function may only modify the contents of the BLOB; it is
|
| +** This function may only modify the contents of the BLOB; it is
|
| ** not possible to increase the size of a BLOB using this API.
|
| ** ^If offset iOffset is less than N bytes from the end of the BLOB,
|
| -** [SQLITE_ERROR] is returned and no data is written. ^If N is
|
| -** less than zero [SQLITE_ERROR] is returned and no data is written.
|
| -** The size of the BLOB (and hence the maximum value of N+iOffset)
|
| -** can be determined using the [sqlite3_blob_bytes()] interface.
|
| +** [SQLITE_ERROR] is returned and no data is written. The size of the
|
| +** BLOB (and hence the maximum value of N+iOffset) can be determined
|
| +** using the [sqlite3_blob_bytes()] interface. ^If N or iOffset are less
|
| +** than zero [SQLITE_ERROR] is returned and no data is written.
|
| **
|
| ** ^An attempt to write to an expired [BLOB handle] fails with an
|
| ** error code of [SQLITE_ABORT]. ^Writes to the BLOB that occurred
|
| @@ -5816,9 +6097,6 @@ SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
|
| ** have been overwritten by the statement that expired the BLOB handle
|
| ** or by other independent statements.
|
| **
|
| -** ^(On success, sqlite3_blob_write() returns SQLITE_OK.
|
| -** Otherwise, an [error code] or an [extended error code] is returned.)^
|
| -**
|
| ** This routine only works on a [BLOB handle] which has been created
|
| ** by a prior successful call to [sqlite3_blob_open()] and which has not
|
| ** been closed by [sqlite3_blob_close()]. Passing any other pointer in
|
| @@ -5826,7 +6104,7 @@ SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
|
| **
|
| ** See also: [sqlite3_blob_read()].
|
| */
|
| -SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
|
|
|
| /*
|
| ** CAPI3REF: Virtual File System Objects
|
| @@ -5857,9 +6135,9 @@ SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOff
|
| ** ^(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 *sqlite3_vfs_find(const char *zVfsName);
|
| -SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
|
| -SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
|
| +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*);
|
|
|
| /*
|
| ** CAPI3REF: Mutexes
|
| @@ -5871,34 +6149,34 @@ SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
|
| **
|
| ** The SQLite source code contains multiple implementations
|
| ** of these mutex routines. An appropriate implementation
|
| -** is selected automatically at compile-time. ^(The following
|
| +** is selected automatically at compile-time. The following
|
| ** implementations are available in the SQLite core:
|
| **
|
| ** <ul>
|
| ** <li> SQLITE_MUTEX_PTHREADS
|
| ** <li> SQLITE_MUTEX_W32
|
| ** <li> SQLITE_MUTEX_NOOP
|
| -** </ul>)^
|
| +** </ul>
|
| **
|
| -** ^The SQLITE_MUTEX_NOOP implementation is a set of routines
|
| +** The SQLITE_MUTEX_NOOP implementation is a set of routines
|
| ** that does no real locking and is appropriate for use in
|
| -** a single-threaded application. ^The SQLITE_MUTEX_PTHREADS and
|
| +** a single-threaded application. The SQLITE_MUTEX_PTHREADS and
|
| ** SQLITE_MUTEX_W32 implementations are appropriate for use on Unix
|
| ** and Windows.
|
| **
|
| -** ^(If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
|
| +** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
|
| ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
|
| ** implementation is included with the library. In this case the
|
| ** application must supply a custom mutex implementation using the
|
| ** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function
|
| ** before calling sqlite3_initialize() or any other public sqlite3_
|
| -** function that calls sqlite3_initialize().)^
|
| +** function that calls sqlite3_initialize().
|
| **
|
| ** ^The sqlite3_mutex_alloc() routine allocates a new
|
| -** mutex and returns a pointer to it. ^If it returns NULL
|
| -** that means that a mutex could not be allocated. ^SQLite
|
| -** will unwind its stack and return an error. ^(The argument
|
| -** to sqlite3_mutex_alloc() is one of these integer constants:
|
| +** mutex and returns a pointer to it. ^The sqlite3_mutex_alloc()
|
| +** routine returns NULL if it is unable to allocate the requested
|
| +** mutex. The argument to sqlite3_mutex_alloc() must one of these
|
| +** integer constants:
|
| **
|
| ** <ul>
|
| ** <li> SQLITE_MUTEX_FAST
|
| @@ -5911,7 +6189,11 @@ SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
|
| ** <li> SQLITE_MUTEX_STATIC_PMEM
|
| ** <li> SQLITE_MUTEX_STATIC_APP1
|
| ** <li> SQLITE_MUTEX_STATIC_APP2
|
| -** </ul>)^
|
| +** <li> SQLITE_MUTEX_STATIC_APP3
|
| +** <li> SQLITE_MUTEX_STATIC_VFS1
|
| +** <li> SQLITE_MUTEX_STATIC_VFS2
|
| +** <li> SQLITE_MUTEX_STATIC_VFS3
|
| +** </ul>
|
| **
|
| ** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)
|
| ** cause sqlite3_mutex_alloc() to create
|
| @@ -5919,14 +6201,14 @@ SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
|
| ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
|
| ** The mutex implementation does not need to make a distinction
|
| ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
|
| -** not want to. ^SQLite will only request a recursive mutex in
|
| -** cases where it really needs one. ^If a faster non-recursive mutex
|
| +** not want to. SQLite will only request a recursive mutex in
|
| +** cases where it really needs one. If a faster non-recursive mutex
|
| ** implementation is available on the host platform, the mutex subsystem
|
| ** might return such a mutex in response to SQLITE_MUTEX_FAST.
|
| **
|
| ** ^The other allowed parameters to sqlite3_mutex_alloc() (anything other
|
| ** than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return
|
| -** a pointer to a static preexisting mutex. ^Six static mutexes are
|
| +** a pointer to a static preexisting mutex. ^Nine static mutexes are
|
| ** used by the current version of SQLite. Future versions of SQLite
|
| ** may add additional static mutexes. Static mutexes are for internal
|
| ** use by SQLite only. Applications that use SQLite mutexes should
|
| @@ -5935,16 +6217,13 @@ SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
|
| **
|
| ** ^Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
|
| ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
|
| -** returns a different mutex on every call. ^But for the static
|
| +** returns a different mutex on every call. ^For the static
|
| ** mutex types, the same mutex is returned on every call that has
|
| ** the same type number.
|
| **
|
| ** ^The sqlite3_mutex_free() routine deallocates a previously
|
| -** allocated dynamic mutex. ^SQLite is careful to deallocate every
|
| -** dynamic mutex that it allocates. The dynamic mutexes must not be in
|
| -** use when they are deallocated. Attempting to deallocate a static
|
| -** mutex results in undefined behavior. ^SQLite never deallocates
|
| -** a static mutex.
|
| +** allocated dynamic mutex. Attempting to deallocate a static
|
| +** mutex results in undefined behavior.
|
| **
|
| ** ^The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
|
| ** to enter a mutex. ^If another thread is already within the mutex,
|
| @@ -5952,23 +6231,21 @@ SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
|
| ** SQLITE_BUSY. ^The sqlite3_mutex_try() interface returns [SQLITE_OK]
|
| ** upon successful entry. ^(Mutexes created using
|
| ** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
|
| -** In such cases the,
|
| +** In such cases, the
|
| ** mutex must be exited an equal number of times before another thread
|
| -** can enter.)^ ^(If the same thread tries to enter any other
|
| -** kind of mutex more than once, the behavior is undefined.
|
| -** SQLite will never exhibit
|
| -** such behavior in its own use of mutexes.)^
|
| +** can enter.)^ If the same thread tries to enter any mutex other
|
| +** than an SQLITE_MUTEX_RECURSIVE more than once, the behavior is undefined.
|
| **
|
| ** ^(Some systems (for example, Windows 95) do not support the operation
|
| ** implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try()
|
| -** will always return SQLITE_BUSY. The SQLite core only ever uses
|
| -** sqlite3_mutex_try() as an optimization so this is acceptable behavior.)^
|
| +** will always return SQLITE_BUSY. The SQLite core only ever uses
|
| +** sqlite3_mutex_try() as an optimization so this is acceptable
|
| +** behavior.)^
|
| **
|
| ** ^The sqlite3_mutex_leave() routine exits a mutex that was
|
| -** previously entered by the same thread. ^(The behavior
|
| +** previously entered by the same thread. The behavior
|
| ** is undefined if the mutex is not currently entered by the
|
| -** calling thread or is not currently allocated. SQLite will
|
| -** never do either.)^
|
| +** calling thread or is not currently allocated.
|
| **
|
| ** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or
|
| ** sqlite3_mutex_leave() is a NULL pointer, then all three routines
|
| @@ -5976,11 +6253,11 @@ SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
|
| **
|
| ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
|
| */
|
| -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*);
|
| +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*);
|
|
|
| /*
|
| ** CAPI3REF: Mutex Methods Object
|
| @@ -5989,9 +6266,9 @@ SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*);
|
| ** used to allocate and use mutexes.
|
| **
|
| ** Usually, the default mutex implementations provided by SQLite are
|
| -** sufficient, however the user has the option of substituting a custom
|
| +** sufficient, however the application has the option of substituting a custom
|
| ** implementation for specialized deployments or systems for which SQLite
|
| -** does not provide a suitable implementation. In this case, the user
|
| +** does not provide a suitable implementation. In this case, the application
|
| ** creates and populates an instance of this structure to pass
|
| ** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option.
|
| ** Additionally, an instance of this structure can be used as an
|
| @@ -6032,13 +6309,13 @@ SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*);
|
| ** (i.e. it is acceptable to provide an implementation that segfaults if
|
| ** it is passed a NULL pointer).
|
| **
|
| -** The xMutexInit() method must be threadsafe. ^It must be harmless to
|
| +** The xMutexInit() method must be threadsafe. It must be harmless to
|
| ** invoke xMutexInit() multiple times within the same process and without
|
| ** intervening calls to xMutexEnd(). Second and subsequent calls to
|
| ** xMutexInit() must be no-ops.
|
| **
|
| -** ^xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()]
|
| -** and its associates). ^Similarly, xMutexAlloc() must not use SQLite memory
|
| +** xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()]
|
| +** and its associates). Similarly, xMutexAlloc() must not use SQLite memory
|
| ** allocation for a static mutex. ^However xMutexAlloc() may use SQLite
|
| ** memory allocation for a fast or recursive mutex.
|
| **
|
| @@ -6064,34 +6341,34 @@ struct sqlite3_mutex_methods {
|
| ** CAPI3REF: Mutex Verification Routines
|
| **
|
| ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
|
| -** are intended for use inside assert() statements. ^The SQLite core
|
| +** are intended for use inside assert() statements. The SQLite core
|
| ** never uses these routines except inside an assert() and applications
|
| -** are advised to follow the lead of the core. ^The SQLite core only
|
| +** are advised to follow the lead of the core. The SQLite core only
|
| ** provides implementations for these routines when it is compiled
|
| -** with the SQLITE_DEBUG flag. ^External mutex implementations
|
| +** with the SQLITE_DEBUG flag. External mutex implementations
|
| ** are only required to provide these routines if SQLITE_DEBUG is
|
| ** defined and if NDEBUG is not defined.
|
| **
|
| -** ^These routines should return true if the mutex in their argument
|
| +** These routines should return true if the mutex in their argument
|
| ** is held or not held, respectively, by the calling thread.
|
| **
|
| -** ^The implementation is not required to provide versions of these
|
| +** The implementation is not required to provide versions of these
|
| ** routines that actually work. If the implementation does not provide working
|
| ** versions of these routines, it should at least provide stubs that always
|
| ** return true so that one does not get spurious assertion failures.
|
| **
|
| -** ^If the argument to sqlite3_mutex_held() is a NULL pointer then
|
| +** If the argument to sqlite3_mutex_held() is a NULL pointer then
|
| ** the routine should return 1. This seems counter-intuitive since
|
| ** clearly the mutex cannot be held if it does not exist. But
|
| ** the reason the mutex does not exist is because the build is not
|
| ** using mutexes. And we do not want the assert() containing the
|
| ** call to sqlite3_mutex_held() to fail, so a non-zero return is
|
| -** the appropriate thing to do. ^The sqlite3_mutex_notheld()
|
| +** the appropriate thing to do. The sqlite3_mutex_notheld()
|
| ** interface should also return 1 when given a NULL pointer.
|
| */
|
| #ifndef NDEBUG
|
| -SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*);
|
| -SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_mutex_held(sqlite3_mutex*);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_mutex_notheld(sqlite3_mutex*);
|
| #endif
|
|
|
| /*
|
| @@ -6117,9 +6394,13 @@ SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*);
|
| #define SQLITE_MUTEX_STATIC_APP1 8 /* For use by application */
|
| #define SQLITE_MUTEX_STATIC_APP2 9 /* For use by application */
|
| #define SQLITE_MUTEX_STATIC_APP3 10 /* For use by application */
|
| +#define SQLITE_MUTEX_STATIC_VFS1 11 /* For use by built-in VFS */
|
| +#define SQLITE_MUTEX_STATIC_VFS2 12 /* For use by extension VFS */
|
| +#define SQLITE_MUTEX_STATIC_VFS3 13 /* For use by application VFS */
|
|
|
| /*
|
| ** CAPI3REF: Retrieve the mutex for a database connection
|
| +** METHOD: sqlite3
|
| **
|
| ** ^This interface returns a pointer the [sqlite3_mutex] object that
|
| ** serializes access to the [database connection] given in the argument
|
| @@ -6127,10 +6408,11 @@ SQLITE_API int 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 *sqlite3_db_mutex(sqlite3*);
|
| +SQLITE_API sqlite3_mutex *SQLITE_STDCALL sqlite3_db_mutex(sqlite3*);
|
|
|
| /*
|
| ** CAPI3REF: Low-Level Control Of Database Files
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The [sqlite3_file_control()] interface makes a direct call to the
|
| ** xFileControl method for the [sqlite3_io_methods] object associated
|
| @@ -6161,7 +6443,7 @@ SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
|
| **
|
| ** See also: [SQLITE_FCNTL_LOCKSTATE]
|
| */
|
| -SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
|
|
|
| /*
|
| ** CAPI3REF: Testing Interface
|
| @@ -6180,7 +6462,7 @@ SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*
|
| ** Unlike most of the SQLite API, this function is not guaranteed to
|
| ** operate consistently from one release to the next.
|
| */
|
| -SQLITE_API int sqlite3_test_control(int op, ...);
|
| +SQLITE_API int SQLITE_CDECL sqlite3_test_control(int op, ...);
|
|
|
| /*
|
| ** CAPI3REF: Testing Interface Operation Codes
|
| @@ -6214,12 +6496,13 @@ SQLITE_API int sqlite3_test_control(int op, ...);
|
| #define SQLITE_TESTCTRL_BYTEORDER 22
|
| #define SQLITE_TESTCTRL_ISINIT 23
|
| #define SQLITE_TESTCTRL_SORTER_MMAP 24
|
| -#define SQLITE_TESTCTRL_LAST 24
|
| +#define SQLITE_TESTCTRL_IMPOSTER 25
|
| +#define SQLITE_TESTCTRL_LAST 25
|
|
|
| /*
|
| ** CAPI3REF: SQLite Runtime Status
|
| **
|
| -** ^This interface is used to retrieve runtime status information
|
| +** ^These interfaces are used to retrieve runtime status information
|
| ** about the performance of SQLite, and optionally to reset various
|
| ** highwater marks. ^The first argument is an integer code for
|
| ** the specific parameter to measure. ^(Recognized integer codes
|
| @@ -6233,19 +6516,22 @@ SQLITE_API int sqlite3_test_control(int op, ...);
|
| ** ^(Other parameters record only the highwater mark and not the current
|
| ** value. For these latter parameters nothing is written into *pCurrent.)^
|
| **
|
| -** ^The sqlite3_status() routine returns SQLITE_OK on success and a
|
| -** non-zero [error code] on failure.
|
| +** ^The sqlite3_status() and sqlite3_status64() routines return
|
| +** SQLITE_OK on success and a non-zero [error code] on failure.
|
| **
|
| -** This routine is threadsafe but is not atomic. This routine can be
|
| -** called while other threads are running the same or different SQLite
|
| -** interfaces. However the values returned in *pCurrent and
|
| -** *pHighwater reflect the status of SQLite at different points in time
|
| -** and it is possible that another thread might change the parameter
|
| -** in between the times when *pCurrent and *pHighwater are written.
|
| +** If either the current value or the highwater mark is too large to
|
| +** be represented by a 32-bit integer, then the values returned by
|
| +** sqlite3_status() are undefined.
|
| **
|
| ** See also: [sqlite3_db_status()]
|
| */
|
| -SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_status64(
|
| + int op,
|
| + sqlite3_int64 *pCurrent,
|
| + sqlite3_int64 *pHighwater,
|
| + int resetFlag
|
| +);
|
|
|
|
|
| /*
|
| @@ -6324,7 +6610,8 @@ SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetF
|
| ** The value written into the *pCurrent parameter is undefined.</dd>)^
|
| **
|
| ** [[SQLITE_STATUS_PARSER_STACK]] ^(<dt>SQLITE_STATUS_PARSER_STACK</dt>
|
| -** <dd>This parameter records the deepest parser stack. It is only
|
| +** <dd>The *pHighwater parameter records the deepest parser stack.
|
| +** The *pCurrent value is undefined. The *pHighwater value is only
|
| ** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
|
| ** </dl>
|
| **
|
| @@ -6343,6 +6630,7 @@ SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetF
|
|
|
| /*
|
| ** CAPI3REF: Database Connection Status
|
| +** METHOD: sqlite3
|
| **
|
| ** ^This interface is used to retrieve runtime status information
|
| ** about a single [database connection]. ^The first argument is the
|
| @@ -6363,7 +6651,7 @@ SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetF
|
| **
|
| ** See also: [sqlite3_status()] and [sqlite3_stmt_status()].
|
| */
|
| -SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
|
|
|
| /*
|
| ** CAPI3REF: Status Parameters for database connections
|
| @@ -6471,6 +6759,7 @@ SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int r
|
|
|
| /*
|
| ** CAPI3REF: Prepared Statement Status
|
| +** METHOD: sqlite3_stmt
|
| **
|
| ** ^(Each prepared statement maintains various
|
| ** [SQLITE_STMTSTATUS counters] that measure the number
|
| @@ -6492,7 +6781,7 @@ SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int r
|
| **
|
| ** See also: [sqlite3_status()] and [sqlite3_db_status()].
|
| */
|
| -SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
|
|
|
| /*
|
| ** CAPI3REF: Status Parameters for prepared statements
|
| @@ -6819,6 +7108,10 @@ 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
|
| +** there is already a read or read-write transaction open on the
|
| +** destination database.
|
| +**
|
| ** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
|
| ** returned and an error code and error message are stored in the
|
| ** destination [database connection] D.
|
| @@ -6911,20 +7204,20 @@ typedef struct sqlite3_backup sqlite3_backup;
|
| ** is not a permanent error and does not affect the return value of
|
| ** sqlite3_backup_finish().
|
| **
|
| -** [[sqlite3_backup__remaining()]] [[sqlite3_backup_pagecount()]]
|
| +** [[sqlite3_backup_remaining()]] [[sqlite3_backup_pagecount()]]
|
| ** <b>sqlite3_backup_remaining() and sqlite3_backup_pagecount()</b>
|
| **
|
| -** ^Each call to sqlite3_backup_step() sets two values inside
|
| -** the [sqlite3_backup] object: the number of pages still to be backed
|
| -** up and the total number of pages in the source database file.
|
| -** The sqlite3_backup_remaining() and sqlite3_backup_pagecount() interfaces
|
| -** retrieve these two values, respectively.
|
| -**
|
| -** ^The values returned by these functions are only updated by
|
| -** sqlite3_backup_step(). ^If the source database is modified during a backup
|
| -** operation, then the values are not updated to account for any extra
|
| -** pages that need to be updated or the size of the source database file
|
| -** changing.
|
| +** ^The sqlite3_backup_remaining() routine returns the number of pages still
|
| +** to be backed up at the conclusion of the most recent sqlite3_backup_step().
|
| +** ^The sqlite3_backup_pagecount() routine returns the total number of pages
|
| +** in the source database at the conclusion of the most recent
|
| +** sqlite3_backup_step().
|
| +** ^(The values returned by these functions are only updated by
|
| +** sqlite3_backup_step(). If the source database is modified in a way that
|
| +** changes the size of the source database or the number of pages remaining,
|
| +** those changes are not reflected in the output of sqlite3_backup_pagecount()
|
| +** and sqlite3_backup_remaining() until after the next
|
| +** sqlite3_backup_step().)^
|
| **
|
| ** <b>Concurrent Usage of Database Handles</b>
|
| **
|
| @@ -6957,19 +7250,20 @@ 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 *sqlite3_backup_init(
|
| +SQLITE_API sqlite3_backup *SQLITE_STDCALL 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 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);
|
| +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);
|
|
|
| /*
|
| ** CAPI3REF: Unlock Notification
|
| +** METHOD: sqlite3
|
| **
|
| ** ^When running in shared-cache mode, a database operation may fail with
|
| ** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
|
| @@ -7082,7 +7376,7 @@ SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
|
| ** the special "DROP TABLE/INDEX" case, the extended error code is just
|
| ** SQLITE_LOCKED.)^
|
| */
|
| -SQLITE_API int sqlite3_unlock_notify(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_unlock_notify(
|
| sqlite3 *pBlocked, /* Waiting connection */
|
| void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */
|
| void *pNotifyArg /* Argument to pass to xNotify */
|
| @@ -7097,23 +7391,87 @@ SQLITE_API int 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 sqlite3_stricmp(const char *, const char *);
|
| -SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_stricmp(const char *, const char *);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_strnicmp(const char *, const char *, int);
|
|
|
| /*
|
| ** CAPI3REF: String Globbing
|
| *
|
| -** ^The [sqlite3_strglob(P,X)] interface returns zero if string X matches
|
| -** the glob pattern P, and it returns non-zero if string X does not match
|
| -** the glob pattern P. ^The definition of glob pattern matching used in
|
| +** ^The [sqlite3_strglob(P,X)] interface returns zero if and only if
|
| +** string X matches the [GLOB] pattern P.
|
| +** ^The definition of [GLOB] pattern matching used in
|
| ** [sqlite3_strglob(P,X)] is the same as for the "X GLOB P" operator in the
|
| -** SQL dialect used by SQLite. ^The sqlite3_strglob(P,X) function is case
|
| -** sensitive.
|
| +** SQL dialect understood by SQLite. ^The [sqlite3_strglob(P,X)] function
|
| +** is case sensitive.
|
| +**
|
| +** Note that this routine returns zero on a match and non-zero if the strings
|
| +** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].
|
| +**
|
| +** See also: [sqlite3_strlike()].
|
| +*/
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_strglob(const char *zGlob, const char *zStr);
|
| +
|
| +/* Begin recover virtual table patch for Chromium */
|
| +/* Our patches don't conform to SQLite's amalgamation processing. Hack it. */
|
| +#ifndef CHROMIUM_SQLITE_API
|
| +#define CHROMIUM_SQLITE_API SQLITE_API
|
| +#endif
|
| +/*
|
| +** Call to initialize the recover virtual-table modules (see recover.c).
|
| +**
|
| +** This could be loaded by default in main.c, but that would make the
|
| +** virtual table available to Web SQL. Breaking it out allows only
|
| +** selected users to enable it (currently sql/recovery.cc).
|
| +*/
|
| +CHROMIUM_SQLITE_API
|
| +int recoverVtableInit(sqlite3 *db);
|
| +/* End recover virtual table patch for Chromium */
|
| +
|
| +/* Begin WebDatabase patch for Chromium */
|
| +/* Expose some SQLite internals for the WebDatabase vfs.
|
| +** DO NOT EXTEND THE USE OF THIS.
|
| +*/
|
| +#ifndef CHROMIUM_SQLITE_API
|
| +#define CHROMIUM_SQLITE_API SQLITE_API
|
| +#endif
|
| +#if defined(CHROMIUM_SQLITE_INTERNALS)
|
| +#ifdef _WIN32
|
| +CHROMIUM_SQLITE_API
|
| +void chromium_sqlite3_initialize_win_sqlite3_file(sqlite3_file* file, HANDLE handle);
|
| +#else /* _WIN32 */
|
| +CHROMIUM_SQLITE_API
|
| +int chromium_sqlite3_fill_in_unix_sqlite3_file(sqlite3_vfs* pVfs,
|
| + int fd,
|
| + sqlite3_file* pFile,
|
| + const char* zPath,
|
| + int noLock,
|
| + int flags);
|
| +#endif /* _WIN32 */
|
| +#endif /* CHROMIUM_SQLITE_INTERNALS */
|
| +/* End WebDatabase patch for Chromium */
|
| +
|
| +/*
|
| +** CAPI3REF: String LIKE Matching
|
| +*
|
| +** ^The [sqlite3_strlike(P,X,E)] interface returns zero if and only if
|
| +** string X matches the [LIKE] pattern P with escape character E.
|
| +** ^The definition of [LIKE] pattern matching used in
|
| +** [sqlite3_strlike(P,X,E)] is the same as for the "X LIKE P ESCAPE E"
|
| +** operator in the SQL dialect understood by SQLite. ^For "X LIKE P" without
|
| +** the ESCAPE clause, set the E parameter of [sqlite3_strlike(P,X,E)] to 0.
|
| +** ^As with the LIKE operator, the [sqlite3_strlike(P,X,E)] function is case
|
| +** insensitive - equivalent upper and lower case ASCII characters match
|
| +** one another.
|
| +**
|
| +** ^The [sqlite3_strlike(P,X,E)] function matches Unicode characters, though
|
| +** only ASCII characters are case folded.
|
| **
|
| ** Note that this routine returns zero on a match and non-zero if the strings
|
| ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].
|
| +**
|
| +** See also: [sqlite3_strglob()].
|
| */
|
| -SQLITE_API int sqlite3_strglob(const char *zGlob, const char *zStr);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int cEsc);
|
|
|
| /*
|
| ** CAPI3REF: Error Logging Interface
|
| @@ -7136,18 +7494,17 @@ SQLITE_API int sqlite3_strglob(const char *zGlob, const char *zStr);
|
| ** a few hundred characters, it will be truncated to the length of the
|
| ** buffer.
|
| */
|
| -SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
|
| +SQLITE_API void SQLITE_CDECL sqlite3_log(int iErrCode, const char *zFormat, ...);
|
|
|
| /*
|
| ** CAPI3REF: Write-Ahead Log Commit Hook
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The [sqlite3_wal_hook()] function is used to register a callback that
|
| -** will be invoked each time a database connection commits data to a
|
| -** [write-ahead log] (i.e. whenever a transaction is committed in
|
| -** [journal_mode | journal_mode=WAL mode]).
|
| +** is invoked each time data is committed to a database in wal mode.
|
| **
|
| -** ^The callback is invoked by SQLite after the commit has taken place and
|
| -** the associated write-lock on the database released, so the implementation
|
| +** ^(The callback is invoked by SQLite after the commit has taken place and
|
| +** the associated write-lock on the database released)^, so the implementation
|
| ** may read, write or [checkpoint] the database as required.
|
| **
|
| ** ^The first parameter passed to the callback function when it is invoked
|
| @@ -7173,7 +7530,7 @@ SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
|
| ** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will
|
| ** those overwrite any prior [sqlite3_wal_hook()] settings.
|
| */
|
| -SQLITE_API void *sqlite3_wal_hook(
|
| +SQLITE_API void *SQLITE_STDCALL sqlite3_wal_hook(
|
| sqlite3*,
|
| int(*)(void *,sqlite3*,const char*,int),
|
| void*
|
| @@ -7181,6 +7538,7 @@ SQLITE_API void *sqlite3_wal_hook(
|
|
|
| /*
|
| ** CAPI3REF: Configure an auto-checkpoint
|
| +** METHOD: sqlite3
|
| **
|
| ** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around
|
| ** [sqlite3_wal_hook()] that causes any database on [database connection] D
|
| @@ -7207,104 +7565,123 @@ SQLITE_API void *sqlite3_wal_hook(
|
| ** is only necessary if the default setting is found to be suboptimal
|
| ** for a particular application.
|
| */
|
| -SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
|
|
|
| /*
|
| ** CAPI3REF: Checkpoint a database
|
| +** METHOD: sqlite3
|
| **
|
| -** ^The [sqlite3_wal_checkpoint(D,X)] interface causes database named X
|
| -** on [database connection] D to be [checkpointed]. ^If X is NULL or an
|
| -** empty string, then a checkpoint is run on all databases of
|
| -** connection D. ^If the database connection D is not in
|
| -** [WAL | write-ahead log mode] then this interface is a harmless no-op.
|
| -** ^The [sqlite3_wal_checkpoint(D,X)] interface initiates a
|
| -** [sqlite3_wal_checkpoint_v2|PASSIVE] checkpoint.
|
| -** Use the [sqlite3_wal_checkpoint_v2()] interface to get a FULL
|
| -** or RESET checkpoint.
|
| +** ^(The sqlite3_wal_checkpoint(D,X) is equivalent to
|
| +** [sqlite3_wal_checkpoint_v2](D,X,[SQLITE_CHECKPOINT_PASSIVE],0,0).)^
|
| **
|
| -** ^The [wal_checkpoint pragma] can be used to invoke this interface
|
| -** from SQL. ^The [sqlite3_wal_autocheckpoint()] interface and the
|
| -** [wal_autocheckpoint pragma] can be used to cause this interface to be
|
| -** run whenever the WAL reaches a certain size threshold.
|
| +** In brief, sqlite3_wal_checkpoint(D,X) causes the content in the
|
| +** [write-ahead log] for database X on [database connection] D to be
|
| +** transferred into the database file and for the write-ahead log to
|
| +** be reset. See the [checkpointing] documentation for addition
|
| +** information.
|
| **
|
| -** See also: [sqlite3_wal_checkpoint_v2()]
|
| +** This interface used to be the only way to cause a checkpoint to
|
| +** occur. But then the newer and more powerful [sqlite3_wal_checkpoint_v2()]
|
| +** interface was added. This interface is retained for backwards
|
| +** compatibility and as a convenience for applications that need to manually
|
| +** start a callback but which do not need the full power (and corresponding
|
| +** complication) of [sqlite3_wal_checkpoint_v2()].
|
| */
|
| -SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
|
|
|
| /*
|
| ** CAPI3REF: Checkpoint a database
|
| +** METHOD: sqlite3
|
| **
|
| -** Run a checkpoint operation on WAL database zDb attached to database
|
| -** handle db. The specific operation is determined by the value of the
|
| -** eMode parameter:
|
| +** ^(The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint
|
| +** operation on database X of [database connection] D in mode M. Status
|
| +** information is written back into integers pointed to by L and C.)^
|
| +** ^(The M parameter must be a valid [checkpoint mode]:)^
|
| **
|
| ** <dl>
|
| ** <dt>SQLITE_CHECKPOINT_PASSIVE<dd>
|
| -** Checkpoint as many frames as possible without waiting for any database
|
| -** readers or writers to finish. Sync the db file if all frames in the log
|
| -** are checkpointed. This mode is the same as calling
|
| -** sqlite3_wal_checkpoint(). The [sqlite3_busy_handler|busy-handler callback]
|
| -** is never invoked.
|
| +** ^Checkpoint as many frames as possible without waiting for any database
|
| +** readers or writers to finish, then sync the database file if all frames
|
| +** in the log were checkpointed. ^The [busy-handler callback]
|
| +** is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode.
|
| +** ^On the other hand, passive mode might leave the checkpoint unfinished
|
| +** if there are concurrent readers or writers.
|
| **
|
| ** <dt>SQLITE_CHECKPOINT_FULL<dd>
|
| -** This mode blocks (it invokes the
|
| +** ^This mode blocks (it invokes the
|
| ** [sqlite3_busy_handler|busy-handler callback]) until there is no
|
| ** database writer and all readers are reading from the most recent database
|
| -** snapshot. It then checkpoints all frames in the log file and syncs the
|
| -** database file. This call blocks database writers while it is running,
|
| -** but not database readers.
|
| +** snapshot. ^It then checkpoints all frames in the log file and syncs the
|
| +** database file. ^This mode blocks new database writers while it is pending,
|
| +** but new database readers are allowed to continue unimpeded.
|
| **
|
| ** <dt>SQLITE_CHECKPOINT_RESTART<dd>
|
| -** This mode works the same way as SQLITE_CHECKPOINT_FULL, except after
|
| -** checkpointing the log file it blocks (calls the
|
| -** [sqlite3_busy_handler|busy-handler callback])
|
| -** until all readers are reading from the database file only. This ensures
|
| -** that the next client to write to the database file restarts the log file
|
| -** from the beginning. This call blocks database writers while it is running,
|
| -** but not database readers.
|
| +** ^This mode works the same way as SQLITE_CHECKPOINT_FULL with the addition
|
| +** that after checkpointing the log file it blocks (calls the
|
| +** [busy-handler callback])
|
| +** until all readers are reading from the database file only. ^This ensures
|
| +** that the next writer will restart the log file from the beginning.
|
| +** ^Like SQLITE_CHECKPOINT_FULL, this mode blocks new
|
| +** database writer attempts while it is pending, but does not impede readers.
|
| +**
|
| +** <dt>SQLITE_CHECKPOINT_TRUNCATE<dd>
|
| +** ^This mode works the same way as SQLITE_CHECKPOINT_RESTART with the
|
| +** addition that it also truncates the log file to zero bytes just prior
|
| +** to a successful return.
|
| ** </dl>
|
| **
|
| -** If pnLog is not NULL, then *pnLog is set to the total number of frames in
|
| -** the log file before returning. If pnCkpt is not NULL, then *pnCkpt is set to
|
| -** the total number of checkpointed frames (including any that were already
|
| -** checkpointed when this function is called). *pnLog and *pnCkpt may be
|
| -** populated even if sqlite3_wal_checkpoint_v2() returns other than SQLITE_OK.
|
| -** If no values are available because of an error, they are both set to -1
|
| -** before returning to communicate this to the caller.
|
| -**
|
| -** All calls obtain an exclusive "checkpoint" lock on the database file. If
|
| +** ^If pnLog is not NULL, then *pnLog is set to the total number of frames in
|
| +** the log file or to -1 if the checkpoint could not run because
|
| +** of an error or because the database is not in [WAL mode]. ^If pnCkpt is not
|
| +** NULL,then *pnCkpt is set to the total number of checkpointed frames in the
|
| +** log file (including any that were already checkpointed before the function
|
| +** was called) or to -1 if the checkpoint could not run due to an error or
|
| +** because the database is not in WAL mode. ^Note that upon successful
|
| +** completion of an SQLITE_CHECKPOINT_TRUNCATE, the log file will have been
|
| +** truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero.
|
| +**
|
| +** ^All calls obtain an exclusive "checkpoint" lock on the database file. ^If
|
| ** any other process is running a checkpoint operation at the same time, the
|
| -** lock cannot be obtained and SQLITE_BUSY is returned. Even if there is a
|
| +** lock cannot be obtained and SQLITE_BUSY is returned. ^Even if there is a
|
| ** busy-handler configured, it will not be invoked in this case.
|
| **
|
| -** The SQLITE_CHECKPOINT_FULL and RESTART modes also obtain the exclusive
|
| -** "writer" lock on the database file. If the writer lock cannot be obtained
|
| -** immediately, and a busy-handler is configured, it is invoked and the writer
|
| -** lock retried until either the busy-handler returns 0 or the lock is
|
| -** successfully obtained. The busy-handler is also invoked while waiting for
|
| -** database readers as described above. If the busy-handler returns 0 before
|
| +** ^The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the
|
| +** exclusive "writer" lock on the database file. ^If the writer lock cannot be
|
| +** obtained immediately, and a busy-handler is configured, it is invoked and
|
| +** the writer lock retried until either the busy-handler returns 0 or the lock
|
| +** is successfully obtained. ^The busy-handler is also invoked while waiting for
|
| +** database readers as described above. ^If the busy-handler returns 0 before
|
| ** the writer lock is obtained or while waiting for database readers, the
|
| ** checkpoint operation proceeds from that point in the same way as
|
| ** SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible
|
| -** without blocking any further. SQLITE_BUSY is returned in this case.
|
| +** without blocking any further. ^SQLITE_BUSY is returned in this case.
|
| **
|
| -** If parameter zDb is NULL or points to a zero length string, then the
|
| -** specified operation is attempted on all WAL databases. In this case the
|
| -** values written to output parameters *pnLog and *pnCkpt are undefined. If
|
| +** ^If parameter zDb is NULL or points to a zero length string, then the
|
| +** specified operation is attempted on all WAL databases [attached] to
|
| +** [database connection] db. In this case the
|
| +** values written to output parameters *pnLog and *pnCkpt are undefined. ^If
|
| ** an SQLITE_BUSY error is encountered when processing one or more of the
|
| ** attached WAL databases, the operation is still attempted on any remaining
|
| -** attached databases and SQLITE_BUSY is returned to the caller. If any other
|
| +** attached databases and SQLITE_BUSY is returned at the end. ^If any other
|
| ** error occurs while processing an attached database, processing is abandoned
|
| -** and the error code returned to the caller immediately. If no error
|
| +** and the error code is returned to the caller immediately. ^If no error
|
| ** (SQLITE_BUSY or otherwise) is encountered while processing the attached
|
| ** databases, SQLITE_OK is returned.
|
| **
|
| -** If database zDb is the name of an attached database that is not in WAL
|
| -** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. If
|
| +** ^If database zDb is the name of an attached database that is not in WAL
|
| +** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. ^If
|
| ** zDb is not NULL (or a zero length string) and is not the name of any
|
| ** attached database, SQLITE_ERROR is returned to the caller.
|
| +**
|
| +** ^Unless it returns SQLITE_MISUSE,
|
| +** the sqlite3_wal_checkpoint_v2() interface
|
| +** sets the error information that is queried by
|
| +** [sqlite3_errcode()] and [sqlite3_errmsg()].
|
| +**
|
| +** ^The [PRAGMA wal_checkpoint] command can be used to invoke this interface
|
| +** from SQL.
|
| */
|
| -SQLITE_API int sqlite3_wal_checkpoint_v2(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_wal_checkpoint_v2(
|
| sqlite3 *db, /* Database handle */
|
| const char *zDb, /* Name of attached database (or NULL) */
|
| int eMode, /* SQLITE_CHECKPOINT_* value */
|
| @@ -7313,16 +7690,18 @@ SQLITE_API int sqlite3_wal_checkpoint_v2(
|
| );
|
|
|
| /*
|
| -** CAPI3REF: Checkpoint operation parameters
|
| +** CAPI3REF: Checkpoint Mode Values
|
| +** KEYWORDS: {checkpoint mode}
|
| **
|
| -** These constants can be used as the 3rd parameter to
|
| -** [sqlite3_wal_checkpoint_v2()]. See the [sqlite3_wal_checkpoint_v2()]
|
| -** documentation for additional information about the meaning and use of
|
| -** each of these values.
|
| +** These constants define all valid values for the "checkpoint mode" passed
|
| +** as the third parameter to the [sqlite3_wal_checkpoint_v2()] interface.
|
| +** See the [sqlite3_wal_checkpoint_v2()] documentation for details on the
|
| +** meaning of each of these checkpoint modes.
|
| */
|
| -#define SQLITE_CHECKPOINT_PASSIVE 0
|
| -#define SQLITE_CHECKPOINT_FULL 1
|
| -#define SQLITE_CHECKPOINT_RESTART 2
|
| +#define SQLITE_CHECKPOINT_PASSIVE 0 /* Do as much as possible w/o blocking */
|
| +#define SQLITE_CHECKPOINT_FULL 1 /* Wait for writers, then checkpoint */
|
| +#define SQLITE_CHECKPOINT_RESTART 2 /* Like FULL but wait for for readers */
|
| +#define SQLITE_CHECKPOINT_TRUNCATE 3 /* Like RESTART but also truncate WAL */
|
|
|
| /*
|
| ** CAPI3REF: Virtual Table Interface Configuration
|
| @@ -7338,7 +7717,7 @@ SQLITE_API int sqlite3_wal_checkpoint_v2(
|
| ** this function. (See [SQLITE_VTAB_CONSTRAINT_SUPPORT].) Further options
|
| ** may be added in the future.
|
| */
|
| -SQLITE_API int sqlite3_vtab_config(sqlite3*, int op, ...);
|
| +SQLITE_API int SQLITE_CDECL sqlite3_vtab_config(sqlite3*, int op, ...);
|
|
|
| /*
|
| ** CAPI3REF: Virtual Table Configuration Options
|
| @@ -7391,7 +7770,7 @@ SQLITE_API int 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 sqlite3_vtab_on_conflict(sqlite3 *);
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_vtab_on_conflict(sqlite3 *);
|
|
|
| /*
|
| ** CAPI3REF: Conflict resolution modes
|
| @@ -7411,46 +7790,232 @@ SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *);
|
| /* #define SQLITE_ABORT 4 // Also an error code */
|
| #define SQLITE_REPLACE 5
|
|
|
| +/*
|
| +** CAPI3REF: Prepared Statement Scan Status Opcodes
|
| +** KEYWORDS: {scanstatus options}
|
| +**
|
| +** The following constants can be used for the T parameter to the
|
| +** [sqlite3_stmt_scanstatus(S,X,T,V)] interface. Each constant designates a
|
| +** different metric for sqlite3_stmt_scanstatus() to return.
|
| +**
|
| +** When the value returned to V is a string, space to hold that string is
|
| +** managed by the prepared statement S and will be automatically freed when
|
| +** S is finalized.
|
| +**
|
| +** <dl>
|
| +** [[SQLITE_SCANSTAT_NLOOP]] <dt>SQLITE_SCANSTAT_NLOOP</dt>
|
| +** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be
|
| +** set to the total number of times that the X-th loop has run.</dd>
|
| +**
|
| +** [[SQLITE_SCANSTAT_NVISIT]] <dt>SQLITE_SCANSTAT_NVISIT</dt>
|
| +** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be set
|
| +** to the total number of rows examined by all iterations of the X-th loop.</dd>
|
| +**
|
| +** [[SQLITE_SCANSTAT_EST]] <dt>SQLITE_SCANSTAT_EST</dt>
|
| +** <dd>^The "double" variable pointed to by the T parameter will be set to the
|
| +** query planner's estimate for the average number of rows output from each
|
| +** iteration of the X-th loop. If the query planner's estimates was accurate,
|
| +** then this value will approximate the quotient NVISIT/NLOOP and the
|
| +** product of this value for all prior loops with the same SELECTID will
|
| +** be the NLOOP value for the current loop.
|
| +**
|
| +** [[SQLITE_SCANSTAT_NAME]] <dt>SQLITE_SCANSTAT_NAME</dt>
|
| +** <dd>^The "const char *" variable pointed to by the T parameter will be set
|
| +** to a zero-terminated UTF-8 string containing the name of the index or table
|
| +** used for the X-th loop.
|
| +**
|
| +** [[SQLITE_SCANSTAT_EXPLAIN]] <dt>SQLITE_SCANSTAT_EXPLAIN</dt>
|
| +** <dd>^The "const char *" variable pointed to by the T parameter will be set
|
| +** to a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN]
|
| +** description for the X-th loop.
|
| +**
|
| +** [[SQLITE_SCANSTAT_SELECTID]] <dt>SQLITE_SCANSTAT_SELECT</dt>
|
| +** <dd>^The "int" variable pointed to by the T parameter will be set to the
|
| +** "select-id" for the X-th loop. The select-id identifies which query or
|
| +** subquery the loop is part of. The main query has a select-id of zero.
|
| +** The select-id is the same value as is output in the first column
|
| +** of an [EXPLAIN QUERY PLAN] query.
|
| +** </dl>
|
| +*/
|
| +#define SQLITE_SCANSTAT_NLOOP 0
|
| +#define SQLITE_SCANSTAT_NVISIT 1
|
| +#define SQLITE_SCANSTAT_EST 2
|
| +#define SQLITE_SCANSTAT_NAME 3
|
| +#define SQLITE_SCANSTAT_EXPLAIN 4
|
| +#define SQLITE_SCANSTAT_SELECTID 5
|
|
|
| +/*
|
| +** CAPI3REF: Prepared Statement Scan Status
|
| +** METHOD: sqlite3_stmt
|
| +**
|
| +** This interface returns information about the predicted and measured
|
| +** performance for pStmt. Advanced applications can use this
|
| +** interface to compare the predicted and the measured performance and
|
| +** issue warnings and/or rerun [ANALYZE] if discrepancies are found.
|
| +**
|
| +** Since this interface is expected to be rarely used, it is only
|
| +** available if SQLite is compiled using the [SQLITE_ENABLE_STMT_SCANSTATUS]
|
| +** compile-time option.
|
| +**
|
| +** The "iScanStatusOp" parameter determines which status information to return.
|
| +** The "iScanStatusOp" must be one of the [scanstatus options] or the behavior
|
| +** of this interface is undefined.
|
| +** ^The requested measurement is written into a variable pointed to by
|
| +** the "pOut" parameter.
|
| +** Parameter "idx" identifies the specific loop to retrieve statistics for.
|
| +** Loops are numbered starting from zero. ^If idx is out of range - less than
|
| +** zero or greater than or equal to the total number of loops used to implement
|
| +** the statement - a non-zero value is returned and the variable that pOut
|
| +** points to is unchanged.
|
| +**
|
| +** ^Statistics might not be available for all loops in all statements. ^In cases
|
| +** where there exist loops with no available statistics, this function behaves
|
| +** as if the loop did not exist - it returns non-zero and leave the variable
|
| +** that pOut points to unchanged.
|
| +**
|
| +** See also: [sqlite3_stmt_scanstatus_reset()]
|
| +*/
|
| +SQLITE_API int SQLITE_STDCALL 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_* */
|
| + void *pOut /* Result written here */
|
| +);
|
|
|
| -/* Begin recover virtual table patch for Chromium */
|
| -/* Our patches don't conform to SQLite's amalgamation processing. Hack it. */
|
| -#ifndef CHROMIUM_SQLITE_API
|
| -#define CHROMIUM_SQLITE_API SQLITE_API
|
| -#endif
|
| /*
|
| -** Call to initialize the recover virtual-table modules (see recover.c).
|
| +** CAPI3REF: Zero Scan-Status Counters
|
| +** METHOD: sqlite3_stmt
|
| **
|
| -** This could be loaded by default in main.c, but that would make the
|
| -** virtual table available to Web SQL. Breaking it out allows only
|
| -** selected users to enable it (currently sql/recovery.cc).
|
| +** ^Zero all [sqlite3_stmt_scanstatus()] related event counters.
|
| +**
|
| +** This API is only available if the library is built with pre-processor
|
| +** symbol [SQLITE_ENABLE_STMT_SCANSTATUS] defined.
|
| */
|
| -CHROMIUM_SQLITE_API
|
| -int recoverVtableInit(sqlite3 *db);
|
| -/* End recover virtual table patch for Chromium */
|
| +SQLITE_API void SQLITE_STDCALL sqlite3_stmt_scanstatus_reset(sqlite3_stmt*);
|
|
|
| -/* Begin WebDatabase patch for Chromium */
|
| -/* Expose some SQLite internals for the WebDatabase vfs.
|
| -** DO NOT EXTEND THE USE OF THIS.
|
| +/*
|
| +** CAPI3REF: Flush caches to disk mid-transaction
|
| +**
|
| +** ^If a write-transaction is open on [database connection] D when the
|
| +** [sqlite3_db_cacheflush(D)] interface invoked, any dirty
|
| +** pages in the pager-cache that are not currently in use are written out
|
| +** to disk. A dirty page may be in use if a database cursor created by an
|
| +** active SQL statement is reading from it, or if it is page 1 of a database
|
| +** file (page 1 is always "in use"). ^The [sqlite3_db_cacheflush(D)]
|
| +** interface flushes caches for all schemas - "main", "temp", and
|
| +** any [attached] databases.
|
| +**
|
| +** ^If this function needs to obtain extra database locks before dirty pages
|
| +** can be flushed to disk, it does so. ^If those locks cannot be obtained
|
| +** immediately and there is a busy-handler callback configured, it is invoked
|
| +** in the usual manner. ^If the required lock still cannot be obtained, then
|
| +** the database is skipped and an attempt made to flush any dirty pages
|
| +** belonging to the next (if any) database. ^If any databases are skipped
|
| +** because locks cannot be obtained, but no other error occurs, this
|
| +** function returns SQLITE_BUSY.
|
| +**
|
| +** ^If any other error occurs while flushing dirty pages to disk (for
|
| +** example an IO error or out-of-memory condition), then processing is
|
| +** abandoned and an SQLite [error code] is returned to the caller immediately.
|
| +**
|
| +** ^Otherwise, if no error occurs, [sqlite3_db_cacheflush()] returns SQLITE_OK.
|
| +**
|
| +** ^This function does not set the database handle error code or message
|
| +** returned by the [sqlite3_errcode()] and [sqlite3_errmsg()] functions.
|
| */
|
| -#ifndef CHROMIUM_SQLITE_API
|
| -#define CHROMIUM_SQLITE_API SQLITE_API
|
| -#endif
|
| -#if defined(CHROMIUM_SQLITE_INTERNALS)
|
| -#ifdef _WIN32
|
| -CHROMIUM_SQLITE_API
|
| -void chromium_sqlite3_initialize_win_sqlite3_file(sqlite3_file* file, HANDLE handle);
|
| -#else /* _WIN32 */
|
| -CHROMIUM_SQLITE_API
|
| -int chromium_sqlite3_fill_in_unix_sqlite3_file(sqlite3_vfs* pVfs,
|
| - int fd,
|
| - sqlite3_file* pFile,
|
| - const char* zPath,
|
| - int noLock,
|
| - int flags);
|
| -#endif /* _WIN32 */
|
| -#endif /* CHROMIUM_SQLITE_INTERNALS */
|
| -/* End WebDatabase patch for Chromium */
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_db_cacheflush(sqlite3*);
|
| +
|
| +/*
|
| +** CAPI3REF: Database Snapshot
|
| +** KEYWORDS: {snapshot}
|
| +** EXPERIMENTAL
|
| +**
|
| +** An instance of the snapshot object records the state of a [WAL mode]
|
| +** database for some specific point in history.
|
| +**
|
| +** In [WAL mode], multiple [database connections] that are open on the
|
| +** same database file can each be reading a different historical version
|
| +** of the database file. When a [database connection] begins a read
|
| +** transaction, that connection sees an unchanging copy of the database
|
| +** as it existed for the point in time when the transaction first started.
|
| +** Subsequent changes to the database from other connections are not seen
|
| +** by the reader until a new read transaction is started.
|
| +**
|
| +** The sqlite3_snapshot object records state information about an historical
|
| +** version of the database file so that it is possible to later open a new read
|
| +** transaction that sees that historical version of the database rather than
|
| +** the most recent version.
|
| +**
|
| +** The constructor for this object is [sqlite3_snapshot_get()]. The
|
| +** [sqlite3_snapshot_open()] method causes a fresh read transaction to refer
|
| +** to an historical snapshot (if possible). The destructor for
|
| +** sqlite3_snapshot objects is [sqlite3_snapshot_free()].
|
| +*/
|
| +typedef struct sqlite3_snapshot sqlite3_snapshot;
|
| +
|
| +/*
|
| +** CAPI3REF: Record A Database Snapshot
|
| +** EXPERIMENTAL
|
| +**
|
| +** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a
|
| +** new [sqlite3_snapshot] object that records the current state of
|
| +** 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].
|
| +**
|
| +** The [sqlite3_snapshot] object returned from a successful call to
|
| +** [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()]
|
| +** to avoid a memory leak.
|
| +**
|
| +** 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(
|
| + sqlite3 *db,
|
| + const char *zSchema,
|
| + sqlite3_snapshot **ppSnapshot
|
| +);
|
| +
|
| +/*
|
| +** 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()] 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 [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(
|
| + sqlite3 *db,
|
| + const char *zSchema,
|
| + sqlite3_snapshot *pSnapshot
|
| +);
|
| +
|
| +/*
|
| +** CAPI3REF: Destroy a snapshot
|
| +** EXPERIMENTAL
|
| +**
|
| +** ^The [sqlite3_snapshot_free(P)] interface destroys [sqlite3_snapshot] P.
|
| +** The application must eventually free every [sqlite3_snapshot] object
|
| +** using this routine to avoid a memory leak.
|
| +**
|
| +** 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*);
|
|
|
| /*
|
| ** Undo the hack that converts floating point types to integer for
|
| @@ -7504,7 +8069,7 @@ typedef struct sqlite3_rtree_query_info sqlite3_rtree_query_info;
|
| **
|
| ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...)
|
| */
|
| -SQLITE_API int sqlite3_rtree_geometry_callback(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_rtree_geometry_callback(
|
| sqlite3 *db,
|
| const char *zGeom,
|
| int (*xGeom)(sqlite3_rtree_geometry*, int, sqlite3_rtree_dbl*,int*),
|
| @@ -7530,7 +8095,7 @@ struct sqlite3_rtree_geometry {
|
| **
|
| ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zQueryFunc(... params ...)
|
| */
|
| -SQLITE_API int sqlite3_rtree_query_callback(
|
| +SQLITE_API int SQLITE_STDCALL sqlite3_rtree_query_callback(
|
| sqlite3 *db,
|
| const char *zQueryFunc,
|
| int (*xQueryFunc)(sqlite3_rtree_query_info*),
|
| @@ -7564,6 +8129,8 @@ struct sqlite3_rtree_query_info {
|
| int eParentWithin; /* Visibility of parent node */
|
| int eWithin; /* OUT: Visiblity */
|
| sqlite3_rtree_dbl rScore; /* OUT: Write the score here */
|
| + /* The following fields are only available in 3.8.11 and later */
|
| + sqlite3_value **apSqlParam; /* Original SQL values of parameters */
|
| };
|
|
|
| /*
|
| @@ -7580,3 +8147,523 @@ struct sqlite3_rtree_query_info {
|
|
|
| #endif /* ifndef _SQLITE3RTREE_H_ */
|
|
|
| +/*
|
| +** 2014 May 31
|
| +**
|
| +** The author disclaims copyright to this source code. In place of
|
| +** a legal notice, here is a blessing:
|
| +**
|
| +** May you do good and not evil.
|
| +** May you find forgiveness for yourself and forgive others.
|
| +** May you share freely, never taking more than you give.
|
| +**
|
| +******************************************************************************
|
| +**
|
| +** Interfaces to extend FTS5. Using the interfaces defined in this file,
|
| +** FTS5 may be extended with:
|
| +**
|
| +** * custom tokenizers, and
|
| +** * custom auxiliary functions.
|
| +*/
|
| +
|
| +
|
| +#ifndef _FTS5_H
|
| +#define _FTS5_H
|
| +
|
| +
|
| +#ifdef __cplusplus
|
| +extern "C" {
|
| +#endif
|
| +
|
| +/*************************************************************************
|
| +** CUSTOM AUXILIARY FUNCTIONS
|
| +**
|
| +** Virtual table implementations may overload SQL functions by implementing
|
| +** the sqlite3_module.xFindFunction() method.
|
| +*/
|
| +
|
| +typedef struct Fts5ExtensionApi Fts5ExtensionApi;
|
| +typedef struct Fts5Context Fts5Context;
|
| +typedef struct Fts5PhraseIter Fts5PhraseIter;
|
| +
|
| +typedef void (*fts5_extension_function)(
|
| + const Fts5ExtensionApi *pApi, /* API offered by current FTS version */
|
| + Fts5Context *pFts, /* First arg to pass to pApi functions */
|
| + sqlite3_context *pCtx, /* Context for returning result/error */
|
| + int nVal, /* Number of values in apVal[] array */
|
| + sqlite3_value **apVal /* Array of trailing arguments */
|
| +);
|
| +
|
| +struct Fts5PhraseIter {
|
| + const unsigned char *a;
|
| + const unsigned char *b;
|
| +};
|
| +
|
| +/*
|
| +** EXTENSION API FUNCTIONS
|
| +**
|
| +** xUserData(pFts):
|
| +** Return a copy of the context pointer the extension function was
|
| +** registered with.
|
| +**
|
| +** xColumnTotalSize(pFts, iCol, pnToken):
|
| +** If parameter iCol is less than zero, set output variable *pnToken
|
| +** to the total number of tokens in the FTS5 table. Or, if iCol is
|
| +** non-negative but less than the number of columns in the table, return
|
| +** the total number of tokens in column iCol, considering all rows in
|
| +** the FTS5 table.
|
| +**
|
| +** If parameter iCol is greater than or equal to the number of columns
|
| +** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.
|
| +** an OOM condition or IO error), an appropriate SQLite error code is
|
| +** returned.
|
| +**
|
| +** xColumnCount(pFts):
|
| +** Return the number of columns in the table.
|
| +**
|
| +** xColumnSize(pFts, iCol, pnToken):
|
| +** If parameter iCol is less than zero, set output variable *pnToken
|
| +** to the total number of tokens in the current row. Or, if iCol is
|
| +** non-negative but less than the number of columns in the table, set
|
| +** *pnToken to the number of tokens in column iCol of the current row.
|
| +**
|
| +** If parameter iCol is greater than or equal to the number of columns
|
| +** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.
|
| +** an OOM condition or IO error), an appropriate SQLite error code is
|
| +** returned.
|
| +**
|
| +** 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
|
| +** containing the text in utf-8 encoding, (*pn) is set to the size in bytes
|
| +** (not characters) of the buffer and SQLITE_OK is returned. Otherwise,
|
| +** if an error occurs, an SQLite error code is returned and the final values
|
| +** of (*pz) and (*pn) are undefined.
|
| +**
|
| +** xPhraseCount:
|
| +** Returns the number of phrases in the current query expression.
|
| +**
|
| +** xPhraseSize:
|
| +** Returns the number of tokens in phrase iPhrase of the query. Phrases
|
| +** are numbered starting from zero.
|
| +**
|
| +** xInstCount:
|
| +** Set *pnInst to the total number of occurrences of all phrases within
|
| +** the query within the current row. Return SQLITE_OK if successful, or
|
| +** an error code (i.e. SQLITE_NOMEM) if an error occurs.
|
| +**
|
| +** 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().
|
| +**
|
| +** Returns SQLITE_OK if successful, or an error code (i.e. SQLITE_NOMEM)
|
| +** if an error occurs.
|
| +**
|
| +** xRowid:
|
| +** Returns the rowid of the current row.
|
| +**
|
| +** xTokenize:
|
| +** Tokenize text using the tokenizer belonging to the FTS5 table.
|
| +**
|
| +** xQueryPhrase(pFts5, iPhrase, pUserData, xCallback):
|
| +** This API function is used to query the FTS table for phrase iPhrase
|
| +** of the current query. Specifically, a query equivalent to:
|
| +**
|
| +** ... 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.
|
| +**
|
| +** If the callback function returns any value other than SQLITE_OK, the
|
| +** query is abandoned and the xQueryPhrase function returns immediately.
|
| +** If the returned value is SQLITE_DONE, xQueryPhrase returns SQLITE_OK.
|
| +** Otherwise, the error code is propagated upwards.
|
| +**
|
| +** If the query runs to completion without incident, SQLITE_OK is returned.
|
| +** Or, if some error occurs before the query completes or is aborted by
|
| +** the callback, an SQLite error code is returned.
|
| +**
|
| +**
|
| +** xSetAuxdata(pFts5, pAux, xDelete)
|
| +**
|
| +** Save the pointer passed as the second argument as the extension functions
|
| +** "auxiliary data". The pointer may then be retrieved by the current or any
|
| +** future invocation of the same fts5 extension function made as part of
|
| +** of the same MATCH query using the xGetAuxdata() API.
|
| +**
|
| +** Each extension function is allocated a single auxiliary data slot for
|
| +** each FTS query (MATCH expression). If the extension function is invoked
|
| +** more than once for a single FTS query, then all invocations share a
|
| +** single auxiliary data context.
|
| +**
|
| +** If there is already an auxiliary data pointer when this function is
|
| +** invoked, then it is replaced by the new pointer. If an xDelete callback
|
| +** was specified along with the original pointer, it is invoked at this
|
| +** point.
|
| +**
|
| +** The xDelete callback, if one is specified, is also invoked on the
|
| +** auxiliary data pointer after the FTS5 query has finished.
|
| +**
|
| +** If an error (e.g. an OOM condition) occurs within this function, an
|
| +** the auxiliary data is set to NULL and an error code returned. If the
|
| +** xDelete parameter was not NULL, it is invoked on the auxiliary data
|
| +** pointer before returning.
|
| +**
|
| +**
|
| +** xGetAuxdata(pFts5, bClear)
|
| +**
|
| +** Returns the current auxiliary data pointer for the fts5 extension
|
| +** function. See the xSetAuxdata() method for details.
|
| +**
|
| +** If the bClear argument is non-zero, then the auxiliary data is cleared
|
| +** (set to NULL) before this function returns. In this case the xDelete,
|
| +** if any, is not invoked.
|
| +**
|
| +**
|
| +** xRowCount(pFts5, pnRow)
|
| +**
|
| +** This function is used to retrieve the total number of rows in the table.
|
| +** In other words, the same value that would be returned by:
|
| +**
|
| +** SELECT count(*) FROM ftstable;
|
| +**
|
| +** xPhraseFirst()
|
| +** This function is used, along with type Fts5PhraseIter and the xPhraseNext
|
| +** method, to iterate through all instances of a single query phrase within
|
| +** the current row. This is the same information as is accessible via the
|
| +** xInstCount/xInst APIs. While the xInstCount/xInst APIs are more convenient
|
| +** to use, this API may be faster under some circumstances. To iterate
|
| +** through instances of phrase iPhrase, use the following code:
|
| +**
|
| +** Fts5PhraseIter iter;
|
| +** int iCol, iOff;
|
| +** for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff);
|
| +** iOff>=0;
|
| +** pApi->xPhraseNext(pFts, &iter, &iCol, &iOff)
|
| +** ){
|
| +** // An instance of phrase iPhrase at offset iOff of column iCol
|
| +** }
|
| +**
|
| +** 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.
|
| +**
|
| +** xPhraseNext()
|
| +** See xPhraseFirst above.
|
| +*/
|
| +struct Fts5ExtensionApi {
|
| + int iVersion; /* Currently always set to 1 */
|
| +
|
| + void *(*xUserData)(Fts5Context*);
|
| +
|
| + int (*xColumnCount)(Fts5Context*);
|
| + int (*xRowCount)(Fts5Context*, sqlite3_int64 *pnRow);
|
| + int (*xColumnTotalSize)(Fts5Context*, int iCol, sqlite3_int64 *pnToken);
|
| +
|
| + int (*xTokenize)(Fts5Context*,
|
| + const char *pText, int nText, /* Text to tokenize */
|
| + void *pCtx, /* Context passed to xToken() */
|
| + int (*xToken)(void*, int, const char*, int, int, int) /* Callback */
|
| + );
|
| +
|
| + int (*xPhraseCount)(Fts5Context*);
|
| + int (*xPhraseSize)(Fts5Context*, int iPhrase);
|
| +
|
| + int (*xInstCount)(Fts5Context*, int *pnInst);
|
| + int (*xInst)(Fts5Context*, int iIdx, int *piPhrase, int *piCol, int *piOff);
|
| +
|
| + sqlite3_int64 (*xRowid)(Fts5Context*);
|
| + int (*xColumnText)(Fts5Context*, int iCol, const char **pz, int *pn);
|
| + int (*xColumnSize)(Fts5Context*, int iCol, int *pnToken);
|
| +
|
| + int (*xQueryPhrase)(Fts5Context*, int iPhrase, void *pUserData,
|
| + int(*)(const Fts5ExtensionApi*,Fts5Context*,void*)
|
| + );
|
| + int (*xSetAuxdata)(Fts5Context*, void *pAux, void(*xDelete)(void*));
|
| + void *(*xGetAuxdata)(Fts5Context*, int bClear);
|
| +
|
| + void (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*);
|
| + void (*xPhraseNext)(Fts5Context*, Fts5PhraseIter*, int *piCol, int *piOff);
|
| +};
|
| +
|
| +/*
|
| +** CUSTOM AUXILIARY FUNCTIONS
|
| +*************************************************************************/
|
| +
|
| +/*************************************************************************
|
| +** CUSTOM TOKENIZERS
|
| +**
|
| +** Applications may also register custom tokenizer types. A tokenizer
|
| +** is registered by providing fts5 with a populated instance of the
|
| +** following structure. All structure methods must be defined, setting
|
| +** any member of the fts5_tokenizer struct to NULL leads to undefined
|
| +** behaviour. The structure methods are expected to function as follows:
|
| +**
|
| +** xCreate:
|
| +** This function is used to allocate and inititalize 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*)
|
| +** pointer provided by the application when the fts5_tokenizer object
|
| +** was registered with FTS5 (the third argument to xCreateTokenizer()).
|
| +** The second and third arguments are an array of nul-terminated strings
|
| +** containing the tokenizer arguments, if any, specified following the
|
| +** tokenizer name as part of the CREATE VIRTUAL TABLE statement used
|
| +** to create the FTS5 table.
|
| +**
|
| +** The final argument is an output variable. If successful, (*ppOut)
|
| +** should be set to point to the new tokenizer handle and SQLITE_OK
|
| +** returned. If an error occurs, some value other than SQLITE_OK should
|
| +** be returned. In this case, fts5 assumes that the final value of *ppOut
|
| +** is undefined.
|
| +**
|
| +** xDelete:
|
| +** This function is invoked to delete a tokenizer handle previously
|
| +** allocated using xCreate(). Fts5 guarantees that this function will
|
| +** be invoked exactly once for each successful call to xCreate().
|
| +**
|
| +** xTokenize:
|
| +** This function is expected to tokenize the nText byte string indicated
|
| +** by argument pText. pText may or may not be nul-terminated. The first
|
| +** argument passed to this function is a pointer to an Fts5Tokenizer object
|
| +** returned by an earlier call to xCreate().
|
| +**
|
| +** The second argument indicates the reason that FTS5 is requesting
|
| +** tokenization of the supplied text. This is always one of the following
|
| +** four values:
|
| +**
|
| +** <ul><li> <b>FTS5_TOKENIZE_DOCUMENT</b> - A document is being inserted into
|
| +** or removed from the FTS table. The tokenizer is being invoked to
|
| +** determine the set of tokens to add to (or delete from) the
|
| +** FTS index.
|
| +**
|
| +** <li> <b>FTS5_TOKENIZE_QUERY</b> - A MATCH query is being executed
|
| +** against the FTS index. The tokenizer is being called to tokenize
|
| +** a bareword or quoted string specified as part of the query.
|
| +**
|
| +** <li> <b>(FTS5_TOKENIZE_QUERY | FTS5_TOKENIZE_PREFIX)</b> - Same as
|
| +** FTS5_TOKENIZE_QUERY, except that the bareword or quoted string is
|
| +** followed by a "*" character, indicating that the last token
|
| +** returned by the tokenizer will be treated as a token prefix.
|
| +**
|
| +** <li> <b>FTS5_TOKENIZE_AUX</b> - The tokenizer is being invoked to
|
| +** satisfy an fts5_api.xTokenize() request made by an auxiliary
|
| +** function. Or an fts5_api.xColumnSize() request made by the same
|
| +** on a columnsize=0 database.
|
| +** </ul>
|
| +**
|
| +** For each token in the input string, the supplied callback xToken() must
|
| +** be invoked. The first argument to it should be a copy of the pointer
|
| +** passed as the second argument to xTokenize(). The third and fourth
|
| +** arguments are a pointer to a buffer containing the token text, and the
|
| +** size of the token in bytes. The 4th and 5th arguments are the byte offsets
|
| +** of the first byte of and first byte immediately following the text from
|
| +** which the token is derived within the input.
|
| +**
|
| +** The second argument passed to the xToken() callback ("tflags") should
|
| +** normally be set to 0. The exception is if the tokenizer supports
|
| +** synonyms. In this case see the discussion below for details.
|
| +**
|
| +** FTS5 assumes the xToken() callback is invoked for each token in the
|
| +** order that they occur within the input text.
|
| +**
|
| +** If an xToken() callback returns any value other than SQLITE_OK, then
|
| +** the tokenization should be abandoned and the xTokenize() method should
|
| +** immediately return a copy of the xToken() return value. Or, if the
|
| +** input buffer is exhausted, xTokenize() should return SQLITE_OK. Finally,
|
| +** if an error occurs with the xTokenize() implementation itself, it
|
| +** may abandon the tokenization and return any error code other than
|
| +** SQLITE_OK or SQLITE_DONE.
|
| +**
|
| +** SYNONYM SUPPORT
|
| +**
|
| +** Custom tokenizers may also support synonyms. Consider a case in which a
|
| +** user wishes to query for a phrase such as "first place". Using the
|
| +** built-in tokenizers, the FTS5 query 'first + place' will match instances
|
| +** of "first place" within the document set, but not alternative forms
|
| +** such as "1st place". In some applications, it would be better to match
|
| +** all instances of "first place" or "1st place" regardless of which form
|
| +** the user specified in the MATCH query text.
|
| +**
|
| +** There are several ways to approach this in FTS5:
|
| +**
|
| +** <ol><li> By mapping all synonyms to a single token. In this case, the
|
| +** In the above example, this means that the tokenizer returns the
|
| +** same token for inputs "first" and "1st". Say that token is in
|
| +** fact "first", so that when the user inserts the document "I won
|
| +** 1st place" entries are added to the index for tokens "i", "won",
|
| +** "first" and "place". If the user then queries for '1st + place',
|
| +** the tokenizer substitutes "first" for "1st" and the query works
|
| +** as expected.
|
| +**
|
| +** <li> By adding multiple synonyms for a single term to the FTS index.
|
| +** In this case, when tokenizing query text, the tokenizer may
|
| +** provide multiple synonyms for a single term within the document.
|
| +** FTS5 then queries the index for each synonym individually. For
|
| +** example, faced with the query:
|
| +**
|
| +** <codeblock>
|
| +** ... MATCH 'first place'</codeblock>
|
| +**
|
| +** the tokenizer offers both "1st" and "first" as synonyms for the
|
| +** first token in the MATCH query and FTS5 effectively runs a query
|
| +** similar to:
|
| +**
|
| +** <codeblock>
|
| +** ... MATCH '(first OR 1st) place'</codeblock>
|
| +**
|
| +** except that, for the purposes of auxiliary functions, the query
|
| +** still appears to contain just two phrases - "(first OR 1st)"
|
| +** being treated as a single phrase.
|
| +**
|
| +** <li> By adding multiple synonyms for a single term to the FTS index.
|
| +** Using this method, when tokenizing document text, the tokenizer
|
| +** provides multiple synonyms for each token. So that when a
|
| +** document such as "I won first place" is tokenized, entries are
|
| +** added to the FTS index for "i", "won", "first", "1st" and
|
| +** "place".
|
| +**
|
| +** This way, even if the tokenizer does not provide synonyms
|
| +** when tokenizing query text (it should not - to do would be
|
| +** inefficient), it doesn't matter if the user queries for
|
| +** 'first + place' or '1st + place', as there are entires in the
|
| +** FTS index corresponding to both forms of the first token.
|
| +** </ol>
|
| +**
|
| +** Whether it is parsing document or query text, any call to xToken that
|
| +** specifies a <i>tflags</i> argument with the FTS5_TOKEN_COLOCATED bit
|
| +** is considered to supply a synonym for the previous token. For example,
|
| +** when parsing the document "I won first place", a tokenizer that supports
|
| +** synonyms would call xToken() 5 times, as follows:
|
| +**
|
| +** <codeblock>
|
| +** xToken(pCtx, 0, "i", 1, 0, 1);
|
| +** xToken(pCtx, 0, "won", 3, 2, 5);
|
| +** xToken(pCtx, 0, "first", 5, 6, 11);
|
| +** xToken(pCtx, FTS5_TOKEN_COLOCATED, "1st", 3, 6, 11);
|
| +** xToken(pCtx, 0, "place", 5, 12, 17);
|
| +**</codeblock>
|
| +**
|
| +** It is an error to specify the FTS5_TOKEN_COLOCATED flag the first time
|
| +** xToken() is called. Multiple synonyms may be specified for a single token
|
| +** by making multiple calls to xToken(FTS5_TOKEN_COLOCATED) in sequence.
|
| +** There is no limit to the number of synonyms that may be provided for a
|
| +** single token.
|
| +**
|
| +** In many cases, method (1) above is the best approach. It does not add
|
| +** extra data to the FTS index or require FTS5 to query for multiple terms,
|
| +** so it is efficient in terms of disk space and query speed. However, it
|
| +** does not support prefix queries very well. If, as suggested above, the
|
| +** token "first" is subsituted for "1st" by the tokenizer, then the query:
|
| +**
|
| +** <codeblock>
|
| +** ... MATCH '1s*'</codeblock>
|
| +**
|
| +** will not match documents that contain the token "1st" (as the tokenizer
|
| +** will probably not map "1s" to any prefix of "first").
|
| +**
|
| +** For full prefix support, method (3) may be preferred. In this case,
|
| +** because the index contains entries for both "first" and "1st", prefix
|
| +** queries such as 'fi*' or '1s*' will match correctly. However, because
|
| +** extra entries are added to the FTS index, this method uses more space
|
| +** within the database.
|
| +**
|
| +** Method (2) offers a midpoint between (1) and (3). Using this method,
|
| +** a query such as '1s*' will match documents that contain the literal
|
| +** token "1st", but not "first" (assuming the tokenizer is not able to
|
| +** provide synonyms for prefixes). However, a non-prefix query like '1st'
|
| +** will match against "1st" and "first". This method does not require
|
| +** extra disk space, as no extra entries are added to the FTS index.
|
| +** On the other hand, it may require more CPU cycles to run MATCH queries,
|
| +** as separate queries of the FTS index are required for each synonym.
|
| +**
|
| +** When using methods (2) or (3), it is important that the tokenizer only
|
| +** provide synonyms when tokenizing document text (method (2)) or query
|
| +** text (method (3)), not both. Doing so will not cause any errors, but is
|
| +** inefficient.
|
| +*/
|
| +typedef struct Fts5Tokenizer Fts5Tokenizer;
|
| +typedef struct fts5_tokenizer fts5_tokenizer;
|
| +struct fts5_tokenizer {
|
| + int (*xCreate)(void*, const char **azArg, int nArg, Fts5Tokenizer **ppOut);
|
| + void (*xDelete)(Fts5Tokenizer*);
|
| + int (*xTokenize)(Fts5Tokenizer*,
|
| + void *pCtx,
|
| + int flags, /* Mask of FTS5_TOKENIZE_* flags */
|
| + const char *pText, int nText,
|
| + int (*xToken)(
|
| + void *pCtx, /* Copy of 2nd argument to xTokenize() */
|
| + int tflags, /* Mask of FTS5_TOKEN_* flags */
|
| + const char *pToken, /* Pointer to buffer containing token */
|
| + int nToken, /* Size of token in bytes */
|
| + int iStart, /* Byte offset of token within input text */
|
| + int iEnd /* Byte offset of end of token within input text */
|
| + )
|
| + );
|
| +};
|
| +
|
| +/* Flags that may be passed as the third argument to xTokenize() */
|
| +#define FTS5_TOKENIZE_QUERY 0x0001
|
| +#define FTS5_TOKENIZE_PREFIX 0x0002
|
| +#define FTS5_TOKENIZE_DOCUMENT 0x0004
|
| +#define FTS5_TOKENIZE_AUX 0x0008
|
| +
|
| +/* Flags that may be passed by the tokenizer implementation back to FTS5
|
| +** as the third argument to the supplied xToken callback. */
|
| +#define FTS5_TOKEN_COLOCATED 0x0001 /* Same position as prev. token */
|
| +
|
| +/*
|
| +** END OF CUSTOM TOKENIZERS
|
| +*************************************************************************/
|
| +
|
| +/*************************************************************************
|
| +** FTS5 EXTENSION REGISTRATION API
|
| +*/
|
| +typedef struct fts5_api fts5_api;
|
| +struct fts5_api {
|
| + int iVersion; /* Currently always set to 2 */
|
| +
|
| + /* Create a new tokenizer */
|
| + int (*xCreateTokenizer)(
|
| + fts5_api *pApi,
|
| + const char *zName,
|
| + void *pContext,
|
| + fts5_tokenizer *pTokenizer,
|
| + void (*xDestroy)(void*)
|
| + );
|
| +
|
| + /* Find an existing tokenizer */
|
| + int (*xFindTokenizer)(
|
| + fts5_api *pApi,
|
| + const char *zName,
|
| + void **ppContext,
|
| + fts5_tokenizer *pTokenizer
|
| + );
|
| +
|
| + /* Create a new auxiliary function */
|
| + int (*xCreateFunction)(
|
| + fts5_api *pApi,
|
| + const char *zName,
|
| + void *pContext,
|
| + fts5_extension_function xFunction,
|
| + void (*xDestroy)(void*)
|
| + );
|
| +};
|
| +
|
| +/*
|
| +** END OF REGISTRATION API
|
| +*************************************************************************/
|
| +
|
| +#ifdef __cplusplus
|
| +} /* end of the 'extern "C"' block */
|
| +#endif
|
| +
|
| +#endif /* _FTS5_H */
|
| +
|
| +
|
|
|
Chromium Code Reviews
Issue 1610963002:
Import SQLite 3.10.2. (Closed)
Base URL: https://chromium.googlesource.com/chromium/src.git@master