| OLD | NEW |
| 1 /* | 1 /* |
| 2 ** 2001 September 15 | 2 ** 2001 September 15 |
| 3 ** | 3 ** |
| 4 ** The author disclaims copyright to this source code. In place of | 4 ** The author disclaims copyright to this source code. In place of |
| 5 ** a legal notice, here is a blessing: | 5 ** a legal notice, here is a blessing: |
| 6 ** | 6 ** |
| 7 ** May you do good and not evil. | 7 ** May you do good and not evil. |
| 8 ** May you find forgiveness for yourself and forgive others. | 8 ** May you find forgiveness for yourself and forgive others. |
| 9 ** May you share freely, never taking more than you give. | 9 ** May you share freely, never taking more than you give. |
| 10 ** | 10 ** |
| (...skipping 12 matching lines...) Expand all Loading... |
| 23 ** | 23 ** |
| 24 ** The official C-language API documentation for SQLite is derived | 24 ** The official C-language API documentation for SQLite is derived |
| 25 ** from comments in this file. This file is the authoritative source | 25 ** from comments in this file. This file is the authoritative source |
| 26 ** on how SQLite interfaces are supposed to operate. | 26 ** on how SQLite interfaces are supposed to operate. |
| 27 ** | 27 ** |
| 28 ** The name of this file under configuration management is "sqlite.h.in". | 28 ** The name of this file under configuration management is "sqlite.h.in". |
| 29 ** The makefile makes some minor changes to this file (such as inserting | 29 ** The makefile makes some minor changes to this file (such as inserting |
| 30 ** the version number) and changes its name to "sqlite3.h" as | 30 ** the version number) and changes its name to "sqlite3.h" as |
| 31 ** part of the build process. | 31 ** part of the build process. |
| 32 */ | 32 */ |
| 33 #ifndef _SQLITE3_H_ | 33 #ifndef SQLITE3_H |
| 34 #define _SQLITE3_H_ | 34 #define SQLITE3_H |
| 35 #include <stdarg.h> /* Needed for the definition of va_list */ | 35 #include <stdarg.h> /* Needed for the definition of va_list */ |
| 36 | 36 |
| 37 /* | 37 /* |
| 38 ** Make sure we can call this stuff from C++. | 38 ** Make sure we can call this stuff from C++. |
| 39 */ | 39 */ |
| 40 #ifdef __cplusplus | 40 #ifdef __cplusplus |
| 41 extern "C" { | 41 extern "C" { |
| 42 #endif | 42 #endif |
| 43 | 43 |
| 44 | 44 |
| 45 /* | 45 /* |
| 46 ** Provide the ability to override linkage features of the interface. | 46 ** Provide the ability to override linkage features of the interface. |
| 47 */ | 47 */ |
| 48 #ifndef SQLITE_EXTERN | 48 #ifndef SQLITE_EXTERN |
| 49 # define SQLITE_EXTERN extern | 49 # define SQLITE_EXTERN extern |
| 50 #endif | 50 #endif |
| 51 #ifndef SQLITE_API | 51 #ifndef SQLITE_API |
| 52 # define SQLITE_API | 52 # define SQLITE_API |
| 53 #endif | 53 #endif |
| 54 #ifndef SQLITE_CDECL | 54 #ifndef SQLITE_CDECL |
| 55 # define SQLITE_CDECL | 55 # define SQLITE_CDECL |
| 56 #endif | 56 #endif |
| 57 #ifndef SQLITE_APICALL |
| 58 # define SQLITE_APICALL |
| 59 #endif |
| 57 #ifndef SQLITE_STDCALL | 60 #ifndef SQLITE_STDCALL |
| 58 # define SQLITE_STDCALL | 61 # define SQLITE_STDCALL SQLITE_APICALL |
| 62 #endif |
| 63 #ifndef SQLITE_CALLBACK |
| 64 # define SQLITE_CALLBACK |
| 65 #endif |
| 66 #ifndef SQLITE_SYSAPI |
| 67 # define SQLITE_SYSAPI |
| 59 #endif | 68 #endif |
| 60 | 69 |
| 61 /* | 70 /* |
| 62 ** These no-op macros are used in front of interfaces to mark those | 71 ** These no-op macros are used in front of interfaces to mark those |
| 63 ** interfaces as either deprecated or experimental. New applications | 72 ** interfaces as either deprecated or experimental. New applications |
| 64 ** should not use deprecated interfaces - they are supported for backwards | 73 ** should not use deprecated interfaces - they are supported for backwards |
| 65 ** compatibility only. Application writers should be aware that | 74 ** compatibility only. Application writers should be aware that |
| 66 ** experimental interfaces are subject to change in point releases. | 75 ** experimental interfaces are subject to change in point releases. |
| 67 ** | 76 ** |
| 68 ** These macros used to resolve to various kinds of compiler magic that | 77 ** These macros used to resolve to various kinds of compiler magic that |
| (...skipping 23 matching lines...) Expand all Loading... |
| 92 ** format "X.Y.Z" where X is the major version number (always 3 for | 101 ** format "X.Y.Z" where X is the major version number (always 3 for |
| 93 ** SQLite3) and Y is the minor version number and Z is the release number.)^ | 102 ** SQLite3) and Y is the minor version number and Z is the release number.)^ |
| 94 ** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer | 103 ** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer |
| 95 ** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same | 104 ** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same |
| 96 ** numbers used in [SQLITE_VERSION].)^ | 105 ** numbers used in [SQLITE_VERSION].)^ |
| 97 ** The SQLITE_VERSION_NUMBER for any given release of SQLite will also | 106 ** The SQLITE_VERSION_NUMBER for any given release of SQLite will also |
| 98 ** be larger than the release from which it is derived. Either Y will | 107 ** be larger than the release from which it is derived. Either Y will |
| 99 ** be held constant and Z will be incremented or else Y will be incremented | 108 ** be held constant and Z will be incremented or else Y will be incremented |
| 100 ** and Z will be reset to zero. | 109 ** and Z will be reset to zero. |
| 101 ** | 110 ** |
| 102 ** Since version 3.6.18, SQLite source code has been stored in the | 111 ** Since [version 3.6.18] ([dateof:3.6.18]), |
| 112 ** SQLite source code has been stored in the |
| 103 ** <a href="http://www.fossil-scm.org/">Fossil configuration management | 113 ** <a href="http://www.fossil-scm.org/">Fossil configuration management |
| 104 ** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to | 114 ** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to |
| 105 ** a string which identifies a particular check-in of SQLite | 115 ** a string which identifies a particular check-in of SQLite |
| 106 ** within its configuration management system. ^The SQLITE_SOURCE_ID | 116 ** within its configuration management system. ^The SQLITE_SOURCE_ID |
| 107 ** string contains the date and time of the check-in (UTC) and an SHA1 | 117 ** string contains the date and time of the check-in (UTC) and an SHA1 |
| 108 ** hash of the entire source tree. | 118 ** hash of the entire source tree. |
| 109 ** | 119 ** |
| 110 ** See also: [sqlite3_libversion()], | 120 ** See also: [sqlite3_libversion()], |
| 111 ** [sqlite3_libversion_number()], [sqlite3_sourceid()], | 121 ** [sqlite3_libversion_number()], [sqlite3_sourceid()], |
| 112 ** [sqlite_version()] and [sqlite_source_id()]. | 122 ** [sqlite_version()] and [sqlite_source_id()]. |
| 113 */ | 123 */ |
| 114 #define SQLITE_VERSION "3.10.2" | 124 #define SQLITE_VERSION "3.17.0" |
| 115 #define SQLITE_VERSION_NUMBER 3010002 | 125 #define SQLITE_VERSION_NUMBER 3017000 |
| 116 #define SQLITE_SOURCE_ID "2016-01-20 15:27:19 17efb4209f97fb4971656086b1385
99a91a75ff9" | 126 #define SQLITE_SOURCE_ID "2017-02-13 16:02:40 ada05cfa86ad7f5645450ac7a2a21
c9aa6e57d2c" |
| 117 | 127 |
| 118 /* | 128 /* |
| 119 ** CAPI3REF: Run-Time Library Version Numbers | 129 ** CAPI3REF: Run-Time Library Version Numbers |
| 120 ** KEYWORDS: sqlite3_version, sqlite3_sourceid | 130 ** KEYWORDS: sqlite3_version sqlite3_sourceid |
| 121 ** | 131 ** |
| 122 ** These interfaces provide the same information as the [SQLITE_VERSION], | 132 ** These interfaces provide the same information as the [SQLITE_VERSION], |
| 123 ** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros | 133 ** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros |
| 124 ** but are associated with the library instead of the header file. ^(Cautious | 134 ** but are associated with the library instead of the header file. ^(Cautious |
| 125 ** programmers might include assert() statements in their application to | 135 ** programmers might include assert() statements in their application to |
| 126 ** verify that values returned by these interfaces match the macros in | 136 ** verify that values returned by these interfaces match the macros in |
| 127 ** the header, and thus ensure that the application is | 137 ** the header, and thus ensure that the application is |
| 128 ** compiled with matching library and header files. | 138 ** compiled with matching library and header files. |
| 129 ** | 139 ** |
| 130 ** <blockquote><pre> | 140 ** <blockquote><pre> |
| 131 ** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER ); | 141 ** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER ); |
| 132 ** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 ); | 142 ** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 ); |
| 133 ** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 ); | 143 ** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 ); |
| 134 ** </pre></blockquote>)^ | 144 ** </pre></blockquote>)^ |
| 135 ** | 145 ** |
| 136 ** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION] | 146 ** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION] |
| 137 ** macro. ^The sqlite3_libversion() function returns a pointer to the | 147 ** macro. ^The sqlite3_libversion() function returns a pointer to the |
| 138 ** to the sqlite3_version[] string constant. The sqlite3_libversion() | 148 ** to the sqlite3_version[] string constant. The sqlite3_libversion() |
| 139 ** function is provided for use in DLLs since DLL users usually do not have | 149 ** function is provided for use in DLLs since DLL users usually do not have |
| 140 ** direct access to string constants within the DLL. ^The | 150 ** direct access to string constants within the DLL. ^The |
| 141 ** sqlite3_libversion_number() function returns an integer equal to | 151 ** sqlite3_libversion_number() function returns an integer equal to |
| 142 ** [SQLITE_VERSION_NUMBER]. ^The sqlite3_sourceid() function returns | 152 ** [SQLITE_VERSION_NUMBER]. ^The sqlite3_sourceid() function returns |
| 143 ** a pointer to a string constant whose value is the same as the | 153 ** a pointer to a string constant whose value is the same as the |
| 144 ** [SQLITE_SOURCE_ID] C preprocessor macro. | 154 ** [SQLITE_SOURCE_ID] C preprocessor macro. |
| 145 ** | 155 ** |
| 146 ** See also: [sqlite_version()] and [sqlite_source_id()]. | 156 ** See also: [sqlite_version()] and [sqlite_source_id()]. |
| 147 */ | 157 */ |
| 148 SQLITE_API SQLITE_EXTERN const char sqlite3_version[]; | 158 SQLITE_API SQLITE_EXTERN const char sqlite3_version[]; |
| 149 SQLITE_API const char *SQLITE_STDCALL sqlite3_libversion(void); | 159 SQLITE_API const char *sqlite3_libversion(void); |
| 150 SQLITE_API const char *SQLITE_STDCALL sqlite3_sourceid(void); | 160 SQLITE_API const char *sqlite3_sourceid(void); |
| 151 SQLITE_API int SQLITE_STDCALL sqlite3_libversion_number(void); | 161 SQLITE_API int sqlite3_libversion_number(void); |
| 152 | 162 |
| 153 /* | 163 /* |
| 154 ** CAPI3REF: Run-Time Library Compilation Options Diagnostics | 164 ** CAPI3REF: Run-Time Library Compilation Options Diagnostics |
| 155 ** | 165 ** |
| 156 ** ^The sqlite3_compileoption_used() function returns 0 or 1 | 166 ** ^The sqlite3_compileoption_used() function returns 0 or 1 |
| 157 ** indicating whether the specified option was defined at | 167 ** indicating whether the specified option was defined at |
| 158 ** compile time. ^The SQLITE_ prefix may be omitted from the | 168 ** compile time. ^The SQLITE_ prefix may be omitted from the |
| 159 ** option name passed to sqlite3_compileoption_used(). | 169 ** option name passed to sqlite3_compileoption_used(). |
| 160 ** | 170 ** |
| 161 ** ^The sqlite3_compileoption_get() function allows iterating | 171 ** ^The sqlite3_compileoption_get() function allows iterating |
| 162 ** over the list of options that were defined at compile time by | 172 ** over the list of options that were defined at compile time by |
| 163 ** returning the N-th compile time option string. ^If N is out of range, | 173 ** returning the N-th compile time option string. ^If N is out of range, |
| 164 ** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_ | 174 ** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_ |
| 165 ** prefix is omitted from any strings returned by | 175 ** prefix is omitted from any strings returned by |
| 166 ** sqlite3_compileoption_get(). | 176 ** sqlite3_compileoption_get(). |
| 167 ** | 177 ** |
| 168 ** ^Support for the diagnostic functions sqlite3_compileoption_used() | 178 ** ^Support for the diagnostic functions sqlite3_compileoption_used() |
| 169 ** and sqlite3_compileoption_get() may be omitted by specifying the | 179 ** and sqlite3_compileoption_get() may be omitted by specifying the |
| 170 ** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time. | 180 ** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time. |
| 171 ** | 181 ** |
| 172 ** See also: SQL functions [sqlite_compileoption_used()] and | 182 ** See also: SQL functions [sqlite_compileoption_used()] and |
| 173 ** [sqlite_compileoption_get()] and the [compile_options pragma]. | 183 ** [sqlite_compileoption_get()] and the [compile_options pragma]. |
| 174 */ | 184 */ |
| 175 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS | 185 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS |
| 176 SQLITE_API int SQLITE_STDCALL sqlite3_compileoption_used(const char *zOptName); | 186 SQLITE_API int sqlite3_compileoption_used(const char *zOptName); |
| 177 SQLITE_API const char *SQLITE_STDCALL sqlite3_compileoption_get(int N); | 187 SQLITE_API const char *sqlite3_compileoption_get(int N); |
| 178 #endif | 188 #endif |
| 179 | 189 |
| 180 /* | 190 /* |
| 181 ** CAPI3REF: Test To See If The Library Is Threadsafe | 191 ** CAPI3REF: Test To See If The Library Is Threadsafe |
| 182 ** | 192 ** |
| 183 ** ^The sqlite3_threadsafe() function returns zero if and only if | 193 ** ^The sqlite3_threadsafe() function returns zero if and only if |
| 184 ** SQLite was compiled with mutexing code omitted due to the | 194 ** SQLite was compiled with mutexing code omitted due to the |
| 185 ** [SQLITE_THREADSAFE] compile-time option being set to 0. | 195 ** [SQLITE_THREADSAFE] compile-time option being set to 0. |
| 186 ** | 196 ** |
| 187 ** SQLite can be compiled with or without mutexes. When | 197 ** SQLite can be compiled with or without mutexes. When |
| (...skipping 18 matching lines...) Expand all Loading... |
| 206 ** can be fully or partially disabled using a call to [sqlite3_config()] | 216 ** can be fully or partially disabled using a call to [sqlite3_config()] |
| 207 ** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD], | 217 ** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD], |
| 208 ** or [SQLITE_CONFIG_SERIALIZED]. ^(The return value of the | 218 ** or [SQLITE_CONFIG_SERIALIZED]. ^(The return value of the |
| 209 ** sqlite3_threadsafe() function shows only the compile-time setting of | 219 ** sqlite3_threadsafe() function shows only the compile-time setting of |
| 210 ** thread safety, not any run-time changes to that setting made by | 220 ** thread safety, not any run-time changes to that setting made by |
| 211 ** sqlite3_config(). In other words, the return value from sqlite3_threadsafe() | 221 ** sqlite3_config(). In other words, the return value from sqlite3_threadsafe() |
| 212 ** is unchanged by calls to sqlite3_config().)^ | 222 ** is unchanged by calls to sqlite3_config().)^ |
| 213 ** | 223 ** |
| 214 ** See the [threading mode] documentation for additional information. | 224 ** See the [threading mode] documentation for additional information. |
| 215 */ | 225 */ |
| 216 SQLITE_API int SQLITE_STDCALL sqlite3_threadsafe(void); | 226 SQLITE_API int sqlite3_threadsafe(void); |
| 217 | 227 |
| 218 /* | 228 /* |
| 219 ** CAPI3REF: Database Connection Handle | 229 ** CAPI3REF: Database Connection Handle |
| 220 ** KEYWORDS: {database connection} {database connections} | 230 ** KEYWORDS: {database connection} {database connections} |
| 221 ** | 231 ** |
| 222 ** Each open SQLite database is represented by a pointer to an instance of | 232 ** Each open SQLite database is represented by a pointer to an instance of |
| 223 ** the opaque structure named "sqlite3". It is useful to think of an sqlite3 | 233 ** the opaque structure named "sqlite3". It is useful to think of an sqlite3 |
| 224 ** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and | 234 ** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and |
| 225 ** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()] | 235 ** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()] |
| 226 ** and [sqlite3_close_v2()] are its destructors. There are many other | 236 ** and [sqlite3_close_v2()] are its destructors. There are many other |
| (...skipping 15 matching lines...) Expand all Loading... |
| 242 ** The sqlite_int64 and sqlite_uint64 types are supported for backwards | 252 ** The sqlite_int64 and sqlite_uint64 types are supported for backwards |
| 243 ** compatibility only. | 253 ** compatibility only. |
| 244 ** | 254 ** |
| 245 ** ^The sqlite3_int64 and sqlite_int64 types can store integer values | 255 ** ^The sqlite3_int64 and sqlite_int64 types can store integer values |
| 246 ** between -9223372036854775808 and +9223372036854775807 inclusive. ^The | 256 ** between -9223372036854775808 and +9223372036854775807 inclusive. ^The |
| 247 ** sqlite3_uint64 and sqlite_uint64 types can store integer values | 257 ** sqlite3_uint64 and sqlite_uint64 types can store integer values |
| 248 ** between 0 and +18446744073709551615 inclusive. | 258 ** between 0 and +18446744073709551615 inclusive. |
| 249 */ | 259 */ |
| 250 #ifdef SQLITE_INT64_TYPE | 260 #ifdef SQLITE_INT64_TYPE |
| 251 typedef SQLITE_INT64_TYPE sqlite_int64; | 261 typedef SQLITE_INT64_TYPE sqlite_int64; |
| 252 typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; | 262 # ifdef SQLITE_UINT64_TYPE |
| 263 typedef SQLITE_UINT64_TYPE sqlite_uint64; |
| 264 # else |
| 265 typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; |
| 266 # endif |
| 253 #elif defined(_MSC_VER) || defined(__BORLANDC__) | 267 #elif defined(_MSC_VER) || defined(__BORLANDC__) |
| 254 typedef __int64 sqlite_int64; | 268 typedef __int64 sqlite_int64; |
| 255 typedef unsigned __int64 sqlite_uint64; | 269 typedef unsigned __int64 sqlite_uint64; |
| 256 #else | 270 #else |
| 257 typedef long long int sqlite_int64; | 271 typedef long long int sqlite_int64; |
| 258 typedef unsigned long long int sqlite_uint64; | 272 typedef unsigned long long int sqlite_uint64; |
| 259 #endif | 273 #endif |
| 260 typedef sqlite_int64 sqlite3_int64; | 274 typedef sqlite_int64 sqlite3_int64; |
| 261 typedef sqlite_uint64 sqlite3_uint64; | 275 typedef sqlite_uint64 sqlite3_uint64; |
| 262 | 276 |
| (...skipping 40 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 303 ** the transaction is automatically rolled back. | 317 ** the transaction is automatically rolled back. |
| 304 ** | 318 ** |
| 305 ** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)] | 319 ** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)] |
| 306 ** must be either a NULL | 320 ** must be either a NULL |
| 307 ** pointer or an [sqlite3] object pointer obtained | 321 ** pointer or an [sqlite3] object pointer obtained |
| 308 ** from [sqlite3_open()], [sqlite3_open16()], or | 322 ** from [sqlite3_open()], [sqlite3_open16()], or |
| 309 ** [sqlite3_open_v2()], and not previously closed. | 323 ** [sqlite3_open_v2()], and not previously closed. |
| 310 ** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer | 324 ** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer |
| 311 ** argument is a harmless no-op. | 325 ** argument is a harmless no-op. |
| 312 */ | 326 */ |
| 313 SQLITE_API int SQLITE_STDCALL sqlite3_close(sqlite3*); | 327 SQLITE_API int sqlite3_close(sqlite3*); |
| 314 SQLITE_API int SQLITE_STDCALL sqlite3_close_v2(sqlite3*); | 328 SQLITE_API int sqlite3_close_v2(sqlite3*); |
| 315 | 329 |
| 316 /* | 330 /* |
| 317 ** The type for a callback function. | 331 ** The type for a callback function. |
| 318 ** This is legacy and deprecated. It is included for historical | 332 ** This is legacy and deprecated. It is included for historical |
| 319 ** compatibility and is not documented. | 333 ** compatibility and is not documented. |
| 320 */ | 334 */ |
| 321 typedef int (*sqlite3_callback)(void*,int,char**, char**); | 335 typedef int (*sqlite3_callback)(void*,int,char**, char**); |
| 322 | 336 |
| 323 /* | 337 /* |
| 324 ** CAPI3REF: One-Step Query Execution Interface | 338 ** CAPI3REF: One-Step Query Execution Interface |
| (...skipping 15 matching lines...) Expand all Loading... |
| 340 ** is NULL, then no callback is ever invoked and result rows are | 354 ** is NULL, then no callback is ever invoked and result rows are |
| 341 ** ignored. | 355 ** ignored. |
| 342 ** | 356 ** |
| 343 ** ^If an error occurs while evaluating the SQL statements passed into | 357 ** ^If an error occurs while evaluating the SQL statements passed into |
| 344 ** sqlite3_exec(), then execution of the current statement stops and | 358 ** sqlite3_exec(), then execution of the current statement stops and |
| 345 ** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec() | 359 ** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec() |
| 346 ** is not NULL then any error message is written into memory obtained | 360 ** is not NULL then any error message is written into memory obtained |
| 347 ** from [sqlite3_malloc()] and passed back through the 5th parameter. | 361 ** from [sqlite3_malloc()] and passed back through the 5th parameter. |
| 348 ** To avoid memory leaks, the application should invoke [sqlite3_free()] | 362 ** To avoid memory leaks, the application should invoke [sqlite3_free()] |
| 349 ** on error message strings returned through the 5th parameter of | 363 ** on error message strings returned through the 5th parameter of |
| 350 ** of sqlite3_exec() after the error message string is no longer needed. | 364 ** sqlite3_exec() after the error message string is no longer needed. |
| 351 ** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors | 365 ** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors |
| 352 ** occur, then sqlite3_exec() sets the pointer in its 5th parameter to | 366 ** occur, then sqlite3_exec() sets the pointer in its 5th parameter to |
| 353 ** NULL before returning. | 367 ** NULL before returning. |
| 354 ** | 368 ** |
| 355 ** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec() | 369 ** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec() |
| 356 ** routine returns SQLITE_ABORT without invoking the callback again and | 370 ** routine returns SQLITE_ABORT without invoking the callback again and |
| 357 ** without running any subsequent SQL statements. | 371 ** without running any subsequent SQL statements. |
| 358 ** | 372 ** |
| 359 ** ^The 2nd argument to the sqlite3_exec() callback function is the | 373 ** ^The 2nd argument to the sqlite3_exec() callback function is the |
| 360 ** number of columns in the result. ^The 3rd argument to the sqlite3_exec() | 374 ** number of columns in the result. ^The 3rd argument to the sqlite3_exec() |
| (...skipping 14 matching lines...) Expand all Loading... |
| 375 ** | 389 ** |
| 376 ** <ul> | 390 ** <ul> |
| 377 ** <li> The application must ensure that the 1st parameter to sqlite3_exec() | 391 ** <li> The application must ensure that the 1st parameter to sqlite3_exec() |
| 378 ** is a valid and open [database connection]. | 392 ** is a valid and open [database connection]. |
| 379 ** <li> The application must not close the [database connection] specified by | 393 ** <li> The application must not close the [database connection] specified by |
| 380 ** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running. | 394 ** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running. |
| 381 ** <li> The application must not modify the SQL statement text passed into | 395 ** <li> The application must not modify the SQL statement text passed into |
| 382 ** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running. | 396 ** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running. |
| 383 ** </ul> | 397 ** </ul> |
| 384 */ | 398 */ |
| 385 SQLITE_API int SQLITE_STDCALL sqlite3_exec( | 399 SQLITE_API int sqlite3_exec( |
| 386 sqlite3*, /* An open database */ | 400 sqlite3*, /* An open database */ |
| 387 const char *sql, /* SQL to be evaluated */ | 401 const char *sql, /* SQL to be evaluated */ |
| 388 int (*callback)(void*,int,char**,char**), /* Callback function */ | 402 int (*callback)(void*,int,char**,char**), /* Callback function */ |
| 389 void *, /* 1st argument to callback */ | 403 void *, /* 1st argument to callback */ |
| 390 char **errmsg /* Error msg written here */ | 404 char **errmsg /* Error msg written here */ |
| 391 ); | 405 ); |
| 392 | 406 |
| 393 /* | 407 /* |
| 394 ** CAPI3REF: Result Codes | 408 ** CAPI3REF: Result Codes |
| 395 ** KEYWORDS: {result code definitions} | 409 ** KEYWORDS: {result code definitions} |
| (...skipping 40 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 436 /* end-of-error-codes */ | 450 /* end-of-error-codes */ |
| 437 | 451 |
| 438 /* | 452 /* |
| 439 ** CAPI3REF: Extended Result Codes | 453 ** CAPI3REF: Extended Result Codes |
| 440 ** KEYWORDS: {extended result code definitions} | 454 ** KEYWORDS: {extended result code definitions} |
| 441 ** | 455 ** |
| 442 ** In its default configuration, SQLite API routines return one of 30 integer | 456 ** In its default configuration, SQLite API routines return one of 30 integer |
| 443 ** [result codes]. However, experience has shown that many of | 457 ** [result codes]. However, experience has shown that many of |
| 444 ** these result codes are too coarse-grained. They do not provide as | 458 ** these result codes are too coarse-grained. They do not provide as |
| 445 ** much information about problems as programmers might like. In an effort to | 459 ** much information about problems as programmers might like. In an effort to |
| 446 ** address this, newer versions of SQLite (version 3.3.8 and later) include | 460 ** address this, newer versions of SQLite (version 3.3.8 [dateof:3.3.8] |
| 461 ** and later) include |
| 447 ** support for additional result codes that provide more detailed information | 462 ** support for additional result codes that provide more detailed information |
| 448 ** about errors. These [extended result codes] are enabled or disabled | 463 ** about errors. These [extended result codes] are enabled or disabled |
| 449 ** on a per database connection basis using the | 464 ** on a per database connection basis using the |
| 450 ** [sqlite3_extended_result_codes()] API. Or, the extended code for | 465 ** [sqlite3_extended_result_codes()] API. Or, the extended code for |
| 451 ** the most recent error can be obtained using | 466 ** the most recent error can be obtained using |
| 452 ** [sqlite3_extended_errcode()]. | 467 ** [sqlite3_extended_errcode()]. |
| 453 */ | 468 */ |
| 454 #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) | 469 #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) |
| 455 #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) | 470 #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) |
| 456 #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) | 471 #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) |
| (...skipping 42 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 499 #define SQLITE_CONSTRAINT_NOTNULL (SQLITE_CONSTRAINT | (5<<8)) | 514 #define SQLITE_CONSTRAINT_NOTNULL (SQLITE_CONSTRAINT | (5<<8)) |
| 500 #define SQLITE_CONSTRAINT_PRIMARYKEY (SQLITE_CONSTRAINT | (6<<8)) | 515 #define SQLITE_CONSTRAINT_PRIMARYKEY (SQLITE_CONSTRAINT | (6<<8)) |
| 501 #define SQLITE_CONSTRAINT_TRIGGER (SQLITE_CONSTRAINT | (7<<8)) | 516 #define SQLITE_CONSTRAINT_TRIGGER (SQLITE_CONSTRAINT | (7<<8)) |
| 502 #define SQLITE_CONSTRAINT_UNIQUE (SQLITE_CONSTRAINT | (8<<8)) | 517 #define SQLITE_CONSTRAINT_UNIQUE (SQLITE_CONSTRAINT | (8<<8)) |
| 503 #define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT | (9<<8)) | 518 #define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT | (9<<8)) |
| 504 #define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT |(10<<8)) | 519 #define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT |(10<<8)) |
| 505 #define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1<<8)) | 520 #define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1<<8)) |
| 506 #define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8)) | 521 #define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8)) |
| 507 #define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8)) | 522 #define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8)) |
| 508 #define SQLITE_AUTH_USER (SQLITE_AUTH | (1<<8)) | 523 #define SQLITE_AUTH_USER (SQLITE_AUTH | (1<<8)) |
| 524 #define SQLITE_OK_LOAD_PERMANENTLY (SQLITE_OK | (1<<8)) |
| 509 | 525 |
| 510 /* | 526 /* |
| 511 ** CAPI3REF: Flags For File Open Operations | 527 ** CAPI3REF: Flags For File Open Operations |
| 512 ** | 528 ** |
| 513 ** These bit values are intended for use in the | 529 ** These bit values are intended for use in the |
| 514 ** 3rd parameter to the [sqlite3_open_v2()] interface and | 530 ** 3rd parameter to the [sqlite3_open_v2()] interface and |
| 515 ** in the 4th parameter to the [sqlite3_vfs.xOpen] method. | 531 ** in the 4th parameter to the [sqlite3_vfs.xOpen] method. |
| 516 */ | 532 */ |
| 517 #define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */ | 533 #define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */ |
| 518 #define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */ | 534 #define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */ |
| (...skipping 34 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 553 ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means | 569 ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means |
| 554 ** that when data is appended to a file, the data is appended | 570 ** that when data is appended to a file, the data is appended |
| 555 ** first then the size of the file is extended, never the other | 571 ** first then the size of the file is extended, never the other |
| 556 ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that | 572 ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that |
| 557 ** information is written to disk in the same order as calls | 573 ** information is written to disk in the same order as calls |
| 558 ** to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that | 574 ** to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that |
| 559 ** after reboot following a crash or power loss, the only bytes in a | 575 ** after reboot following a crash or power loss, the only bytes in a |
| 560 ** file that were written at the application level might have changed | 576 ** file that were written at the application level might have changed |
| 561 ** and that adjacent bytes, even bytes within the same sector are | 577 ** and that adjacent bytes, even bytes within the same sector are |
| 562 ** guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN | 578 ** guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN |
| 563 ** flag indicate that a file cannot be deleted when open. The | 579 ** flag indicates that a file cannot be deleted when open. The |
| 564 ** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on | 580 ** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on |
| 565 ** read-only media and cannot be changed even by processes with | 581 ** read-only media and cannot be changed even by processes with |
| 566 ** elevated privileges. | 582 ** elevated privileges. |
| 567 */ | 583 */ |
| 568 #define SQLITE_IOCAP_ATOMIC 0x00000001 | 584 #define SQLITE_IOCAP_ATOMIC 0x00000001 |
| 569 #define SQLITE_IOCAP_ATOMIC512 0x00000002 | 585 #define SQLITE_IOCAP_ATOMIC512 0x00000002 |
| 570 #define SQLITE_IOCAP_ATOMIC1K 0x00000004 | 586 #define SQLITE_IOCAP_ATOMIC1K 0x00000004 |
| 571 #define SQLITE_IOCAP_ATOMIC2K 0x00000008 | 587 #define SQLITE_IOCAP_ATOMIC2K 0x00000008 |
| 572 #define SQLITE_IOCAP_ATOMIC4K 0x00000010 | 588 #define SQLITE_IOCAP_ATOMIC4K 0x00000010 |
| 573 #define SQLITE_IOCAP_ATOMIC8K 0x00000020 | 589 #define SQLITE_IOCAP_ATOMIC8K 0x00000020 |
| (...skipping 129 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 703 ** <li> [SQLITE_IOCAP_ATOMIC512] | 719 ** <li> [SQLITE_IOCAP_ATOMIC512] |
| 704 ** <li> [SQLITE_IOCAP_ATOMIC1K] | 720 ** <li> [SQLITE_IOCAP_ATOMIC1K] |
| 705 ** <li> [SQLITE_IOCAP_ATOMIC2K] | 721 ** <li> [SQLITE_IOCAP_ATOMIC2K] |
| 706 ** <li> [SQLITE_IOCAP_ATOMIC4K] | 722 ** <li> [SQLITE_IOCAP_ATOMIC4K] |
| 707 ** <li> [SQLITE_IOCAP_ATOMIC8K] | 723 ** <li> [SQLITE_IOCAP_ATOMIC8K] |
| 708 ** <li> [SQLITE_IOCAP_ATOMIC16K] | 724 ** <li> [SQLITE_IOCAP_ATOMIC16K] |
| 709 ** <li> [SQLITE_IOCAP_ATOMIC32K] | 725 ** <li> [SQLITE_IOCAP_ATOMIC32K] |
| 710 ** <li> [SQLITE_IOCAP_ATOMIC64K] | 726 ** <li> [SQLITE_IOCAP_ATOMIC64K] |
| 711 ** <li> [SQLITE_IOCAP_SAFE_APPEND] | 727 ** <li> [SQLITE_IOCAP_SAFE_APPEND] |
| 712 ** <li> [SQLITE_IOCAP_SEQUENTIAL] | 728 ** <li> [SQLITE_IOCAP_SEQUENTIAL] |
| 729 ** <li> [SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN] |
| 730 ** <li> [SQLITE_IOCAP_POWERSAFE_OVERWRITE] |
| 731 ** <li> [SQLITE_IOCAP_IMMUTABLE] |
| 713 ** </ul> | 732 ** </ul> |
| 714 ** | 733 ** |
| 715 ** The SQLITE_IOCAP_ATOMIC property means that all writes of | 734 ** The SQLITE_IOCAP_ATOMIC property means that all writes of |
| 716 ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values | 735 ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values |
| 717 ** mean that writes of blocks that are nnn bytes in size and | 736 ** mean that writes of blocks that are nnn bytes in size and |
| 718 ** are aligned to an address which is an integer multiple of | 737 ** are aligned to an address which is an integer multiple of |
| 719 ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means | 738 ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means |
| 720 ** that when data is appended to a file, the data is appended | 739 ** that when data is appended to a file, the data is appended |
| 721 ** first then the size of the file is extended, never the other | 740 ** first then the size of the file is extended, never the other |
| 722 ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that | 741 ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that |
| (...skipping 236 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 959 ** The argument is a zero-terminated string. Higher layers in the | 978 ** The argument is a zero-terminated string. Higher layers in the |
| 960 ** SQLite stack may generate instances of this file control if | 979 ** SQLite stack may generate instances of this file control if |
| 961 ** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled. | 980 ** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled. |
| 962 ** | 981 ** |
| 963 ** <li>[[SQLITE_FCNTL_HAS_MOVED]] | 982 ** <li>[[SQLITE_FCNTL_HAS_MOVED]] |
| 964 ** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a | 983 ** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a |
| 965 ** pointer to an integer and it writes a boolean into that integer depending | 984 ** pointer to an integer and it writes a boolean into that integer depending |
| 966 ** on whether or not the file has been renamed, moved, or deleted since it | 985 ** on whether or not the file has been renamed, moved, or deleted since it |
| 967 ** was first opened. | 986 ** was first opened. |
| 968 ** | 987 ** |
| 988 ** <li>[[SQLITE_FCNTL_WIN32_GET_HANDLE]] |
| 989 ** The [SQLITE_FCNTL_WIN32_GET_HANDLE] opcode can be used to obtain the |
| 990 ** underlying native file handle associated with a file handle. This file |
| 991 ** control interprets its argument as a pointer to a native file handle and |
| 992 ** writes the resulting value there. |
| 993 ** |
| 969 ** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]] | 994 ** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]] |
| 970 ** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This | 995 ** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This |
| 971 ** opcode causes the xFileControl method to swap the file handle with the one | 996 ** opcode causes the xFileControl method to swap the file handle with the one |
| 972 ** pointed to by the pArg argument. This capability is used during testing | 997 ** pointed to by the pArg argument. This capability is used during testing |
| 973 ** and only needs to be supported when SQLITE_TEST is defined. | 998 ** and only needs to be supported when SQLITE_TEST is defined. |
| 974 ** | 999 ** |
| 975 ** <li>[[SQLITE_FCNTL_WAL_BLOCK]] | 1000 ** <li>[[SQLITE_FCNTL_WAL_BLOCK]] |
| 976 ** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might | 1001 ** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might |
| 977 ** be advantageous to block on the next WAL lock if the lock is not immediately | 1002 ** be advantageous to block on the next WAL lock if the lock is not immediately |
| 978 ** available. The WAL subsystem issues this signal during rare | 1003 ** available. The WAL subsystem issues this signal during rare |
| (...skipping 30 matching lines...) Expand all Loading... |
| 1009 #define SQLITE_FCNTL_TRACE 19 | 1034 #define SQLITE_FCNTL_TRACE 19 |
| 1010 #define SQLITE_FCNTL_HAS_MOVED 20 | 1035 #define SQLITE_FCNTL_HAS_MOVED 20 |
| 1011 #define SQLITE_FCNTL_SYNC 21 | 1036 #define SQLITE_FCNTL_SYNC 21 |
| 1012 #define SQLITE_FCNTL_COMMIT_PHASETWO 22 | 1037 #define SQLITE_FCNTL_COMMIT_PHASETWO 22 |
| 1013 #define SQLITE_FCNTL_WIN32_SET_HANDLE 23 | 1038 #define SQLITE_FCNTL_WIN32_SET_HANDLE 23 |
| 1014 #define SQLITE_FCNTL_WAL_BLOCK 24 | 1039 #define SQLITE_FCNTL_WAL_BLOCK 24 |
| 1015 #define SQLITE_FCNTL_ZIPVFS 25 | 1040 #define SQLITE_FCNTL_ZIPVFS 25 |
| 1016 #define SQLITE_FCNTL_RBU 26 | 1041 #define SQLITE_FCNTL_RBU 26 |
| 1017 #define SQLITE_FCNTL_VFS_POINTER 27 | 1042 #define SQLITE_FCNTL_VFS_POINTER 27 |
| 1018 #define SQLITE_FCNTL_JOURNAL_POINTER 28 | 1043 #define SQLITE_FCNTL_JOURNAL_POINTER 28 |
| 1044 #define SQLITE_FCNTL_WIN32_GET_HANDLE 29 |
| 1045 #define SQLITE_FCNTL_PDB 30 |
| 1019 | 1046 |
| 1020 /* deprecated names */ | 1047 /* deprecated names */ |
| 1021 #define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE | 1048 #define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE |
| 1022 #define SQLITE_SET_LOCKPROXYFILE SQLITE_FCNTL_SET_LOCKPROXYFILE | 1049 #define SQLITE_SET_LOCKPROXYFILE SQLITE_FCNTL_SET_LOCKPROXYFILE |
| 1023 #define SQLITE_LAST_ERRNO SQLITE_FCNTL_LAST_ERRNO | 1050 #define SQLITE_LAST_ERRNO SQLITE_FCNTL_LAST_ERRNO |
| 1024 | 1051 |
| 1025 | 1052 |
| 1026 /* | 1053 /* |
| 1027 ** CAPI3REF: Mutex Handle | 1054 ** CAPI3REF: Mutex Handle |
| 1028 ** | 1055 ** |
| 1029 ** The mutex module within SQLite defines [sqlite3_mutex] to be an | 1056 ** The mutex module within SQLite defines [sqlite3_mutex] to be an |
| 1030 ** abstract type for a mutex object. The SQLite core never looks | 1057 ** abstract type for a mutex object. The SQLite core never looks |
| 1031 ** at the internal representation of an [sqlite3_mutex]. It only | 1058 ** at the internal representation of an [sqlite3_mutex]. It only |
| 1032 ** deals with pointers to the [sqlite3_mutex] object. | 1059 ** deals with pointers to the [sqlite3_mutex] object. |
| 1033 ** | 1060 ** |
| 1034 ** Mutexes are created using [sqlite3_mutex_alloc()]. | 1061 ** Mutexes are created using [sqlite3_mutex_alloc()]. |
| 1035 */ | 1062 */ |
| 1036 typedef struct sqlite3_mutex sqlite3_mutex; | 1063 typedef struct sqlite3_mutex sqlite3_mutex; |
| 1037 | 1064 |
| 1038 /* | 1065 /* |
| 1066 ** CAPI3REF: Loadable Extension Thunk |
| 1067 ** |
| 1068 ** A pointer to the opaque sqlite3_api_routines structure is passed as |
| 1069 ** the third parameter to entry points of [loadable extensions]. This |
| 1070 ** structure must be typedefed in order to work around compiler warnings |
| 1071 ** on some platforms. |
| 1072 */ |
| 1073 typedef struct sqlite3_api_routines sqlite3_api_routines; |
| 1074 |
| 1075 /* |
| 1039 ** CAPI3REF: OS Interface Object | 1076 ** CAPI3REF: OS Interface Object |
| 1040 ** | 1077 ** |
| 1041 ** An instance of the sqlite3_vfs object defines the interface between | 1078 ** An instance of the sqlite3_vfs object defines the interface between |
| 1042 ** the SQLite core and the underlying operating system. The "vfs" | 1079 ** the SQLite core and the underlying operating system. The "vfs" |
| 1043 ** in the name of the object stands for "virtual file system". See | 1080 ** in the name of the object stands for "virtual file system". See |
| 1044 ** the [VFS | VFS documentation] for further information. | 1081 ** the [VFS | VFS documentation] for further information. |
| 1045 ** | 1082 ** |
| 1046 ** The value of the iVersion field is initially 1 but may be larger in | 1083 ** The value of the iVersion field is initially 1 but may be larger in |
| 1047 ** future versions of SQLite. Additional fields may be appended to this | 1084 ** future versions of SQLite. Additional fields may be appended to this |
| 1048 ** object when the iVersion value is increased. Note that the structure | 1085 ** object when the iVersion value is increased. Note that the structure |
| (...skipping 172 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1221 int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*); | 1258 int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*); |
| 1222 /* | 1259 /* |
| 1223 ** The methods above are in versions 1 and 2 of the sqlite_vfs object. | 1260 ** The methods above are in versions 1 and 2 of the sqlite_vfs object. |
| 1224 ** Those below are for version 3 and greater. | 1261 ** Those below are for version 3 and greater. |
| 1225 */ | 1262 */ |
| 1226 int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr); | 1263 int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr); |
| 1227 sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName); | 1264 sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName); |
| 1228 const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName); | 1265 const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName); |
| 1229 /* | 1266 /* |
| 1230 ** The methods above are in versions 1 through 3 of the sqlite_vfs object. | 1267 ** The methods above are in versions 1 through 3 of the sqlite_vfs object. |
| 1231 ** New fields may be appended in figure versions. The iVersion | 1268 ** New fields may be appended in future versions. The iVersion |
| 1232 ** value will increment whenever this happens. | 1269 ** value will increment whenever this happens. |
| 1233 */ | 1270 */ |
| 1234 }; | 1271 }; |
| 1235 | 1272 |
| 1236 /* | 1273 /* |
| 1237 ** CAPI3REF: Flags for the xAccess VFS method | 1274 ** CAPI3REF: Flags for the xAccess VFS method |
| 1238 ** | 1275 ** |
| 1239 ** These integer constants can be used as the third parameter to | 1276 ** These integer constants can be used as the third parameter to |
| 1240 ** the xAccess method of an [sqlite3_vfs] object. They determine | 1277 ** the xAccess method of an [sqlite3_vfs] object. They determine |
| 1241 ** what kind of permissions the xAccess method is looking for. | 1278 ** what kind of permissions the xAccess method is looking for. |
| (...skipping 121 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1363 ** implementations for sqlite3_os_init() and sqlite3_os_end() | 1400 ** implementations for sqlite3_os_init() and sqlite3_os_end() |
| 1364 ** are built into SQLite when it is compiled for Unix, Windows, or OS/2. | 1401 ** are built into SQLite when it is compiled for Unix, Windows, or OS/2. |
| 1365 ** When [custom builds | built for other platforms] | 1402 ** When [custom builds | built for other platforms] |
| 1366 ** (using the [SQLITE_OS_OTHER=1] compile-time | 1403 ** (using the [SQLITE_OS_OTHER=1] compile-time |
| 1367 ** option) the application must supply a suitable implementation for | 1404 ** option) the application must supply a suitable implementation for |
| 1368 ** sqlite3_os_init() and sqlite3_os_end(). An application-supplied | 1405 ** sqlite3_os_init() and sqlite3_os_end(). An application-supplied |
| 1369 ** implementation of sqlite3_os_init() or sqlite3_os_end() | 1406 ** implementation of sqlite3_os_init() or sqlite3_os_end() |
| 1370 ** must return [SQLITE_OK] on success and some other [error code] upon | 1407 ** must return [SQLITE_OK] on success and some other [error code] upon |
| 1371 ** failure. | 1408 ** failure. |
| 1372 */ | 1409 */ |
| 1373 SQLITE_API int SQLITE_STDCALL sqlite3_initialize(void); | 1410 SQLITE_API int sqlite3_initialize(void); |
| 1374 SQLITE_API int SQLITE_STDCALL sqlite3_shutdown(void); | 1411 SQLITE_API int sqlite3_shutdown(void); |
| 1375 SQLITE_API int SQLITE_STDCALL sqlite3_os_init(void); | 1412 SQLITE_API int sqlite3_os_init(void); |
| 1376 SQLITE_API int SQLITE_STDCALL sqlite3_os_end(void); | 1413 SQLITE_API int sqlite3_os_end(void); |
| 1377 | 1414 |
| 1378 /* | 1415 /* |
| 1379 ** CAPI3REF: Configuring The SQLite Library | 1416 ** CAPI3REF: Configuring The SQLite Library |
| 1380 ** | 1417 ** |
| 1381 ** The sqlite3_config() interface is used to make global configuration | 1418 ** The sqlite3_config() interface is used to make global configuration |
| 1382 ** changes to SQLite in order to tune SQLite to the specific needs of | 1419 ** changes to SQLite in order to tune SQLite to the specific needs of |
| 1383 ** the application. The default configuration is recommended for most | 1420 ** the application. The default configuration is recommended for most |
| 1384 ** applications and so this routine is usually not necessary. It is | 1421 ** applications and so this routine is usually not necessary. It is |
| 1385 ** provided to support rare applications with unusual needs. | 1422 ** provided to support rare applications with unusual needs. |
| 1386 ** | 1423 ** |
| (...skipping 12 matching lines...) Expand all Loading... |
| 1399 ** The first argument to sqlite3_config() is an integer | 1436 ** The first argument to sqlite3_config() is an integer |
| 1400 ** [configuration option] that determines | 1437 ** [configuration option] that determines |
| 1401 ** what property of SQLite is to be configured. Subsequent arguments | 1438 ** what property of SQLite is to be configured. Subsequent arguments |
| 1402 ** vary depending on the [configuration option] | 1439 ** vary depending on the [configuration option] |
| 1403 ** in the first argument. | 1440 ** in the first argument. |
| 1404 ** | 1441 ** |
| 1405 ** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK]. | 1442 ** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK]. |
| 1406 ** ^If the option is unknown or SQLite is unable to set the option | 1443 ** ^If the option is unknown or SQLite is unable to set the option |
| 1407 ** then this routine returns a non-zero [error code]. | 1444 ** then this routine returns a non-zero [error code]. |
| 1408 */ | 1445 */ |
| 1409 SQLITE_API int SQLITE_CDECL sqlite3_config(int, ...); | 1446 SQLITE_API int sqlite3_config(int, ...); |
| 1410 | 1447 |
| 1411 /* | 1448 /* |
| 1412 ** CAPI3REF: Configure database connections | 1449 ** CAPI3REF: Configure database connections |
| 1413 ** METHOD: sqlite3 | 1450 ** METHOD: sqlite3 |
| 1414 ** | 1451 ** |
| 1415 ** The sqlite3_db_config() interface is used to make configuration | 1452 ** The sqlite3_db_config() interface is used to make configuration |
| 1416 ** changes to a [database connection]. The interface is similar to | 1453 ** changes to a [database connection]. The interface is similar to |
| 1417 ** [sqlite3_config()] except that the changes apply to a single | 1454 ** [sqlite3_config()] except that the changes apply to a single |
| 1418 ** [database connection] (specified in the first argument). | 1455 ** [database connection] (specified in the first argument). |
| 1419 ** | 1456 ** |
| 1420 ** The second argument to sqlite3_db_config(D,V,...) is the | 1457 ** The second argument to sqlite3_db_config(D,V,...) is the |
| 1421 ** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code | 1458 ** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code |
| 1422 ** that indicates what aspect of the [database connection] is being configured. | 1459 ** that indicates what aspect of the [database connection] is being configured. |
| 1423 ** Subsequent arguments vary depending on the configuration verb. | 1460 ** Subsequent arguments vary depending on the configuration verb. |
| 1424 ** | 1461 ** |
| 1425 ** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if | 1462 ** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if |
| 1426 ** the call is considered successful. | 1463 ** the call is considered successful. |
| 1427 */ | 1464 */ |
| 1428 SQLITE_API int SQLITE_CDECL sqlite3_db_config(sqlite3*, int op, ...); | 1465 SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...); |
| 1429 | 1466 |
| 1430 /* | 1467 /* |
| 1431 ** CAPI3REF: Memory Allocation Routines | 1468 ** CAPI3REF: Memory Allocation Routines |
| 1432 ** | 1469 ** |
| 1433 ** An instance of this object defines the interface between SQLite | 1470 ** An instance of this object defines the interface between SQLite |
| 1434 ** and low-level memory allocation routines. | 1471 ** and low-level memory allocation routines. |
| 1435 ** | 1472 ** |
| 1436 ** This object is used in only one place in the SQLite interface. | 1473 ** This object is used in only one place in the SQLite interface. |
| 1437 ** A pointer to an instance of this object is the argument to | 1474 ** A pointer to an instance of this object is the argument to |
| 1438 ** [sqlite3_config()] when the configuration option is | 1475 ** [sqlite3_config()] when the configuration option is |
| (...skipping 374 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1813 ** [[SQLITE_CONFIG_PMASZ]] | 1850 ** [[SQLITE_CONFIG_PMASZ]] |
| 1814 ** <dt>SQLITE_CONFIG_PMASZ | 1851 ** <dt>SQLITE_CONFIG_PMASZ |
| 1815 ** <dd>^The SQLITE_CONFIG_PMASZ option takes a single parameter which | 1852 ** <dd>^The SQLITE_CONFIG_PMASZ option takes a single parameter which |
| 1816 ** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded | 1853 ** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded |
| 1817 ** sorter to that integer. The default minimum PMA Size is set by the | 1854 ** sorter to that integer. The default minimum PMA Size is set by the |
| 1818 ** [SQLITE_SORTER_PMASZ] compile-time option. New threads are launched | 1855 ** [SQLITE_SORTER_PMASZ] compile-time option. New threads are launched |
| 1819 ** to help with sort operations when multithreaded sorting | 1856 ** to help with sort operations when multithreaded sorting |
| 1820 ** is enabled (using the [PRAGMA threads] command) and the amount of content | 1857 ** is enabled (using the [PRAGMA threads] command) and the amount of content |
| 1821 ** to be sorted exceeds the page size times the minimum of the | 1858 ** to be sorted exceeds the page size times the minimum of the |
| 1822 ** [PRAGMA cache_size] setting and this value. | 1859 ** [PRAGMA cache_size] setting and this value. |
| 1860 ** |
| 1861 ** [[SQLITE_CONFIG_STMTJRNL_SPILL]] |
| 1862 ** <dt>SQLITE_CONFIG_STMTJRNL_SPILL |
| 1863 ** <dd>^The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which |
| 1864 ** becomes the [statement journal] spill-to-disk threshold. |
| 1865 ** [Statement journals] are held in memory until their size (in bytes) |
| 1866 ** exceeds this threshold, at which point they are written to disk. |
| 1867 ** Or if the threshold is -1, statement journals are always held |
| 1868 ** exclusively in memory. |
| 1869 ** Since many statement journals never become large, setting the spill |
| 1870 ** threshold to a value such as 64KiB can greatly reduce the amount of |
| 1871 ** I/O required to support statement rollback. |
| 1872 ** The default value for this setting is controlled by the |
| 1873 ** [SQLITE_STMTJRNL_SPILL] compile-time option. |
| 1823 ** </dl> | 1874 ** </dl> |
| 1824 */ | 1875 */ |
| 1825 #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ | 1876 #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */ |
| 1826 #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ | 1877 #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */ |
| 1827 #define SQLITE_CONFIG_SERIALIZED 3 /* nil */ | 1878 #define SQLITE_CONFIG_SERIALIZED 3 /* nil */ |
| 1828 #define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */ | 1879 #define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */ |
| 1829 #define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */ | 1880 #define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */ |
| 1830 #define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */ | 1881 #define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */ |
| 1831 #define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */ | 1882 #define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */ |
| 1832 #define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ | 1883 #define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */ |
| 1833 #define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ | 1884 #define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */ |
| 1834 #define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ | 1885 #define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ |
| 1835 #define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ | 1886 #define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ |
| 1836 /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ | 1887 /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ |
| 1837 #define SQLITE_CONFIG_LOOKASIDE 13 /* int int */ | 1888 #define SQLITE_CONFIG_LOOKASIDE 13 /* int int */ |
| 1838 #define SQLITE_CONFIG_PCACHE 14 /* no-op */ | 1889 #define SQLITE_CONFIG_PCACHE 14 /* no-op */ |
| 1839 #define SQLITE_CONFIG_GETPCACHE 15 /* no-op */ | 1890 #define SQLITE_CONFIG_GETPCACHE 15 /* no-op */ |
| 1840 #define SQLITE_CONFIG_LOG 16 /* xFunc, void* */ | 1891 #define SQLITE_CONFIG_LOG 16 /* xFunc, void* */ |
| 1841 #define SQLITE_CONFIG_URI 17 /* int */ | 1892 #define SQLITE_CONFIG_URI 17 /* int */ |
| 1842 #define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */ | 1893 #define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */ |
| 1843 #define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */ | 1894 #define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */ |
| 1844 #define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */ | 1895 #define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */ |
| 1845 #define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */ | 1896 #define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */ |
| 1846 #define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */ | 1897 #define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */ |
| 1847 #define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */ | 1898 #define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */ |
| 1848 #define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */ | 1899 #define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */ |
| 1849 #define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */ | 1900 #define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */ |
| 1901 #define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */ |
| 1850 | 1902 |
| 1851 /* | 1903 /* |
| 1852 ** CAPI3REF: Database Connection Configuration Options | 1904 ** CAPI3REF: Database Connection Configuration Options |
| 1853 ** | 1905 ** |
| 1854 ** These constants are the available integer configuration options that | 1906 ** These constants are the available integer configuration options that |
| 1855 ** can be passed as the second argument to the [sqlite3_db_config()] interface. | 1907 ** can be passed as the second argument to the [sqlite3_db_config()] interface. |
| 1856 ** | 1908 ** |
| 1857 ** New configuration options may be added in future releases of SQLite. | 1909 ** New configuration options may be added in future releases of SQLite. |
| 1858 ** Existing configuration options might be discontinued. Applications | 1910 ** Existing configuration options might be discontinued. Applications |
| 1859 ** should check the return code from [sqlite3_db_config()] to make sure that | 1911 ** should check the return code from [sqlite3_db_config()] to make sure that |
| (...skipping 37 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1897 ** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt> | 1949 ** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt> |
| 1898 ** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers]. | 1950 ** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers]. |
| 1899 ** There should be two additional arguments. | 1951 ** There should be two additional arguments. |
| 1900 ** The first argument is an integer which is 0 to disable triggers, | 1952 ** The first argument is an integer which is 0 to disable triggers, |
| 1901 ** positive to enable triggers or negative to leave the setting unchanged. | 1953 ** positive to enable triggers or negative to leave the setting unchanged. |
| 1902 ** The second parameter is a pointer to an integer into which | 1954 ** The second parameter is a pointer to an integer into which |
| 1903 ** is written 0 or 1 to indicate whether triggers are disabled or enabled | 1955 ** is written 0 or 1 to indicate whether triggers are disabled or enabled |
| 1904 ** following this call. The second parameter may be a NULL pointer, in | 1956 ** following this call. The second parameter may be a NULL pointer, in |
| 1905 ** which case the trigger setting is not reported back. </dd> | 1957 ** which case the trigger setting is not reported back. </dd> |
| 1906 ** | 1958 ** |
| 1959 ** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt> |
| 1960 ** <dd> ^This option is used to enable or disable the two-argument |
| 1961 ** version of the [fts3_tokenizer()] function which is part of the |
| 1962 ** [FTS3] full-text search engine extension. |
| 1963 ** There should be two additional arguments. |
| 1964 ** The first argument is an integer which is 0 to disable fts3_tokenizer() or |
| 1965 ** positive to enable fts3_tokenizer() or negative to leave the setting |
| 1966 ** unchanged. |
| 1967 ** The second parameter is a pointer to an integer into which |
| 1968 ** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled |
| 1969 ** following this call. The second parameter may be a NULL pointer, in |
| 1970 ** which case the new setting is not reported back. </dd> |
| 1971 ** |
| 1972 ** <dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt> |
| 1973 ** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()] |
| 1974 ** interface independently of the [load_extension()] SQL function. |
| 1975 ** The [sqlite3_enable_load_extension()] API enables or disables both the |
| 1976 ** C-API [sqlite3_load_extension()] and the SQL function [load_extension()]. |
| 1977 ** There should be two additional arguments. |
| 1978 ** When the first argument to this interface is 1, then only the C-API is |
| 1979 ** enabled and the SQL function remains disabled. If the first argument to |
| 1980 ** this interface is 0, then both the C-API and the SQL function are disabled. |
| 1981 ** If the first argument is -1, then no changes are made to state of either the |
| 1982 ** C-API or the SQL function. |
| 1983 ** The second parameter is a pointer to an integer into which |
| 1984 ** is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface |
| 1985 ** is disabled or enabled following this call. The second parameter may |
| 1986 ** be a NULL pointer, in which case the new setting is not reported back. |
| 1987 ** </dd> |
| 1988 ** |
| 1989 ** <dt>SQLITE_DBCONFIG_MAINDBNAME</dt> |
| 1990 ** <dd> ^This option is used to change the name of the "main" database |
| 1991 ** schema. ^The sole argument is a pointer to a constant UTF8 string |
| 1992 ** which will become the new schema name in place of "main". ^SQLite |
| 1993 ** does not make a copy of the new main schema name string, so the application |
| 1994 ** must ensure that the argument passed into this DBCONFIG option is unchanged |
| 1995 ** until after the database connection closes. |
| 1996 ** </dd> |
| 1997 ** |
| 1998 ** <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt> |
| 1999 ** <dd> Usually, when a database in wal mode is closed or detached from a |
| 2000 ** database handle, SQLite checks if this will mean that there are now no |
| 2001 ** connections at all to the database. If so, it performs a checkpoint |
| 2002 ** operation before closing the connection. This option may be used to |
| 2003 ** override this behaviour. The first parameter passed to this operation |
| 2004 ** is an integer - non-zero to disable checkpoints-on-close, or zero (the |
| 2005 ** default) to enable them. The second parameter is a pointer to an integer |
| 2006 ** into which is written 0 or 1 to indicate whether checkpoints-on-close |
| 2007 ** have been disabled - 0 if they are not disabled, 1 if they are. |
| 2008 ** </dd> |
| 2009 ** |
| 1907 ** </dl> | 2010 ** </dl> |
| 1908 */ | 2011 */ |
| 1909 #define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ | 2012 #define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */ |
| 1910 #define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */ | 2013 #define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ |
| 1911 #define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */ | 2014 #define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */ |
| 2015 #define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */ |
| 2016 #define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */ |
| 2017 #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */ |
| 2018 #define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */ |
| 1912 | 2019 |
| 1913 | 2020 |
| 1914 /* | 2021 /* |
| 1915 ** CAPI3REF: Enable Or Disable Extended Result Codes | 2022 ** CAPI3REF: Enable Or Disable Extended Result Codes |
| 1916 ** METHOD: sqlite3 | 2023 ** METHOD: sqlite3 |
| 1917 ** | 2024 ** |
| 1918 ** ^The sqlite3_extended_result_codes() routine enables or disables the | 2025 ** ^The sqlite3_extended_result_codes() routine enables or disables the |
| 1919 ** [extended result codes] feature of SQLite. ^The extended result | 2026 ** [extended result codes] feature of SQLite. ^The extended result |
| 1920 ** codes are disabled by default for historical compatibility. | 2027 ** codes are disabled by default for historical compatibility. |
| 1921 */ | 2028 */ |
| 1922 SQLITE_API int SQLITE_STDCALL sqlite3_extended_result_codes(sqlite3*, int onoff)
; | 2029 SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff); |
| 1923 | 2030 |
| 1924 /* | 2031 /* |
| 1925 ** CAPI3REF: Last Insert Rowid | 2032 ** CAPI3REF: Last Insert Rowid |
| 1926 ** METHOD: sqlite3 | 2033 ** METHOD: sqlite3 |
| 1927 ** | 2034 ** |
| 1928 ** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables) | 2035 ** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables) |
| 1929 ** has a unique 64-bit signed | 2036 ** has a unique 64-bit signed |
| 1930 ** integer key called the [ROWID | "rowid"]. ^The rowid is always available | 2037 ** integer key called the [ROWID | "rowid"]. ^The rowid is always available |
| 1931 ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those | 2038 ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those |
| 1932 ** names are not also used by explicitly declared columns. ^If | 2039 ** names are not also used by explicitly declared columns. ^If |
| (...skipping 31 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1964 ** This function is accessible to SQL statements via the | 2071 ** This function is accessible to SQL statements via the |
| 1965 ** [last_insert_rowid() SQL function]. | 2072 ** [last_insert_rowid() SQL function]. |
| 1966 ** | 2073 ** |
| 1967 ** If a separate thread performs a new [INSERT] on the same | 2074 ** If a separate thread performs a new [INSERT] on the same |
| 1968 ** database connection while the [sqlite3_last_insert_rowid()] | 2075 ** database connection while the [sqlite3_last_insert_rowid()] |
| 1969 ** function is running and thus changes the last insert [rowid], | 2076 ** function is running and thus changes the last insert [rowid], |
| 1970 ** then the value returned by [sqlite3_last_insert_rowid()] is | 2077 ** then the value returned by [sqlite3_last_insert_rowid()] is |
| 1971 ** unpredictable and might not equal either the old or the new | 2078 ** unpredictable and might not equal either the old or the new |
| 1972 ** last insert [rowid]. | 2079 ** last insert [rowid]. |
| 1973 */ | 2080 */ |
| 1974 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_last_insert_rowid(sqlite3*); | 2081 SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); |
| 1975 | 2082 |
| 1976 /* | 2083 /* |
| 1977 ** CAPI3REF: Count The Number Of Rows Modified | 2084 ** CAPI3REF: Count The Number Of Rows Modified |
| 1978 ** METHOD: sqlite3 | 2085 ** METHOD: sqlite3 |
| 1979 ** | 2086 ** |
| 1980 ** ^This function returns the number of rows modified, inserted or | 2087 ** ^This function returns the number of rows modified, inserted or |
| 1981 ** deleted by the most recently completed INSERT, UPDATE or DELETE | 2088 ** deleted by the most recently completed INSERT, UPDATE or DELETE |
| 1982 ** statement on the database connection specified by the only parameter. | 2089 ** statement on the database connection specified by the only parameter. |
| 1983 ** ^Executing any other type of SQL statement does not modify the value | 2090 ** ^Executing any other type of SQL statement does not modify the value |
| 1984 ** returned by this function. | 2091 ** returned by this function. |
| (...skipping 32 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 2017 ** program, the value returned reflects the number of rows modified by the | 2124 ** program, the value returned reflects the number of rows modified by the |
| 2018 ** previous INSERT, UPDATE or DELETE statement within the same trigger. | 2125 ** previous INSERT, UPDATE or DELETE statement within the same trigger. |
| 2019 ** | 2126 ** |
| 2020 ** See also the [sqlite3_total_changes()] interface, the | 2127 ** See also the [sqlite3_total_changes()] interface, the |
| 2021 ** [count_changes pragma], and the [changes() SQL function]. | 2128 ** [count_changes pragma], and the [changes() SQL function]. |
| 2022 ** | 2129 ** |
| 2023 ** If a separate thread makes changes on the same database connection | 2130 ** If a separate thread makes changes on the same database connection |
| 2024 ** while [sqlite3_changes()] is running then the value returned | 2131 ** while [sqlite3_changes()] is running then the value returned |
| 2025 ** is unpredictable and not meaningful. | 2132 ** is unpredictable and not meaningful. |
| 2026 */ | 2133 */ |
| 2027 SQLITE_API int SQLITE_STDCALL sqlite3_changes(sqlite3*); | 2134 SQLITE_API int sqlite3_changes(sqlite3*); |
| 2028 | 2135 |
| 2029 /* | 2136 /* |
| 2030 ** CAPI3REF: Total Number Of Rows Modified | 2137 ** CAPI3REF: Total Number Of Rows Modified |
| 2031 ** METHOD: sqlite3 | 2138 ** METHOD: sqlite3 |
| 2032 ** | 2139 ** |
| 2033 ** ^This function returns the total number of rows inserted, modified or | 2140 ** ^This function returns the total number of rows inserted, modified or |
| 2034 ** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed | 2141 ** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed |
| 2035 ** since the database connection was opened, including those executed as | 2142 ** since the database connection was opened, including those executed as |
| 2036 ** part of trigger programs. ^Executing any other type of SQL statement | 2143 ** part of trigger programs. ^Executing any other type of SQL statement |
| 2037 ** does not affect the value returned by sqlite3_total_changes(). | 2144 ** does not affect the value returned by sqlite3_total_changes(). |
| 2038 ** | 2145 ** |
| 2039 ** ^Changes made as part of [foreign key actions] are included in the | 2146 ** ^Changes made as part of [foreign key actions] are included in the |
| 2040 ** count, but those made as part of REPLACE constraint resolution are | 2147 ** count, but those made as part of REPLACE constraint resolution are |
| 2041 ** not. ^Changes to a view that are intercepted by INSTEAD OF triggers | 2148 ** not. ^Changes to a view that are intercepted by INSTEAD OF triggers |
| 2042 ** are not counted. | 2149 ** are not counted. |
| 2043 ** | 2150 ** |
| 2044 ** See also the [sqlite3_changes()] interface, the | 2151 ** See also the [sqlite3_changes()] interface, the |
| 2045 ** [count_changes pragma], and the [total_changes() SQL function]. | 2152 ** [count_changes pragma], and the [total_changes() SQL function]. |
| 2046 ** | 2153 ** |
| 2047 ** If a separate thread makes changes on the same database connection | 2154 ** If a separate thread makes changes on the same database connection |
| 2048 ** while [sqlite3_total_changes()] is running then the value | 2155 ** while [sqlite3_total_changes()] is running then the value |
| 2049 ** returned is unpredictable and not meaningful. | 2156 ** returned is unpredictable and not meaningful. |
| 2050 */ | 2157 */ |
| 2051 SQLITE_API int SQLITE_STDCALL sqlite3_total_changes(sqlite3*); | 2158 SQLITE_API int sqlite3_total_changes(sqlite3*); |
| 2052 | 2159 |
| 2053 /* | 2160 /* |
| 2054 ** CAPI3REF: Interrupt A Long-Running Query | 2161 ** CAPI3REF: Interrupt A Long-Running Query |
| 2055 ** METHOD: sqlite3 | 2162 ** METHOD: sqlite3 |
| 2056 ** | 2163 ** |
| 2057 ** ^This function causes any pending database operation to abort and | 2164 ** ^This function causes any pending database operation to abort and |
| 2058 ** return at its earliest opportunity. This routine is typically | 2165 ** return at its earliest opportunity. This routine is typically |
| 2059 ** called in response to a user action such as pressing "Cancel" | 2166 ** called in response to a user action such as pressing "Cancel" |
| 2060 ** or Ctrl-C where the user wants a long query operation to halt | 2167 ** or Ctrl-C where the user wants a long query operation to halt |
| 2061 ** immediately. | 2168 ** immediately. |
| (...skipping 19 matching lines...) Expand all Loading... |
| 2081 ** running prior to the sqlite3_interrupt() call. ^New SQL statements | 2188 ** running prior to the sqlite3_interrupt() call. ^New SQL statements |
| 2082 ** that are started after the running statement count reaches zero are | 2189 ** that are started after the running statement count reaches zero are |
| 2083 ** not effected by the sqlite3_interrupt(). | 2190 ** not effected by the sqlite3_interrupt(). |
| 2084 ** ^A call to sqlite3_interrupt(D) that occurs when there are no running | 2191 ** ^A call to sqlite3_interrupt(D) that occurs when there are no running |
| 2085 ** SQL statements is a no-op and has no effect on SQL statements | 2192 ** SQL statements is a no-op and has no effect on SQL statements |
| 2086 ** that are started after the sqlite3_interrupt() call returns. | 2193 ** that are started after the sqlite3_interrupt() call returns. |
| 2087 ** | 2194 ** |
| 2088 ** If the database connection closes while [sqlite3_interrupt()] | 2195 ** If the database connection closes while [sqlite3_interrupt()] |
| 2089 ** is running then bad things will likely happen. | 2196 ** is running then bad things will likely happen. |
| 2090 */ | 2197 */ |
| 2091 SQLITE_API void SQLITE_STDCALL sqlite3_interrupt(sqlite3*); | 2198 SQLITE_API void sqlite3_interrupt(sqlite3*); |
| 2092 | 2199 |
| 2093 /* | 2200 /* |
| 2094 ** CAPI3REF: Determine If An SQL Statement Is Complete | 2201 ** CAPI3REF: Determine If An SQL Statement Is Complete |
| 2095 ** | 2202 ** |
| 2096 ** These routines are useful during command-line input to determine if the | 2203 ** These routines are useful during command-line input to determine if the |
| 2097 ** currently entered text seems to form a complete SQL statement or | 2204 ** currently entered text seems to form a complete SQL statement or |
| 2098 ** if additional input is needed before sending the text into | 2205 ** if additional input is needed before sending the text into |
| 2099 ** SQLite for parsing. ^These routines return 1 if the input string | 2206 ** SQLite for parsing. ^These routines return 1 if the input string |
| 2100 ** appears to be a complete SQL statement. ^A statement is judged to be | 2207 ** appears to be a complete SQL statement. ^A statement is judged to be |
| 2101 ** complete if it ends with a semicolon token and is not a prefix of a | 2208 ** complete if it ends with a semicolon token and is not a prefix of a |
| (...skipping 14 matching lines...) Expand all Loading... |
| 2116 ** automatically by sqlite3_complete16(). If that initialization fails, | 2223 ** automatically by sqlite3_complete16(). If that initialization fails, |
| 2117 ** then the return value from sqlite3_complete16() will be non-zero | 2224 ** then the return value from sqlite3_complete16() will be non-zero |
| 2118 ** regardless of whether or not the input SQL is complete.)^ | 2225 ** regardless of whether or not the input SQL is complete.)^ |
| 2119 ** | 2226 ** |
| 2120 ** The input to [sqlite3_complete()] must be a zero-terminated | 2227 ** The input to [sqlite3_complete()] must be a zero-terminated |
| 2121 ** UTF-8 string. | 2228 ** UTF-8 string. |
| 2122 ** | 2229 ** |
| 2123 ** The input to [sqlite3_complete16()] must be a zero-terminated | 2230 ** The input to [sqlite3_complete16()] must be a zero-terminated |
| 2124 ** UTF-16 string in native byte order. | 2231 ** UTF-16 string in native byte order. |
| 2125 */ | 2232 */ |
| 2126 SQLITE_API int SQLITE_STDCALL sqlite3_complete(const char *sql); | 2233 SQLITE_API int sqlite3_complete(const char *sql); |
| 2127 SQLITE_API int SQLITE_STDCALL sqlite3_complete16(const void *sql); | 2234 SQLITE_API int sqlite3_complete16(const void *sql); |
| 2128 | 2235 |
| 2129 /* | 2236 /* |
| 2130 ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors | 2237 ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors |
| 2131 ** KEYWORDS: {busy-handler callback} {busy handler} | 2238 ** KEYWORDS: {busy-handler callback} {busy handler} |
| 2132 ** METHOD: sqlite3 | 2239 ** METHOD: sqlite3 |
| 2133 ** | 2240 ** |
| 2134 ** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X | 2241 ** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X |
| 2135 ** that might be invoked with argument P whenever | 2242 ** that might be invoked with argument P whenever |
| 2136 ** an attempt is made to access a database table associated with | 2243 ** an attempt is made to access a database table associated with |
| 2137 ** [database connection] D when another thread | 2244 ** [database connection] D when another thread |
| (...skipping 40 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 2178 ** busy handler and thus clear any previously set busy handler. | 2285 ** busy handler and thus clear any previously set busy handler. |
| 2179 ** | 2286 ** |
| 2180 ** The busy callback should not take any actions which modify the | 2287 ** The busy callback should not take any actions which modify the |
| 2181 ** database connection that invoked the busy handler. In other words, | 2288 ** database connection that invoked the busy handler. In other words, |
| 2182 ** the busy handler is not reentrant. Any such actions | 2289 ** the busy handler is not reentrant. Any such actions |
| 2183 ** result in undefined behavior. | 2290 ** result in undefined behavior. |
| 2184 ** | 2291 ** |
| 2185 ** A busy handler must not close the database connection | 2292 ** A busy handler must not close the database connection |
| 2186 ** or [prepared statement] that invoked the busy handler. | 2293 ** or [prepared statement] that invoked the busy handler. |
| 2187 */ | 2294 */ |
| 2188 SQLITE_API int SQLITE_STDCALL sqlite3_busy_handler(sqlite3*, int(*)(void*,int),
void*); | 2295 SQLITE_API int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*); |
| 2189 | 2296 |
| 2190 /* | 2297 /* |
| 2191 ** CAPI3REF: Set A Busy Timeout | 2298 ** CAPI3REF: Set A Busy Timeout |
| 2192 ** METHOD: sqlite3 | 2299 ** METHOD: sqlite3 |
| 2193 ** | 2300 ** |
| 2194 ** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps | 2301 ** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps |
| 2195 ** for a specified amount of time when a table is locked. ^The handler | 2302 ** for a specified amount of time when a table is locked. ^The handler |
| 2196 ** will sleep multiple times until at least "ms" milliseconds of sleeping | 2303 ** will sleep multiple times until at least "ms" milliseconds of sleeping |
| 2197 ** have accumulated. ^After at least "ms" milliseconds of sleeping, | 2304 ** have accumulated. ^After at least "ms" milliseconds of sleeping, |
| 2198 ** the handler returns 0 which causes [sqlite3_step()] to return | 2305 ** the handler returns 0 which causes [sqlite3_step()] to return |
| 2199 ** [SQLITE_BUSY]. | 2306 ** [SQLITE_BUSY]. |
| 2200 ** | 2307 ** |
| 2201 ** ^Calling this routine with an argument less than or equal to zero | 2308 ** ^Calling this routine with an argument less than or equal to zero |
| 2202 ** turns off all busy handlers. | 2309 ** turns off all busy handlers. |
| 2203 ** | 2310 ** |
| 2204 ** ^(There can only be a single busy handler for a particular | 2311 ** ^(There can only be a single busy handler for a particular |
| 2205 ** [database connection] at any given moment. If another busy handler | 2312 ** [database connection] at any given moment. If another busy handler |
| 2206 ** was defined (using [sqlite3_busy_handler()]) prior to calling | 2313 ** was defined (using [sqlite3_busy_handler()]) prior to calling |
| 2207 ** this routine, that other busy handler is cleared.)^ | 2314 ** this routine, that other busy handler is cleared.)^ |
| 2208 ** | 2315 ** |
| 2209 ** See also: [PRAGMA busy_timeout] | 2316 ** See also: [PRAGMA busy_timeout] |
| 2210 */ | 2317 */ |
| 2211 SQLITE_API int SQLITE_STDCALL sqlite3_busy_timeout(sqlite3*, int ms); | 2318 SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms); |
| 2212 | 2319 |
| 2213 /* | 2320 /* |
| 2214 ** CAPI3REF: Convenience Routines For Running Queries | 2321 ** CAPI3REF: Convenience Routines For Running Queries |
| 2215 ** METHOD: sqlite3 | 2322 ** METHOD: sqlite3 |
| 2216 ** | 2323 ** |
| 2217 ** This is a legacy interface that is preserved for backwards compatibility. | 2324 ** This is a legacy interface that is preserved for backwards compatibility. |
| 2218 ** Use of this interface is not recommended. | 2325 ** Use of this interface is not recommended. |
| 2219 ** | 2326 ** |
| 2220 ** Definition: A <b>result table</b> is memory data structure created by the | 2327 ** Definition: A <b>result table</b> is memory data structure created by the |
| 2221 ** [sqlite3_get_table()] interface. A result table records the | 2328 ** [sqlite3_get_table()] interface. A result table records the |
| (...skipping 54 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 2276 ** [sqlite3_free_table()] is able to release the memory properly and safely. | 2383 ** [sqlite3_free_table()] is able to release the memory properly and safely. |
| 2277 ** | 2384 ** |
| 2278 ** The sqlite3_get_table() interface is implemented as a wrapper around | 2385 ** The sqlite3_get_table() interface is implemented as a wrapper around |
| 2279 ** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access | 2386 ** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access |
| 2280 ** to any internal data structures of SQLite. It uses only the public | 2387 ** to any internal data structures of SQLite. It uses only the public |
| 2281 ** interface defined here. As a consequence, errors that occur in the | 2388 ** interface defined here. As a consequence, errors that occur in the |
| 2282 ** wrapper layer outside of the internal [sqlite3_exec()] call are not | 2389 ** wrapper layer outside of the internal [sqlite3_exec()] call are not |
| 2283 ** reflected in subsequent calls to [sqlite3_errcode()] or | 2390 ** reflected in subsequent calls to [sqlite3_errcode()] or |
| 2284 ** [sqlite3_errmsg()]. | 2391 ** [sqlite3_errmsg()]. |
| 2285 */ | 2392 */ |
| 2286 SQLITE_API int SQLITE_STDCALL sqlite3_get_table( | 2393 SQLITE_API int sqlite3_get_table( |
| 2287 sqlite3 *db, /* An open database */ | 2394 sqlite3 *db, /* An open database */ |
| 2288 const char *zSql, /* SQL to be evaluated */ | 2395 const char *zSql, /* SQL to be evaluated */ |
| 2289 char ***pazResult, /* Results of the query */ | 2396 char ***pazResult, /* Results of the query */ |
| 2290 int *pnRow, /* Number of result rows written here */ | 2397 int *pnRow, /* Number of result rows written here */ |
| 2291 int *pnColumn, /* Number of result columns written here */ | 2398 int *pnColumn, /* Number of result columns written here */ |
| 2292 char **pzErrmsg /* Error msg written here */ | 2399 char **pzErrmsg /* Error msg written here */ |
| 2293 ); | 2400 ); |
| 2294 SQLITE_API void SQLITE_STDCALL sqlite3_free_table(char **result); | 2401 SQLITE_API void sqlite3_free_table(char **result); |
| 2295 | 2402 |
| 2296 /* | 2403 /* |
| 2297 ** CAPI3REF: Formatted String Printing Functions | 2404 ** CAPI3REF: Formatted String Printing Functions |
| 2298 ** | 2405 ** |
| 2299 ** These routines are work-alikes of the "printf()" family of functions | 2406 ** These routines are work-alikes of the "printf()" family of functions |
| 2300 ** from the standard C library. | 2407 ** from the standard C library. |
| 2301 ** These routines understand most of the common K&R formatting options, | 2408 ** These routines understand most of the common K&R formatting options, |
| 2302 ** plus some additional non-standard formats, detailed below. | 2409 ** plus some additional non-standard formats, detailed below. |
| 2303 ** Note that some of the more obscure formatting options from recent | 2410 ** Note that some of the more obscure formatting options from recent |
| 2304 ** C-library standards are omitted from this implementation. | 2411 ** C-library standards are omitted from this implementation. |
| (...skipping 85 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 2390 ** ^(The "%w" formatting option is like "%q" except that it expects to | 2497 ** ^(The "%w" formatting option is like "%q" except that it expects to |
| 2391 ** be contained within double-quotes instead of single quotes, and it | 2498 ** be contained within double-quotes instead of single quotes, and it |
| 2392 ** escapes the double-quote character instead of the single-quote | 2499 ** escapes the double-quote character instead of the single-quote |
| 2393 ** character.)^ The "%w" formatting option is intended for safely inserting | 2500 ** character.)^ The "%w" formatting option is intended for safely inserting |
| 2394 ** table and column names into a constructed SQL statement. | 2501 ** table and column names into a constructed SQL statement. |
| 2395 ** | 2502 ** |
| 2396 ** ^(The "%z" formatting option works like "%s" but with the | 2503 ** ^(The "%z" formatting option works like "%s" but with the |
| 2397 ** addition that after the string has been read and copied into | 2504 ** addition that after the string has been read and copied into |
| 2398 ** the result, [sqlite3_free()] is called on the input string.)^ | 2505 ** the result, [sqlite3_free()] is called on the input string.)^ |
| 2399 */ | 2506 */ |
| 2400 SQLITE_API char *SQLITE_CDECL sqlite3_mprintf(const char*,...); | 2507 SQLITE_API char *sqlite3_mprintf(const char*,...); |
| 2401 SQLITE_API char *SQLITE_STDCALL sqlite3_vmprintf(const char*, va_list); | 2508 SQLITE_API char *sqlite3_vmprintf(const char*, va_list); |
| 2402 SQLITE_API char *SQLITE_CDECL sqlite3_snprintf(int,char*,const char*, ...); | 2509 SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...); |
| 2403 SQLITE_API char *SQLITE_STDCALL sqlite3_vsnprintf(int,char*,const char*, va_list
); | 2510 SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list); |
| 2404 | 2511 |
| 2405 /* | 2512 /* |
| 2406 ** CAPI3REF: Memory Allocation Subsystem | 2513 ** CAPI3REF: Memory Allocation Subsystem |
| 2407 ** | 2514 ** |
| 2408 ** The SQLite core uses these three routines for all of its own | 2515 ** The SQLite core uses these three routines for all of its own |
| 2409 ** internal memory allocation needs. "Core" in the previous sentence | 2516 ** internal memory allocation needs. "Core" in the previous sentence |
| 2410 ** does not include operating-system specific VFS implementation. The | 2517 ** does not include operating-system specific VFS implementation. The |
| 2411 ** Windows VFS uses native malloc() and free() for some operations. | 2518 ** Windows VFS uses native malloc() and free() for some operations. |
| 2412 ** | 2519 ** |
| 2413 ** ^The sqlite3_malloc() routine returns a pointer to a block | 2520 ** ^The sqlite3_malloc() routine returns a pointer to a block |
| (...skipping 69 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 2483 ** | 2590 ** |
| 2484 ** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()] | 2591 ** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()] |
| 2485 ** must be either NULL or else pointers obtained from a prior | 2592 ** must be either NULL or else pointers obtained from a prior |
| 2486 ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have | 2593 ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have |
| 2487 ** not yet been released. | 2594 ** not yet been released. |
| 2488 ** | 2595 ** |
| 2489 ** The application must not read or write any part of | 2596 ** The application must not read or write any part of |
| 2490 ** a block of memory after it has been released using | 2597 ** a block of memory after it has been released using |
| 2491 ** [sqlite3_free()] or [sqlite3_realloc()]. | 2598 ** [sqlite3_free()] or [sqlite3_realloc()]. |
| 2492 */ | 2599 */ |
| 2493 SQLITE_API void *SQLITE_STDCALL sqlite3_malloc(int); | 2600 SQLITE_API void *sqlite3_malloc(int); |
| 2494 SQLITE_API void *SQLITE_STDCALL sqlite3_malloc64(sqlite3_uint64); | 2601 SQLITE_API void *sqlite3_malloc64(sqlite3_uint64); |
| 2495 SQLITE_API void *SQLITE_STDCALL sqlite3_realloc(void*, int); | 2602 SQLITE_API void *sqlite3_realloc(void*, int); |
| 2496 SQLITE_API void *SQLITE_STDCALL sqlite3_realloc64(void*, sqlite3_uint64); | 2603 SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64); |
| 2497 SQLITE_API void SQLITE_STDCALL sqlite3_free(void*); | 2604 SQLITE_API void sqlite3_free(void*); |
| 2498 SQLITE_API sqlite3_uint64 SQLITE_STDCALL sqlite3_msize(void*); | 2605 SQLITE_API sqlite3_uint64 sqlite3_msize(void*); |
| 2499 | 2606 |
| 2500 /* | 2607 /* |
| 2501 ** CAPI3REF: Memory Allocator Statistics | 2608 ** CAPI3REF: Memory Allocator Statistics |
| 2502 ** | 2609 ** |
| 2503 ** SQLite provides these two interfaces for reporting on the status | 2610 ** SQLite provides these two interfaces for reporting on the status |
| 2504 ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()] | 2611 ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()] |
| 2505 ** routines, which form the built-in memory allocation subsystem. | 2612 ** routines, which form the built-in memory allocation subsystem. |
| 2506 ** | 2613 ** |
| 2507 ** ^The [sqlite3_memory_used()] routine returns the number of bytes | 2614 ** ^The [sqlite3_memory_used()] routine returns the number of bytes |
| 2508 ** of memory currently outstanding (malloced but not freed). | 2615 ** of memory currently outstanding (malloced but not freed). |
| 2509 ** ^The [sqlite3_memory_highwater()] routine returns the maximum | 2616 ** ^The [sqlite3_memory_highwater()] routine returns the maximum |
| 2510 ** value of [sqlite3_memory_used()] since the high-water mark | 2617 ** value of [sqlite3_memory_used()] since the high-water mark |
| 2511 ** was last reset. ^The values returned by [sqlite3_memory_used()] and | 2618 ** was last reset. ^The values returned by [sqlite3_memory_used()] and |
| 2512 ** [sqlite3_memory_highwater()] include any overhead | 2619 ** [sqlite3_memory_highwater()] include any overhead |
| 2513 ** added by SQLite in its implementation of [sqlite3_malloc()], | 2620 ** added by SQLite in its implementation of [sqlite3_malloc()], |
| 2514 ** but not overhead added by the any underlying system library | 2621 ** but not overhead added by the any underlying system library |
| 2515 ** routines that [sqlite3_malloc()] may call. | 2622 ** routines that [sqlite3_malloc()] may call. |
| 2516 ** | 2623 ** |
| 2517 ** ^The memory high-water mark is reset to the current value of | 2624 ** ^The memory high-water mark is reset to the current value of |
| 2518 ** [sqlite3_memory_used()] if and only if the parameter to | 2625 ** [sqlite3_memory_used()] if and only if the parameter to |
| 2519 ** [sqlite3_memory_highwater()] is true. ^The value returned | 2626 ** [sqlite3_memory_highwater()] is true. ^The value returned |
| 2520 ** by [sqlite3_memory_highwater(1)] is the high-water mark | 2627 ** by [sqlite3_memory_highwater(1)] is the high-water mark |
| 2521 ** prior to the reset. | 2628 ** prior to the reset. |
| 2522 */ | 2629 */ |
| 2523 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_memory_used(void); | 2630 SQLITE_API sqlite3_int64 sqlite3_memory_used(void); |
| 2524 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_memory_highwater(int resetFlag); | 2631 SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag); |
| 2525 | 2632 |
| 2526 /* | 2633 /* |
| 2527 ** CAPI3REF: Pseudo-Random Number Generator | 2634 ** CAPI3REF: Pseudo-Random Number Generator |
| 2528 ** | 2635 ** |
| 2529 ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to | 2636 ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to |
| 2530 ** select random [ROWID | ROWIDs] when inserting new records into a table that | 2637 ** select random [ROWID | ROWIDs] when inserting new records into a table that |
| 2531 ** already uses the largest possible [ROWID]. The PRNG is also used for | 2638 ** already uses the largest possible [ROWID]. The PRNG is also used for |
| 2532 ** the build-in random() and randomblob() SQL functions. This interface allows | 2639 ** the build-in random() and randomblob() SQL functions. This interface allows |
| 2533 ** applications to access the same PRNG for other purposes. | 2640 ** applications to access the same PRNG for other purposes. |
| 2534 ** | 2641 ** |
| 2535 ** ^A call to this routine stores N bytes of randomness into buffer P. | 2642 ** ^A call to this routine stores N bytes of randomness into buffer P. |
| 2536 ** ^The P parameter can be a NULL pointer. | 2643 ** ^The P parameter can be a NULL pointer. |
| 2537 ** | 2644 ** |
| 2538 ** ^If this routine has not been previously called or if the previous | 2645 ** ^If this routine has not been previously called or if the previous |
| 2539 ** call had N less than one or a NULL pointer for P, then the PRNG is | 2646 ** call had N less than one or a NULL pointer for P, then the PRNG is |
| 2540 ** seeded using randomness obtained from the xRandomness method of | 2647 ** seeded using randomness obtained from the xRandomness method of |
| 2541 ** the default [sqlite3_vfs] object. | 2648 ** the default [sqlite3_vfs] object. |
| 2542 ** ^If the previous call to this routine had an N of 1 or more and a | 2649 ** ^If the previous call to this routine had an N of 1 or more and a |
| 2543 ** non-NULL P then the pseudo-randomness is generated | 2650 ** non-NULL P then the pseudo-randomness is generated |
| 2544 ** internally and without recourse to the [sqlite3_vfs] xRandomness | 2651 ** internally and without recourse to the [sqlite3_vfs] xRandomness |
| 2545 ** method. | 2652 ** method. |
| 2546 */ | 2653 */ |
| 2547 SQLITE_API void SQLITE_STDCALL sqlite3_randomness(int N, void *P); | 2654 SQLITE_API void sqlite3_randomness(int N, void *P); |
| 2548 | 2655 |
| 2549 /* | 2656 /* |
| 2550 ** CAPI3REF: Compile-Time Authorization Callbacks | 2657 ** CAPI3REF: Compile-Time Authorization Callbacks |
| 2551 ** METHOD: sqlite3 | 2658 ** METHOD: sqlite3 |
| 2552 ** | 2659 ** |
| 2553 ** ^This routine registers an authorizer callback with a particular | 2660 ** ^This routine registers an authorizer callback with a particular |
| 2554 ** [database connection], supplied in the first argument. | 2661 ** [database connection], supplied in the first argument. |
| 2555 ** ^The authorizer callback is invoked as SQL statements are being compiled | 2662 ** ^The authorizer callback is invoked as SQL statements are being compiled |
| 2556 ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()], | 2663 ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()], |
| 2557 ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. ^At various | 2664 ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. ^At various |
| (...skipping 62 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 2620 ** statement might be re-prepared during [sqlite3_step()] due to a | 2727 ** statement might be re-prepared during [sqlite3_step()] due to a |
| 2621 ** schema change. Hence, the application should ensure that the | 2728 ** schema change. Hence, the application should ensure that the |
| 2622 ** correct authorizer callback remains in place during the [sqlite3_step()]. | 2729 ** correct authorizer callback remains in place during the [sqlite3_step()]. |
| 2623 ** | 2730 ** |
| 2624 ** ^Note that the authorizer callback is invoked only during | 2731 ** ^Note that the authorizer callback is invoked only during |
| 2625 ** [sqlite3_prepare()] or its variants. Authorization is not | 2732 ** [sqlite3_prepare()] or its variants. Authorization is not |
| 2626 ** performed during statement evaluation in [sqlite3_step()], unless | 2733 ** performed during statement evaluation in [sqlite3_step()], unless |
| 2627 ** as stated in the previous paragraph, sqlite3_step() invokes | 2734 ** as stated in the previous paragraph, sqlite3_step() invokes |
| 2628 ** sqlite3_prepare_v2() to reprepare a statement after a schema change. | 2735 ** sqlite3_prepare_v2() to reprepare a statement after a schema change. |
| 2629 */ | 2736 */ |
| 2630 SQLITE_API int SQLITE_STDCALL sqlite3_set_authorizer( | 2737 SQLITE_API int sqlite3_set_authorizer( |
| 2631 sqlite3*, | 2738 sqlite3*, |
| 2632 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), | 2739 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), |
| 2633 void *pUserData | 2740 void *pUserData |
| 2634 ); | 2741 ); |
| 2635 | 2742 |
| 2636 /* | 2743 /* |
| 2637 ** CAPI3REF: Authorizer Return Codes | 2744 ** CAPI3REF: Authorizer Return Codes |
| 2638 ** | 2745 ** |
| 2639 ** The [sqlite3_set_authorizer | authorizer callback function] must | 2746 ** The [sqlite3_set_authorizer | authorizer callback function] must |
| 2640 ** return either [SQLITE_OK] or one of these two constants in order | 2747 ** return either [SQLITE_OK] or one of these two constants in order |
| (...skipping 59 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 2700 #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ | 2807 #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ |
| 2701 #define SQLITE_FUNCTION 31 /* NULL Function Name */ | 2808 #define SQLITE_FUNCTION 31 /* NULL Function Name */ |
| 2702 #define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */ | 2809 #define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */ |
| 2703 #define SQLITE_COPY 0 /* No longer used */ | 2810 #define SQLITE_COPY 0 /* No longer used */ |
| 2704 #define SQLITE_RECURSIVE 33 /* NULL NULL */ | 2811 #define SQLITE_RECURSIVE 33 /* NULL NULL */ |
| 2705 | 2812 |
| 2706 /* | 2813 /* |
| 2707 ** CAPI3REF: Tracing And Profiling Functions | 2814 ** CAPI3REF: Tracing And Profiling Functions |
| 2708 ** METHOD: sqlite3 | 2815 ** METHOD: sqlite3 |
| 2709 ** | 2816 ** |
| 2817 ** These routines are deprecated. Use the [sqlite3_trace_v2()] interface |
| 2818 ** instead of the routines described here. |
| 2819 ** |
| 2710 ** These routines register callback functions that can be used for | 2820 ** These routines register callback functions that can be used for |
| 2711 ** tracing and profiling the execution of SQL statements. | 2821 ** tracing and profiling the execution of SQL statements. |
| 2712 ** | 2822 ** |
| 2713 ** ^The callback function registered by sqlite3_trace() is invoked at | 2823 ** ^The callback function registered by sqlite3_trace() is invoked at |
| 2714 ** various times when an SQL statement is being run by [sqlite3_step()]. | 2824 ** various times when an SQL statement is being run by [sqlite3_step()]. |
| 2715 ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the | 2825 ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the |
| 2716 ** SQL statement text as the statement first begins executing. | 2826 ** SQL statement text as the statement first begins executing. |
| 2717 ** ^(Additional sqlite3_trace() callbacks might occur | 2827 ** ^(Additional sqlite3_trace() callbacks might occur |
| 2718 ** as each triggered subprogram is entered. The callbacks for triggers | 2828 ** as each triggered subprogram is entered. The callbacks for triggers |
| 2719 ** contain a UTF-8 SQL comment that identifies the trigger.)^ | 2829 ** contain a UTF-8 SQL comment that identifies the trigger.)^ |
| 2720 ** | 2830 ** |
| 2721 ** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit | 2831 ** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit |
| 2722 ** the length of [bound parameter] expansion in the output of sqlite3_trace(). | 2832 ** the length of [bound parameter] expansion in the output of sqlite3_trace(). |
| 2723 ** | 2833 ** |
| 2724 ** ^The callback function registered by sqlite3_profile() is invoked | 2834 ** ^The callback function registered by sqlite3_profile() is invoked |
| 2725 ** as each SQL statement finishes. ^The profile callback contains | 2835 ** as each SQL statement finishes. ^The profile callback contains |
| 2726 ** the original statement text and an estimate of wall-clock time | 2836 ** the original statement text and an estimate of wall-clock time |
| 2727 ** of how long that statement took to run. ^The profile callback | 2837 ** of how long that statement took to run. ^The profile callback |
| 2728 ** time is in units of nanoseconds, however the current implementation | 2838 ** time is in units of nanoseconds, however the current implementation |
| 2729 ** is only capable of millisecond resolution so the six least significant | 2839 ** is only capable of millisecond resolution so the six least significant |
| 2730 ** digits in the time are meaningless. Future versions of SQLite | 2840 ** digits in the time are meaningless. Future versions of SQLite |
| 2731 ** might provide greater resolution on the profiler callback. The | 2841 ** might provide greater resolution on the profiler callback. The |
| 2732 ** sqlite3_profile() function is considered experimental and is | 2842 ** sqlite3_profile() function is considered experimental and is |
| 2733 ** subject to change in future versions of SQLite. | 2843 ** subject to change in future versions of SQLite. |
| 2734 */ | 2844 */ |
| 2735 SQLITE_API void *SQLITE_STDCALL sqlite3_trace(sqlite3*, void(*xTrace)(void*,cons
t char*), void*); | 2845 SQLITE_API SQLITE_DEPRECATED void *sqlite3_trace(sqlite3*, |
| 2736 SQLITE_API SQLITE_EXPERIMENTAL void *SQLITE_STDCALL sqlite3_profile(sqlite3*, | 2846 void(*xTrace)(void*,const char*), void*); |
| 2847 SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*, |
| 2737 void(*xProfile)(void*,const char*,sqlite3_uint64), void*); | 2848 void(*xProfile)(void*,const char*,sqlite3_uint64), void*); |
| 2738 | 2849 |
| 2739 /* | 2850 /* |
| 2851 ** CAPI3REF: SQL Trace Event Codes |
| 2852 ** KEYWORDS: SQLITE_TRACE |
| 2853 ** |
| 2854 ** These constants identify classes of events that can be monitored |
| 2855 ** using the [sqlite3_trace_v2()] tracing logic. The third argument |
| 2856 ** to [sqlite3_trace_v2()] is an OR-ed combination of one or more of |
| 2857 ** the following constants. ^The first argument to the trace callback |
| 2858 ** is one of the following constants. |
| 2859 ** |
| 2860 ** New tracing constants may be added in future releases. |
| 2861 ** |
| 2862 ** ^A trace callback has four arguments: xCallback(T,C,P,X). |
| 2863 ** ^The T argument is one of the integer type codes above. |
| 2864 ** ^The C argument is a copy of the context pointer passed in as the |
| 2865 ** fourth argument to [sqlite3_trace_v2()]. |
| 2866 ** The P and X arguments are pointers whose meanings depend on T. |
| 2867 ** |
| 2868 ** <dl> |
| 2869 ** [[SQLITE_TRACE_STMT]] <dt>SQLITE_TRACE_STMT</dt> |
| 2870 ** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement |
| 2871 ** first begins running and possibly at other times during the |
| 2872 ** execution of the prepared statement, such as at the start of each |
| 2873 ** trigger subprogram. ^The P argument is a pointer to the |
| 2874 ** [prepared statement]. ^The X argument is a pointer to a string which |
| 2875 ** is the unexpanded SQL text of the prepared statement or an SQL comment |
| 2876 ** that indicates the invocation of a trigger. ^The callback can compute |
| 2877 ** the same text that would have been returned by the legacy [sqlite3_trace()] |
| 2878 ** interface by using the X argument when X begins with "--" and invoking |
| 2879 ** [sqlite3_expanded_sql(P)] otherwise. |
| 2880 ** |
| 2881 ** [[SQLITE_TRACE_PROFILE]] <dt>SQLITE_TRACE_PROFILE</dt> |
| 2882 ** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same |
| 2883 ** information as is provided by the [sqlite3_profile()] callback. |
| 2884 ** ^The P argument is a pointer to the [prepared statement] and the |
| 2885 ** X argument points to a 64-bit integer which is the estimated of |
| 2886 ** the number of nanosecond that the prepared statement took to run. |
| 2887 ** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes. |
| 2888 ** |
| 2889 ** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt> |
| 2890 ** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared |
| 2891 ** statement generates a single row of result. |
| 2892 ** ^The P argument is a pointer to the [prepared statement] and the |
| 2893 ** X argument is unused. |
| 2894 ** |
| 2895 ** [[SQLITE_TRACE_CLOSE]] <dt>SQLITE_TRACE_CLOSE</dt> |
| 2896 ** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database |
| 2897 ** connection closes. |
| 2898 ** ^The P argument is a pointer to the [database connection] object |
| 2899 ** and the X argument is unused. |
| 2900 ** </dl> |
| 2901 */ |
| 2902 #define SQLITE_TRACE_STMT 0x01 |
| 2903 #define SQLITE_TRACE_PROFILE 0x02 |
| 2904 #define SQLITE_TRACE_ROW 0x04 |
| 2905 #define SQLITE_TRACE_CLOSE 0x08 |
| 2906 |
| 2907 /* |
| 2908 ** CAPI3REF: SQL Trace Hook |
| 2909 ** METHOD: sqlite3 |
| 2910 ** |
| 2911 ** ^The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback |
| 2912 ** function X against [database connection] D, using property mask M |
| 2913 ** and context pointer P. ^If the X callback is |
| 2914 ** NULL or if the M mask is zero, then tracing is disabled. The |
| 2915 ** M argument should be the bitwise OR-ed combination of |
| 2916 ** zero or more [SQLITE_TRACE] constants. |
| 2917 ** |
| 2918 ** ^Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides |
| 2919 ** (cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2(). |
| 2920 ** |
| 2921 ** ^The X callback is invoked whenever any of the events identified by |
| 2922 ** mask M occur. ^The integer return value from the callback is currently |
| 2923 ** ignored, though this may change in future releases. Callback |
| 2924 ** implementations should return zero to ensure future compatibility. |
| 2925 ** |
| 2926 ** ^A trace callback is invoked with four arguments: callback(T,C,P,X). |
| 2927 ** ^The T argument is one of the [SQLITE_TRACE] |
| 2928 ** constants to indicate why the callback was invoked. |
| 2929 ** ^The C argument is a copy of the context pointer. |
| 2930 ** The P and X arguments are pointers whose meanings depend on T. |
| 2931 ** |
| 2932 ** The sqlite3_trace_v2() interface is intended to replace the legacy |
| 2933 ** interfaces [sqlite3_trace()] and [sqlite3_profile()], both of which |
| 2934 ** are deprecated. |
| 2935 */ |
| 2936 SQLITE_API int sqlite3_trace_v2( |
| 2937 sqlite3*, |
| 2938 unsigned uMask, |
| 2939 int(*xCallback)(unsigned,void*,void*,void*), |
| 2940 void *pCtx |
| 2941 ); |
| 2942 |
| 2943 /* |
| 2740 ** CAPI3REF: Query Progress Callbacks | 2944 ** CAPI3REF: Query Progress Callbacks |
| 2741 ** METHOD: sqlite3 | 2945 ** METHOD: sqlite3 |
| 2742 ** | 2946 ** |
| 2743 ** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback | 2947 ** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback |
| 2744 ** function X to be invoked periodically during long running calls to | 2948 ** function X to be invoked periodically during long running calls to |
| 2745 ** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for | 2949 ** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for |
| 2746 ** database connection D. An example use for this | 2950 ** database connection D. An example use for this |
| 2747 ** interface is to keep a GUI updated during a large query. | 2951 ** interface is to keep a GUI updated during a large query. |
| 2748 ** | 2952 ** |
| 2749 ** ^The parameter P is passed through as the only parameter to the | 2953 ** ^The parameter P is passed through as the only parameter to the |
| (...skipping 11 matching lines...) Expand all Loading... |
| 2761 ** ^If the progress callback returns non-zero, the operation is | 2965 ** ^If the progress callback returns non-zero, the operation is |
| 2762 ** interrupted. This feature can be used to implement a | 2966 ** interrupted. This feature can be used to implement a |
| 2763 ** "Cancel" button on a GUI progress dialog box. | 2967 ** "Cancel" button on a GUI progress dialog box. |
| 2764 ** | 2968 ** |
| 2765 ** The progress handler callback must not do anything that will modify | 2969 ** The progress handler callback must not do anything that will modify |
| 2766 ** the database connection that invoked the progress handler. | 2970 ** the database connection that invoked the progress handler. |
| 2767 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their | 2971 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their |
| 2768 ** database connections for the meaning of "modify" in this paragraph. | 2972 ** database connections for the meaning of "modify" in this paragraph. |
| 2769 ** | 2973 ** |
| 2770 */ | 2974 */ |
| 2771 SQLITE_API void SQLITE_STDCALL sqlite3_progress_handler(sqlite3*, int, int(*)(vo
id*), void*); | 2975 SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); |
| 2772 | 2976 |
| 2773 /* | 2977 /* |
| 2774 ** CAPI3REF: Opening A New Database Connection | 2978 ** CAPI3REF: Opening A New Database Connection |
| 2775 ** CONSTRUCTOR: sqlite3 | 2979 ** CONSTRUCTOR: sqlite3 |
| 2776 ** | 2980 ** |
| 2777 ** ^These routines open an SQLite database file as specified by the | 2981 ** ^These routines open an SQLite database file as specified by the |
| 2778 ** filename argument. ^The filename argument is interpreted as UTF-8 for | 2982 ** filename argument. ^The filename argument is interpreted as UTF-8 for |
| 2779 ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte | 2983 ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte |
| 2780 ** order for sqlite3_open16(). ^(A [database connection] handle is usually | 2984 ** order for sqlite3_open16(). ^(A [database connection] handle is usually |
| 2781 ** returned in *ppDb, even if an error occurs. The only exception is that | 2985 ** returned in *ppDb, even if an error occurs. The only exception is that |
| (...skipping 208 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 2990 ** codepage is currently defined. Filenames containing international | 3194 ** codepage is currently defined. Filenames containing international |
| 2991 ** characters must be converted to UTF-8 prior to passing them into | 3195 ** characters must be converted to UTF-8 prior to passing them into |
| 2992 ** sqlite3_open() or sqlite3_open_v2(). | 3196 ** sqlite3_open() or sqlite3_open_v2(). |
| 2993 ** | 3197 ** |
| 2994 ** <b>Note to Windows Runtime users:</b> The temporary directory must be set | 3198 ** <b>Note to Windows Runtime users:</b> The temporary directory must be set |
| 2995 ** prior to calling sqlite3_open() or sqlite3_open_v2(). Otherwise, various | 3199 ** prior to calling sqlite3_open() or sqlite3_open_v2(). Otherwise, various |
| 2996 ** features that require the use of temporary files may fail. | 3200 ** features that require the use of temporary files may fail. |
| 2997 ** | 3201 ** |
| 2998 ** See also: [sqlite3_temp_directory] | 3202 ** See also: [sqlite3_temp_directory] |
| 2999 */ | 3203 */ |
| 3000 SQLITE_API int SQLITE_STDCALL sqlite3_open( | 3204 SQLITE_API int sqlite3_open( |
| 3001 const char *filename, /* Database filename (UTF-8) */ | 3205 const char *filename, /* Database filename (UTF-8) */ |
| 3002 sqlite3 **ppDb /* OUT: SQLite db handle */ | 3206 sqlite3 **ppDb /* OUT: SQLite db handle */ |
| 3003 ); | 3207 ); |
| 3004 SQLITE_API int SQLITE_STDCALL sqlite3_open16( | 3208 SQLITE_API int sqlite3_open16( |
| 3005 const void *filename, /* Database filename (UTF-16) */ | 3209 const void *filename, /* Database filename (UTF-16) */ |
| 3006 sqlite3 **ppDb /* OUT: SQLite db handle */ | 3210 sqlite3 **ppDb /* OUT: SQLite db handle */ |
| 3007 ); | 3211 ); |
| 3008 SQLITE_API int SQLITE_STDCALL sqlite3_open_v2( | 3212 SQLITE_API int sqlite3_open_v2( |
| 3009 const char *filename, /* Database filename (UTF-8) */ | 3213 const char *filename, /* Database filename (UTF-8) */ |
| 3010 sqlite3 **ppDb, /* OUT: SQLite db handle */ | 3214 sqlite3 **ppDb, /* OUT: SQLite db handle */ |
| 3011 int flags, /* Flags */ | 3215 int flags, /* Flags */ |
| 3012 const char *zVfs /* Name of VFS module to use */ | 3216 const char *zVfs /* Name of VFS module to use */ |
| 3013 ); | 3217 ); |
| 3014 | 3218 |
| 3015 /* | 3219 /* |
| 3016 ** CAPI3REF: Obtain Values For URI Parameters | 3220 ** CAPI3REF: Obtain Values For URI Parameters |
| 3017 ** | 3221 ** |
| 3018 ** These are utility routines, useful to VFS implementations, that check | 3222 ** These are utility routines, useful to VFS implementations, that check |
| (...skipping 25 matching lines...) Expand all Loading... |
| 3044 ** 64-bit signed integer and returns that integer, or D if P does not | 3248 ** 64-bit signed integer and returns that integer, or D if P does not |
| 3045 ** exist. If the value of P is something other than an integer, then | 3249 ** exist. If the value of P is something other than an integer, then |
| 3046 ** zero is returned. | 3250 ** zero is returned. |
| 3047 ** | 3251 ** |
| 3048 ** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and | 3252 ** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and |
| 3049 ** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and | 3253 ** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and |
| 3050 ** is not a database file pathname pointer that SQLite passed into the xOpen | 3254 ** is not a database file pathname pointer that SQLite passed into the xOpen |
| 3051 ** VFS method, then the behavior of this routine is undefined and probably | 3255 ** VFS method, then the behavior of this routine is undefined and probably |
| 3052 ** undesirable. | 3256 ** undesirable. |
| 3053 */ | 3257 */ |
| 3054 SQLITE_API const char *SQLITE_STDCALL sqlite3_uri_parameter(const char *zFilenam
e, const char *zParam); | 3258 SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *
zParam); |
| 3055 SQLITE_API int SQLITE_STDCALL sqlite3_uri_boolean(const char *zFile, const char
*zParam, int bDefault); | 3259 SQLITE_API int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bD
efault); |
| 3056 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_uri_int64(const char*, const cha
r*, sqlite3_int64); | 3260 SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int
64); |
| 3057 | 3261 |
| 3058 | 3262 |
| 3059 /* | 3263 /* |
| 3060 ** CAPI3REF: Error Codes And Messages | 3264 ** CAPI3REF: Error Codes And Messages |
| 3061 ** METHOD: sqlite3 | 3265 ** METHOD: sqlite3 |
| 3062 ** | 3266 ** |
| 3063 ** ^If the most recent sqlite3_* API call associated with | 3267 ** ^If the most recent sqlite3_* API call associated with |
| 3064 ** [database connection] D failed, then the sqlite3_errcode(D) interface | 3268 ** [database connection] D failed, then the sqlite3_errcode(D) interface |
| 3065 ** returns the numeric [result code] or [extended result code] for that | 3269 ** returns the numeric [result code] or [extended result code] for that |
| 3066 ** API call. | 3270 ** API call. |
| (...skipping 23 matching lines...) Expand all Loading... |
| 3090 ** interfaces always report the most recent result. To avoid | 3294 ** interfaces always report the most recent result. To avoid |
| 3091 ** this, each thread can obtain exclusive use of the [database connection] D | 3295 ** this, each thread can obtain exclusive use of the [database connection] D |
| 3092 ** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning | 3296 ** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning |
| 3093 ** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after | 3297 ** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after |
| 3094 ** all calls to the interfaces listed here are completed. | 3298 ** all calls to the interfaces listed here are completed. |
| 3095 ** | 3299 ** |
| 3096 ** If an interface fails with SQLITE_MISUSE, that means the interface | 3300 ** If an interface fails with SQLITE_MISUSE, that means the interface |
| 3097 ** was invoked incorrectly by the application. In that case, the | 3301 ** was invoked incorrectly by the application. In that case, the |
| 3098 ** error code and message may or may not be set. | 3302 ** error code and message may or may not be set. |
| 3099 */ | 3303 */ |
| 3100 SQLITE_API int SQLITE_STDCALL sqlite3_errcode(sqlite3 *db); | 3304 SQLITE_API int sqlite3_errcode(sqlite3 *db); |
| 3101 SQLITE_API int SQLITE_STDCALL sqlite3_extended_errcode(sqlite3 *db); | 3305 SQLITE_API int sqlite3_extended_errcode(sqlite3 *db); |
| 3102 SQLITE_API const char *SQLITE_STDCALL sqlite3_errmsg(sqlite3*); | 3306 SQLITE_API const char *sqlite3_errmsg(sqlite3*); |
| 3103 SQLITE_API const void *SQLITE_STDCALL sqlite3_errmsg16(sqlite3*); | 3307 SQLITE_API const void *sqlite3_errmsg16(sqlite3*); |
| 3104 SQLITE_API const char *SQLITE_STDCALL sqlite3_errstr(int); | 3308 SQLITE_API const char *sqlite3_errstr(int); |
| 3105 | 3309 |
| 3106 /* | 3310 /* |
| 3107 ** CAPI3REF: Prepared Statement Object | 3311 ** CAPI3REF: Prepared Statement Object |
| 3108 ** KEYWORDS: {prepared statement} {prepared statements} | 3312 ** KEYWORDS: {prepared statement} {prepared statements} |
| 3109 ** | 3313 ** |
| 3110 ** An instance of this object represents a single SQL statement that | 3314 ** An instance of this object represents a single SQL statement that |
| 3111 ** has been compiled into binary form and is ready to be evaluated. | 3315 ** has been compiled into binary form and is ready to be evaluated. |
| 3112 ** | 3316 ** |
| 3113 ** Think of each SQL statement as a separate computer program. The | 3317 ** Think of each SQL statement as a separate computer program. The |
| 3114 ** original SQL text is source code. A prepared statement object | 3318 ** original SQL text is source code. A prepared statement object |
| (...skipping 47 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 3162 ** off the Internet. The internal databases can be given the | 3366 ** off the Internet. The internal databases can be given the |
| 3163 ** large, default limits. Databases managed by external sources can | 3367 ** large, default limits. Databases managed by external sources can |
| 3164 ** be given much smaller limits designed to prevent a denial of service | 3368 ** be given much smaller limits designed to prevent a denial of service |
| 3165 ** attack. Developers might also want to use the [sqlite3_set_authorizer()] | 3369 ** attack. Developers might also want to use the [sqlite3_set_authorizer()] |
| 3166 ** interface to further control untrusted SQL. The size of the database | 3370 ** interface to further control untrusted SQL. The size of the database |
| 3167 ** created by an untrusted script can be contained using the | 3371 ** created by an untrusted script can be contained using the |
| 3168 ** [max_page_count] [PRAGMA]. | 3372 ** [max_page_count] [PRAGMA]. |
| 3169 ** | 3373 ** |
| 3170 ** New run-time limit categories may be added in future releases. | 3374 ** New run-time limit categories may be added in future releases. |
| 3171 */ | 3375 */ |
| 3172 SQLITE_API int SQLITE_STDCALL sqlite3_limit(sqlite3*, int id, int newVal); | 3376 SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal); |
| 3173 | 3377 |
| 3174 /* | 3378 /* |
| 3175 ** CAPI3REF: Run-Time Limit Categories | 3379 ** CAPI3REF: Run-Time Limit Categories |
| 3176 ** KEYWORDS: {limit category} {*limit categories} | 3380 ** KEYWORDS: {limit category} {*limit categories} |
| 3177 ** | 3381 ** |
| 3178 ** These constants define various performance limits | 3382 ** These constants define various performance limits |
| 3179 ** that can be lowered at run-time using [sqlite3_limit()]. | 3383 ** that can be lowered at run-time using [sqlite3_limit()]. |
| 3180 ** The synopsis of the meanings of the various limits is shown below. | 3384 ** The synopsis of the meanings of the various limits is shown below. |
| 3181 ** Additional information is available at [limits | Limits in SQLite]. | 3385 ** Additional information is available at [limits | Limits in SQLite]. |
| 3182 ** | 3386 ** |
| (...skipping 131 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 3314 ** then the statement will be automatically recompiled, as if there had been | 3518 ** then the statement will be automatically recompiled, as if there had been |
| 3315 ** a schema change, on the first [sqlite3_step()] call following any change | 3519 ** a schema change, on the first [sqlite3_step()] call following any change |
| 3316 ** to the [sqlite3_bind_text | bindings] of that [parameter]. | 3520 ** to the [sqlite3_bind_text | bindings] of that [parameter]. |
| 3317 ** ^The specific value of WHERE-clause [parameter] might influence the | 3521 ** ^The specific value of WHERE-clause [parameter] might influence the |
| 3318 ** choice of query plan if the parameter is the left-hand side of a [LIKE] | 3522 ** choice of query plan if the parameter is the left-hand side of a [LIKE] |
| 3319 ** or [GLOB] operator or if the parameter is compared to an indexed column | 3523 ** or [GLOB] operator or if the parameter is compared to an indexed column |
| 3320 ** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled. | 3524 ** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled. |
| 3321 ** </li> | 3525 ** </li> |
| 3322 ** </ol> | 3526 ** </ol> |
| 3323 */ | 3527 */ |
| 3324 SQLITE_API int SQLITE_STDCALL sqlite3_prepare( | 3528 SQLITE_API int sqlite3_prepare( |
| 3325 sqlite3 *db, /* Database handle */ | 3529 sqlite3 *db, /* Database handle */ |
| 3326 const char *zSql, /* SQL statement, UTF-8 encoded */ | 3530 const char *zSql, /* SQL statement, UTF-8 encoded */ |
| 3327 int nByte, /* Maximum length of zSql in bytes. */ | 3531 int nByte, /* Maximum length of zSql in bytes. */ |
| 3328 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ | 3532 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
| 3329 const char **pzTail /* OUT: Pointer to unused portion of zSql */ | 3533 const char **pzTail /* OUT: Pointer to unused portion of zSql */ |
| 3330 ); | 3534 ); |
| 3331 SQLITE_API int SQLITE_STDCALL sqlite3_prepare_v2( | 3535 SQLITE_API int sqlite3_prepare_v2( |
| 3332 sqlite3 *db, /* Database handle */ | 3536 sqlite3 *db, /* Database handle */ |
| 3333 const char *zSql, /* SQL statement, UTF-8 encoded */ | 3537 const char *zSql, /* SQL statement, UTF-8 encoded */ |
| 3334 int nByte, /* Maximum length of zSql in bytes. */ | 3538 int nByte, /* Maximum length of zSql in bytes. */ |
| 3335 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ | 3539 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
| 3336 const char **pzTail /* OUT: Pointer to unused portion of zSql */ | 3540 const char **pzTail /* OUT: Pointer to unused portion of zSql */ |
| 3337 ); | 3541 ); |
| 3338 SQLITE_API int SQLITE_STDCALL sqlite3_prepare16( | 3542 SQLITE_API int sqlite3_prepare16( |
| 3339 sqlite3 *db, /* Database handle */ | 3543 sqlite3 *db, /* Database handle */ |
| 3340 const void *zSql, /* SQL statement, UTF-16 encoded */ | 3544 const void *zSql, /* SQL statement, UTF-16 encoded */ |
| 3341 int nByte, /* Maximum length of zSql in bytes. */ | 3545 int nByte, /* Maximum length of zSql in bytes. */ |
| 3342 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ | 3546 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
| 3343 const void **pzTail /* OUT: Pointer to unused portion of zSql */ | 3547 const void **pzTail /* OUT: Pointer to unused portion of zSql */ |
| 3344 ); | 3548 ); |
| 3345 SQLITE_API int SQLITE_STDCALL sqlite3_prepare16_v2( | 3549 SQLITE_API int sqlite3_prepare16_v2( |
| 3346 sqlite3 *db, /* Database handle */ | 3550 sqlite3 *db, /* Database handle */ |
| 3347 const void *zSql, /* SQL statement, UTF-16 encoded */ | 3551 const void *zSql, /* SQL statement, UTF-16 encoded */ |
| 3348 int nByte, /* Maximum length of zSql in bytes. */ | 3552 int nByte, /* Maximum length of zSql in bytes. */ |
| 3349 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ | 3553 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ |
| 3350 const void **pzTail /* OUT: Pointer to unused portion of zSql */ | 3554 const void **pzTail /* OUT: Pointer to unused portion of zSql */ |
| 3351 ); | 3555 ); |
| 3352 | 3556 |
| 3353 /* | 3557 /* |
| 3354 ** CAPI3REF: Retrieving Statement SQL | 3558 ** CAPI3REF: Retrieving Statement SQL |
| 3355 ** METHOD: sqlite3_stmt | 3559 ** METHOD: sqlite3_stmt |
| 3356 ** | 3560 ** |
| 3357 ** ^This interface can be used to retrieve a saved copy of the original | 3561 ** ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8 |
| 3358 ** SQL text used to create a [prepared statement] if that statement was | 3562 ** SQL text used to create [prepared statement] P if P was |
| 3359 ** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()]. | 3563 ** created by either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()]. |
| 3564 ** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8 |
| 3565 ** string containing the SQL text of prepared statement P with |
| 3566 ** [bound parameters] expanded. |
| 3567 ** |
| 3568 ** ^(For example, if a prepared statement is created using the SQL |
| 3569 ** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345 |
| 3570 ** and parameter :xyz is unbound, then sqlite3_sql() will return |
| 3571 ** the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql() |
| 3572 ** will return "SELECT 2345,NULL".)^ |
| 3573 ** |
| 3574 ** ^The sqlite3_expanded_sql() interface returns NULL if insufficient memory |
| 3575 ** is available to hold the result, or if the result would exceed the |
| 3576 ** the maximum string length determined by the [SQLITE_LIMIT_LENGTH]. |
| 3577 ** |
| 3578 ** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of |
| 3579 ** bound parameter expansions. ^The [SQLITE_OMIT_TRACE] compile-time |
| 3580 ** option causes sqlite3_expanded_sql() to always return NULL. |
| 3581 ** |
| 3582 ** ^The string returned by sqlite3_sql(P) is managed by SQLite and is |
| 3583 ** automatically freed when the prepared statement is finalized. |
| 3584 ** ^The string returned by sqlite3_expanded_sql(P), on the other hand, |
| 3585 ** is obtained from [sqlite3_malloc()] and must be free by the application |
| 3586 ** by passing it to [sqlite3_free()]. |
| 3360 */ | 3587 */ |
| 3361 SQLITE_API const char *SQLITE_STDCALL sqlite3_sql(sqlite3_stmt *pStmt); | 3588 SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt); |
| 3589 SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt); |
| 3362 | 3590 |
| 3363 /* | 3591 /* |
| 3364 ** CAPI3REF: Determine If An SQL Statement Writes The Database | 3592 ** CAPI3REF: Determine If An SQL Statement Writes The Database |
| 3365 ** METHOD: sqlite3_stmt | 3593 ** METHOD: sqlite3_stmt |
| 3366 ** | 3594 ** |
| 3367 ** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if | 3595 ** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if |
| 3368 ** and only if the [prepared statement] X makes no direct changes to | 3596 ** and only if the [prepared statement] X makes no direct changes to |
| 3369 ** the content of the database file. | 3597 ** the content of the database file. |
| 3370 ** | 3598 ** |
| 3371 ** Note that [application-defined SQL functions] or | 3599 ** Note that [application-defined SQL functions] or |
| (...skipping 10 matching lines...) Expand all Loading... |
| 3382 ** directly, sqlite3_stmt_readonly() would still return true.)^ | 3610 ** directly, sqlite3_stmt_readonly() would still return true.)^ |
| 3383 ** | 3611 ** |
| 3384 ** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK], | 3612 ** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK], |
| 3385 ** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true, | 3613 ** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true, |
| 3386 ** since the statements themselves do not actually modify the database but | 3614 ** since the statements themselves do not actually modify the database but |
| 3387 ** rather they control the timing of when other statements modify the | 3615 ** rather they control the timing of when other statements modify the |
| 3388 ** database. ^The [ATTACH] and [DETACH] statements also cause | 3616 ** database. ^The [ATTACH] and [DETACH] statements also cause |
| 3389 ** sqlite3_stmt_readonly() to return true since, while those statements | 3617 ** sqlite3_stmt_readonly() to return true since, while those statements |
| 3390 ** change the configuration of a database connection, they do not make | 3618 ** change the configuration of a database connection, they do not make |
| 3391 ** changes to the content of the database files on disk. | 3619 ** changes to the content of the database files on disk. |
| 3620 ** ^The sqlite3_stmt_readonly() interface returns true for [BEGIN] since |
| 3621 ** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and |
| 3622 ** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so |
| 3623 ** sqlite3_stmt_readonly() returns false for those commands. |
| 3392 */ | 3624 */ |
| 3393 SQLITE_API int SQLITE_STDCALL sqlite3_stmt_readonly(sqlite3_stmt *pStmt); | 3625 SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt); |
| 3394 | 3626 |
| 3395 /* | 3627 /* |
| 3396 ** CAPI3REF: Determine If A Prepared Statement Has Been Reset | 3628 ** CAPI3REF: Determine If A Prepared Statement Has Been Reset |
| 3397 ** METHOD: sqlite3_stmt | 3629 ** METHOD: sqlite3_stmt |
| 3398 ** | 3630 ** |
| 3399 ** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the | 3631 ** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the |
| 3400 ** [prepared statement] S has been stepped at least once using | 3632 ** [prepared statement] S has been stepped at least once using |
| 3401 ** [sqlite3_step(S)] but has neither run to completion (returned | 3633 ** [sqlite3_step(S)] but has neither run to completion (returned |
| 3402 ** [SQLITE_DONE] from [sqlite3_step(S)]) nor | 3634 ** [SQLITE_DONE] from [sqlite3_step(S)]) nor |
| 3403 ** been reset using [sqlite3_reset(S)]. ^The sqlite3_stmt_busy(S) | 3635 ** been reset using [sqlite3_reset(S)]. ^The sqlite3_stmt_busy(S) |
| 3404 ** interface returns false if S is a NULL pointer. If S is not a | 3636 ** interface returns false if S is a NULL pointer. If S is not a |
| 3405 ** NULL pointer and is not a pointer to a valid [prepared statement] | 3637 ** NULL pointer and is not a pointer to a valid [prepared statement] |
| 3406 ** object, then the behavior is undefined and probably undesirable. | 3638 ** object, then the behavior is undefined and probably undesirable. |
| 3407 ** | 3639 ** |
| 3408 ** This interface can be used in combination [sqlite3_next_stmt()] | 3640 ** This interface can be used in combination [sqlite3_next_stmt()] |
| 3409 ** to locate all prepared statements associated with a database | 3641 ** to locate all prepared statements associated with a database |
| 3410 ** connection that are in need of being reset. This can be used, | 3642 ** connection that are in need of being reset. This can be used, |
| 3411 ** for example, in diagnostic routines to search for prepared | 3643 ** for example, in diagnostic routines to search for prepared |
| 3412 ** statements that are holding a transaction open. | 3644 ** statements that are holding a transaction open. |
| 3413 */ | 3645 */ |
| 3414 SQLITE_API int SQLITE_STDCALL sqlite3_stmt_busy(sqlite3_stmt*); | 3646 SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*); |
| 3415 | 3647 |
| 3416 /* | 3648 /* |
| 3417 ** CAPI3REF: Dynamically Typed Value Object | 3649 ** CAPI3REF: Dynamically Typed Value Object |
| 3418 ** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value} | 3650 ** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value} |
| 3419 ** | 3651 ** |
| 3420 ** SQLite uses the sqlite3_value object to represent all values | 3652 ** SQLite uses the sqlite3_value object to represent all values |
| 3421 ** that can be stored in a database table. SQLite uses dynamic typing | 3653 ** that can be stored in a database table. SQLite uses dynamic typing |
| 3422 ** for the values it stores. ^Values stored in sqlite3_value objects | 3654 ** for the values it stores. ^Values stored in sqlite3_value objects |
| 3423 ** can be integers, floating point values, strings, BLOBs, or NULL. | 3655 ** can be integers, floating point values, strings, BLOBs, or NULL. |
| 3424 ** | 3656 ** |
| (...skipping 143 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 3568 ** [error code] if anything goes wrong. | 3800 ** [error code] if anything goes wrong. |
| 3569 ** ^[SQLITE_TOOBIG] might be returned if the size of a string or BLOB | 3801 ** ^[SQLITE_TOOBIG] might be returned if the size of a string or BLOB |
| 3570 ** exceeds limits imposed by [sqlite3_limit]([SQLITE_LIMIT_LENGTH]) or | 3802 ** exceeds limits imposed by [sqlite3_limit]([SQLITE_LIMIT_LENGTH]) or |
| 3571 ** [SQLITE_MAX_LENGTH]. | 3803 ** [SQLITE_MAX_LENGTH]. |
| 3572 ** ^[SQLITE_RANGE] is returned if the parameter | 3804 ** ^[SQLITE_RANGE] is returned if the parameter |
| 3573 ** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails. | 3805 ** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails. |
| 3574 ** | 3806 ** |
| 3575 ** See also: [sqlite3_bind_parameter_count()], | 3807 ** See also: [sqlite3_bind_parameter_count()], |
| 3576 ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()]. | 3808 ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()]. |
| 3577 */ | 3809 */ |
| 3578 SQLITE_API int SQLITE_STDCALL sqlite3_bind_blob(sqlite3_stmt*, int, const void*,
int n, void(*)(void*)); | 3810 SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)
(void*)); |
| 3579 SQLITE_API int SQLITE_STDCALL sqlite3_bind_blob64(sqlite3_stmt*, int, const void
*, sqlite3_uint64, | 3811 SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint
64, |
| 3580 void(*)(void*)); | 3812 void(*)(void*)); |
| 3581 SQLITE_API int SQLITE_STDCALL sqlite3_bind_double(sqlite3_stmt*, int, double); | 3813 SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double); |
| 3582 SQLITE_API int SQLITE_STDCALL sqlite3_bind_int(sqlite3_stmt*, int, int); | 3814 SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int); |
| 3583 SQLITE_API int SQLITE_STDCALL sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int
64); | 3815 SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); |
| 3584 SQLITE_API int SQLITE_STDCALL sqlite3_bind_null(sqlite3_stmt*, int); | 3816 SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int); |
| 3585 SQLITE_API int SQLITE_STDCALL sqlite3_bind_text(sqlite3_stmt*,int,const char*,in
t,void(*)(void*)); | 3817 SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*
)); |
| 3586 SQLITE_API int SQLITE_STDCALL sqlite3_bind_text16(sqlite3_stmt*, int, const void
*, int, void(*)(void*)); | 3818 SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)
(void*)); |
| 3587 SQLITE_API int SQLITE_STDCALL sqlite3_bind_text64(sqlite3_stmt*, int, const char
*, sqlite3_uint64, | 3819 SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint
64, |
| 3588 void(*)(void*), unsigned char encoding); | 3820 void(*)(void*), unsigned char encoding); |
| 3589 SQLITE_API int SQLITE_STDCALL sqlite3_bind_value(sqlite3_stmt*, int, const sqlit
e3_value*); | 3821 SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); |
| 3590 SQLITE_API int SQLITE_STDCALL sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); | 3822 SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); |
| 3591 SQLITE_API int SQLITE_STDCALL sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite
3_uint64); | 3823 SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64); |
| 3592 | 3824 |
| 3593 /* | 3825 /* |
| 3594 ** CAPI3REF: Number Of SQL Parameters | 3826 ** CAPI3REF: Number Of SQL Parameters |
| 3595 ** METHOD: sqlite3_stmt | 3827 ** METHOD: sqlite3_stmt |
| 3596 ** | 3828 ** |
| 3597 ** ^This routine can be used to find the number of [SQL parameters] | 3829 ** ^This routine can be used to find the number of [SQL parameters] |
| 3598 ** in a [prepared statement]. SQL parameters are tokens of the | 3830 ** in a [prepared statement]. SQL parameters are tokens of the |
| 3599 ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as | 3831 ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as |
| 3600 ** placeholders for values that are [sqlite3_bind_blob | bound] | 3832 ** placeholders for values that are [sqlite3_bind_blob | bound] |
| 3601 ** to the parameters at a later time. | 3833 ** to the parameters at a later time. |
| 3602 ** | 3834 ** |
| 3603 ** ^(This routine actually returns the index of the largest (rightmost) | 3835 ** ^(This routine actually returns the index of the largest (rightmost) |
| 3604 ** parameter. For all forms except ?NNN, this will correspond to the | 3836 ** parameter. For all forms except ?NNN, this will correspond to the |
| 3605 ** number of unique parameters. If parameters of the ?NNN form are used, | 3837 ** number of unique parameters. If parameters of the ?NNN form are used, |
| 3606 ** there may be gaps in the list.)^ | 3838 ** there may be gaps in the list.)^ |
| 3607 ** | 3839 ** |
| 3608 ** See also: [sqlite3_bind_blob|sqlite3_bind()], | 3840 ** See also: [sqlite3_bind_blob|sqlite3_bind()], |
| 3609 ** [sqlite3_bind_parameter_name()], and | 3841 ** [sqlite3_bind_parameter_name()], and |
| 3610 ** [sqlite3_bind_parameter_index()]. | 3842 ** [sqlite3_bind_parameter_index()]. |
| 3611 */ | 3843 */ |
| 3612 SQLITE_API int SQLITE_STDCALL sqlite3_bind_parameter_count(sqlite3_stmt*); | 3844 SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*); |
| 3613 | 3845 |
| 3614 /* | 3846 /* |
| 3615 ** CAPI3REF: Name Of A Host Parameter | 3847 ** CAPI3REF: Name Of A Host Parameter |
| 3616 ** METHOD: sqlite3_stmt | 3848 ** METHOD: sqlite3_stmt |
| 3617 ** | 3849 ** |
| 3618 ** ^The sqlite3_bind_parameter_name(P,N) interface returns | 3850 ** ^The sqlite3_bind_parameter_name(P,N) interface returns |
| 3619 ** the name of the N-th [SQL parameter] in the [prepared statement] P. | 3851 ** the name of the N-th [SQL parameter] in the [prepared statement] P. |
| 3620 ** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA" | 3852 ** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA" |
| 3621 ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA" | 3853 ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA" |
| 3622 ** respectively. | 3854 ** respectively. |
| 3623 ** In other words, the initial ":" or "$" or "@" or "?" | 3855 ** In other words, the initial ":" or "$" or "@" or "?" |
| 3624 ** is included as part of the name.)^ | 3856 ** is included as part of the name.)^ |
| 3625 ** ^Parameters of the form "?" without a following integer have no name | 3857 ** ^Parameters of the form "?" without a following integer have no name |
| 3626 ** and are referred to as "nameless" or "anonymous parameters". | 3858 ** and are referred to as "nameless" or "anonymous parameters". |
| 3627 ** | 3859 ** |
| 3628 ** ^The first host parameter has an index of 1, not 0. | 3860 ** ^The first host parameter has an index of 1, not 0. |
| 3629 ** | 3861 ** |
| 3630 ** ^If the value N is out of range or if the N-th parameter is | 3862 ** ^If the value N is out of range or if the N-th parameter is |
| 3631 ** nameless, then NULL is returned. ^The returned string is | 3863 ** nameless, then NULL is returned. ^The returned string is |
| 3632 ** always in UTF-8 encoding even if the named parameter was | 3864 ** always in UTF-8 encoding even if the named parameter was |
| 3633 ** originally specified as UTF-16 in [sqlite3_prepare16()] or | 3865 ** originally specified as UTF-16 in [sqlite3_prepare16()] or |
| 3634 ** [sqlite3_prepare16_v2()]. | 3866 ** [sqlite3_prepare16_v2()]. |
| 3635 ** | 3867 ** |
| 3636 ** See also: [sqlite3_bind_blob|sqlite3_bind()], | 3868 ** See also: [sqlite3_bind_blob|sqlite3_bind()], |
| 3637 ** [sqlite3_bind_parameter_count()], and | 3869 ** [sqlite3_bind_parameter_count()], and |
| 3638 ** [sqlite3_bind_parameter_index()]. | 3870 ** [sqlite3_bind_parameter_index()]. |
| 3639 */ | 3871 */ |
| 3640 SQLITE_API const char *SQLITE_STDCALL sqlite3_bind_parameter_name(sqlite3_stmt*,
int); | 3872 SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); |
| 3641 | 3873 |
| 3642 /* | 3874 /* |
| 3643 ** CAPI3REF: Index Of A Parameter With A Given Name | 3875 ** CAPI3REF: Index Of A Parameter With A Given Name |
| 3644 ** METHOD: sqlite3_stmt | 3876 ** METHOD: sqlite3_stmt |
| 3645 ** | 3877 ** |
| 3646 ** ^Return the index of an SQL parameter given its name. ^The | 3878 ** ^Return the index of an SQL parameter given its name. ^The |
| 3647 ** index value returned is suitable for use as the second | 3879 ** index value returned is suitable for use as the second |
| 3648 ** parameter to [sqlite3_bind_blob|sqlite3_bind()]. ^A zero | 3880 ** parameter to [sqlite3_bind_blob|sqlite3_bind()]. ^A zero |
| 3649 ** is returned if no matching parameter is found. ^The parameter | 3881 ** is returned if no matching parameter is found. ^The parameter |
| 3650 ** name must be given in UTF-8 even if the original statement | 3882 ** name must be given in UTF-8 even if the original statement |
| 3651 ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()]. | 3883 ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()]. |
| 3652 ** | 3884 ** |
| 3653 ** See also: [sqlite3_bind_blob|sqlite3_bind()], | 3885 ** See also: [sqlite3_bind_blob|sqlite3_bind()], |
| 3654 ** [sqlite3_bind_parameter_count()], and | 3886 ** [sqlite3_bind_parameter_count()], and |
| 3655 ** [sqlite3_bind_parameter_name()]. | 3887 ** [sqlite3_bind_parameter_name()]. |
| 3656 */ | 3888 */ |
| 3657 SQLITE_API int SQLITE_STDCALL sqlite3_bind_parameter_index(sqlite3_stmt*, const
char *zName); | 3889 SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); |
| 3658 | 3890 |
| 3659 /* | 3891 /* |
| 3660 ** CAPI3REF: Reset All Bindings On A Prepared Statement | 3892 ** CAPI3REF: Reset All Bindings On A Prepared Statement |
| 3661 ** METHOD: sqlite3_stmt | 3893 ** METHOD: sqlite3_stmt |
| 3662 ** | 3894 ** |
| 3663 ** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset | 3895 ** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset |
| 3664 ** the [sqlite3_bind_blob | bindings] on a [prepared statement]. | 3896 ** the [sqlite3_bind_blob | bindings] on a [prepared statement]. |
| 3665 ** ^Use this routine to reset all host parameters to NULL. | 3897 ** ^Use this routine to reset all host parameters to NULL. |
| 3666 */ | 3898 */ |
| 3667 SQLITE_API int SQLITE_STDCALL sqlite3_clear_bindings(sqlite3_stmt*); | 3899 SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*); |
| 3668 | 3900 |
| 3669 /* | 3901 /* |
| 3670 ** CAPI3REF: Number Of Columns In A Result Set | 3902 ** CAPI3REF: Number Of Columns In A Result Set |
| 3671 ** METHOD: sqlite3_stmt | 3903 ** METHOD: sqlite3_stmt |
| 3672 ** | 3904 ** |
| 3673 ** ^Return the number of columns in the result set returned by the | 3905 ** ^Return the number of columns in the result set returned by the |
| 3674 ** [prepared statement]. ^This routine returns 0 if pStmt is an SQL | 3906 ** [prepared statement]. ^If this routine returns 0, that means the |
| 3675 ** statement that does not return data (for example an [UPDATE]). | 3907 ** [prepared statement] returns no data (for example an [UPDATE]). |
| 3908 ** ^However, just because this routine returns a positive number does not |
| 3909 ** mean that one or more rows of data will be returned. ^A SELECT statement |
| 3910 ** will always have a positive sqlite3_column_count() but depending on the |
| 3911 ** WHERE clause constraints and the table content, it might return no rows. |
| 3676 ** | 3912 ** |
| 3677 ** See also: [sqlite3_data_count()] | 3913 ** See also: [sqlite3_data_count()] |
| 3678 */ | 3914 */ |
| 3679 SQLITE_API int SQLITE_STDCALL sqlite3_column_count(sqlite3_stmt *pStmt); | 3915 SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt); |
| 3680 | 3916 |
| 3681 /* | 3917 /* |
| 3682 ** CAPI3REF: Column Names In A Result Set | 3918 ** CAPI3REF: Column Names In A Result Set |
| 3683 ** METHOD: sqlite3_stmt | 3919 ** METHOD: sqlite3_stmt |
| 3684 ** | 3920 ** |
| 3685 ** ^These routines return the name assigned to a particular column | 3921 ** ^These routines return the name assigned to a particular column |
| 3686 ** in the result set of a [SELECT] statement. ^The sqlite3_column_name() | 3922 ** in the result set of a [SELECT] statement. ^The sqlite3_column_name() |
| 3687 ** interface returns a pointer to a zero-terminated UTF-8 string | 3923 ** interface returns a pointer to a zero-terminated UTF-8 string |
| 3688 ** and sqlite3_column_name16() returns a pointer to a zero-terminated | 3924 ** and sqlite3_column_name16() returns a pointer to a zero-terminated |
| 3689 ** UTF-16 string. ^The first parameter is the [prepared statement] | 3925 ** UTF-16 string. ^The first parameter is the [prepared statement] |
| 3690 ** that implements the [SELECT] statement. ^The second parameter is the | 3926 ** that implements the [SELECT] statement. ^The second parameter is the |
| 3691 ** column number. ^The leftmost column is number 0. | 3927 ** column number. ^The leftmost column is number 0. |
| 3692 ** | 3928 ** |
| 3693 ** ^The returned string pointer is valid until either the [prepared statement] | 3929 ** ^The returned string pointer is valid until either the [prepared statement] |
| 3694 ** is destroyed by [sqlite3_finalize()] or until the statement is automatically | 3930 ** is destroyed by [sqlite3_finalize()] or until the statement is automatically |
| 3695 ** reprepared by the first call to [sqlite3_step()] for a particular run | 3931 ** reprepared by the first call to [sqlite3_step()] for a particular run |
| 3696 ** or until the next call to | 3932 ** or until the next call to |
| 3697 ** sqlite3_column_name() or sqlite3_column_name16() on the same column. | 3933 ** sqlite3_column_name() or sqlite3_column_name16() on the same column. |
| 3698 ** | 3934 ** |
| 3699 ** ^If sqlite3_malloc() fails during the processing of either routine | 3935 ** ^If sqlite3_malloc() fails during the processing of either routine |
| 3700 ** (for example during a conversion from UTF-8 to UTF-16) then a | 3936 ** (for example during a conversion from UTF-8 to UTF-16) then a |
| 3701 ** NULL pointer is returned. | 3937 ** NULL pointer is returned. |
| 3702 ** | 3938 ** |
| 3703 ** ^The name of a result column is the value of the "AS" clause for | 3939 ** ^The name of a result column is the value of the "AS" clause for |
| 3704 ** that column, if there is an AS clause. If there is no AS clause | 3940 ** that column, if there is an AS clause. If there is no AS clause |
| 3705 ** then the name of the column is unspecified and may change from | 3941 ** then the name of the column is unspecified and may change from |
| 3706 ** one release of SQLite to the next. | 3942 ** one release of SQLite to the next. |
| 3707 */ | 3943 */ |
| 3708 SQLITE_API const char *SQLITE_STDCALL sqlite3_column_name(sqlite3_stmt*, int N); | 3944 SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N); |
| 3709 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_name16(sqlite3_stmt*, int N
); | 3945 SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N); |
| 3710 | 3946 |
| 3711 /* | 3947 /* |
| 3712 ** CAPI3REF: Source Of Data In A Query Result | 3948 ** CAPI3REF: Source Of Data In A Query Result |
| 3713 ** METHOD: sqlite3_stmt | 3949 ** METHOD: sqlite3_stmt |
| 3714 ** | 3950 ** |
| 3715 ** ^These routines provide a means to determine the database, table, and | 3951 ** ^These routines provide a means to determine the database, table, and |
| 3716 ** table column that is the origin of a particular result column in | 3952 ** table column that is the origin of a particular result column in |
| 3717 ** [SELECT] statement. | 3953 ** [SELECT] statement. |
| 3718 ** ^The name of the database or table or column can be returned as | 3954 ** ^The name of the database or table or column can be returned as |
| 3719 ** either a UTF-8 or UTF-16 string. ^The _database_ routines return | 3955 ** either a UTF-8 or UTF-16 string. ^The _database_ routines return |
| (...skipping 27 matching lines...) Expand all Loading... |
| 3747 ** | 3983 ** |
| 3748 ** If two or more threads call one or more of these routines against the same | 3984 ** If two or more threads call one or more of these routines against the same |
| 3749 ** prepared statement and column at the same time then the results are | 3985 ** prepared statement and column at the same time then the results are |
| 3750 ** undefined. | 3986 ** undefined. |
| 3751 ** | 3987 ** |
| 3752 ** If two or more threads call one or more | 3988 ** If two or more threads call one or more |
| 3753 ** [sqlite3_column_database_name | column metadata interfaces] | 3989 ** [sqlite3_column_database_name | column metadata interfaces] |
| 3754 ** for the same [prepared statement] and result column | 3990 ** for the same [prepared statement] and result column |
| 3755 ** at the same time then the results are undefined. | 3991 ** at the same time then the results are undefined. |
| 3756 */ | 3992 */ |
| 3757 SQLITE_API const char *SQLITE_STDCALL sqlite3_column_database_name(sqlite3_stmt*
,int); | 3993 SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int); |
| 3758 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_database_name16(sqlite3_stm
t*,int); | 3994 SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int); |
| 3759 SQLITE_API const char *SQLITE_STDCALL sqlite3_column_table_name(sqlite3_stmt*,in
t); | 3995 SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int); |
| 3760 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_table_name16(sqlite3_stmt*,
int); | 3996 SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int); |
| 3761 SQLITE_API const char *SQLITE_STDCALL sqlite3_column_origin_name(sqlite3_stmt*,i
nt); | 3997 SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int); |
| 3762 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_origin_name16(sqlite3_stmt*
,int); | 3998 SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); |
| 3763 | 3999 |
| 3764 /* | 4000 /* |
| 3765 ** CAPI3REF: Declared Datatype Of A Query Result | 4001 ** CAPI3REF: Declared Datatype Of A Query Result |
| 3766 ** METHOD: sqlite3_stmt | 4002 ** METHOD: sqlite3_stmt |
| 3767 ** | 4003 ** |
| 3768 ** ^(The first parameter is a [prepared statement]. | 4004 ** ^(The first parameter is a [prepared statement]. |
| 3769 ** If this statement is a [SELECT] statement and the Nth column of the | 4005 ** If this statement is a [SELECT] statement and the Nth column of the |
| 3770 ** returned result set of that [SELECT] is a table column (not an | 4006 ** returned result set of that [SELECT] is a table column (not an |
| 3771 ** expression or subquery) then the declared type of the table | 4007 ** expression or subquery) then the declared type of the table |
| 3772 ** column is returned.)^ ^If the Nth column of the result set is an | 4008 ** column is returned.)^ ^If the Nth column of the result set is an |
| (...skipping 11 matching lines...) Expand all Loading... |
| 3784 ** this routine would return the string "VARIANT" for the second result | 4020 ** this routine would return the string "VARIANT" for the second result |
| 3785 ** column (i==1), and a NULL pointer for the first result column (i==0).)^ | 4021 ** column (i==1), and a NULL pointer for the first result column (i==0).)^ |
| 3786 ** | 4022 ** |
| 3787 ** ^SQLite uses dynamic run-time typing. ^So just because a column | 4023 ** ^SQLite uses dynamic run-time typing. ^So just because a column |
| 3788 ** is declared to contain a particular type does not mean that the | 4024 ** is declared to contain a particular type does not mean that the |
| 3789 ** data stored in that column is of the declared type. SQLite is | 4025 ** data stored in that column is of the declared type. SQLite is |
| 3790 ** strongly typed, but the typing is dynamic not static. ^Type | 4026 ** strongly typed, but the typing is dynamic not static. ^Type |
| 3791 ** is associated with individual values, not with the containers | 4027 ** is associated with individual values, not with the containers |
| 3792 ** used to hold those values. | 4028 ** used to hold those values. |
| 3793 */ | 4029 */ |
| 3794 SQLITE_API const char *SQLITE_STDCALL sqlite3_column_decltype(sqlite3_stmt*,int)
; | 4030 SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int); |
| 3795 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_decltype16(sqlite3_stmt*,in
t); | 4031 SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int); |
| 3796 | 4032 |
| 3797 /* | 4033 /* |
| 3798 ** CAPI3REF: Evaluate An SQL Statement | 4034 ** CAPI3REF: Evaluate An SQL Statement |
| 3799 ** METHOD: sqlite3_stmt | 4035 ** METHOD: sqlite3_stmt |
| 3800 ** | 4036 ** |
| 3801 ** After a [prepared statement] has been prepared using either | 4037 ** After a [prepared statement] has been prepared using either |
| 3802 ** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy | 4038 ** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy |
| 3803 ** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function | 4039 ** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function |
| 3804 ** must be called one or more times to evaluate the statement. | 4040 ** must be called one or more times to evaluate the statement. |
| 3805 ** | 4041 ** |
| (...skipping 40 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 3846 ** already been [sqlite3_finalize | finalized] or on one that had | 4082 ** already been [sqlite3_finalize | finalized] or on one that had |
| 3847 ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could | 4083 ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could |
| 3848 ** be the case that the same database connection is being used by two or | 4084 ** be the case that the same database connection is being used by two or |
| 3849 ** more threads at the same moment in time. | 4085 ** more threads at the same moment in time. |
| 3850 ** | 4086 ** |
| 3851 ** For all versions of SQLite up to and including 3.6.23.1, a call to | 4087 ** For all versions of SQLite up to and including 3.6.23.1, a call to |
| 3852 ** [sqlite3_reset()] was required after sqlite3_step() returned anything | 4088 ** [sqlite3_reset()] was required after sqlite3_step() returned anything |
| 3853 ** other than [SQLITE_ROW] before any subsequent invocation of | 4089 ** other than [SQLITE_ROW] before any subsequent invocation of |
| 3854 ** sqlite3_step(). Failure to reset the prepared statement using | 4090 ** sqlite3_step(). Failure to reset the prepared statement using |
| 3855 ** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from | 4091 ** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from |
| 3856 ** sqlite3_step(). But after version 3.6.23.1, sqlite3_step() began | 4092 ** sqlite3_step(). But after [version 3.6.23.1] ([dateof:3.6.23.1], |
| 4093 ** sqlite3_step() began |
| 3857 ** calling [sqlite3_reset()] automatically in this circumstance rather | 4094 ** calling [sqlite3_reset()] automatically in this circumstance rather |
| 3858 ** than returning [SQLITE_MISUSE]. This is not considered a compatibility | 4095 ** than returning [SQLITE_MISUSE]. This is not considered a compatibility |
| 3859 ** break because any application that ever receives an SQLITE_MISUSE error | 4096 ** break because any application that ever receives an SQLITE_MISUSE error |
| 3860 ** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option | 4097 ** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option |
| 3861 ** can be used to restore the legacy behavior. | 4098 ** can be used to restore the legacy behavior. |
| 3862 ** | 4099 ** |
| 3863 ** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step() | 4100 ** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step() |
| 3864 ** API always returns a generic error code, [SQLITE_ERROR], following any | 4101 ** API always returns a generic error code, [SQLITE_ERROR], following any |
| 3865 ** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call | 4102 ** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call |
| 3866 ** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the | 4103 ** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the |
| 3867 ** specific [error codes] that better describes the error. | 4104 ** specific [error codes] that better describes the error. |
| 3868 ** We admit that this is a goofy design. The problem has been fixed | 4105 ** We admit that this is a goofy design. The problem has been fixed |
| 3869 ** with the "v2" interface. If you prepare all of your SQL statements | 4106 ** with the "v2" interface. If you prepare all of your SQL statements |
| 3870 ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead | 4107 ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead |
| 3871 ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces, | 4108 ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces, |
| 3872 ** then the more specific [error codes] are returned directly | 4109 ** then the more specific [error codes] are returned directly |
| 3873 ** by sqlite3_step(). The use of the "v2" interface is recommended. | 4110 ** by sqlite3_step(). The use of the "v2" interface is recommended. |
| 3874 */ | 4111 */ |
| 3875 SQLITE_API int SQLITE_STDCALL sqlite3_step(sqlite3_stmt*); | 4112 SQLITE_API int sqlite3_step(sqlite3_stmt*); |
| 3876 | 4113 |
| 3877 /* | 4114 /* |
| 3878 ** CAPI3REF: Number of columns in a result set | 4115 ** CAPI3REF: Number of columns in a result set |
| 3879 ** METHOD: sqlite3_stmt | 4116 ** METHOD: sqlite3_stmt |
| 3880 ** | 4117 ** |
| 3881 ** ^The sqlite3_data_count(P) interface returns the number of columns in the | 4118 ** ^The sqlite3_data_count(P) interface returns the number of columns in the |
| 3882 ** current row of the result set of [prepared statement] P. | 4119 ** current row of the result set of [prepared statement] P. |
| 3883 ** ^If prepared statement P does not have results ready to return | 4120 ** ^If prepared statement P does not have results ready to return |
| 3884 ** (via calls to the [sqlite3_column_int | sqlite3_column_*()] of | 4121 ** (via calls to the [sqlite3_column_int | sqlite3_column_*()] of |
| 3885 ** interfaces) then sqlite3_data_count(P) returns 0. | 4122 ** interfaces) then sqlite3_data_count(P) returns 0. |
| 3886 ** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer. | 4123 ** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer. |
| 3887 ** ^The sqlite3_data_count(P) routine returns 0 if the previous call to | 4124 ** ^The sqlite3_data_count(P) routine returns 0 if the previous call to |
| 3888 ** [sqlite3_step](P) returned [SQLITE_DONE]. ^The sqlite3_data_count(P) | 4125 ** [sqlite3_step](P) returned [SQLITE_DONE]. ^The sqlite3_data_count(P) |
| 3889 ** will return non-zero if previous call to [sqlite3_step](P) returned | 4126 ** will return non-zero if previous call to [sqlite3_step](P) returned |
| 3890 ** [SQLITE_ROW], except in the case of the [PRAGMA incremental_vacuum] | 4127 ** [SQLITE_ROW], except in the case of the [PRAGMA incremental_vacuum] |
| 3891 ** where it always returns zero since each step of that multi-step | 4128 ** where it always returns zero since each step of that multi-step |
| 3892 ** pragma returns 0 columns of data. | 4129 ** pragma returns 0 columns of data. |
| 3893 ** | 4130 ** |
| 3894 ** See also: [sqlite3_column_count()] | 4131 ** See also: [sqlite3_column_count()] |
| 3895 */ | 4132 */ |
| 3896 SQLITE_API int SQLITE_STDCALL sqlite3_data_count(sqlite3_stmt *pStmt); | 4133 SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt); |
| 3897 | 4134 |
| 3898 /* | 4135 /* |
| 3899 ** CAPI3REF: Fundamental Datatypes | 4136 ** CAPI3REF: Fundamental Datatypes |
| 3900 ** KEYWORDS: SQLITE_TEXT | 4137 ** KEYWORDS: SQLITE_TEXT |
| 3901 ** | 4138 ** |
| 3902 ** ^(Every value in SQLite has one of five fundamental datatypes: | 4139 ** ^(Every value in SQLite has one of five fundamental datatypes: |
| 3903 ** | 4140 ** |
| 3904 ** <ul> | 4141 ** <ul> |
| 3905 ** <li> 64-bit signed integer | 4142 ** <li> 64-bit signed integer |
| 3906 ** <li> 64-bit IEEE floating point number | 4143 ** <li> 64-bit IEEE floating point number |
| (...skipping 169 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 4076 ** and BLOBs is freed automatically. Do <em>not</em> pass the pointers returned | 4313 ** and BLOBs is freed automatically. Do <em>not</em> pass the pointers returned |
| 4077 ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into | 4314 ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into |
| 4078 ** [sqlite3_free()]. | 4315 ** [sqlite3_free()]. |
| 4079 ** | 4316 ** |
| 4080 ** ^(If a memory allocation error occurs during the evaluation of any | 4317 ** ^(If a memory allocation error occurs during the evaluation of any |
| 4081 ** of these routines, a default value is returned. The default value | 4318 ** of these routines, a default value is returned. The default value |
| 4082 ** is either the integer 0, the floating point number 0.0, or a NULL | 4319 ** is either the integer 0, the floating point number 0.0, or a NULL |
| 4083 ** pointer. Subsequent calls to [sqlite3_errcode()] will return | 4320 ** pointer. Subsequent calls to [sqlite3_errcode()] will return |
| 4084 ** [SQLITE_NOMEM].)^ | 4321 ** [SQLITE_NOMEM].)^ |
| 4085 */ | 4322 */ |
| 4086 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_blob(sqlite3_stmt*, int iCo
l); | 4323 SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); |
| 4087 SQLITE_API int SQLITE_STDCALL sqlite3_column_bytes(sqlite3_stmt*, int iCol); | 4324 SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol); |
| 4088 SQLITE_API int SQLITE_STDCALL sqlite3_column_bytes16(sqlite3_stmt*, int iCol); | 4325 SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); |
| 4089 SQLITE_API double SQLITE_STDCALL sqlite3_column_double(sqlite3_stmt*, int iCol); | 4326 SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol); |
| 4090 SQLITE_API int SQLITE_STDCALL sqlite3_column_int(sqlite3_stmt*, int iCol); | 4327 SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol); |
| 4091 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_column_int64(sqlite3_stmt*, int
iCol); | 4328 SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); |
| 4092 SQLITE_API const unsigned char *SQLITE_STDCALL sqlite3_column_text(sqlite3_stmt*
, int iCol); | 4329 SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); |
| 4093 SQLITE_API const void *SQLITE_STDCALL sqlite3_column_text16(sqlite3_stmt*, int i
Col); | 4330 SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); |
| 4094 SQLITE_API int SQLITE_STDCALL sqlite3_column_type(sqlite3_stmt*, int iCol); | 4331 SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol); |
| 4095 SQLITE_API sqlite3_value *SQLITE_STDCALL sqlite3_column_value(sqlite3_stmt*, int
iCol); | 4332 SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); |
| 4096 | 4333 |
| 4097 /* | 4334 /* |
| 4098 ** CAPI3REF: Destroy A Prepared Statement Object | 4335 ** CAPI3REF: Destroy A Prepared Statement Object |
| 4099 ** DESTRUCTOR: sqlite3_stmt | 4336 ** DESTRUCTOR: sqlite3_stmt |
| 4100 ** | 4337 ** |
| 4101 ** ^The sqlite3_finalize() function is called to delete a [prepared statement]. | 4338 ** ^The sqlite3_finalize() function is called to delete a [prepared statement]. |
| 4102 ** ^If the most recent evaluation of the statement encountered no errors | 4339 ** ^If the most recent evaluation of the statement encountered no errors |
| 4103 ** or if the statement is never been evaluated, then sqlite3_finalize() returns | 4340 ** or if the statement is never been evaluated, then sqlite3_finalize() returns |
| 4104 ** SQLITE_OK. ^If the most recent evaluation of statement S failed, then | 4341 ** SQLITE_OK. ^If the most recent evaluation of statement S failed, then |
| 4105 ** sqlite3_finalize(S) returns the appropriate [error code] or | 4342 ** sqlite3_finalize(S) returns the appropriate [error code] or |
| 4106 ** [extended error code]. | 4343 ** [extended error code]. |
| 4107 ** | 4344 ** |
| 4108 ** ^The sqlite3_finalize(S) routine can be called at any point during | 4345 ** ^The sqlite3_finalize(S) routine can be called at any point during |
| 4109 ** the life cycle of [prepared statement] S: | 4346 ** the life cycle of [prepared statement] S: |
| 4110 ** before statement S is ever evaluated, after | 4347 ** before statement S is ever evaluated, after |
| 4111 ** one or more calls to [sqlite3_reset()], or after any call | 4348 ** one or more calls to [sqlite3_reset()], or after any call |
| 4112 ** to [sqlite3_step()] regardless of whether or not the statement has | 4349 ** to [sqlite3_step()] regardless of whether or not the statement has |
| 4113 ** completed execution. | 4350 ** completed execution. |
| 4114 ** | 4351 ** |
| 4115 ** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op. | 4352 ** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op. |
| 4116 ** | 4353 ** |
| 4117 ** The application must finalize every [prepared statement] in order to avoid | 4354 ** The application must finalize every [prepared statement] in order to avoid |
| 4118 ** resource leaks. It is a grievous error for the application to try to use | 4355 ** resource leaks. It is a grievous error for the application to try to use |
| 4119 ** a prepared statement after it has been finalized. Any use of a prepared | 4356 ** a prepared statement after it has been finalized. Any use of a prepared |
| 4120 ** statement after it has been finalized can result in undefined and | 4357 ** statement after it has been finalized can result in undefined and |
| 4121 ** undesirable behavior such as segfaults and heap corruption. | 4358 ** undesirable behavior such as segfaults and heap corruption. |
| 4122 */ | 4359 */ |
| 4123 SQLITE_API int SQLITE_STDCALL sqlite3_finalize(sqlite3_stmt *pStmt); | 4360 SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt); |
| 4124 | 4361 |
| 4125 /* | 4362 /* |
| 4126 ** CAPI3REF: Reset A Prepared Statement Object | 4363 ** CAPI3REF: Reset A Prepared Statement Object |
| 4127 ** METHOD: sqlite3_stmt | 4364 ** METHOD: sqlite3_stmt |
| 4128 ** | 4365 ** |
| 4129 ** The sqlite3_reset() function is called to reset a [prepared statement] | 4366 ** The sqlite3_reset() function is called to reset a [prepared statement] |
| 4130 ** object back to its initial state, ready to be re-executed. | 4367 ** object back to its initial state, ready to be re-executed. |
| 4131 ** ^Any SQL statement variables that had values bound to them using | 4368 ** ^Any SQL statement variables that had values bound to them using |
| 4132 ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values. | 4369 ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values. |
| 4133 ** Use [sqlite3_clear_bindings()] to reset the bindings. | 4370 ** Use [sqlite3_clear_bindings()] to reset the bindings. |
| 4134 ** | 4371 ** |
| 4135 ** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S | 4372 ** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S |
| 4136 ** back to the beginning of its program. | 4373 ** back to the beginning of its program. |
| 4137 ** | 4374 ** |
| 4138 ** ^If the most recent call to [sqlite3_step(S)] for the | 4375 ** ^If the most recent call to [sqlite3_step(S)] for the |
| 4139 ** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE], | 4376 ** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE], |
| 4140 ** or if [sqlite3_step(S)] has never before been called on S, | 4377 ** or if [sqlite3_step(S)] has never before been called on S, |
| 4141 ** then [sqlite3_reset(S)] returns [SQLITE_OK]. | 4378 ** then [sqlite3_reset(S)] returns [SQLITE_OK]. |
| 4142 ** | 4379 ** |
| 4143 ** ^If the most recent call to [sqlite3_step(S)] for the | 4380 ** ^If the most recent call to [sqlite3_step(S)] for the |
| 4144 ** [prepared statement] S indicated an error, then | 4381 ** [prepared statement] S indicated an error, then |
| 4145 ** [sqlite3_reset(S)] returns an appropriate [error code]. | 4382 ** [sqlite3_reset(S)] returns an appropriate [error code]. |
| 4146 ** | 4383 ** |
| 4147 ** ^The [sqlite3_reset(S)] interface does not change the values | 4384 ** ^The [sqlite3_reset(S)] interface does not change the values |
| 4148 ** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S. | 4385 ** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S. |
| 4149 */ | 4386 */ |
| 4150 SQLITE_API int SQLITE_STDCALL sqlite3_reset(sqlite3_stmt *pStmt); | 4387 SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt); |
| 4151 | 4388 |
| 4152 /* | 4389 /* |
| 4153 ** CAPI3REF: Create Or Redefine SQL Functions | 4390 ** CAPI3REF: Create Or Redefine SQL Functions |
| 4154 ** KEYWORDS: {function creation routines} | 4391 ** KEYWORDS: {function creation routines} |
| 4155 ** KEYWORDS: {application-defined SQL function} | 4392 ** KEYWORDS: {application-defined SQL function} |
| 4156 ** KEYWORDS: {application-defined SQL functions} | 4393 ** KEYWORDS: {application-defined SQL functions} |
| 4157 ** METHOD: sqlite3 | 4394 ** METHOD: sqlite3 |
| 4158 ** | 4395 ** |
| 4159 ** ^These functions (collectively known as "function creation routines") | 4396 ** ^These functions (collectively known as "function creation routines") |
| 4160 ** are used to add SQL functions or aggregates or to redefine the behavior | 4397 ** are used to add SQL functions or aggregates or to redefine the behavior |
| (...skipping 79 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 4240 ** is a closer match than a function where the encoding difference is | 4477 ** is a closer match than a function where the encoding difference is |
| 4241 ** between UTF8 and UTF16. | 4478 ** between UTF8 and UTF16. |
| 4242 ** | 4479 ** |
| 4243 ** ^Built-in functions may be overloaded by new application-defined functions. | 4480 ** ^Built-in functions may be overloaded by new application-defined functions. |
| 4244 ** | 4481 ** |
| 4245 ** ^An application-defined function is permitted to call other | 4482 ** ^An application-defined function is permitted to call other |
| 4246 ** SQLite interfaces. However, such calls must not | 4483 ** SQLite interfaces. However, such calls must not |
| 4247 ** close the database connection nor finalize or reset the prepared | 4484 ** close the database connection nor finalize or reset the prepared |
| 4248 ** statement in which the function is running. | 4485 ** statement in which the function is running. |
| 4249 */ | 4486 */ |
| 4250 SQLITE_API int SQLITE_STDCALL sqlite3_create_function( | 4487 SQLITE_API int sqlite3_create_function( |
| 4251 sqlite3 *db, | 4488 sqlite3 *db, |
| 4252 const char *zFunctionName, | 4489 const char *zFunctionName, |
| 4253 int nArg, | 4490 int nArg, |
| 4254 int eTextRep, | 4491 int eTextRep, |
| 4255 void *pApp, | 4492 void *pApp, |
| 4256 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), | 4493 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), |
| 4257 void (*xStep)(sqlite3_context*,int,sqlite3_value**), | 4494 void (*xStep)(sqlite3_context*,int,sqlite3_value**), |
| 4258 void (*xFinal)(sqlite3_context*) | 4495 void (*xFinal)(sqlite3_context*) |
| 4259 ); | 4496 ); |
| 4260 SQLITE_API int SQLITE_STDCALL sqlite3_create_function16( | 4497 SQLITE_API int sqlite3_create_function16( |
| 4261 sqlite3 *db, | 4498 sqlite3 *db, |
| 4262 const void *zFunctionName, | 4499 const void *zFunctionName, |
| 4263 int nArg, | 4500 int nArg, |
| 4264 int eTextRep, | 4501 int eTextRep, |
| 4265 void *pApp, | 4502 void *pApp, |
| 4266 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), | 4503 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), |
| 4267 void (*xStep)(sqlite3_context*,int,sqlite3_value**), | 4504 void (*xStep)(sqlite3_context*,int,sqlite3_value**), |
| 4268 void (*xFinal)(sqlite3_context*) | 4505 void (*xFinal)(sqlite3_context*) |
| 4269 ); | 4506 ); |
| 4270 SQLITE_API int SQLITE_STDCALL sqlite3_create_function_v2( | 4507 SQLITE_API int sqlite3_create_function_v2( |
| 4271 sqlite3 *db, | 4508 sqlite3 *db, |
| 4272 const char *zFunctionName, | 4509 const char *zFunctionName, |
| 4273 int nArg, | 4510 int nArg, |
| 4274 int eTextRep, | 4511 int eTextRep, |
| 4275 void *pApp, | 4512 void *pApp, |
| 4276 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), | 4513 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), |
| 4277 void (*xStep)(sqlite3_context*,int,sqlite3_value**), | 4514 void (*xStep)(sqlite3_context*,int,sqlite3_value**), |
| 4278 void (*xFinal)(sqlite3_context*), | 4515 void (*xFinal)(sqlite3_context*), |
| 4279 void(*xDestroy)(void*) | 4516 void(*xDestroy)(void*) |
| 4280 ); | 4517 ); |
| (...skipping 25 matching lines...) Expand all Loading... |
| 4306 ** CAPI3REF: Deprecated Functions | 4543 ** CAPI3REF: Deprecated Functions |
| 4307 ** DEPRECATED | 4544 ** DEPRECATED |
| 4308 ** | 4545 ** |
| 4309 ** These functions are [deprecated]. In order to maintain | 4546 ** These functions are [deprecated]. In order to maintain |
| 4310 ** backwards compatibility with older code, these functions continue | 4547 ** backwards compatibility with older code, these functions continue |
| 4311 ** to be supported. However, new applications should avoid | 4548 ** to be supported. However, new applications should avoid |
| 4312 ** the use of these functions. To encourage programmers to avoid | 4549 ** the use of these functions. To encourage programmers to avoid |
| 4313 ** these functions, we will not explain what they do. | 4550 ** these functions, we will not explain what they do. |
| 4314 */ | 4551 */ |
| 4315 #ifndef SQLITE_OMIT_DEPRECATED | 4552 #ifndef SQLITE_OMIT_DEPRECATED |
| 4316 SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_aggregate_count(sqlite3_
context*); | 4553 SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*); |
| 4317 SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_expired(sqlite3_stmt*); | 4554 SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*); |
| 4318 SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_transfer_bindings(sqlite
3_stmt*, sqlite3_stmt*); | 4555 SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite
3_stmt*); |
| 4319 SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_global_recover(void); | 4556 SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void); |
| 4320 SQLITE_API SQLITE_DEPRECATED void SQLITE_STDCALL sqlite3_thread_cleanup(void); | 4557 SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void); |
| 4321 SQLITE_API SQLITE_DEPRECATED int SQLITE_STDCALL sqlite3_memory_alarm(void(*)(voi
d*,sqlite3_int64,int), | 4558 SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int6
4,int), |
| 4322 void*,sqlite3_int64); | 4559 void*,sqlite3_int64); |
| 4323 #endif | 4560 #endif |
| 4324 | 4561 |
| 4325 /* | 4562 /* |
| 4326 ** CAPI3REF: Obtaining SQL Values | 4563 ** CAPI3REF: Obtaining SQL Values |
| 4327 ** METHOD: sqlite3_value | 4564 ** METHOD: sqlite3_value |
| 4328 ** | 4565 ** |
| 4329 ** The C-language implementation of SQL functions and aggregates uses | 4566 ** The C-language implementation of SQL functions and aggregates uses |
| 4330 ** this set of interface routines to access the parameter values on | 4567 ** this set of interface routines to access the parameter values on |
| 4331 ** the function or aggregate. | 4568 ** the function or aggregate. |
| (...skipping 29 matching lines...) Expand all Loading... |
| 4361 ** | 4598 ** |
| 4362 ** Please pay particular attention to the fact that the pointer returned | 4599 ** Please pay particular attention to the fact that the pointer returned |
| 4363 ** from [sqlite3_value_blob()], [sqlite3_value_text()], or | 4600 ** from [sqlite3_value_blob()], [sqlite3_value_text()], or |
| 4364 ** [sqlite3_value_text16()] can be invalidated by a subsequent call to | 4601 ** [sqlite3_value_text16()] can be invalidated by a subsequent call to |
| 4365 ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()], | 4602 ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()], |
| 4366 ** or [sqlite3_value_text16()]. | 4603 ** or [sqlite3_value_text16()]. |
| 4367 ** | 4604 ** |
| 4368 ** These routines must be called from the same thread as | 4605 ** These routines must be called from the same thread as |
| 4369 ** the SQL function that supplied the [sqlite3_value*] parameters. | 4606 ** the SQL function that supplied the [sqlite3_value*] parameters. |
| 4370 */ | 4607 */ |
| 4371 SQLITE_API const void *SQLITE_STDCALL sqlite3_value_blob(sqlite3_value*); | 4608 SQLITE_API const void *sqlite3_value_blob(sqlite3_value*); |
| 4372 SQLITE_API int SQLITE_STDCALL sqlite3_value_bytes(sqlite3_value*); | 4609 SQLITE_API int sqlite3_value_bytes(sqlite3_value*); |
| 4373 SQLITE_API int SQLITE_STDCALL sqlite3_value_bytes16(sqlite3_value*); | 4610 SQLITE_API int sqlite3_value_bytes16(sqlite3_value*); |
| 4374 SQLITE_API double SQLITE_STDCALL sqlite3_value_double(sqlite3_value*); | 4611 SQLITE_API double sqlite3_value_double(sqlite3_value*); |
| 4375 SQLITE_API int SQLITE_STDCALL sqlite3_value_int(sqlite3_value*); | 4612 SQLITE_API int sqlite3_value_int(sqlite3_value*); |
| 4376 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_value_int64(sqlite3_value*); | 4613 SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*); |
| 4377 SQLITE_API const unsigned char *SQLITE_STDCALL sqlite3_value_text(sqlite3_value*
); | 4614 SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*); |
| 4378 SQLITE_API const void *SQLITE_STDCALL sqlite3_value_text16(sqlite3_value*); | 4615 SQLITE_API const void *sqlite3_value_text16(sqlite3_value*); |
| 4379 SQLITE_API const void *SQLITE_STDCALL sqlite3_value_text16le(sqlite3_value*); | 4616 SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*); |
| 4380 SQLITE_API const void *SQLITE_STDCALL sqlite3_value_text16be(sqlite3_value*); | 4617 SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*); |
| 4381 SQLITE_API int SQLITE_STDCALL sqlite3_value_type(sqlite3_value*); | 4618 SQLITE_API int sqlite3_value_type(sqlite3_value*); |
| 4382 SQLITE_API int SQLITE_STDCALL sqlite3_value_numeric_type(sqlite3_value*); | 4619 SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*); |
| 4383 | 4620 |
| 4384 /* | 4621 /* |
| 4385 ** CAPI3REF: Finding The Subtype Of SQL Values | 4622 ** CAPI3REF: Finding The Subtype Of SQL Values |
| 4386 ** METHOD: sqlite3_value | 4623 ** METHOD: sqlite3_value |
| 4387 ** | 4624 ** |
| 4388 ** The sqlite3_value_subtype(V) function returns the subtype for | 4625 ** The sqlite3_value_subtype(V) function returns the subtype for |
| 4389 ** an [application-defined SQL function] argument V. The subtype | 4626 ** an [application-defined SQL function] argument V. The subtype |
| 4390 ** information can be used to pass a limited amount of context from | 4627 ** information can be used to pass a limited amount of context from |
| 4391 ** one SQL function to another. Use the [sqlite3_result_subtype()] | 4628 ** one SQL function to another. Use the [sqlite3_result_subtype()] |
| 4392 ** routine to set the subtype for the return value of an SQL function. | 4629 ** routine to set the subtype for the return value of an SQL function. |
| 4393 ** | 4630 ** |
| 4394 ** SQLite makes no use of subtype itself. It merely passes the subtype | 4631 ** SQLite makes no use of subtype itself. It merely passes the subtype |
| 4395 ** from the result of one [application-defined SQL function] into the | 4632 ** from the result of one [application-defined SQL function] into the |
| 4396 ** input of another. | 4633 ** input of another. |
| 4397 */ | 4634 */ |
| 4398 SQLITE_API unsigned int SQLITE_STDCALL sqlite3_value_subtype(sqlite3_value*); | 4635 SQLITE_API unsigned int sqlite3_value_subtype(sqlite3_value*); |
| 4399 | 4636 |
| 4400 /* | 4637 /* |
| 4401 ** CAPI3REF: Copy And Free SQL Values | 4638 ** CAPI3REF: Copy And Free SQL Values |
| 4402 ** METHOD: sqlite3_value | 4639 ** METHOD: sqlite3_value |
| 4403 ** | 4640 ** |
| 4404 ** ^The sqlite3_value_dup(V) interface makes a copy of the [sqlite3_value] | 4641 ** ^The sqlite3_value_dup(V) interface makes a copy of the [sqlite3_value] |
| 4405 ** object D and returns a pointer to that copy. ^The [sqlite3_value] returned | 4642 ** object D and returns a pointer to that copy. ^The [sqlite3_value] returned |
| 4406 ** is a [protected sqlite3_value] object even if the input is not. | 4643 ** is a [protected sqlite3_value] object even if the input is not. |
| 4407 ** ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a | 4644 ** ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a |
| 4408 ** memory allocation fails. | 4645 ** memory allocation fails. |
| 4409 ** | 4646 ** |
| 4410 ** ^The sqlite3_value_free(V) interface frees an [sqlite3_value] object | 4647 ** ^The sqlite3_value_free(V) interface frees an [sqlite3_value] object |
| 4411 ** previously obtained from [sqlite3_value_dup()]. ^If V is a NULL pointer | 4648 ** previously obtained from [sqlite3_value_dup()]. ^If V is a NULL pointer |
| 4412 ** then sqlite3_value_free(V) is a harmless no-op. | 4649 ** then sqlite3_value_free(V) is a harmless no-op. |
| 4413 */ | 4650 */ |
| 4414 SQLITE_API sqlite3_value *SQLITE_STDCALL sqlite3_value_dup(const sqlite3_value*)
; | 4651 SQLITE_API sqlite3_value *sqlite3_value_dup(const sqlite3_value*); |
| 4415 SQLITE_API void SQLITE_STDCALL sqlite3_value_free(sqlite3_value*); | 4652 SQLITE_API void sqlite3_value_free(sqlite3_value*); |
| 4416 | 4653 |
| 4417 /* | 4654 /* |
| 4418 ** CAPI3REF: Obtain Aggregate Function Context | 4655 ** CAPI3REF: Obtain Aggregate Function Context |
| 4419 ** METHOD: sqlite3_context | 4656 ** METHOD: sqlite3_context |
| 4420 ** | 4657 ** |
| 4421 ** Implementations of aggregate SQL functions use this | 4658 ** Implementations of aggregate SQL functions use this |
| 4422 ** routine to allocate memory for storing their state. | 4659 ** routine to allocate memory for storing their state. |
| 4423 ** | 4660 ** |
| 4424 ** ^The first time the sqlite3_aggregate_context(C,N) routine is called | 4661 ** ^The first time the sqlite3_aggregate_context(C,N) routine is called |
| 4425 ** for a particular aggregate function, SQLite | 4662 ** for a particular aggregate function, SQLite |
| (...skipping 24 matching lines...) Expand all Loading... |
| 4450 ** sqlite3_aggregate_context() when the aggregate query concludes. | 4687 ** sqlite3_aggregate_context() when the aggregate query concludes. |
| 4451 ** | 4688 ** |
| 4452 ** The first parameter must be a copy of the | 4689 ** The first parameter must be a copy of the |
| 4453 ** [sqlite3_context | SQL function context] that is the first parameter | 4690 ** [sqlite3_context | SQL function context] that is the first parameter |
| 4454 ** to the xStep or xFinal callback routine that implements the aggregate | 4691 ** to the xStep or xFinal callback routine that implements the aggregate |
| 4455 ** function. | 4692 ** function. |
| 4456 ** | 4693 ** |
| 4457 ** This routine must be called from the same thread in which | 4694 ** This routine must be called from the same thread in which |
| 4458 ** the aggregate SQL function is running. | 4695 ** the aggregate SQL function is running. |
| 4459 */ | 4696 */ |
| 4460 SQLITE_API void *SQLITE_STDCALL sqlite3_aggregate_context(sqlite3_context*, int
nBytes); | 4697 SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); |
| 4461 | 4698 |
| 4462 /* | 4699 /* |
| 4463 ** CAPI3REF: User Data For Functions | 4700 ** CAPI3REF: User Data For Functions |
| 4464 ** METHOD: sqlite3_context | 4701 ** METHOD: sqlite3_context |
| 4465 ** | 4702 ** |
| 4466 ** ^The sqlite3_user_data() interface returns a copy of | 4703 ** ^The sqlite3_user_data() interface returns a copy of |
| 4467 ** the pointer that was the pUserData parameter (the 5th parameter) | 4704 ** the pointer that was the pUserData parameter (the 5th parameter) |
| 4468 ** of the [sqlite3_create_function()] | 4705 ** of the [sqlite3_create_function()] |
| 4469 ** and [sqlite3_create_function16()] routines that originally | 4706 ** and [sqlite3_create_function16()] routines that originally |
| 4470 ** registered the application defined function. | 4707 ** registered the application defined function. |
| 4471 ** | 4708 ** |
| 4472 ** This routine must be called from the same thread in which | 4709 ** This routine must be called from the same thread in which |
| 4473 ** the application-defined function is running. | 4710 ** the application-defined function is running. |
| 4474 */ | 4711 */ |
| 4475 SQLITE_API void *SQLITE_STDCALL sqlite3_user_data(sqlite3_context*); | 4712 SQLITE_API void *sqlite3_user_data(sqlite3_context*); |
| 4476 | 4713 |
| 4477 /* | 4714 /* |
| 4478 ** CAPI3REF: Database Connection For Functions | 4715 ** CAPI3REF: Database Connection For Functions |
| 4479 ** METHOD: sqlite3_context | 4716 ** METHOD: sqlite3_context |
| 4480 ** | 4717 ** |
| 4481 ** ^The sqlite3_context_db_handle() interface returns a copy of | 4718 ** ^The sqlite3_context_db_handle() interface returns a copy of |
| 4482 ** the pointer to the [database connection] (the 1st parameter) | 4719 ** the pointer to the [database connection] (the 1st parameter) |
| 4483 ** of the [sqlite3_create_function()] | 4720 ** of the [sqlite3_create_function()] |
| 4484 ** and [sqlite3_create_function16()] routines that originally | 4721 ** and [sqlite3_create_function16()] routines that originally |
| 4485 ** registered the application defined function. | 4722 ** registered the application defined function. |
| 4486 */ | 4723 */ |
| 4487 SQLITE_API sqlite3 *SQLITE_STDCALL sqlite3_context_db_handle(sqlite3_context*); | 4724 SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*); |
| 4488 | 4725 |
| 4489 /* | 4726 /* |
| 4490 ** CAPI3REF: Function Auxiliary Data | 4727 ** CAPI3REF: Function Auxiliary Data |
| 4491 ** METHOD: sqlite3_context | 4728 ** METHOD: sqlite3_context |
| 4492 ** | 4729 ** |
| 4493 ** These functions may be used by (non-aggregate) SQL functions to | 4730 ** These functions may be used by (non-aggregate) SQL functions to |
| 4494 ** associate metadata with argument values. If the same value is passed to | 4731 ** associate metadata with argument values. If the same value is passed to |
| 4495 ** multiple invocations of the same SQL function during query execution, under | 4732 ** multiple invocations of the same SQL function during query execution, under |
| 4496 ** some circumstances the associated metadata may be preserved. An example | 4733 ** some circumstances the associated metadata may be preserved. An example |
| 4497 ** of where this might be useful is in a regular-expression matching | 4734 ** of where this might be useful is in a regular-expression matching |
| (...skipping 11 matching lines...) Expand all Loading... |
| 4509 ** | 4746 ** |
| 4510 ** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th | 4747 ** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th |
| 4511 ** argument of the application-defined function. ^Subsequent | 4748 ** argument of the application-defined function. ^Subsequent |
| 4512 ** calls to sqlite3_get_auxdata(C,N) return P from the most recent | 4749 ** calls to sqlite3_get_auxdata(C,N) return P from the most recent |
| 4513 ** sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or | 4750 ** sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or |
| 4514 ** NULL if the metadata has been discarded. | 4751 ** NULL if the metadata has been discarded. |
| 4515 ** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL, | 4752 ** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL, |
| 4516 ** SQLite will invoke the destructor function X with parameter P exactly | 4753 ** SQLite will invoke the destructor function X with parameter P exactly |
| 4517 ** once, when the metadata is discarded. | 4754 ** once, when the metadata is discarded. |
| 4518 ** SQLite is free to discard the metadata at any time, including: <ul> | 4755 ** SQLite is free to discard the metadata at any time, including: <ul> |
| 4519 ** <li> when the corresponding function parameter changes, or | 4756 ** <li> ^(when the corresponding function parameter changes)^, or |
| 4520 ** <li> when [sqlite3_reset()] or [sqlite3_finalize()] is called for the | 4757 ** <li> ^(when [sqlite3_reset()] or [sqlite3_finalize()] is called for the |
| 4521 ** SQL statement, or | 4758 ** SQL statement)^, or |
| 4522 ** <li> when sqlite3_set_auxdata() is invoked again on the same parameter, or | 4759 ** <li> ^(when sqlite3_set_auxdata() is invoked again on the same |
| 4523 ** <li> during the original sqlite3_set_auxdata() call when a memory | 4760 ** parameter)^, or |
| 4524 ** allocation error occurs. </ul>)^ | 4761 ** <li> ^(during the original sqlite3_set_auxdata() call when a memory |
| 4762 ** allocation error occurs.)^ </ul> |
| 4525 ** | 4763 ** |
| 4526 ** Note the last bullet in particular. The destructor X in | 4764 ** Note the last bullet in particular. The destructor X in |
| 4527 ** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the | 4765 ** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the |
| 4528 ** sqlite3_set_auxdata() interface even returns. Hence sqlite3_set_auxdata() | 4766 ** sqlite3_set_auxdata() interface even returns. Hence sqlite3_set_auxdata() |
| 4529 ** should be called near the end of the function implementation and the | 4767 ** should be called near the end of the function implementation and the |
| 4530 ** function implementation should not make any use of P after | 4768 ** function implementation should not make any use of P after |
| 4531 ** sqlite3_set_auxdata() has been called. | 4769 ** sqlite3_set_auxdata() has been called. |
| 4532 ** | 4770 ** |
| 4533 ** ^(In practice, metadata is preserved between function calls for | 4771 ** ^(In practice, metadata is preserved between function calls for |
| 4534 ** function parameters that are compile-time constants, including literal | 4772 ** function parameters that are compile-time constants, including literal |
| 4535 ** values and [parameters] and expressions composed from the same.)^ | 4773 ** values and [parameters] and expressions composed from the same.)^ |
| 4536 ** | 4774 ** |
| 4537 ** These routines must be called from the same thread in which | 4775 ** These routines must be called from the same thread in which |
| 4538 ** the SQL function is running. | 4776 ** the SQL function is running. |
| 4539 */ | 4777 */ |
| 4540 SQLITE_API void *SQLITE_STDCALL sqlite3_get_auxdata(sqlite3_context*, int N); | 4778 SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N); |
| 4541 SQLITE_API void SQLITE_STDCALL sqlite3_set_auxdata(sqlite3_context*, int N, void
*, void (*)(void*)); | 4779 SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(voi
d*)); |
| 4542 | 4780 |
| 4543 | 4781 |
| 4544 /* | 4782 /* |
| 4545 ** CAPI3REF: Constants Defining Special Destructor Behavior | 4783 ** CAPI3REF: Constants Defining Special Destructor Behavior |
| 4546 ** | 4784 ** |
| 4547 ** These are special values for the destructor that is passed in as the | 4785 ** These are special values for the destructor that is passed in as the |
| 4548 ** final argument to routines like [sqlite3_result_blob()]. ^If the destructor | 4786 ** final argument to routines like [sqlite3_result_blob()]. ^If the destructor |
| 4549 ** argument is SQLITE_STATIC, it means that the content pointer is constant | 4787 ** argument is SQLITE_STATIC, it means that the content pointer is constant |
| 4550 ** and will never change. It does not need to be destroyed. ^The | 4788 ** and will never change. It does not need to be destroyed. ^The |
| 4551 ** SQLITE_TRANSIENT value means that the content will likely change in | 4789 ** SQLITE_TRANSIENT value means that the content will likely change in |
| (...skipping 115 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 4667 ** so that the [sqlite3_value] specified in the parameter may change or | 4905 ** so that the [sqlite3_value] specified in the parameter may change or |
| 4668 ** be deallocated after sqlite3_result_value() returns without harm. | 4906 ** be deallocated after sqlite3_result_value() returns without harm. |
| 4669 ** ^A [protected sqlite3_value] object may always be used where an | 4907 ** ^A [protected sqlite3_value] object may always be used where an |
| 4670 ** [unprotected sqlite3_value] object is required, so either | 4908 ** [unprotected sqlite3_value] object is required, so either |
| 4671 ** kind of [sqlite3_value] object can be used with this interface. | 4909 ** kind of [sqlite3_value] object can be used with this interface. |
| 4672 ** | 4910 ** |
| 4673 ** If these routines are called from within the different thread | 4911 ** If these routines are called from within the different thread |
| 4674 ** than the one containing the application-defined function that received | 4912 ** than the one containing the application-defined function that received |
| 4675 ** the [sqlite3_context] pointer, the results are undefined. | 4913 ** the [sqlite3_context] pointer, the results are undefined. |
| 4676 */ | 4914 */ |
| 4677 SQLITE_API void SQLITE_STDCALL sqlite3_result_blob(sqlite3_context*, const void*
, int, void(*)(void*)); | 4915 SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(
void*)); |
| 4678 SQLITE_API void SQLITE_STDCALL sqlite3_result_blob64(sqlite3_context*,const void
*, | 4916 SQLITE_API void sqlite3_result_blob64(sqlite3_context*,const void*, |
| 4679 sqlite3_uint64,void(*)(void*)); | 4917 sqlite3_uint64,void(*)(void*)); |
| 4680 SQLITE_API void SQLITE_STDCALL sqlite3_result_double(sqlite3_context*, double); | 4918 SQLITE_API void sqlite3_result_double(sqlite3_context*, double); |
| 4681 SQLITE_API void SQLITE_STDCALL sqlite3_result_error(sqlite3_context*, const char
*, int); | 4919 SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int); |
| 4682 SQLITE_API void SQLITE_STDCALL sqlite3_result_error16(sqlite3_context*, const vo
id*, int); | 4920 SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int); |
| 4683 SQLITE_API void SQLITE_STDCALL sqlite3_result_error_toobig(sqlite3_context*); | 4921 SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*); |
| 4684 SQLITE_API void SQLITE_STDCALL sqlite3_result_error_nomem(sqlite3_context*); | 4922 SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*); |
| 4685 SQLITE_API void SQLITE_STDCALL sqlite3_result_error_code(sqlite3_context*, int); | 4923 SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int); |
| 4686 SQLITE_API void SQLITE_STDCALL sqlite3_result_int(sqlite3_context*, int); | 4924 SQLITE_API void sqlite3_result_int(sqlite3_context*, int); |
| 4687 SQLITE_API void SQLITE_STDCALL sqlite3_result_int64(sqlite3_context*, sqlite3_in
t64); | 4925 SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64); |
| 4688 SQLITE_API void SQLITE_STDCALL sqlite3_result_null(sqlite3_context*); | 4926 SQLITE_API void sqlite3_result_null(sqlite3_context*); |
| 4689 SQLITE_API void SQLITE_STDCALL sqlite3_result_text(sqlite3_context*, const char*
, int, void(*)(void*)); | 4927 SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(
void*)); |
| 4690 SQLITE_API void SQLITE_STDCALL sqlite3_result_text64(sqlite3_context*, const cha
r*,sqlite3_uint64, | 4928 SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint
64, |
| 4691 void(*)(void*), unsigned char encoding); | 4929 void(*)(void*), unsigned char encoding); |
| 4692 SQLITE_API void SQLITE_STDCALL sqlite3_result_text16(sqlite3_context*, const voi
d*, int, void(*)(void*)); | 4930 SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*
)(void*)); |
| 4693 SQLITE_API void SQLITE_STDCALL sqlite3_result_text16le(sqlite3_context*, const v
oid*, int,void(*)(void*)); | 4931 SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(
*)(void*)); |
| 4694 SQLITE_API void SQLITE_STDCALL sqlite3_result_text16be(sqlite3_context*, const v
oid*, int,void(*)(void*)); | 4932 SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(
*)(void*)); |
| 4695 SQLITE_API void SQLITE_STDCALL sqlite3_result_value(sqlite3_context*, sqlite3_va
lue*); | 4933 SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*); |
| 4696 SQLITE_API void SQLITE_STDCALL sqlite3_result_zeroblob(sqlite3_context*, int n); | 4934 SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n); |
| 4697 SQLITE_API int SQLITE_STDCALL sqlite3_result_zeroblob64(sqlite3_context*, sqlite
3_uint64 n); | 4935 SQLITE_API int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n); |
| 4698 | 4936 |
| 4699 | 4937 |
| 4700 /* | 4938 /* |
| 4701 ** CAPI3REF: Setting The Subtype Of An SQL Function | 4939 ** CAPI3REF: Setting The Subtype Of An SQL Function |
| 4702 ** METHOD: sqlite3_context | 4940 ** METHOD: sqlite3_context |
| 4703 ** | 4941 ** |
| 4704 ** The sqlite3_result_subtype(C,T) function causes the subtype of | 4942 ** The sqlite3_result_subtype(C,T) function causes the subtype of |
| 4705 ** the result from the [application-defined SQL function] with | 4943 ** the result from the [application-defined SQL function] with |
| 4706 ** [sqlite3_context] C to be the value T. Only the lower 8 bits | 4944 ** [sqlite3_context] C to be the value T. Only the lower 8 bits |
| 4707 ** of the subtype T are preserved in current versions of SQLite; | 4945 ** of the subtype T are preserved in current versions of SQLite; |
| 4708 ** higher order bits are discarded. | 4946 ** higher order bits are discarded. |
| 4709 ** The number of subtype bytes preserved by SQLite might increase | 4947 ** The number of subtype bytes preserved by SQLite might increase |
| 4710 ** in future releases of SQLite. | 4948 ** in future releases of SQLite. |
| 4711 */ | 4949 */ |
| 4712 SQLITE_API void SQLITE_STDCALL sqlite3_result_subtype(sqlite3_context*,unsigned
int); | 4950 SQLITE_API void sqlite3_result_subtype(sqlite3_context*,unsigned int); |
| 4713 | 4951 |
| 4714 /* | 4952 /* |
| 4715 ** CAPI3REF: Define New Collating Sequences | 4953 ** CAPI3REF: Define New Collating Sequences |
| 4716 ** METHOD: sqlite3 | 4954 ** METHOD: sqlite3 |
| 4717 ** | 4955 ** |
| 4718 ** ^These functions add, remove, or modify a [collation] associated | 4956 ** ^These functions add, remove, or modify a [collation] associated |
| 4719 ** with the [database connection] specified as the first argument. | 4957 ** with the [database connection] specified as the first argument. |
| 4720 ** | 4958 ** |
| 4721 ** ^The name of the collation is a UTF-8 string | 4959 ** ^The name of the collation is a UTF-8 string |
| 4722 ** for sqlite3_create_collation() and sqlite3_create_collation_v2() | 4960 ** for sqlite3_create_collation() and sqlite3_create_collation_v2() |
| (...skipping 61 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 4784 ** sqlite3_create_collation_v2() function fails. Applications that invoke | 5022 ** sqlite3_create_collation_v2() function fails. Applications that invoke |
| 4785 ** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should | 5023 ** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should |
| 4786 ** check the return code and dispose of the application data pointer | 5024 ** check the return code and dispose of the application data pointer |
| 4787 ** themselves rather than expecting SQLite to deal with it for them. | 5025 ** themselves rather than expecting SQLite to deal with it for them. |
| 4788 ** This is different from every other SQLite interface. The inconsistency | 5026 ** This is different from every other SQLite interface. The inconsistency |
| 4789 ** is unfortunate but cannot be changed without breaking backwards | 5027 ** is unfortunate but cannot be changed without breaking backwards |
| 4790 ** compatibility. | 5028 ** compatibility. |
| 4791 ** | 5029 ** |
| 4792 ** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()]. | 5030 ** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()]. |
| 4793 */ | 5031 */ |
| 4794 SQLITE_API int SQLITE_STDCALL sqlite3_create_collation( | 5032 SQLITE_API int sqlite3_create_collation( |
| 4795 sqlite3*, | 5033 sqlite3*, |
| 4796 const char *zName, | 5034 const char *zName, |
| 4797 int eTextRep, | 5035 int eTextRep, |
| 4798 void *pArg, | 5036 void *pArg, |
| 4799 int(*xCompare)(void*,int,const void*,int,const void*) | 5037 int(*xCompare)(void*,int,const void*,int,const void*) |
| 4800 ); | 5038 ); |
| 4801 SQLITE_API int SQLITE_STDCALL sqlite3_create_collation_v2( | 5039 SQLITE_API int sqlite3_create_collation_v2( |
| 4802 sqlite3*, | 5040 sqlite3*, |
| 4803 const char *zName, | 5041 const char *zName, |
| 4804 int eTextRep, | 5042 int eTextRep, |
| 4805 void *pArg, | 5043 void *pArg, |
| 4806 int(*xCompare)(void*,int,const void*,int,const void*), | 5044 int(*xCompare)(void*,int,const void*,int,const void*), |
| 4807 void(*xDestroy)(void*) | 5045 void(*xDestroy)(void*) |
| 4808 ); | 5046 ); |
| 4809 SQLITE_API int SQLITE_STDCALL sqlite3_create_collation16( | 5047 SQLITE_API int sqlite3_create_collation16( |
| 4810 sqlite3*, | 5048 sqlite3*, |
| 4811 const void *zName, | 5049 const void *zName, |
| 4812 int eTextRep, | 5050 int eTextRep, |
| 4813 void *pArg, | 5051 void *pArg, |
| 4814 int(*xCompare)(void*,int,const void*,int,const void*) | 5052 int(*xCompare)(void*,int,const void*,int,const void*) |
| 4815 ); | 5053 ); |
| 4816 | 5054 |
| 4817 /* | 5055 /* |
| 4818 ** CAPI3REF: Collation Needed Callbacks | 5056 ** CAPI3REF: Collation Needed Callbacks |
| 4819 ** METHOD: sqlite3 | 5057 ** METHOD: sqlite3 |
| (...skipping 14 matching lines...) Expand all Loading... |
| 4834 ** sqlite3_collation_needed16(). The second argument is the database | 5072 ** sqlite3_collation_needed16(). The second argument is the database |
| 4835 ** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], | 5073 ** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], |
| 4836 ** or [SQLITE_UTF16LE], indicating the most desirable form of the collation | 5074 ** or [SQLITE_UTF16LE], indicating the most desirable form of the collation |
| 4837 ** sequence function required. The fourth parameter is the name of the | 5075 ** sequence function required. The fourth parameter is the name of the |
| 4838 ** required collation sequence.)^ | 5076 ** required collation sequence.)^ |
| 4839 ** | 5077 ** |
| 4840 ** The callback function should register the desired collation using | 5078 ** The callback function should register the desired collation using |
| 4841 ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or | 5079 ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or |
| 4842 ** [sqlite3_create_collation_v2()]. | 5080 ** [sqlite3_create_collation_v2()]. |
| 4843 */ | 5081 */ |
| 4844 SQLITE_API int SQLITE_STDCALL sqlite3_collation_needed( | 5082 SQLITE_API int sqlite3_collation_needed( |
| 4845 sqlite3*, | 5083 sqlite3*, |
| 4846 void*, | 5084 void*, |
| 4847 void(*)(void*,sqlite3*,int eTextRep,const char*) | 5085 void(*)(void*,sqlite3*,int eTextRep,const char*) |
| 4848 ); | 5086 ); |
| 4849 SQLITE_API int SQLITE_STDCALL sqlite3_collation_needed16( | 5087 SQLITE_API int sqlite3_collation_needed16( |
| 4850 sqlite3*, | 5088 sqlite3*, |
| 4851 void*, | 5089 void*, |
| 4852 void(*)(void*,sqlite3*,int eTextRep,const void*) | 5090 void(*)(void*,sqlite3*,int eTextRep,const void*) |
| 4853 ); | 5091 ); |
| 4854 | 5092 |
| 4855 #ifdef SQLITE_HAS_CODEC | 5093 #ifdef SQLITE_HAS_CODEC |
| 4856 /* | 5094 /* |
| 4857 ** Specify the key for an encrypted database. This routine should be | 5095 ** Specify the key for an encrypted database. This routine should be |
| 4858 ** called right after sqlite3_open(). | 5096 ** called right after sqlite3_open(). |
| 4859 ** | 5097 ** |
| 4860 ** The code to implement this API is not available in the public release | 5098 ** The code to implement this API is not available in the public release |
| 4861 ** of SQLite. | 5099 ** of SQLite. |
| 4862 */ | 5100 */ |
| 4863 SQLITE_API int SQLITE_STDCALL sqlite3_key( | 5101 SQLITE_API int sqlite3_key( |
| 4864 sqlite3 *db, /* Database to be rekeyed */ | 5102 sqlite3 *db, /* Database to be rekeyed */ |
| 4865 const void *pKey, int nKey /* The key */ | 5103 const void *pKey, int nKey /* The key */ |
| 4866 ); | 5104 ); |
| 4867 SQLITE_API int SQLITE_STDCALL sqlite3_key_v2( | 5105 SQLITE_API int sqlite3_key_v2( |
| 4868 sqlite3 *db, /* Database to be rekeyed */ | 5106 sqlite3 *db, /* Database to be rekeyed */ |
| 4869 const char *zDbName, /* Name of the database */ | 5107 const char *zDbName, /* Name of the database */ |
| 4870 const void *pKey, int nKey /* The key */ | 5108 const void *pKey, int nKey /* The key */ |
| 4871 ); | 5109 ); |
| 4872 | 5110 |
| 4873 /* | 5111 /* |
| 4874 ** Change the key on an open database. If the current database is not | 5112 ** Change the key on an open database. If the current database is not |
| 4875 ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the | 5113 ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the |
| 4876 ** database is decrypted. | 5114 ** database is decrypted. |
| 4877 ** | 5115 ** |
| 4878 ** The code to implement this API is not available in the public release | 5116 ** The code to implement this API is not available in the public release |
| 4879 ** of SQLite. | 5117 ** of SQLite. |
| 4880 */ | 5118 */ |
| 4881 SQLITE_API int SQLITE_STDCALL sqlite3_rekey( | 5119 SQLITE_API int sqlite3_rekey( |
| 4882 sqlite3 *db, /* Database to be rekeyed */ | 5120 sqlite3 *db, /* Database to be rekeyed */ |
| 4883 const void *pKey, int nKey /* The new key */ | 5121 const void *pKey, int nKey /* The new key */ |
| 4884 ); | 5122 ); |
| 4885 SQLITE_API int SQLITE_STDCALL sqlite3_rekey_v2( | 5123 SQLITE_API int sqlite3_rekey_v2( |
| 4886 sqlite3 *db, /* Database to be rekeyed */ | 5124 sqlite3 *db, /* Database to be rekeyed */ |
| 4887 const char *zDbName, /* Name of the database */ | 5125 const char *zDbName, /* Name of the database */ |
| 4888 const void *pKey, int nKey /* The new key */ | 5126 const void *pKey, int nKey /* The new key */ |
| 4889 ); | 5127 ); |
| 4890 | 5128 |
| 4891 /* | 5129 /* |
| 4892 ** Specify the activation key for a SEE database. Unless | 5130 ** Specify the activation key for a SEE database. Unless |
| 4893 ** activated, none of the SEE routines will work. | 5131 ** activated, none of the SEE routines will work. |
| 4894 */ | 5132 */ |
| 4895 SQLITE_API void SQLITE_STDCALL sqlite3_activate_see( | 5133 SQLITE_API void sqlite3_activate_see( |
| 4896 const char *zPassPhrase /* Activation phrase */ | 5134 const char *zPassPhrase /* Activation phrase */ |
| 4897 ); | 5135 ); |
| 4898 #endif | 5136 #endif |
| 4899 | 5137 |
| 4900 #ifdef SQLITE_ENABLE_CEROD | 5138 #ifdef SQLITE_ENABLE_CEROD |
| 4901 /* | 5139 /* |
| 4902 ** Specify the activation key for a CEROD database. Unless | 5140 ** Specify the activation key for a CEROD database. Unless |
| 4903 ** activated, none of the CEROD routines will work. | 5141 ** activated, none of the CEROD routines will work. |
| 4904 */ | 5142 */ |
| 4905 SQLITE_API void SQLITE_STDCALL sqlite3_activate_cerod( | 5143 SQLITE_API void sqlite3_activate_cerod( |
| 4906 const char *zPassPhrase /* Activation phrase */ | 5144 const char *zPassPhrase /* Activation phrase */ |
| 4907 ); | 5145 ); |
| 4908 #endif | 5146 #endif |
| 4909 | 5147 |
| 4910 /* | 5148 /* |
| 4911 ** CAPI3REF: Suspend Execution For A Short Time | 5149 ** CAPI3REF: Suspend Execution For A Short Time |
| 4912 ** | 5150 ** |
| 4913 ** The sqlite3_sleep() function causes the current thread to suspend execution | 5151 ** The sqlite3_sleep() function causes the current thread to suspend execution |
| 4914 ** for at least a number of milliseconds specified in its parameter. | 5152 ** for at least a number of milliseconds specified in its parameter. |
| 4915 ** | 5153 ** |
| 4916 ** If the operating system does not support sleep requests with | 5154 ** If the operating system does not support sleep requests with |
| 4917 ** millisecond time resolution, then the time will be rounded up to | 5155 ** millisecond time resolution, then the time will be rounded up to |
| 4918 ** the nearest second. The number of milliseconds of sleep actually | 5156 ** the nearest second. The number of milliseconds of sleep actually |
| 4919 ** requested from the operating system is returned. | 5157 ** requested from the operating system is returned. |
| 4920 ** | 5158 ** |
| 4921 ** ^SQLite implements this interface by calling the xSleep() | 5159 ** ^SQLite implements this interface by calling the xSleep() |
| 4922 ** method of the default [sqlite3_vfs] object. If the xSleep() method | 5160 ** method of the default [sqlite3_vfs] object. If the xSleep() method |
| 4923 ** of the default VFS is not implemented correctly, or not implemented at | 5161 ** of the default VFS is not implemented correctly, or not implemented at |
| 4924 ** all, then the behavior of sqlite3_sleep() may deviate from the description | 5162 ** all, then the behavior of sqlite3_sleep() may deviate from the description |
| 4925 ** in the previous paragraphs. | 5163 ** in the previous paragraphs. |
| 4926 */ | 5164 */ |
| 4927 SQLITE_API int SQLITE_STDCALL sqlite3_sleep(int); | 5165 SQLITE_API int sqlite3_sleep(int); |
| 4928 | 5166 |
| 4929 /* | 5167 /* |
| 4930 ** CAPI3REF: Name Of The Folder Holding Temporary Files | 5168 ** CAPI3REF: Name Of The Folder Holding Temporary Files |
| 4931 ** | 5169 ** |
| 4932 ** ^(If this global variable is made to point to a string which is | 5170 ** ^(If this global variable is made to point to a string which is |
| 4933 ** the name of a folder (a.k.a. directory), then all temporary files | 5171 ** the name of a folder (a.k.a. directory), then all temporary files |
| 4934 ** created by SQLite when using a built-in [sqlite3_vfs | VFS] | 5172 ** created by SQLite when using a built-in [sqlite3_vfs | VFS] |
| 4935 ** will be placed in that directory.)^ ^If this variable | 5173 ** will be placed in that directory.)^ ^If this variable |
| 4936 ** is a NULL pointer, then SQLite performs a search for an appropriate | 5174 ** is a NULL pointer, then SQLite performs a search for an appropriate |
| 4937 ** temporary file directory. | 5175 ** temporary file directory. |
| (...skipping 98 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 5036 ** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR], | 5274 ** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR], |
| 5037 ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the | 5275 ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the |
| 5038 ** transaction might be rolled back automatically. The only way to | 5276 ** transaction might be rolled back automatically. The only way to |
| 5039 ** find out whether SQLite automatically rolled back the transaction after | 5277 ** find out whether SQLite automatically rolled back the transaction after |
| 5040 ** an error is to use this function. | 5278 ** an error is to use this function. |
| 5041 ** | 5279 ** |
| 5042 ** If another thread changes the autocommit status of the database | 5280 ** If another thread changes the autocommit status of the database |
| 5043 ** connection while this routine is running, then the return value | 5281 ** connection while this routine is running, then the return value |
| 5044 ** is undefined. | 5282 ** is undefined. |
| 5045 */ | 5283 */ |
| 5046 SQLITE_API int SQLITE_STDCALL sqlite3_get_autocommit(sqlite3*); | 5284 SQLITE_API int sqlite3_get_autocommit(sqlite3*); |
| 5047 | 5285 |
| 5048 /* | 5286 /* |
| 5049 ** CAPI3REF: Find The Database Handle Of A Prepared Statement | 5287 ** CAPI3REF: Find The Database Handle Of A Prepared Statement |
| 5050 ** METHOD: sqlite3_stmt | 5288 ** METHOD: sqlite3_stmt |
| 5051 ** | 5289 ** |
| 5052 ** ^The sqlite3_db_handle interface returns the [database connection] handle | 5290 ** ^The sqlite3_db_handle interface returns the [database connection] handle |
| 5053 ** to which a [prepared statement] belongs. ^The [database connection] | 5291 ** to which a [prepared statement] belongs. ^The [database connection] |
| 5054 ** returned by sqlite3_db_handle is the same [database connection] | 5292 ** returned by sqlite3_db_handle is the same [database connection] |
| 5055 ** that was the first argument | 5293 ** that was the first argument |
| 5056 ** to the [sqlite3_prepare_v2()] call (or its variants) that was used to | 5294 ** to the [sqlite3_prepare_v2()] call (or its variants) that was used to |
| 5057 ** create the statement in the first place. | 5295 ** create the statement in the first place. |
| 5058 */ | 5296 */ |
| 5059 SQLITE_API sqlite3 *SQLITE_STDCALL sqlite3_db_handle(sqlite3_stmt*); | 5297 SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*); |
| 5060 | 5298 |
| 5061 /* | 5299 /* |
| 5062 ** CAPI3REF: Return The Filename For A Database Connection | 5300 ** CAPI3REF: Return The Filename For A Database Connection |
| 5063 ** METHOD: sqlite3 | 5301 ** METHOD: sqlite3 |
| 5064 ** | 5302 ** |
| 5065 ** ^The sqlite3_db_filename(D,N) interface returns a pointer to a filename | 5303 ** ^The sqlite3_db_filename(D,N) interface returns a pointer to a filename |
| 5066 ** associated with database N of connection D. ^The main database file | 5304 ** associated with database N of connection D. ^The main database file |
| 5067 ** has the name "main". If there is no attached database N on the database | 5305 ** has the name "main". If there is no attached database N on the database |
| 5068 ** connection D, or if database N is a temporary or in-memory database, then | 5306 ** connection D, or if database N is a temporary or in-memory database, then |
| 5069 ** a NULL pointer is returned. | 5307 ** a NULL pointer is returned. |
| 5070 ** | 5308 ** |
| 5071 ** ^The filename returned by this function is the output of the | 5309 ** ^The filename returned by this function is the output of the |
| 5072 ** xFullPathname method of the [VFS]. ^In other words, the filename | 5310 ** xFullPathname method of the [VFS]. ^In other words, the filename |
| 5073 ** will be an absolute pathname, even if the filename used | 5311 ** will be an absolute pathname, even if the filename used |
| 5074 ** to open the database originally was a URI or relative pathname. | 5312 ** to open the database originally was a URI or relative pathname. |
| 5075 */ | 5313 */ |
| 5076 SQLITE_API const char *SQLITE_STDCALL sqlite3_db_filename(sqlite3 *db, const cha
r *zDbName); | 5314 SQLITE_API const char *sqlite3_db_filename(sqlite3 *db, const char *zDbName); |
| 5077 | 5315 |
| 5078 /* | 5316 /* |
| 5079 ** CAPI3REF: Determine if a database is read-only | 5317 ** CAPI3REF: Determine if a database is read-only |
| 5080 ** METHOD: sqlite3 | 5318 ** METHOD: sqlite3 |
| 5081 ** | 5319 ** |
| 5082 ** ^The sqlite3_db_readonly(D,N) interface returns 1 if the database N | 5320 ** ^The sqlite3_db_readonly(D,N) interface returns 1 if the database N |
| 5083 ** of connection D is read-only, 0 if it is read/write, or -1 if N is not | 5321 ** of connection D is read-only, 0 if it is read/write, or -1 if N is not |
| 5084 ** the name of a database on connection D. | 5322 ** the name of a database on connection D. |
| 5085 */ | 5323 */ |
| 5086 SQLITE_API int SQLITE_STDCALL sqlite3_db_readonly(sqlite3 *db, const char *zDbNa
me); | 5324 SQLITE_API int sqlite3_db_readonly(sqlite3 *db, const char *zDbName); |
| 5087 | 5325 |
| 5088 /* | 5326 /* |
| 5089 ** CAPI3REF: Find the next prepared statement | 5327 ** CAPI3REF: Find the next prepared statement |
| 5090 ** METHOD: sqlite3 | 5328 ** METHOD: sqlite3 |
| 5091 ** | 5329 ** |
| 5092 ** ^This interface returns a pointer to the next [prepared statement] after | 5330 ** ^This interface returns a pointer to the next [prepared statement] after |
| 5093 ** pStmt associated with the [database connection] pDb. ^If pStmt is NULL | 5331 ** pStmt associated with the [database connection] pDb. ^If pStmt is NULL |
| 5094 ** then this interface returns a pointer to the first prepared statement | 5332 ** then this interface returns a pointer to the first prepared statement |
| 5095 ** associated with the database connection pDb. ^If no prepared statement | 5333 ** associated with the database connection pDb. ^If no prepared statement |
| 5096 ** satisfies the conditions of this routine, it returns NULL. | 5334 ** satisfies the conditions of this routine, it returns NULL. |
| 5097 ** | 5335 ** |
| 5098 ** The [database connection] pointer D in a call to | 5336 ** The [database connection] pointer D in a call to |
| 5099 ** [sqlite3_next_stmt(D,S)] must refer to an open database | 5337 ** [sqlite3_next_stmt(D,S)] must refer to an open database |
| 5100 ** connection and in particular must not be a NULL pointer. | 5338 ** connection and in particular must not be a NULL pointer. |
| 5101 */ | 5339 */ |
| 5102 SQLITE_API sqlite3_stmt *SQLITE_STDCALL sqlite3_next_stmt(sqlite3 *pDb, sqlite3_
stmt *pStmt); | 5340 SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt); |
| 5103 | 5341 |
| 5104 /* | 5342 /* |
| 5105 ** CAPI3REF: Commit And Rollback Notification Callbacks | 5343 ** CAPI3REF: Commit And Rollback Notification Callbacks |
| 5106 ** METHOD: sqlite3 | 5344 ** METHOD: sqlite3 |
| 5107 ** | 5345 ** |
| 5108 ** ^The sqlite3_commit_hook() interface registers a callback | 5346 ** ^The sqlite3_commit_hook() interface registers a callback |
| 5109 ** function to be invoked whenever a transaction is [COMMIT | committed]. | 5347 ** function to be invoked whenever a transaction is [COMMIT | committed]. |
| 5110 ** ^Any callback set by a previous call to sqlite3_commit_hook() | 5348 ** ^Any callback set by a previous call to sqlite3_commit_hook() |
| 5111 ** for the same database connection is overridden. | 5349 ** for the same database connection is overridden. |
| 5112 ** ^The sqlite3_rollback_hook() interface registers a callback | 5350 ** ^The sqlite3_rollback_hook() interface registers a callback |
| (...skipping 28 matching lines...) Expand all Loading... |
| 5141 ** hook returning non-zero, just as it would be with any other rollback. | 5379 ** hook returning non-zero, just as it would be with any other rollback. |
| 5142 ** | 5380 ** |
| 5143 ** ^For the purposes of this API, a transaction is said to have been | 5381 ** ^For the purposes of this API, a transaction is said to have been |
| 5144 ** rolled back if an explicit "ROLLBACK" statement is executed, or | 5382 ** rolled back if an explicit "ROLLBACK" statement is executed, or |
| 5145 ** an error or constraint causes an implicit rollback to occur. | 5383 ** an error or constraint causes an implicit rollback to occur. |
| 5146 ** ^The rollback callback is not invoked if a transaction is | 5384 ** ^The rollback callback is not invoked if a transaction is |
| 5147 ** automatically rolled back because the database connection is closed. | 5385 ** automatically rolled back because the database connection is closed. |
| 5148 ** | 5386 ** |
| 5149 ** See also the [sqlite3_update_hook()] interface. | 5387 ** See also the [sqlite3_update_hook()] interface. |
| 5150 */ | 5388 */ |
| 5151 SQLITE_API void *SQLITE_STDCALL sqlite3_commit_hook(sqlite3*, int(*)(void*), voi
d*); | 5389 SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); |
| 5152 SQLITE_API void *SQLITE_STDCALL sqlite3_rollback_hook(sqlite3*, void(*)(void *),
void*); | 5390 SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); |
| 5153 | 5391 |
| 5154 /* | 5392 /* |
| 5155 ** CAPI3REF: Data Change Notification Callbacks | 5393 ** CAPI3REF: Data Change Notification Callbacks |
| 5156 ** METHOD: sqlite3 | 5394 ** METHOD: sqlite3 |
| 5157 ** | 5395 ** |
| 5158 ** ^The sqlite3_update_hook() interface registers a callback function | 5396 ** ^The sqlite3_update_hook() interface registers a callback function |
| 5159 ** with the [database connection] identified by the first argument | 5397 ** with the [database connection] identified by the first argument |
| 5160 ** to be invoked whenever a row is updated, inserted or deleted in | 5398 ** to be invoked whenever a row is updated, inserted or deleted in |
| 5161 ** a rowid table. | 5399 ** a [rowid table]. |
| 5162 ** ^Any callback set by a previous call to this function | 5400 ** ^Any callback set by a previous call to this function |
| 5163 ** for the same database connection is overridden. | 5401 ** for the same database connection is overridden. |
| 5164 ** | 5402 ** |
| 5165 ** ^The second argument is a pointer to the function to invoke when a | 5403 ** ^The second argument is a pointer to the function to invoke when a |
| 5166 ** row is updated, inserted or deleted in a rowid table. | 5404 ** row is updated, inserted or deleted in a rowid table. |
| 5167 ** ^The first argument to the callback is a copy of the third argument | 5405 ** ^The first argument to the callback is a copy of the third argument |
| 5168 ** to sqlite3_update_hook(). | 5406 ** to sqlite3_update_hook(). |
| 5169 ** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE], | 5407 ** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE], |
| 5170 ** or [SQLITE_UPDATE], depending on the operation that caused the callback | 5408 ** or [SQLITE_UPDATE], depending on the operation that caused the callback |
| 5171 ** to be invoked. | 5409 ** to be invoked. |
| 5172 ** ^The third and fourth arguments to the callback contain pointers to the | 5410 ** ^The third and fourth arguments to the callback contain pointers to the |
| 5173 ** database and table name containing the affected row. | 5411 ** database and table name containing the affected row. |
| 5174 ** ^The final callback parameter is the [rowid] of the row. | 5412 ** ^The final callback parameter is the [rowid] of the row. |
| 5175 ** ^In the case of an update, this is the [rowid] after the update takes place. | 5413 ** ^In the case of an update, this is the [rowid] after the update takes place. |
| 5176 ** | 5414 ** |
| 5177 ** ^(The update hook is not invoked when internal system tables are | 5415 ** ^(The update hook is not invoked when internal system tables are |
| 5178 ** modified (i.e. sqlite_master and sqlite_sequence).)^ | 5416 ** modified (i.e. sqlite_master and sqlite_sequence).)^ |
| 5179 ** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified. | 5417 ** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified. |
| 5180 ** | 5418 ** |
| 5181 ** ^In the current implementation, the update hook | 5419 ** ^In the current implementation, the update hook |
| 5182 ** is not invoked when duplication rows are deleted because of an | 5420 ** is not invoked when conflicting rows are deleted because of an |
| 5183 ** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook | 5421 ** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook |
| 5184 ** invoked when rows are deleted using the [truncate optimization]. | 5422 ** invoked when rows are deleted using the [truncate optimization]. |
| 5185 ** The exceptions defined in this paragraph might change in a future | 5423 ** The exceptions defined in this paragraph might change in a future |
| 5186 ** release of SQLite. | 5424 ** release of SQLite. |
| 5187 ** | 5425 ** |
| 5188 ** The update hook implementation must not do anything that will modify | 5426 ** The update hook implementation must not do anything that will modify |
| 5189 ** the database connection that invoked the update hook. Any actions | 5427 ** the database connection that invoked the update hook. Any actions |
| 5190 ** to modify the database connection must be deferred until after the | 5428 ** to modify the database connection must be deferred until after the |
| 5191 ** completion of the [sqlite3_step()] call that triggered the update hook. | 5429 ** completion of the [sqlite3_step()] call that triggered the update hook. |
| 5192 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their | 5430 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their |
| 5193 ** database connections for the meaning of "modify" in this paragraph. | 5431 ** database connections for the meaning of "modify" in this paragraph. |
| 5194 ** | 5432 ** |
| 5195 ** ^The sqlite3_update_hook(D,C,P) function | 5433 ** ^The sqlite3_update_hook(D,C,P) function |
| 5196 ** returns the P argument from the previous call | 5434 ** returns the P argument from the previous call |
| 5197 ** on the same [database connection] D, or NULL for | 5435 ** on the same [database connection] D, or NULL for |
| 5198 ** the first call on D. | 5436 ** the first call on D. |
| 5199 ** | 5437 ** |
| 5200 ** See also the [sqlite3_commit_hook()] and [sqlite3_rollback_hook()] | 5438 ** See also the [sqlite3_commit_hook()], [sqlite3_rollback_hook()], |
| 5201 ** interfaces. | 5439 ** and [sqlite3_preupdate_hook()] interfaces. |
| 5202 */ | 5440 */ |
| 5203 SQLITE_API void *SQLITE_STDCALL sqlite3_update_hook( | 5441 SQLITE_API void *sqlite3_update_hook( |
| 5204 sqlite3*, | 5442 sqlite3*, |
| 5205 void(*)(void *,int ,char const *,char const *,sqlite3_int64), | 5443 void(*)(void *,int ,char const *,char const *,sqlite3_int64), |
| 5206 void* | 5444 void* |
| 5207 ); | 5445 ); |
| 5208 | 5446 |
| 5209 /* | 5447 /* |
| 5210 ** CAPI3REF: Enable Or Disable Shared Pager Cache | 5448 ** CAPI3REF: Enable Or Disable Shared Pager Cache |
| 5211 ** | 5449 ** |
| 5212 ** ^(This routine enables or disables the sharing of the database cache | 5450 ** ^(This routine enables or disables the sharing of the database cache |
| 5213 ** and schema data structures between [database connection | connections] | 5451 ** and schema data structures between [database connection | connections] |
| 5214 ** to the same database. Sharing is enabled if the argument is true | 5452 ** to the same database. Sharing is enabled if the argument is true |
| 5215 ** and disabled if the argument is false.)^ | 5453 ** and disabled if the argument is false.)^ |
| 5216 ** | 5454 ** |
| 5217 ** ^Cache sharing is enabled and disabled for an entire process. | 5455 ** ^Cache sharing is enabled and disabled for an entire process. |
| 5218 ** This is a change as of SQLite version 3.5.0. In prior versions of SQLite, | 5456 ** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]). |
| 5457 ** In prior versions of SQLite, |
| 5219 ** sharing was enabled or disabled for each thread separately. | 5458 ** sharing was enabled or disabled for each thread separately. |
| 5220 ** | 5459 ** |
| 5221 ** ^(The cache sharing mode set by this interface effects all subsequent | 5460 ** ^(The cache sharing mode set by this interface effects all subsequent |
| 5222 ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()]. | 5461 ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()]. |
| 5223 ** Existing database connections continue use the sharing mode | 5462 ** Existing database connections continue use the sharing mode |
| 5224 ** that was in effect at the time they were opened.)^ | 5463 ** that was in effect at the time they were opened.)^ |
| 5225 ** | 5464 ** |
| 5226 ** ^(This routine returns [SQLITE_OK] if shared cache was enabled or disabled | 5465 ** ^(This routine returns [SQLITE_OK] if shared cache was enabled or disabled |
| 5227 ** successfully. An [error code] is returned otherwise.)^ | 5466 ** successfully. An [error code] is returned otherwise.)^ |
| 5228 ** | 5467 ** |
| 5229 ** ^Shared cache is disabled by default. But this might change in | 5468 ** ^Shared cache is disabled by default. But this might change in |
| 5230 ** future releases of SQLite. Applications that care about shared | 5469 ** future releases of SQLite. Applications that care about shared |
| 5231 ** cache setting should set it explicitly. | 5470 ** cache setting should set it explicitly. |
| 5232 ** | 5471 ** |
| 5233 ** Note: This method is disabled on MacOS X 10.7 and iOS version 5.0 | 5472 ** Note: This method is disabled on MacOS X 10.7 and iOS version 5.0 |
| 5234 ** and will always return SQLITE_MISUSE. On those systems, | 5473 ** and will always return SQLITE_MISUSE. On those systems, |
| 5235 ** shared cache mode should be enabled per-database connection via | 5474 ** shared cache mode should be enabled per-database connection via |
| 5236 ** [sqlite3_open_v2()] with [SQLITE_OPEN_SHAREDCACHE]. | 5475 ** [sqlite3_open_v2()] with [SQLITE_OPEN_SHAREDCACHE]. |
| 5237 ** | 5476 ** |
| 5238 ** This interface is threadsafe on processors where writing a | 5477 ** This interface is threadsafe on processors where writing a |
| 5239 ** 32-bit integer is atomic. | 5478 ** 32-bit integer is atomic. |
| 5240 ** | 5479 ** |
| 5241 ** See Also: [SQLite Shared-Cache Mode] | 5480 ** See Also: [SQLite Shared-Cache Mode] |
| 5242 */ | 5481 */ |
| 5243 SQLITE_API int SQLITE_STDCALL sqlite3_enable_shared_cache(int); | 5482 SQLITE_API int sqlite3_enable_shared_cache(int); |
| 5244 | 5483 |
| 5245 /* | 5484 /* |
| 5246 ** CAPI3REF: Attempt To Free Heap Memory | 5485 ** CAPI3REF: Attempt To Free Heap Memory |
| 5247 ** | 5486 ** |
| 5248 ** ^The sqlite3_release_memory() interface attempts to free N bytes | 5487 ** ^The sqlite3_release_memory() interface attempts to free N bytes |
| 5249 ** of heap memory by deallocating non-essential memory allocations | 5488 ** of heap memory by deallocating non-essential memory allocations |
| 5250 ** held by the database library. Memory used to cache database | 5489 ** held by the database library. Memory used to cache database |
| 5251 ** pages to improve performance is an example of non-essential memory. | 5490 ** pages to improve performance is an example of non-essential memory. |
| 5252 ** ^sqlite3_release_memory() returns the number of bytes actually freed, | 5491 ** ^sqlite3_release_memory() returns the number of bytes actually freed, |
| 5253 ** which might be more or less than the amount requested. | 5492 ** which might be more or less than the amount requested. |
| 5254 ** ^The sqlite3_release_memory() routine is a no-op returning zero | 5493 ** ^The sqlite3_release_memory() routine is a no-op returning zero |
| 5255 ** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT]. | 5494 ** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT]. |
| 5256 ** | 5495 ** |
| 5257 ** See also: [sqlite3_db_release_memory()] | 5496 ** See also: [sqlite3_db_release_memory()] |
| 5258 */ | 5497 */ |
| 5259 SQLITE_API int SQLITE_STDCALL sqlite3_release_memory(int); | 5498 SQLITE_API int sqlite3_release_memory(int); |
| 5260 | 5499 |
| 5261 /* | 5500 /* |
| 5262 ** CAPI3REF: Free Memory Used By A Database Connection | 5501 ** CAPI3REF: Free Memory Used By A Database Connection |
| 5263 ** METHOD: sqlite3 | 5502 ** METHOD: sqlite3 |
| 5264 ** | 5503 ** |
| 5265 ** ^The sqlite3_db_release_memory(D) interface attempts to free as much heap | 5504 ** ^The sqlite3_db_release_memory(D) interface attempts to free as much heap |
| 5266 ** memory as possible from database connection D. Unlike the | 5505 ** memory as possible from database connection D. Unlike the |
| 5267 ** [sqlite3_release_memory()] interface, this interface is in effect even | 5506 ** [sqlite3_release_memory()] interface, this interface is in effect even |
| 5268 ** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is | 5507 ** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is |
| 5269 ** omitted. | 5508 ** omitted. |
| 5270 ** | 5509 ** |
| 5271 ** See also: [sqlite3_release_memory()] | 5510 ** See also: [sqlite3_release_memory()] |
| 5272 */ | 5511 */ |
| 5273 SQLITE_API int SQLITE_STDCALL sqlite3_db_release_memory(sqlite3*); | 5512 SQLITE_API int sqlite3_db_release_memory(sqlite3*); |
| 5274 | 5513 |
| 5275 /* | 5514 /* |
| 5276 ** CAPI3REF: Impose A Limit On Heap Size | 5515 ** CAPI3REF: Impose A Limit On Heap Size |
| 5277 ** | 5516 ** |
| 5278 ** ^The sqlite3_soft_heap_limit64() interface sets and/or queries the | 5517 ** ^The sqlite3_soft_heap_limit64() interface sets and/or queries the |
| 5279 ** soft limit on the amount of heap memory that may be allocated by SQLite. | 5518 ** soft limit on the amount of heap memory that may be allocated by SQLite. |
| 5280 ** ^SQLite strives to keep heap memory utilization below the soft heap | 5519 ** ^SQLite strives to keep heap memory utilization below the soft heap |
| 5281 ** limit by reducing the number of pages held in the page cache | 5520 ** limit by reducing the number of pages held in the page cache |
| 5282 ** as heap memory usages approaches the limit. | 5521 ** as heap memory usages approaches the limit. |
| 5283 ** ^The soft heap limit is "soft" because even though SQLite strives to stay | 5522 ** ^The soft heap limit is "soft" because even though SQLite strives to stay |
| (...skipping 18 matching lines...) Expand all Loading... |
| 5302 ** <li> Memory accounting is disabled using a combination of the | 5541 ** <li> Memory accounting is disabled using a combination of the |
| 5303 ** [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and | 5542 ** [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and |
| 5304 ** the [SQLITE_DEFAULT_MEMSTATUS] compile-time option. | 5543 ** the [SQLITE_DEFAULT_MEMSTATUS] compile-time option. |
| 5305 ** <li> An alternative page cache implementation is specified using | 5544 ** <li> An alternative page cache implementation is specified using |
| 5306 ** [sqlite3_config]([SQLITE_CONFIG_PCACHE2],...). | 5545 ** [sqlite3_config]([SQLITE_CONFIG_PCACHE2],...). |
| 5307 ** <li> The page cache allocates from its own memory pool supplied | 5546 ** <li> The page cache allocates from its own memory pool supplied |
| 5308 ** by [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],...) rather than | 5547 ** by [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],...) rather than |
| 5309 ** from the heap. | 5548 ** from the heap. |
| 5310 ** </ul>)^ | 5549 ** </ul>)^ |
| 5311 ** | 5550 ** |
| 5312 ** Beginning with SQLite version 3.7.3, the soft heap limit is enforced | 5551 ** Beginning with SQLite [version 3.7.3] ([dateof:3.7.3]), |
| 5552 ** the soft heap limit is enforced |
| 5313 ** regardless of whether or not the [SQLITE_ENABLE_MEMORY_MANAGEMENT] | 5553 ** regardless of whether or not the [SQLITE_ENABLE_MEMORY_MANAGEMENT] |
| 5314 ** compile-time option is invoked. With [SQLITE_ENABLE_MEMORY_MANAGEMENT], | 5554 ** compile-time option is invoked. With [SQLITE_ENABLE_MEMORY_MANAGEMENT], |
| 5315 ** the soft heap limit is enforced on every memory allocation. Without | 5555 ** the soft heap limit is enforced on every memory allocation. Without |
| 5316 ** [SQLITE_ENABLE_MEMORY_MANAGEMENT], the soft heap limit is only enforced | 5556 ** [SQLITE_ENABLE_MEMORY_MANAGEMENT], the soft heap limit is only enforced |
| 5317 ** when memory is allocated by the page cache. Testing suggests that because | 5557 ** when memory is allocated by the page cache. Testing suggests that because |
| 5318 ** the page cache is the predominate memory user in SQLite, most | 5558 ** the page cache is the predominate memory user in SQLite, most |
| 5319 ** applications will achieve adequate soft heap limit enforcement without | 5559 ** applications will achieve adequate soft heap limit enforcement without |
| 5320 ** the use of [SQLITE_ENABLE_MEMORY_MANAGEMENT]. | 5560 ** the use of [SQLITE_ENABLE_MEMORY_MANAGEMENT]. |
| 5321 ** | 5561 ** |
| 5322 ** The circumstances under which SQLite will enforce the soft heap limit may | 5562 ** The circumstances under which SQLite will enforce the soft heap limit may |
| 5323 ** changes in future releases of SQLite. | 5563 ** changes in future releases of SQLite. |
| 5324 */ | 5564 */ |
| 5325 SQLITE_API sqlite3_int64 SQLITE_STDCALL sqlite3_soft_heap_limit64(sqlite3_int64
N); | 5565 SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N); |
| 5326 | 5566 |
| 5327 /* | 5567 /* |
| 5328 ** CAPI3REF: Deprecated Soft Heap Limit Interface | 5568 ** CAPI3REF: Deprecated Soft Heap Limit Interface |
| 5329 ** DEPRECATED | 5569 ** DEPRECATED |
| 5330 ** | 5570 ** |
| 5331 ** This is a deprecated version of the [sqlite3_soft_heap_limit64()] | 5571 ** This is a deprecated version of the [sqlite3_soft_heap_limit64()] |
| 5332 ** interface. This routine is provided for historical compatibility | 5572 ** interface. This routine is provided for historical compatibility |
| 5333 ** only. All new applications should use the | 5573 ** only. All new applications should use the |
| 5334 ** [sqlite3_soft_heap_limit64()] interface rather than this one. | 5574 ** [sqlite3_soft_heap_limit64()] interface rather than this one. |
| 5335 */ | 5575 */ |
| 5336 SQLITE_API SQLITE_DEPRECATED void SQLITE_STDCALL sqlite3_soft_heap_limit(int N); | 5576 SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N); |
| 5337 | 5577 |
| 5338 | 5578 |
| 5339 /* | 5579 /* |
| 5340 ** CAPI3REF: Extract Metadata About A Column Of A Table | 5580 ** CAPI3REF: Extract Metadata About A Column Of A Table |
| 5341 ** METHOD: sqlite3 | 5581 ** METHOD: sqlite3 |
| 5342 ** | 5582 ** |
| 5343 ** ^(The sqlite3_table_column_metadata(X,D,T,C,....) routine returns | 5583 ** ^(The sqlite3_table_column_metadata(X,D,T,C,....) routine returns |
| 5344 ** information about column C of table T in database D | 5584 ** information about column C of table T in database D |
| 5345 ** on [database connection] X.)^ ^The sqlite3_table_column_metadata() | 5585 ** on [database connection] X.)^ ^The sqlite3_table_column_metadata() |
| 5346 ** interface returns SQLITE_OK and fills in the non-NULL pointers in | 5586 ** interface returns SQLITE_OK and fills in the non-NULL pointers in |
| 5347 ** the final five arguments with appropriate values if the specified | 5587 ** the final five arguments with appropriate values if the specified |
| 5348 ** column exists. ^The sqlite3_table_column_metadata() interface returns | 5588 ** column exists. ^The sqlite3_table_column_metadata() interface returns |
| 5349 ** SQLITE_ERROR and if the specified column does not exist. | 5589 ** SQLITE_ERROR and if the specified column does not exist. |
| 5350 ** ^If the column-name parameter to sqlite3_table_column_metadata() is a | 5590 ** ^If the column-name parameter to sqlite3_table_column_metadata() is a |
| 5351 ** NULL pointer, then this routine simply checks for the existance of the | 5591 ** NULL pointer, then this routine simply checks for the existence of the |
| 5352 ** table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it | 5592 ** table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it |
| 5353 ** does not. | 5593 ** does not. |
| 5354 ** | 5594 ** |
| 5355 ** ^The column is identified by the second, third and fourth parameters to | 5595 ** ^The column is identified by the second, third and fourth parameters to |
| 5356 ** this function. ^(The second parameter is either the name of the database | 5596 ** this function. ^(The second parameter is either the name of the database |
| 5357 ** (i.e. "main", "temp", or an attached database) containing the specified | 5597 ** (i.e. "main", "temp", or an attached database) containing the specified |
| 5358 ** table or NULL.)^ ^If it is NULL, then all attached databases are searched | 5598 ** table or NULL.)^ ^If it is NULL, then all attached databases are searched |
| 5359 ** for the table using the same algorithm used by the database engine to | 5599 ** for the table using the same algorithm used by the database engine to |
| 5360 ** resolve unqualified table references. | 5600 ** resolve unqualified table references. |
| 5361 ** | 5601 ** |
| (...skipping 34 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 5396 ** collation sequence: "BINARY" | 5636 ** collation sequence: "BINARY" |
| 5397 ** not null: 0 | 5637 ** not null: 0 |
| 5398 ** primary key: 1 | 5638 ** primary key: 1 |
| 5399 ** auto increment: 0 | 5639 ** auto increment: 0 |
| 5400 ** </pre>)^ | 5640 ** </pre>)^ |
| 5401 ** | 5641 ** |
| 5402 ** ^This function causes all database schemas to be read from disk and | 5642 ** ^This function causes all database schemas to be read from disk and |
| 5403 ** parsed, if that has not already been done, and returns an error if | 5643 ** parsed, if that has not already been done, and returns an error if |
| 5404 ** any errors are encountered while loading the schema. | 5644 ** any errors are encountered while loading the schema. |
| 5405 */ | 5645 */ |
| 5406 SQLITE_API int SQLITE_STDCALL sqlite3_table_column_metadata( | 5646 SQLITE_API int sqlite3_table_column_metadata( |
| 5407 sqlite3 *db, /* Connection handle */ | 5647 sqlite3 *db, /* Connection handle */ |
| 5408 const char *zDbName, /* Database name or NULL */ | 5648 const char *zDbName, /* Database name or NULL */ |
| 5409 const char *zTableName, /* Table name */ | 5649 const char *zTableName, /* Table name */ |
| 5410 const char *zColumnName, /* Column name */ | 5650 const char *zColumnName, /* Column name */ |
| 5411 char const **pzDataType, /* OUTPUT: Declared data type */ | 5651 char const **pzDataType, /* OUTPUT: Declared data type */ |
| 5412 char const **pzCollSeq, /* OUTPUT: Collation sequence name */ | 5652 char const **pzCollSeq, /* OUTPUT: Collation sequence name */ |
| 5413 int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ | 5653 int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ |
| 5414 int *pPrimaryKey, /* OUTPUT: True if column part of PK */ | 5654 int *pPrimaryKey, /* OUTPUT: True if column part of PK */ |
| 5415 int *pAutoinc /* OUTPUT: True if column is auto-increment */ | 5655 int *pAutoinc /* OUTPUT: True if column is auto-increment */ |
| 5416 ); | 5656 ); |
| (...skipping 21 matching lines...) Expand all Loading... |
| 5438 ** "." and omitting any initial "lib".)^ | 5678 ** "." and omitting any initial "lib".)^ |
| 5439 ** ^The sqlite3_load_extension() interface returns | 5679 ** ^The sqlite3_load_extension() interface returns |
| 5440 ** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. | 5680 ** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. |
| 5441 ** ^If an error occurs and pzErrMsg is not 0, then the | 5681 ** ^If an error occurs and pzErrMsg is not 0, then the |
| 5442 ** [sqlite3_load_extension()] interface shall attempt to | 5682 ** [sqlite3_load_extension()] interface shall attempt to |
| 5443 ** fill *pzErrMsg with error message text stored in memory | 5683 ** fill *pzErrMsg with error message text stored in memory |
| 5444 ** obtained from [sqlite3_malloc()]. The calling function | 5684 ** obtained from [sqlite3_malloc()]. The calling function |
| 5445 ** should free this memory by calling [sqlite3_free()]. | 5685 ** should free this memory by calling [sqlite3_free()]. |
| 5446 ** | 5686 ** |
| 5447 ** ^Extension loading must be enabled using | 5687 ** ^Extension loading must be enabled using |
| 5448 ** [sqlite3_enable_load_extension()] prior to calling this API, | 5688 ** [sqlite3_enable_load_extension()] or |
| 5689 ** [sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],1,NULL) |
| 5690 ** prior to calling this API, |
| 5449 ** otherwise an error will be returned. | 5691 ** otherwise an error will be returned. |
| 5450 ** | 5692 ** |
| 5693 ** <b>Security warning:</b> It is recommended that the |
| 5694 ** [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method be used to enable only this |
| 5695 ** interface. The use of the [sqlite3_enable_load_extension()] interface |
| 5696 ** should be avoided. This will keep the SQL function [load_extension()] |
| 5697 ** disabled and prevent SQL injections from giving attackers |
| 5698 ** access to extension loading capabilities. |
| 5699 ** |
| 5451 ** See also the [load_extension() SQL function]. | 5700 ** See also the [load_extension() SQL function]. |
| 5452 */ | 5701 */ |
| 5453 SQLITE_API int SQLITE_STDCALL sqlite3_load_extension( | 5702 SQLITE_API int sqlite3_load_extension( |
| 5454 sqlite3 *db, /* Load the extension into this database connection */ | 5703 sqlite3 *db, /* Load the extension into this database connection */ |
| 5455 const char *zFile, /* Name of the shared library containing extension */ | 5704 const char *zFile, /* Name of the shared library containing extension */ |
| 5456 const char *zProc, /* Entry point. Derived from zFile if 0 */ | 5705 const char *zProc, /* Entry point. Derived from zFile if 0 */ |
| 5457 char **pzErrMsg /* Put error message here if not 0 */ | 5706 char **pzErrMsg /* Put error message here if not 0 */ |
| 5458 ); | 5707 ); |
| 5459 | 5708 |
| 5460 /* | 5709 /* |
| 5461 ** CAPI3REF: Enable Or Disable Extension Loading | 5710 ** CAPI3REF: Enable Or Disable Extension Loading |
| 5462 ** METHOD: sqlite3 | 5711 ** METHOD: sqlite3 |
| 5463 ** | 5712 ** |
| 5464 ** ^So as not to open security holes in older applications that are | 5713 ** ^So as not to open security holes in older applications that are |
| 5465 ** unprepared to deal with [extension loading], and as a means of disabling | 5714 ** unprepared to deal with [extension loading], and as a means of disabling |
| 5466 ** [extension loading] while evaluating user-entered SQL, the following API | 5715 ** [extension loading] while evaluating user-entered SQL, the following API |
| 5467 ** is provided to turn the [sqlite3_load_extension()] mechanism on and off. | 5716 ** is provided to turn the [sqlite3_load_extension()] mechanism on and off. |
| 5468 ** | 5717 ** |
| 5469 ** ^Extension loading is off by default. | 5718 ** ^Extension loading is off by default. |
| 5470 ** ^Call the sqlite3_enable_load_extension() routine with onoff==1 | 5719 ** ^Call the sqlite3_enable_load_extension() routine with onoff==1 |
| 5471 ** to turn extension loading on and call it with onoff==0 to turn | 5720 ** to turn extension loading on and call it with onoff==0 to turn |
| 5472 ** it back off again. | 5721 ** it back off again. |
| 5722 ** |
| 5723 ** ^This interface enables or disables both the C-API |
| 5724 ** [sqlite3_load_extension()] and the SQL function [load_extension()]. |
| 5725 ** ^(Use [sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],..) |
| 5726 ** to enable or disable only the C-API.)^ |
| 5727 ** |
| 5728 ** <b>Security warning:</b> It is recommended that extension loading |
| 5729 ** be disabled using the [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method |
| 5730 ** rather than this interface, so the [load_extension()] SQL function |
| 5731 ** remains disabled. This will prevent SQL injections from giving attackers |
| 5732 ** access to extension loading capabilities. |
| 5473 */ | 5733 */ |
| 5474 SQLITE_API int SQLITE_STDCALL sqlite3_enable_load_extension(sqlite3 *db, int ono
ff); | 5734 SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff); |
| 5475 | 5735 |
| 5476 /* | 5736 /* |
| 5477 ** CAPI3REF: Automatically Load Statically Linked Extensions | 5737 ** CAPI3REF: Automatically Load Statically Linked Extensions |
| 5478 ** | 5738 ** |
| 5479 ** ^This interface causes the xEntryPoint() function to be invoked for | 5739 ** ^This interface causes the xEntryPoint() function to be invoked for |
| 5480 ** each new [database connection] that is created. The idea here is that | 5740 ** each new [database connection] that is created. The idea here is that |
| 5481 ** xEntryPoint() is the entry point for a statically linked [SQLite extension] | 5741 ** xEntryPoint() is the entry point for a statically linked [SQLite extension] |
| 5482 ** that is to be automatically loaded into all new database connections. | 5742 ** that is to be automatically loaded into all new database connections. |
| 5483 ** | 5743 ** |
| 5484 ** ^(Even though the function prototype shows that xEntryPoint() takes | 5744 ** ^(Even though the function prototype shows that xEntryPoint() takes |
| 5485 ** no arguments and returns void, SQLite invokes xEntryPoint() with three | 5745 ** no arguments and returns void, SQLite invokes xEntryPoint() with three |
| 5486 ** arguments and expects and integer result as if the signature of the | 5746 ** arguments and expects an integer result as if the signature of the |
| 5487 ** entry point where as follows: | 5747 ** entry point where as follows: |
| 5488 ** | 5748 ** |
| 5489 ** <blockquote><pre> | 5749 ** <blockquote><pre> |
| 5490 ** int xEntryPoint( | 5750 ** int xEntryPoint( |
| 5491 ** sqlite3 *db, | 5751 ** sqlite3 *db, |
| 5492 ** const char **pzErrMsg, | 5752 ** const char **pzErrMsg, |
| 5493 ** const struct sqlite3_api_routines *pThunk | 5753 ** const struct sqlite3_api_routines *pThunk |
| 5494 ** ); | 5754 ** ); |
| 5495 ** </pre></blockquote>)^ | 5755 ** </pre></blockquote>)^ |
| 5496 ** | 5756 ** |
| 5497 ** If the xEntryPoint routine encounters an error, it should make *pzErrMsg | 5757 ** If the xEntryPoint routine encounters an error, it should make *pzErrMsg |
| 5498 ** point to an appropriate error message (obtained from [sqlite3_mprintf()]) | 5758 ** point to an appropriate error message (obtained from [sqlite3_mprintf()]) |
| 5499 ** and return an appropriate [error code]. ^SQLite ensures that *pzErrMsg | 5759 ** and return an appropriate [error code]. ^SQLite ensures that *pzErrMsg |
| 5500 ** is NULL before calling the xEntryPoint(). ^SQLite will invoke | 5760 ** is NULL before calling the xEntryPoint(). ^SQLite will invoke |
| 5501 ** [sqlite3_free()] on *pzErrMsg after xEntryPoint() returns. ^If any | 5761 ** [sqlite3_free()] on *pzErrMsg after xEntryPoint() returns. ^If any |
| 5502 ** xEntryPoint() returns an error, the [sqlite3_open()], [sqlite3_open16()], | 5762 ** xEntryPoint() returns an error, the [sqlite3_open()], [sqlite3_open16()], |
| 5503 ** or [sqlite3_open_v2()] call that provoked the xEntryPoint() will fail. | 5763 ** or [sqlite3_open_v2()] call that provoked the xEntryPoint() will fail. |
| 5504 ** | 5764 ** |
| 5505 ** ^Calling sqlite3_auto_extension(X) with an entry point X that is already | 5765 ** ^Calling sqlite3_auto_extension(X) with an entry point X that is already |
| 5506 ** on the list of automatic extensions is a harmless no-op. ^No entry point | 5766 ** on the list of automatic extensions is a harmless no-op. ^No entry point |
| 5507 ** will be called more than once for each database connection that is opened. | 5767 ** will be called more than once for each database connection that is opened. |
| 5508 ** | 5768 ** |
| 5509 ** See also: [sqlite3_reset_auto_extension()] | 5769 ** See also: [sqlite3_reset_auto_extension()] |
| 5510 ** and [sqlite3_cancel_auto_extension()] | 5770 ** and [sqlite3_cancel_auto_extension()] |
| 5511 */ | 5771 */ |
| 5512 SQLITE_API int SQLITE_STDCALL sqlite3_auto_extension(void (*xEntryPoint)(void)); | 5772 SQLITE_API int sqlite3_auto_extension(void(*xEntryPoint)(void)); |
| 5513 | 5773 |
| 5514 /* | 5774 /* |
| 5515 ** CAPI3REF: Cancel Automatic Extension Loading | 5775 ** CAPI3REF: Cancel Automatic Extension Loading |
| 5516 ** | 5776 ** |
| 5517 ** ^The [sqlite3_cancel_auto_extension(X)] interface unregisters the | 5777 ** ^The [sqlite3_cancel_auto_extension(X)] interface unregisters the |
| 5518 ** initialization routine X that was registered using a prior call to | 5778 ** initialization routine X that was registered using a prior call to |
| 5519 ** [sqlite3_auto_extension(X)]. ^The [sqlite3_cancel_auto_extension(X)] | 5779 ** [sqlite3_auto_extension(X)]. ^The [sqlite3_cancel_auto_extension(X)] |
| 5520 ** routine returns 1 if initialization routine X was successfully | 5780 ** routine returns 1 if initialization routine X was successfully |
| 5521 ** unregistered and it returns 0 if X was not on the list of initialization | 5781 ** unregistered and it returns 0 if X was not on the list of initialization |
| 5522 ** routines. | 5782 ** routines. |
| 5523 */ | 5783 */ |
| 5524 SQLITE_API int SQLITE_STDCALL sqlite3_cancel_auto_extension(void (*xEntryPoint)(
void)); | 5784 SQLITE_API int sqlite3_cancel_auto_extension(void(*xEntryPoint)(void)); |
| 5525 | 5785 |
| 5526 /* | 5786 /* |
| 5527 ** CAPI3REF: Reset Automatic Extension Loading | 5787 ** CAPI3REF: Reset Automatic Extension Loading |
| 5528 ** | 5788 ** |
| 5529 ** ^This interface disables all automatic extensions previously | 5789 ** ^This interface disables all automatic extensions previously |
| 5530 ** registered using [sqlite3_auto_extension()]. | 5790 ** registered using [sqlite3_auto_extension()]. |
| 5531 */ | 5791 */ |
| 5532 SQLITE_API void SQLITE_STDCALL sqlite3_reset_auto_extension(void); | 5792 SQLITE_API void sqlite3_reset_auto_extension(void); |
| 5533 | 5793 |
| 5534 /* | 5794 /* |
| 5535 ** The interface to the virtual-table mechanism is currently considered | 5795 ** The interface to the virtual-table mechanism is currently considered |
| 5536 ** to be experimental. The interface might change in incompatible ways. | 5796 ** to be experimental. The interface might change in incompatible ways. |
| 5537 ** If this is a problem for you, do not use the interface at this time. | 5797 ** If this is a problem for you, do not use the interface at this time. |
| 5538 ** | 5798 ** |
| 5539 ** When the virtual-table mechanism stabilizes, we will declare the | 5799 ** When the virtual-table mechanism stabilizes, we will declare the |
| 5540 ** interface fixed, support it indefinitely, and remove this comment. | 5800 ** interface fixed, support it indefinitely, and remove this comment. |
| 5541 */ | 5801 */ |
| 5542 | 5802 |
| (...skipping 133 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 5676 ** SQLite also assumes that if a call to the xUpdate() method is made as | 5936 ** SQLite also assumes that if a call to the xUpdate() method is made as |
| 5677 ** part of the same statement to delete or update a virtual table row and the | 5937 ** part of the same statement to delete or update a virtual table row and the |
| 5678 ** implementation returns SQLITE_CONSTRAINT, then there is no need to rollback | 5938 ** implementation returns SQLITE_CONSTRAINT, then there is no need to rollback |
| 5679 ** any database changes. In other words, if the xUpdate() returns | 5939 ** any database changes. In other words, if the xUpdate() returns |
| 5680 ** SQLITE_CONSTRAINT, the database contents must be exactly as they were | 5940 ** SQLITE_CONSTRAINT, the database contents must be exactly as they were |
| 5681 ** before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not | 5941 ** before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not |
| 5682 ** set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by | 5942 ** set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by |
| 5683 ** the xUpdate method are automatically rolled back by SQLite. | 5943 ** the xUpdate method are automatically rolled back by SQLite. |
| 5684 ** | 5944 ** |
| 5685 ** IMPORTANT: The estimatedRows field was added to the sqlite3_index_info | 5945 ** IMPORTANT: The estimatedRows field was added to the sqlite3_index_info |
| 5686 ** structure for SQLite version 3.8.2. If a virtual table extension is | 5946 ** structure for SQLite [version 3.8.2] ([dateof:3.8.2]). |
| 5947 ** If a virtual table extension is |
| 5687 ** used with an SQLite version earlier than 3.8.2, the results of attempting | 5948 ** used with an SQLite version earlier than 3.8.2, the results of attempting |
| 5688 ** to read or write the estimatedRows field are undefined (but are likely | 5949 ** to read or write the estimatedRows field are undefined (but are likely |
| 5689 ** to included crashing the application). The estimatedRows field should | 5950 ** to included crashing the application). The estimatedRows field should |
| 5690 ** therefore only be used if [sqlite3_libversion_number()] returns a | 5951 ** therefore only be used if [sqlite3_libversion_number()] returns a |
| 5691 ** value greater than or equal to 3008002. Similarly, the idxFlags field | 5952 ** value greater than or equal to 3008002. Similarly, the idxFlags field |
| 5692 ** was added for version 3.9.0. It may therefore only be used if | 5953 ** was added for [version 3.9.0] ([dateof:3.9.0]). |
| 5954 ** It may therefore only be used if |
| 5693 ** sqlite3_libversion_number() returns a value greater than or equal to | 5955 ** sqlite3_libversion_number() returns a value greater than or equal to |
| 5694 ** 3009000. | 5956 ** 3009000. |
| 5695 */ | 5957 */ |
| 5696 struct sqlite3_index_info { | 5958 struct sqlite3_index_info { |
| 5697 /* Inputs */ | 5959 /* Inputs */ |
| 5698 int nConstraint; /* Number of entries in aConstraint */ | 5960 int nConstraint; /* Number of entries in aConstraint */ |
| 5699 struct sqlite3_index_constraint { | 5961 struct sqlite3_index_constraint { |
| 5700 int iColumn; /* Column on left-hand side of constraint */ | 5962 int iColumn; /* Column constrained. -1 for ROWID */ |
| 5701 unsigned char op; /* Constraint operator */ | 5963 unsigned char op; /* Constraint operator */ |
| 5702 unsigned char usable; /* True if this constraint is usable */ | 5964 unsigned char usable; /* True if this constraint is usable */ |
| 5703 int iTermOffset; /* Used internally - xBestIndex should ignore */ | 5965 int iTermOffset; /* Used internally - xBestIndex should ignore */ |
| 5704 } *aConstraint; /* Table of WHERE clause constraints */ | 5966 } *aConstraint; /* Table of WHERE clause constraints */ |
| 5705 int nOrderBy; /* Number of terms in the ORDER BY clause */ | 5967 int nOrderBy; /* Number of terms in the ORDER BY clause */ |
| 5706 struct sqlite3_index_orderby { | 5968 struct sqlite3_index_orderby { |
| 5707 int iColumn; /* Column number */ | 5969 int iColumn; /* Column number */ |
| 5708 unsigned char desc; /* True for DESC. False for ASC. */ | 5970 unsigned char desc; /* True for DESC. False for ASC. */ |
| 5709 } *aOrderBy; /* The ORDER BY clause */ | 5971 } *aOrderBy; /* The ORDER BY clause */ |
| 5710 /* Outputs */ | 5972 /* Outputs */ |
| (...skipping 56 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 5767 ** | 6029 ** |
| 5768 ** ^The sqlite3_create_module_v2() interface has a fifth parameter which | 6030 ** ^The sqlite3_create_module_v2() interface has a fifth parameter which |
| 5769 ** is a pointer to a destructor for the pClientData. ^SQLite will | 6031 ** is a pointer to a destructor for the pClientData. ^SQLite will |
| 5770 ** invoke the destructor function (if it is not NULL) when SQLite | 6032 ** invoke the destructor function (if it is not NULL) when SQLite |
| 5771 ** no longer needs the pClientData pointer. ^The destructor will also | 6033 ** no longer needs the pClientData pointer. ^The destructor will also |
| 5772 ** be invoked if the call to sqlite3_create_module_v2() fails. | 6034 ** be invoked if the call to sqlite3_create_module_v2() fails. |
| 5773 ** ^The sqlite3_create_module() | 6035 ** ^The sqlite3_create_module() |
| 5774 ** interface is equivalent to sqlite3_create_module_v2() with a NULL | 6036 ** interface is equivalent to sqlite3_create_module_v2() with a NULL |
| 5775 ** destructor. | 6037 ** destructor. |
| 5776 */ | 6038 */ |
| 5777 SQLITE_API int SQLITE_STDCALL sqlite3_create_module( | 6039 SQLITE_API int sqlite3_create_module( |
| 5778 sqlite3 *db, /* SQLite connection to register module with */ | 6040 sqlite3 *db, /* SQLite connection to register module with */ |
| 5779 const char *zName, /* Name of the module */ | 6041 const char *zName, /* Name of the module */ |
| 5780 const sqlite3_module *p, /* Methods for the module */ | 6042 const sqlite3_module *p, /* Methods for the module */ |
| 5781 void *pClientData /* Client data for xCreate/xConnect */ | 6043 void *pClientData /* Client data for xCreate/xConnect */ |
| 5782 ); | 6044 ); |
| 5783 SQLITE_API int SQLITE_STDCALL sqlite3_create_module_v2( | 6045 SQLITE_API int sqlite3_create_module_v2( |
| 5784 sqlite3 *db, /* SQLite connection to register module with */ | 6046 sqlite3 *db, /* SQLite connection to register module with */ |
| 5785 const char *zName, /* Name of the module */ | 6047 const char *zName, /* Name of the module */ |
| 5786 const sqlite3_module *p, /* Methods for the module */ | 6048 const sqlite3_module *p, /* Methods for the module */ |
| 5787 void *pClientData, /* Client data for xCreate/xConnect */ | 6049 void *pClientData, /* Client data for xCreate/xConnect */ |
| 5788 void(*xDestroy)(void*) /* Module destructor function */ | 6050 void(*xDestroy)(void*) /* Module destructor function */ |
| 5789 ); | 6051 ); |
| 5790 | 6052 |
| 5791 /* | 6053 /* |
| 5792 ** CAPI3REF: Virtual Table Instance Object | 6054 ** CAPI3REF: Virtual Table Instance Object |
| 5793 ** KEYWORDS: sqlite3_vtab | 6055 ** KEYWORDS: sqlite3_vtab |
| (...skipping 42 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 5836 }; | 6098 }; |
| 5837 | 6099 |
| 5838 /* | 6100 /* |
| 5839 ** CAPI3REF: Declare The Schema Of A Virtual Table | 6101 ** CAPI3REF: Declare The Schema Of A Virtual Table |
| 5840 ** | 6102 ** |
| 5841 ** ^The [xCreate] and [xConnect] methods of a | 6103 ** ^The [xCreate] and [xConnect] methods of a |
| 5842 ** [virtual table module] call this interface | 6104 ** [virtual table module] call this interface |
| 5843 ** to declare the format (the names and datatypes of the columns) of | 6105 ** to declare the format (the names and datatypes of the columns) of |
| 5844 ** the virtual tables they implement. | 6106 ** the virtual tables they implement. |
| 5845 */ | 6107 */ |
| 5846 SQLITE_API int SQLITE_STDCALL sqlite3_declare_vtab(sqlite3*, const char *zSQL); | 6108 SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL); |
| 5847 | 6109 |
| 5848 /* | 6110 /* |
| 5849 ** CAPI3REF: Overload A Function For A Virtual Table | 6111 ** CAPI3REF: Overload A Function For A Virtual Table |
| 5850 ** METHOD: sqlite3 | 6112 ** METHOD: sqlite3 |
| 5851 ** | 6113 ** |
| 5852 ** ^(Virtual tables can provide alternative implementations of functions | 6114 ** ^(Virtual tables can provide alternative implementations of functions |
| 5853 ** using the [xFindFunction] method of the [virtual table module]. | 6115 ** using the [xFindFunction] method of the [virtual table module]. |
| 5854 ** But global versions of those functions | 6116 ** But global versions of those functions |
| 5855 ** must exist in order to be overloaded.)^ | 6117 ** must exist in order to be overloaded.)^ |
| 5856 ** | 6118 ** |
| 5857 ** ^(This API makes sure a global version of a function with a particular | 6119 ** ^(This API makes sure a global version of a function with a particular |
| 5858 ** name and number of parameters exists. If no such function exists | 6120 ** name and number of parameters exists. If no such function exists |
| 5859 ** before this API is called, a new function is created.)^ ^The implementation | 6121 ** before this API is called, a new function is created.)^ ^The implementation |
| 5860 ** of the new function always causes an exception to be thrown. So | 6122 ** of the new function always causes an exception to be thrown. So |
| 5861 ** the new function is not good for anything by itself. Its only | 6123 ** the new function is not good for anything by itself. Its only |
| 5862 ** purpose is to be a placeholder function that can be overloaded | 6124 ** purpose is to be a placeholder function that can be overloaded |
| 5863 ** by a [virtual table]. | 6125 ** by a [virtual table]. |
| 5864 */ | 6126 */ |
| 5865 SQLITE_API int SQLITE_STDCALL sqlite3_overload_function(sqlite3*, const char *zF
uncName, int nArg); | 6127 SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nA
rg); |
| 5866 | 6128 |
| 5867 /* | 6129 /* |
| 5868 ** The interface to the virtual-table mechanism defined above (back up | 6130 ** The interface to the virtual-table mechanism defined above (back up |
| 5869 ** to a comment remarkably similar to this one) is currently considered | 6131 ** to a comment remarkably similar to this one) is currently considered |
| 5870 ** to be experimental. The interface might change in incompatible ways. | 6132 ** to be experimental. The interface might change in incompatible ways. |
| 5871 ** If this is a problem for you, do not use the interface at this time. | 6133 ** If this is a problem for you, do not use the interface at this time. |
| 5872 ** | 6134 ** |
| 5873 ** When the virtual-table mechanism stabilizes, we will declare the | 6135 ** When the virtual-table mechanism stabilizes, we will declare the |
| 5874 ** interface fixed, support it indefinitely, and remove this comment. | 6136 ** interface fixed, support it indefinitely, and remove this comment. |
| 5875 */ | 6137 */ |
| (...skipping 54 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 5930 ** constraint and the blob is being opened for read/write access)^, | 6192 ** constraint and the blob is being opened for read/write access)^, |
| 5931 ** <li> ^([foreign key constraints | Foreign key constraints] are enabled, | 6193 ** <li> ^([foreign key constraints | Foreign key constraints] are enabled, |
| 5932 ** column zColumn is part of a [child key] definition and the blob is | 6194 ** column zColumn is part of a [child key] definition and the blob is |
| 5933 ** being opened for read/write access)^. | 6195 ** being opened for read/write access)^. |
| 5934 ** </ul> | 6196 ** </ul> |
| 5935 ** | 6197 ** |
| 5936 ** ^Unless it returns SQLITE_MISUSE, this function sets the | 6198 ** ^Unless it returns SQLITE_MISUSE, this function sets the |
| 5937 ** [database connection] error code and message accessible via | 6199 ** [database connection] error code and message accessible via |
| 5938 ** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions. | 6200 ** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions. |
| 5939 ** | 6201 ** |
| 6202 ** A BLOB referenced by sqlite3_blob_open() may be read using the |
| 6203 ** [sqlite3_blob_read()] interface and modified by using |
| 6204 ** [sqlite3_blob_write()]. The [BLOB handle] can be moved to a |
| 6205 ** different row of the same table using the [sqlite3_blob_reopen()] |
| 6206 ** interface. However, the column, table, or database of a [BLOB handle] |
| 6207 ** cannot be changed after the [BLOB handle] is opened. |
| 5940 ** | 6208 ** |
| 5941 ** ^(If the row that a BLOB handle points to is modified by an | 6209 ** ^(If the row that a BLOB handle points to is modified by an |
| 5942 ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects | 6210 ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects |
| 5943 ** then the BLOB handle is marked as "expired". | 6211 ** then the BLOB handle is marked as "expired". |
| 5944 ** This is true if any column of the row is changed, even a column | 6212 ** This is true if any column of the row is changed, even a column |
| 5945 ** other than the one the BLOB handle is open on.)^ | 6213 ** other than the one the BLOB handle is open on.)^ |
| 5946 ** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for | 6214 ** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for |
| 5947 ** an expired BLOB handle fail with a return code of [SQLITE_ABORT]. | 6215 ** an expired BLOB handle fail with a return code of [SQLITE_ABORT]. |
| 5948 ** ^(Changes written into a BLOB prior to the BLOB expiring are not | 6216 ** ^(Changes written into a BLOB prior to the BLOB expiring are not |
| 5949 ** rolled back by the expiration of the BLOB. Such changes will eventually | 6217 ** rolled back by the expiration of the BLOB. Such changes will eventually |
| 5950 ** commit if the transaction continues to completion.)^ | 6218 ** commit if the transaction continues to completion.)^ |
| 5951 ** | 6219 ** |
| 5952 ** ^Use the [sqlite3_blob_bytes()] interface to determine the size of | 6220 ** ^Use the [sqlite3_blob_bytes()] interface to determine the size of |
| 5953 ** the opened blob. ^The size of a blob may not be changed by this | 6221 ** the opened blob. ^The size of a blob may not be changed by this |
| 5954 ** interface. Use the [UPDATE] SQL command to change the size of a | 6222 ** interface. Use the [UPDATE] SQL command to change the size of a |
| 5955 ** blob. | 6223 ** blob. |
| 5956 ** | 6224 ** |
| 5957 ** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces | 6225 ** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces |
| 5958 ** and the built-in [zeroblob] SQL function may be used to create a | 6226 ** and the built-in [zeroblob] SQL function may be used to create a |
| 5959 ** zero-filled blob to read or write using the incremental-blob interface. | 6227 ** zero-filled blob to read or write using the incremental-blob interface. |
| 5960 ** | 6228 ** |
| 5961 ** To avoid a resource leak, every open [BLOB handle] should eventually | 6229 ** To avoid a resource leak, every open [BLOB handle] should eventually |
| 5962 ** be released by a call to [sqlite3_blob_close()]. | 6230 ** be released by a call to [sqlite3_blob_close()]. |
| 6231 ** |
| 6232 ** See also: [sqlite3_blob_close()], |
| 6233 ** [sqlite3_blob_reopen()], [sqlite3_blob_read()], |
| 6234 ** [sqlite3_blob_bytes()], [sqlite3_blob_write()]. |
| 5963 */ | 6235 */ |
| 5964 SQLITE_API int SQLITE_STDCALL sqlite3_blob_open( | 6236 SQLITE_API int sqlite3_blob_open( |
| 5965 sqlite3*, | 6237 sqlite3*, |
| 5966 const char *zDb, | 6238 const char *zDb, |
| 5967 const char *zTable, | 6239 const char *zTable, |
| 5968 const char *zColumn, | 6240 const char *zColumn, |
| 5969 sqlite3_int64 iRow, | 6241 sqlite3_int64 iRow, |
| 5970 int flags, | 6242 int flags, |
| 5971 sqlite3_blob **ppBlob | 6243 sqlite3_blob **ppBlob |
| 5972 ); | 6244 ); |
| 5973 | 6245 |
| 5974 /* | 6246 /* |
| 5975 ** CAPI3REF: Move a BLOB Handle to a New Row | 6247 ** CAPI3REF: Move a BLOB Handle to a New Row |
| 5976 ** METHOD: sqlite3_blob | 6248 ** METHOD: sqlite3_blob |
| 5977 ** | 6249 ** |
| 5978 ** ^This function is used to move an existing blob handle so that it points | 6250 ** ^This function is used to move an existing [BLOB handle] so that it points |
| 5979 ** to a different row of the same database table. ^The new row is identified | 6251 ** to a different row of the same database table. ^The new row is identified |
| 5980 ** by the rowid value passed as the second argument. Only the row can be | 6252 ** by the rowid value passed as the second argument. Only the row can be |
| 5981 ** changed. ^The database, table and column on which the blob handle is open | 6253 ** changed. ^The database, table and column on which the blob handle is open |
| 5982 ** remain the same. Moving an existing blob handle to a new row can be | 6254 ** remain the same. Moving an existing [BLOB handle] to a new row is |
| 5983 ** faster than closing the existing handle and opening a new one. | 6255 ** faster than closing the existing handle and opening a new one. |
| 5984 ** | 6256 ** |
| 5985 ** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] - | 6257 ** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] - |
| 5986 ** it must exist and there must be either a blob or text value stored in | 6258 ** it must exist and there must be either a blob or text value stored in |
| 5987 ** the nominated column.)^ ^If the new row is not present in the table, or if | 6259 ** the nominated column.)^ ^If the new row is not present in the table, or if |
| 5988 ** it does not contain a blob or text value, or if another error occurs, an | 6260 ** it does not contain a blob or text value, or if another error occurs, an |
| 5989 ** SQLite error code is returned and the blob handle is considered aborted. | 6261 ** SQLite error code is returned and the blob handle is considered aborted. |
| 5990 ** ^All subsequent calls to [sqlite3_blob_read()], [sqlite3_blob_write()] or | 6262 ** ^All subsequent calls to [sqlite3_blob_read()], [sqlite3_blob_write()] or |
| 5991 ** [sqlite3_blob_reopen()] on an aborted blob handle immediately return | 6263 ** [sqlite3_blob_reopen()] on an aborted blob handle immediately return |
| 5992 ** SQLITE_ABORT. ^Calling [sqlite3_blob_bytes()] on an aborted blob handle | 6264 ** SQLITE_ABORT. ^Calling [sqlite3_blob_bytes()] on an aborted blob handle |
| 5993 ** always returns zero. | 6265 ** always returns zero. |
| 5994 ** | 6266 ** |
| 5995 ** ^This function sets the database handle error code and message. | 6267 ** ^This function sets the database handle error code and message. |
| 5996 */ | 6268 */ |
| 5997 SQLITE_API int SQLITE_STDCALL sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64)
; | 6269 SQLITE_API int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64); |
| 5998 | 6270 |
| 5999 /* | 6271 /* |
| 6000 ** CAPI3REF: Close A BLOB Handle | 6272 ** CAPI3REF: Close A BLOB Handle |
| 6001 ** DESTRUCTOR: sqlite3_blob | 6273 ** DESTRUCTOR: sqlite3_blob |
| 6002 ** | 6274 ** |
| 6003 ** ^This function closes an open [BLOB handle]. ^(The BLOB handle is closed | 6275 ** ^This function closes an open [BLOB handle]. ^(The BLOB handle is closed |
| 6004 ** unconditionally. Even if this routine returns an error code, the | 6276 ** unconditionally. Even if this routine returns an error code, the |
| 6005 ** handle is still closed.)^ | 6277 ** handle is still closed.)^ |
| 6006 ** | 6278 ** |
| 6007 ** ^If the blob handle being closed was opened for read-write access, and if | 6279 ** ^If the blob handle being closed was opened for read-write access, and if |
| 6008 ** the database is in auto-commit mode and there are no other open read-write | 6280 ** the database is in auto-commit mode and there are no other open read-write |
| 6009 ** blob handles or active write statements, the current transaction is | 6281 ** blob handles or active write statements, the current transaction is |
| 6010 ** committed. ^If an error occurs while committing the transaction, an error | 6282 ** committed. ^If an error occurs while committing the transaction, an error |
| 6011 ** code is returned and the transaction rolled back. | 6283 ** code is returned and the transaction rolled back. |
| 6012 ** | 6284 ** |
| 6013 ** Calling this function with an argument that is not a NULL pointer or an | 6285 ** Calling this function with an argument that is not a NULL pointer or an |
| 6014 ** open blob handle results in undefined behaviour. ^Calling this routine | 6286 ** open blob handle results in undefined behaviour. ^Calling this routine |
| 6015 ** with a null pointer (such as would be returned by a failed call to | 6287 ** with a null pointer (such as would be returned by a failed call to |
| 6016 ** [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function | 6288 ** [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function |
| 6017 ** is passed a valid open blob handle, the values returned by the | 6289 ** is passed a valid open blob handle, the values returned by the |
| 6018 ** sqlite3_errcode() and sqlite3_errmsg() functions are set before returning. | 6290 ** sqlite3_errcode() and sqlite3_errmsg() functions are set before returning. |
| 6019 */ | 6291 */ |
| 6020 SQLITE_API int SQLITE_STDCALL sqlite3_blob_close(sqlite3_blob *); | 6292 SQLITE_API int sqlite3_blob_close(sqlite3_blob *); |
| 6021 | 6293 |
| 6022 /* | 6294 /* |
| 6023 ** CAPI3REF: Return The Size Of An Open BLOB | 6295 ** CAPI3REF: Return The Size Of An Open BLOB |
| 6024 ** METHOD: sqlite3_blob | 6296 ** METHOD: sqlite3_blob |
| 6025 ** | 6297 ** |
| 6026 ** ^Returns the size in bytes of the BLOB accessible via the | 6298 ** ^Returns the size in bytes of the BLOB accessible via the |
| 6027 ** successfully opened [BLOB handle] in its only argument. ^The | 6299 ** successfully opened [BLOB handle] in its only argument. ^The |
| 6028 ** incremental blob I/O routines can only read or overwriting existing | 6300 ** incremental blob I/O routines can only read or overwriting existing |
| 6029 ** blob content; they cannot change the size of a blob. | 6301 ** blob content; they cannot change the size of a blob. |
| 6030 ** | 6302 ** |
| 6031 ** This routine only works on a [BLOB handle] which has been created | 6303 ** This routine only works on a [BLOB handle] which has been created |
| 6032 ** by a prior successful call to [sqlite3_blob_open()] and which has not | 6304 ** by a prior successful call to [sqlite3_blob_open()] and which has not |
| 6033 ** been closed by [sqlite3_blob_close()]. Passing any other pointer in | 6305 ** been closed by [sqlite3_blob_close()]. Passing any other pointer in |
| 6034 ** to this routine results in undefined and probably undesirable behavior. | 6306 ** to this routine results in undefined and probably undesirable behavior. |
| 6035 */ | 6307 */ |
| 6036 SQLITE_API int SQLITE_STDCALL sqlite3_blob_bytes(sqlite3_blob *); | 6308 SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *); |
| 6037 | 6309 |
| 6038 /* | 6310 /* |
| 6039 ** CAPI3REF: Read Data From A BLOB Incrementally | 6311 ** CAPI3REF: Read Data From A BLOB Incrementally |
| 6040 ** METHOD: sqlite3_blob | 6312 ** METHOD: sqlite3_blob |
| 6041 ** | 6313 ** |
| 6042 ** ^(This function is used to read data from an open [BLOB handle] into a | 6314 ** ^(This function is used to read data from an open [BLOB handle] into a |
| 6043 ** caller-supplied buffer. N bytes of data are copied into buffer Z | 6315 ** caller-supplied buffer. N bytes of data are copied into buffer Z |
| 6044 ** from the open BLOB, starting at offset iOffset.)^ | 6316 ** from the open BLOB, starting at offset iOffset.)^ |
| 6045 ** | 6317 ** |
| 6046 ** ^If offset iOffset is less than N bytes from the end of the BLOB, | 6318 ** ^If offset iOffset is less than N bytes from the end of the BLOB, |
| 6047 ** [SQLITE_ERROR] is returned and no data is read. ^If N or iOffset is | 6319 ** [SQLITE_ERROR] is returned and no data is read. ^If N or iOffset is |
| 6048 ** less than zero, [SQLITE_ERROR] is returned and no data is read. | 6320 ** less than zero, [SQLITE_ERROR] is returned and no data is read. |
| 6049 ** ^The size of the blob (and hence the maximum value of N+iOffset) | 6321 ** ^The size of the blob (and hence the maximum value of N+iOffset) |
| 6050 ** can be determined using the [sqlite3_blob_bytes()] interface. | 6322 ** can be determined using the [sqlite3_blob_bytes()] interface. |
| 6051 ** | 6323 ** |
| 6052 ** ^An attempt to read from an expired [BLOB handle] fails with an | 6324 ** ^An attempt to read from an expired [BLOB handle] fails with an |
| 6053 ** error code of [SQLITE_ABORT]. | 6325 ** error code of [SQLITE_ABORT]. |
| 6054 ** | 6326 ** |
| 6055 ** ^(On success, sqlite3_blob_read() returns SQLITE_OK. | 6327 ** ^(On success, sqlite3_blob_read() returns SQLITE_OK. |
| 6056 ** Otherwise, an [error code] or an [extended error code] is returned.)^ | 6328 ** Otherwise, an [error code] or an [extended error code] is returned.)^ |
| 6057 ** | 6329 ** |
| 6058 ** This routine only works on a [BLOB handle] which has been created | 6330 ** This routine only works on a [BLOB handle] which has been created |
| 6059 ** by a prior successful call to [sqlite3_blob_open()] and which has not | 6331 ** by a prior successful call to [sqlite3_blob_open()] and which has not |
| 6060 ** been closed by [sqlite3_blob_close()]. Passing any other pointer in | 6332 ** been closed by [sqlite3_blob_close()]. Passing any other pointer in |
| 6061 ** to this routine results in undefined and probably undesirable behavior. | 6333 ** to this routine results in undefined and probably undesirable behavior. |
| 6062 ** | 6334 ** |
| 6063 ** See also: [sqlite3_blob_write()]. | 6335 ** See also: [sqlite3_blob_write()]. |
| 6064 */ | 6336 */ |
| 6065 SQLITE_API int SQLITE_STDCALL sqlite3_blob_read(sqlite3_blob *, void *Z, int N,
int iOffset); | 6337 SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset); |
| 6066 | 6338 |
| 6067 /* | 6339 /* |
| 6068 ** CAPI3REF: Write Data Into A BLOB Incrementally | 6340 ** CAPI3REF: Write Data Into A BLOB Incrementally |
| 6069 ** METHOD: sqlite3_blob | 6341 ** METHOD: sqlite3_blob |
| 6070 ** | 6342 ** |
| 6071 ** ^(This function is used to write data into an open [BLOB handle] from a | 6343 ** ^(This function is used to write data into an open [BLOB handle] from a |
| 6072 ** caller-supplied buffer. N bytes of data are copied from the buffer Z | 6344 ** caller-supplied buffer. N bytes of data are copied from the buffer Z |
| 6073 ** into the open BLOB, starting at offset iOffset.)^ | 6345 ** into the open BLOB, starting at offset iOffset.)^ |
| 6074 ** | 6346 ** |
| 6075 ** ^(On success, sqlite3_blob_write() returns SQLITE_OK. | 6347 ** ^(On success, sqlite3_blob_write() returns SQLITE_OK. |
| (...skipping 21 matching lines...) Expand all Loading... |
| 6097 ** have been overwritten by the statement that expired the BLOB handle | 6369 ** have been overwritten by the statement that expired the BLOB handle |
| 6098 ** or by other independent statements. | 6370 ** or by other independent statements. |
| 6099 ** | 6371 ** |
| 6100 ** This routine only works on a [BLOB handle] which has been created | 6372 ** This routine only works on a [BLOB handle] which has been created |
| 6101 ** by a prior successful call to [sqlite3_blob_open()] and which has not | 6373 ** by a prior successful call to [sqlite3_blob_open()] and which has not |
| 6102 ** been closed by [sqlite3_blob_close()]. Passing any other pointer in | 6374 ** been closed by [sqlite3_blob_close()]. Passing any other pointer in |
| 6103 ** to this routine results in undefined and probably undesirable behavior. | 6375 ** to this routine results in undefined and probably undesirable behavior. |
| 6104 ** | 6376 ** |
| 6105 ** See also: [sqlite3_blob_read()]. | 6377 ** See also: [sqlite3_blob_read()]. |
| 6106 */ | 6378 */ |
| 6107 SQLITE_API int SQLITE_STDCALL sqlite3_blob_write(sqlite3_blob *, const void *z,
int n, int iOffset); | 6379 SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOff
set); |
| 6108 | 6380 |
| 6109 /* | 6381 /* |
| 6110 ** CAPI3REF: Virtual File System Objects | 6382 ** CAPI3REF: Virtual File System Objects |
| 6111 ** | 6383 ** |
| 6112 ** A virtual filesystem (VFS) is an [sqlite3_vfs] object | 6384 ** A virtual filesystem (VFS) is an [sqlite3_vfs] object |
| 6113 ** that SQLite uses to interact | 6385 ** that SQLite uses to interact |
| 6114 ** with the underlying operating system. Most SQLite builds come with a | 6386 ** with the underlying operating system. Most SQLite builds come with a |
| 6115 ** single default VFS that is appropriate for the host computer. | 6387 ** single default VFS that is appropriate for the host computer. |
| 6116 ** New VFSes can be registered and existing VFSes can be unregistered. | 6388 ** New VFSes can be registered and existing VFSes can be unregistered. |
| 6117 ** The following interfaces are provided. | 6389 ** The following interfaces are provided. |
| (...skipping 10 matching lines...) Expand all Loading... |
| 6128 ** ^To make an existing VFS into the default VFS, register it again | 6400 ** ^To make an existing VFS into the default VFS, register it again |
| 6129 ** with the makeDflt flag set. If two different VFSes with the | 6401 ** with the makeDflt flag set. If two different VFSes with the |
| 6130 ** same name are registered, the behavior is undefined. If a | 6402 ** same name are registered, the behavior is undefined. If a |
| 6131 ** VFS is registered with a name that is NULL or an empty string, | 6403 ** VFS is registered with a name that is NULL or an empty string, |
| 6132 ** then the behavior is undefined. | 6404 ** then the behavior is undefined. |
| 6133 ** | 6405 ** |
| 6134 ** ^Unregister a VFS with the sqlite3_vfs_unregister() interface. | 6406 ** ^Unregister a VFS with the sqlite3_vfs_unregister() interface. |
| 6135 ** ^(If the default VFS is unregistered, another VFS is chosen as | 6407 ** ^(If the default VFS is unregistered, another VFS is chosen as |
| 6136 ** the default. The choice for the new VFS is arbitrary.)^ | 6408 ** the default. The choice for the new VFS is arbitrary.)^ |
| 6137 */ | 6409 */ |
| 6138 SQLITE_API sqlite3_vfs *SQLITE_STDCALL sqlite3_vfs_find(const char *zVfsName); | 6410 SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); |
| 6139 SQLITE_API int SQLITE_STDCALL sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); | 6411 SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); |
| 6140 SQLITE_API int SQLITE_STDCALL sqlite3_vfs_unregister(sqlite3_vfs*); | 6412 SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*); |
| 6141 | 6413 |
| 6142 /* | 6414 /* |
| 6143 ** CAPI3REF: Mutexes | 6415 ** CAPI3REF: Mutexes |
| 6144 ** | 6416 ** |
| 6145 ** The SQLite core uses these routines for thread | 6417 ** The SQLite core uses these routines for thread |
| 6146 ** synchronization. Though they are intended for internal | 6418 ** synchronization. Though they are intended for internal |
| 6147 ** use by SQLite, code that links against SQLite is | 6419 ** use by SQLite, code that links against SQLite is |
| 6148 ** permitted to use any of these routines. | 6420 ** permitted to use any of these routines. |
| 6149 ** | 6421 ** |
| 6150 ** The SQLite source code contains multiple implementations | 6422 ** The SQLite source code contains multiple implementations |
| (...skipping 95 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 6246 ** previously entered by the same thread. The behavior | 6518 ** previously entered by the same thread. The behavior |
| 6247 ** is undefined if the mutex is not currently entered by the | 6519 ** is undefined if the mutex is not currently entered by the |
| 6248 ** calling thread or is not currently allocated. | 6520 ** calling thread or is not currently allocated. |
| 6249 ** | 6521 ** |
| 6250 ** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or | 6522 ** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or |
| 6251 ** sqlite3_mutex_leave() is a NULL pointer, then all three routines | 6523 ** sqlite3_mutex_leave() is a NULL pointer, then all three routines |
| 6252 ** behave as no-ops. | 6524 ** behave as no-ops. |
| 6253 ** | 6525 ** |
| 6254 ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()]. | 6526 ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()]. |
| 6255 */ | 6527 */ |
| 6256 SQLITE_API sqlite3_mutex *SQLITE_STDCALL sqlite3_mutex_alloc(int); | 6528 SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int); |
| 6257 SQLITE_API void SQLITE_STDCALL sqlite3_mutex_free(sqlite3_mutex*); | 6529 SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*); |
| 6258 SQLITE_API void SQLITE_STDCALL sqlite3_mutex_enter(sqlite3_mutex*); | 6530 SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*); |
| 6259 SQLITE_API int SQLITE_STDCALL sqlite3_mutex_try(sqlite3_mutex*); | 6531 SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*); |
| 6260 SQLITE_API void SQLITE_STDCALL sqlite3_mutex_leave(sqlite3_mutex*); | 6532 SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*); |
| 6261 | 6533 |
| 6262 /* | 6534 /* |
| 6263 ** CAPI3REF: Mutex Methods Object | 6535 ** CAPI3REF: Mutex Methods Object |
| 6264 ** | 6536 ** |
| 6265 ** An instance of this structure defines the low-level routines | 6537 ** An instance of this structure defines the low-level routines |
| 6266 ** used to allocate and use mutexes. | 6538 ** used to allocate and use mutexes. |
| 6267 ** | 6539 ** |
| 6268 ** Usually, the default mutex implementations provided by SQLite are | 6540 ** Usually, the default mutex implementations provided by SQLite are |
| 6269 ** sufficient, however the application has the option of substituting a custom | 6541 ** sufficient, however the application has the option of substituting a custom |
| 6270 ** implementation for specialized deployments or systems for which SQLite | 6542 ** implementation for specialized deployments or systems for which SQLite |
| (...skipping 89 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 6360 ** If the argument to sqlite3_mutex_held() is a NULL pointer then | 6632 ** If the argument to sqlite3_mutex_held() is a NULL pointer then |
| 6361 ** the routine should return 1. This seems counter-intuitive since | 6633 ** the routine should return 1. This seems counter-intuitive since |
| 6362 ** clearly the mutex cannot be held if it does not exist. But | 6634 ** clearly the mutex cannot be held if it does not exist. But |
| 6363 ** the reason the mutex does not exist is because the build is not | 6635 ** the reason the mutex does not exist is because the build is not |
| 6364 ** using mutexes. And we do not want the assert() containing the | 6636 ** using mutexes. And we do not want the assert() containing the |
| 6365 ** call to sqlite3_mutex_held() to fail, so a non-zero return is | 6637 ** call to sqlite3_mutex_held() to fail, so a non-zero return is |
| 6366 ** the appropriate thing to do. The sqlite3_mutex_notheld() | 6638 ** the appropriate thing to do. The sqlite3_mutex_notheld() |
| 6367 ** interface should also return 1 when given a NULL pointer. | 6639 ** interface should also return 1 when given a NULL pointer. |
| 6368 */ | 6640 */ |
| 6369 #ifndef NDEBUG | 6641 #ifndef NDEBUG |
| 6370 SQLITE_API int SQLITE_STDCALL sqlite3_mutex_held(sqlite3_mutex*); | 6642 SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*); |
| 6371 SQLITE_API int SQLITE_STDCALL sqlite3_mutex_notheld(sqlite3_mutex*); | 6643 SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*); |
| 6372 #endif | 6644 #endif |
| 6373 | 6645 |
| 6374 /* | 6646 /* |
| 6375 ** CAPI3REF: Mutex Types | 6647 ** CAPI3REF: Mutex Types |
| 6376 ** | 6648 ** |
| 6377 ** The [sqlite3_mutex_alloc()] interface takes a single argument | 6649 ** The [sqlite3_mutex_alloc()] interface takes a single argument |
| 6378 ** which is one of these integer constants. | 6650 ** which is one of these integer constants. |
| 6379 ** | 6651 ** |
| 6380 ** The set of static mutexes may change from one SQLite release to the | 6652 ** The set of static mutexes may change from one SQLite release to the |
| 6381 ** next. Applications that override the built-in mutex logic must be | 6653 ** next. Applications that override the built-in mutex logic must be |
| 6382 ** prepared to accommodate additional static mutexes. | 6654 ** prepared to accommodate additional static mutexes. |
| 6383 */ | 6655 */ |
| 6384 #define SQLITE_MUTEX_FAST 0 | 6656 #define SQLITE_MUTEX_FAST 0 |
| 6385 #define SQLITE_MUTEX_RECURSIVE 1 | 6657 #define SQLITE_MUTEX_RECURSIVE 1 |
| 6386 #define SQLITE_MUTEX_STATIC_MASTER 2 | 6658 #define SQLITE_MUTEX_STATIC_MASTER 2 |
| 6387 #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ | 6659 #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ |
| 6388 #define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */ | 6660 #define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */ |
| 6389 #define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */ | 6661 #define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */ |
| 6390 #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */ | 6662 #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_randomness() */ |
| 6391 #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ | 6663 #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ |
| 6392 #define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */ | 6664 #define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */ |
| 6393 #define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */ | 6665 #define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */ |
| 6394 #define SQLITE_MUTEX_STATIC_APP1 8 /* For use by application */ | 6666 #define SQLITE_MUTEX_STATIC_APP1 8 /* For use by application */ |
| 6395 #define SQLITE_MUTEX_STATIC_APP2 9 /* For use by application */ | 6667 #define SQLITE_MUTEX_STATIC_APP2 9 /* For use by application */ |
| 6396 #define SQLITE_MUTEX_STATIC_APP3 10 /* For use by application */ | 6668 #define SQLITE_MUTEX_STATIC_APP3 10 /* For use by application */ |
| 6397 #define SQLITE_MUTEX_STATIC_VFS1 11 /* For use by built-in VFS */ | 6669 #define SQLITE_MUTEX_STATIC_VFS1 11 /* For use by built-in VFS */ |
| 6398 #define SQLITE_MUTEX_STATIC_VFS2 12 /* For use by extension VFS */ | 6670 #define SQLITE_MUTEX_STATIC_VFS2 12 /* For use by extension VFS */ |
| 6399 #define SQLITE_MUTEX_STATIC_VFS3 13 /* For use by application VFS */ | 6671 #define SQLITE_MUTEX_STATIC_VFS3 13 /* For use by application VFS */ |
| 6400 | 6672 |
| 6401 /* | 6673 /* |
| 6402 ** CAPI3REF: Retrieve the mutex for a database connection | 6674 ** CAPI3REF: Retrieve the mutex for a database connection |
| 6403 ** METHOD: sqlite3 | 6675 ** METHOD: sqlite3 |
| 6404 ** | 6676 ** |
| 6405 ** ^This interface returns a pointer the [sqlite3_mutex] object that | 6677 ** ^This interface returns a pointer the [sqlite3_mutex] object that |
| 6406 ** serializes access to the [database connection] given in the argument | 6678 ** serializes access to the [database connection] given in the argument |
| 6407 ** when the [threading mode] is Serialized. | 6679 ** when the [threading mode] is Serialized. |
| 6408 ** ^If the [threading mode] is Single-thread or Multi-thread then this | 6680 ** ^If the [threading mode] is Single-thread or Multi-thread then this |
| 6409 ** routine returns a NULL pointer. | 6681 ** routine returns a NULL pointer. |
| 6410 */ | 6682 */ |
| 6411 SQLITE_API sqlite3_mutex *SQLITE_STDCALL sqlite3_db_mutex(sqlite3*); | 6683 SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*); |
| 6412 | 6684 |
| 6413 /* | 6685 /* |
| 6414 ** CAPI3REF: Low-Level Control Of Database Files | 6686 ** CAPI3REF: Low-Level Control Of Database Files |
| 6415 ** METHOD: sqlite3 | 6687 ** METHOD: sqlite3 |
| 6416 ** | 6688 ** |
| 6417 ** ^The [sqlite3_file_control()] interface makes a direct call to the | 6689 ** ^The [sqlite3_file_control()] interface makes a direct call to the |
| 6418 ** xFileControl method for the [sqlite3_io_methods] object associated | 6690 ** xFileControl method for the [sqlite3_io_methods] object associated |
| 6419 ** with a particular database identified by the second argument. ^The | 6691 ** with a particular database identified by the second argument. ^The |
| 6420 ** name of the database is "main" for the main database or "temp" for the | 6692 ** name of the database is "main" for the main database or "temp" for the |
| 6421 ** TEMP database, or the name that appears after the AS keyword for | 6693 ** TEMP database, or the name that appears after the AS keyword for |
| (...skipping 14 matching lines...) Expand all Loading... |
| 6436 ** ^If the second parameter (zDbName) does not match the name of any | 6708 ** ^If the second parameter (zDbName) does not match the name of any |
| 6437 ** open database file, then SQLITE_ERROR is returned. ^This error | 6709 ** open database file, then SQLITE_ERROR is returned. ^This error |
| 6438 ** code is not remembered and will not be recalled by [sqlite3_errcode()] | 6710 ** code is not remembered and will not be recalled by [sqlite3_errcode()] |
| 6439 ** or [sqlite3_errmsg()]. The underlying xFileControl method might | 6711 ** or [sqlite3_errmsg()]. The underlying xFileControl method might |
| 6440 ** also return SQLITE_ERROR. There is no way to distinguish between | 6712 ** also return SQLITE_ERROR. There is no way to distinguish between |
| 6441 ** an incorrect zDbName and an SQLITE_ERROR return from the underlying | 6713 ** an incorrect zDbName and an SQLITE_ERROR return from the underlying |
| 6442 ** xFileControl method. | 6714 ** xFileControl method. |
| 6443 ** | 6715 ** |
| 6444 ** See also: [SQLITE_FCNTL_LOCKSTATE] | 6716 ** See also: [SQLITE_FCNTL_LOCKSTATE] |
| 6445 */ | 6717 */ |
| 6446 SQLITE_API int SQLITE_STDCALL sqlite3_file_control(sqlite3*, const char *zDbName
, int op, void*); | 6718 SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*
); |
| 6447 | 6719 |
| 6448 /* | 6720 /* |
| 6449 ** CAPI3REF: Testing Interface | 6721 ** CAPI3REF: Testing Interface |
| 6450 ** | 6722 ** |
| 6451 ** ^The sqlite3_test_control() interface is used to read out internal | 6723 ** ^The sqlite3_test_control() interface is used to read out internal |
| 6452 ** state of SQLite and to inject faults into SQLite for testing | 6724 ** state of SQLite and to inject faults into SQLite for testing |
| 6453 ** purposes. ^The first parameter is an operation code that determines | 6725 ** purposes. ^The first parameter is an operation code that determines |
| 6454 ** the number, meaning, and operation of all subsequent parameters. | 6726 ** the number, meaning, and operation of all subsequent parameters. |
| 6455 ** | 6727 ** |
| 6456 ** This interface is not for use by applications. It exists solely | 6728 ** This interface is not for use by applications. It exists solely |
| 6457 ** for verifying the correct operation of the SQLite library. Depending | 6729 ** for verifying the correct operation of the SQLite library. Depending |
| 6458 ** on how the SQLite library is compiled, this interface might not exist. | 6730 ** on how the SQLite library is compiled, this interface might not exist. |
| 6459 ** | 6731 ** |
| 6460 ** The details of the operation codes, their meanings, the parameters | 6732 ** The details of the operation codes, their meanings, the parameters |
| 6461 ** they take, and what they do are all subject to change without notice. | 6733 ** they take, and what they do are all subject to change without notice. |
| 6462 ** Unlike most of the SQLite API, this function is not guaranteed to | 6734 ** Unlike most of the SQLite API, this function is not guaranteed to |
| 6463 ** operate consistently from one release to the next. | 6735 ** operate consistently from one release to the next. |
| 6464 */ | 6736 */ |
| 6465 SQLITE_API int SQLITE_CDECL sqlite3_test_control(int op, ...); | 6737 SQLITE_API int sqlite3_test_control(int op, ...); |
| 6466 | 6738 |
| 6467 /* | 6739 /* |
| 6468 ** CAPI3REF: Testing Interface Operation Codes | 6740 ** CAPI3REF: Testing Interface Operation Codes |
| 6469 ** | 6741 ** |
| 6470 ** These constants are the valid operation code parameters used | 6742 ** These constants are the valid operation code parameters used |
| 6471 ** as the first argument to [sqlite3_test_control()]. | 6743 ** as the first argument to [sqlite3_test_control()]. |
| 6472 ** | 6744 ** |
| 6473 ** These parameters and their meanings are subject to change | 6745 ** These parameters and their meanings are subject to change |
| 6474 ** without notice. These values are for testing purposes only. | 6746 ** without notice. These values are for testing purposes only. |
| 6475 ** Applications should not use any of these parameters or the | 6747 ** Applications should not use any of these parameters or the |
| 6476 ** [sqlite3_test_control()] interface. | 6748 ** [sqlite3_test_control()] interface. |
| 6477 */ | 6749 */ |
| 6478 #define SQLITE_TESTCTRL_FIRST 5 | 6750 #define SQLITE_TESTCTRL_FIRST 5 |
| 6479 #define SQLITE_TESTCTRL_PRNG_SAVE 5 | 6751 #define SQLITE_TESTCTRL_PRNG_SAVE 5 |
| 6480 #define SQLITE_TESTCTRL_PRNG_RESTORE 6 | 6752 #define SQLITE_TESTCTRL_PRNG_RESTORE 6 |
| 6481 #define SQLITE_TESTCTRL_PRNG_RESET 7 | 6753 #define SQLITE_TESTCTRL_PRNG_RESET 7 |
| 6482 #define SQLITE_TESTCTRL_BITVEC_TEST 8 | 6754 #define SQLITE_TESTCTRL_BITVEC_TEST 8 |
| 6483 #define SQLITE_TESTCTRL_FAULT_INSTALL 9 | 6755 #define SQLITE_TESTCTRL_FAULT_INSTALL 9 |
| 6484 #define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10 | 6756 #define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10 |
| 6485 #define SQLITE_TESTCTRL_PENDING_BYTE 11 | 6757 #define SQLITE_TESTCTRL_PENDING_BYTE 11 |
| 6486 #define SQLITE_TESTCTRL_ASSERT 12 | 6758 #define SQLITE_TESTCTRL_ASSERT 12 |
| 6487 #define SQLITE_TESTCTRL_ALWAYS 13 | 6759 #define SQLITE_TESTCTRL_ALWAYS 13 |
| 6488 #define SQLITE_TESTCTRL_RESERVE 14 | 6760 #define SQLITE_TESTCTRL_RESERVE 14 |
| 6489 #define SQLITE_TESTCTRL_OPTIMIZATIONS 15 | 6761 #define SQLITE_TESTCTRL_OPTIMIZATIONS 15 |
| 6490 #define SQLITE_TESTCTRL_ISKEYWORD 16 | 6762 #define SQLITE_TESTCTRL_ISKEYWORD 16 |
| 6491 #define SQLITE_TESTCTRL_SCRATCHMALLOC 17 | 6763 #define SQLITE_TESTCTRL_SCRATCHMALLOC 17 |
| 6492 #define SQLITE_TESTCTRL_LOCALTIME_FAULT 18 | 6764 #define SQLITE_TESTCTRL_LOCALTIME_FAULT 18 |
| 6493 #define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */ | 6765 #define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */ |
| 6766 #define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD 19 |
| 6494 #define SQLITE_TESTCTRL_NEVER_CORRUPT 20 | 6767 #define SQLITE_TESTCTRL_NEVER_CORRUPT 20 |
| 6495 #define SQLITE_TESTCTRL_VDBE_COVERAGE 21 | 6768 #define SQLITE_TESTCTRL_VDBE_COVERAGE 21 |
| 6496 #define SQLITE_TESTCTRL_BYTEORDER 22 | 6769 #define SQLITE_TESTCTRL_BYTEORDER 22 |
| 6497 #define SQLITE_TESTCTRL_ISINIT 23 | 6770 #define SQLITE_TESTCTRL_ISINIT 23 |
| 6498 #define SQLITE_TESTCTRL_SORTER_MMAP 24 | 6771 #define SQLITE_TESTCTRL_SORTER_MMAP 24 |
| 6499 #define SQLITE_TESTCTRL_IMPOSTER 25 | 6772 #define SQLITE_TESTCTRL_IMPOSTER 25 |
| 6500 #define SQLITE_TESTCTRL_LAST 25 | 6773 #define SQLITE_TESTCTRL_LAST 25 |
| 6501 | 6774 |
| 6502 /* | 6775 /* |
| 6503 ** CAPI3REF: SQLite Runtime Status | 6776 ** CAPI3REF: SQLite Runtime Status |
| (...skipping 14 matching lines...) Expand all Loading... |
| 6518 ** | 6791 ** |
| 6519 ** ^The sqlite3_status() and sqlite3_status64() routines return | 6792 ** ^The sqlite3_status() and sqlite3_status64() routines return |
| 6520 ** SQLITE_OK on success and a non-zero [error code] on failure. | 6793 ** SQLITE_OK on success and a non-zero [error code] on failure. |
| 6521 ** | 6794 ** |
| 6522 ** If either the current value or the highwater mark is too large to | 6795 ** If either the current value or the highwater mark is too large to |
| 6523 ** be represented by a 32-bit integer, then the values returned by | 6796 ** be represented by a 32-bit integer, then the values returned by |
| 6524 ** sqlite3_status() are undefined. | 6797 ** sqlite3_status() are undefined. |
| 6525 ** | 6798 ** |
| 6526 ** See also: [sqlite3_db_status()] | 6799 ** See also: [sqlite3_db_status()] |
| 6527 */ | 6800 */ |
| 6528 SQLITE_API int SQLITE_STDCALL sqlite3_status(int op, int *pCurrent, int *pHighwa
ter, int resetFlag); | 6801 SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetF
lag); |
| 6529 SQLITE_API int SQLITE_STDCALL sqlite3_status64( | 6802 SQLITE_API int sqlite3_status64( |
| 6530 int op, | 6803 int op, |
| 6531 sqlite3_int64 *pCurrent, | 6804 sqlite3_int64 *pCurrent, |
| 6532 sqlite3_int64 *pHighwater, | 6805 sqlite3_int64 *pHighwater, |
| 6533 int resetFlag | 6806 int resetFlag |
| 6534 ); | 6807 ); |
| 6535 | 6808 |
| 6536 | 6809 |
| 6537 /* | 6810 /* |
| 6538 ** CAPI3REF: Status Parameters | 6811 ** CAPI3REF: Status Parameters |
| 6539 ** KEYWORDS: {status parameters} | 6812 ** KEYWORDS: {status parameters} |
| (...skipping 104 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 6644 ** ^The current value of the requested parameter is written into *pCur | 6917 ** ^The current value of the requested parameter is written into *pCur |
| 6645 ** and the highest instantaneous value is written into *pHiwtr. ^If | 6918 ** and the highest instantaneous value is written into *pHiwtr. ^If |
| 6646 ** the resetFlg is true, then the highest instantaneous value is | 6919 ** the resetFlg is true, then the highest instantaneous value is |
| 6647 ** reset back down to the current value. | 6920 ** reset back down to the current value. |
| 6648 ** | 6921 ** |
| 6649 ** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a | 6922 ** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a |
| 6650 ** non-zero [error code] on failure. | 6923 ** non-zero [error code] on failure. |
| 6651 ** | 6924 ** |
| 6652 ** See also: [sqlite3_status()] and [sqlite3_stmt_status()]. | 6925 ** See also: [sqlite3_status()] and [sqlite3_stmt_status()]. |
| 6653 */ | 6926 */ |
| 6654 SQLITE_API int SQLITE_STDCALL sqlite3_db_status(sqlite3*, int op, int *pCur, int
*pHiwtr, int resetFlg); | 6927 SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int r
esetFlg); |
| 6655 | 6928 |
| 6656 /* | 6929 /* |
| 6657 ** CAPI3REF: Status Parameters for database connections | 6930 ** CAPI3REF: Status Parameters for database connections |
| 6658 ** KEYWORDS: {SQLITE_DBSTATUS options} | 6931 ** KEYWORDS: {SQLITE_DBSTATUS options} |
| 6659 ** | 6932 ** |
| 6660 ** These constants are the available integer "verbs" that can be passed as | 6933 ** These constants are the available integer "verbs" that can be passed as |
| 6661 ** the second argument to the [sqlite3_db_status()] interface. | 6934 ** the second argument to the [sqlite3_db_status()] interface. |
| 6662 ** | 6935 ** |
| 6663 ** New verbs may be added in future releases of SQLite. Existing verbs | 6936 ** New verbs may be added in future releases of SQLite. Existing verbs |
| 6664 ** might be discontinued. Applications should check the return code from | 6937 ** might be discontinued. Applications should check the return code from |
| (...skipping 25 matching lines...) Expand all Loading... |
| 6690 ** been satisfied using lookaside memory but failed due to all lookaside | 6963 ** been satisfied using lookaside memory but failed due to all lookaside |
| 6691 ** memory already being in use. | 6964 ** memory already being in use. |
| 6692 ** Only the high-water value is meaningful; | 6965 ** Only the high-water value is meaningful; |
| 6693 ** the current value is always zero.)^ | 6966 ** the current value is always zero.)^ |
| 6694 ** | 6967 ** |
| 6695 ** [[SQLITE_DBSTATUS_CACHE_USED]] ^(<dt>SQLITE_DBSTATUS_CACHE_USED</dt> | 6968 ** [[SQLITE_DBSTATUS_CACHE_USED]] ^(<dt>SQLITE_DBSTATUS_CACHE_USED</dt> |
| 6696 ** <dd>This parameter returns the approximate number of bytes of heap | 6969 ** <dd>This parameter returns the approximate number of bytes of heap |
| 6697 ** memory used by all pager caches associated with the database connection.)^ | 6970 ** memory used by all pager caches associated with the database connection.)^ |
| 6698 ** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0. | 6971 ** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0. |
| 6699 ** | 6972 ** |
| 6973 ** [[SQLITE_DBSTATUS_CACHE_USED_SHARED]] |
| 6974 ** ^(<dt>SQLITE_DBSTATUS_CACHE_USED_SHARED</dt> |
| 6975 ** <dd>This parameter is similar to DBSTATUS_CACHE_USED, except that if a |
| 6976 ** pager cache is shared between two or more connections the bytes of heap |
| 6977 ** memory used by that pager cache is divided evenly between the attached |
| 6978 ** connections.)^ In other words, if none of the pager caches associated |
| 6979 ** with the database connection are shared, this request returns the same |
| 6980 ** value as DBSTATUS_CACHE_USED. Or, if one or more or the pager caches are |
| 6981 ** shared, the value returned by this call will be smaller than that returned |
| 6982 ** by DBSTATUS_CACHE_USED. ^The highwater mark associated with |
| 6983 ** SQLITE_DBSTATUS_CACHE_USED_SHARED is always 0. |
| 6984 ** |
| 6700 ** [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt> | 6985 ** [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt> |
| 6701 ** <dd>This parameter returns the approximate number of bytes of heap | 6986 ** <dd>This parameter returns the approximate number of bytes of heap |
| 6702 ** memory used to store the schema for all databases associated | 6987 ** memory used to store the schema for all databases associated |
| 6703 ** with the connection - main, temp, and any [ATTACH]-ed databases.)^ | 6988 ** with the connection - main, temp, and any [ATTACH]-ed databases.)^ |
| 6704 ** ^The full amount of memory used by the schemas is reported, even if the | 6989 ** ^The full amount of memory used by the schemas is reported, even if the |
| 6705 ** schema memory is shared with other database connections due to | 6990 ** schema memory is shared with other database connections due to |
| 6706 ** [shared cache mode] being enabled. | 6991 ** [shared cache mode] being enabled. |
| 6707 ** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0. | 6992 ** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0. |
| 6708 ** | 6993 ** |
| 6709 ** [[SQLITE_DBSTATUS_STMT_USED]] ^(<dt>SQLITE_DBSTATUS_STMT_USED</dt> | 6994 ** [[SQLITE_DBSTATUS_STMT_USED]] ^(<dt>SQLITE_DBSTATUS_STMT_USED</dt> |
| (...skipping 37 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 6747 #define SQLITE_DBSTATUS_CACHE_USED 1 | 7032 #define SQLITE_DBSTATUS_CACHE_USED 1 |
| 6748 #define SQLITE_DBSTATUS_SCHEMA_USED 2 | 7033 #define SQLITE_DBSTATUS_SCHEMA_USED 2 |
| 6749 #define SQLITE_DBSTATUS_STMT_USED 3 | 7034 #define SQLITE_DBSTATUS_STMT_USED 3 |
| 6750 #define SQLITE_DBSTATUS_LOOKASIDE_HIT 4 | 7035 #define SQLITE_DBSTATUS_LOOKASIDE_HIT 4 |
| 6751 #define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5 | 7036 #define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5 |
| 6752 #define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6 | 7037 #define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6 |
| 6753 #define SQLITE_DBSTATUS_CACHE_HIT 7 | 7038 #define SQLITE_DBSTATUS_CACHE_HIT 7 |
| 6754 #define SQLITE_DBSTATUS_CACHE_MISS 8 | 7039 #define SQLITE_DBSTATUS_CACHE_MISS 8 |
| 6755 #define SQLITE_DBSTATUS_CACHE_WRITE 9 | 7040 #define SQLITE_DBSTATUS_CACHE_WRITE 9 |
| 6756 #define SQLITE_DBSTATUS_DEFERRED_FKS 10 | 7041 #define SQLITE_DBSTATUS_DEFERRED_FKS 10 |
| 6757 #define SQLITE_DBSTATUS_MAX 10 /* Largest defined DBSTATUS */ | 7042 #define SQLITE_DBSTATUS_CACHE_USED_SHARED 11 |
| 7043 #define SQLITE_DBSTATUS_MAX 11 /* Largest defined DBSTATUS */ |
| 6758 | 7044 |
| 6759 | 7045 |
| 6760 /* | 7046 /* |
| 6761 ** CAPI3REF: Prepared Statement Status | 7047 ** CAPI3REF: Prepared Statement Status |
| 6762 ** METHOD: sqlite3_stmt | 7048 ** METHOD: sqlite3_stmt |
| 6763 ** | 7049 ** |
| 6764 ** ^(Each prepared statement maintains various | 7050 ** ^(Each prepared statement maintains various |
| 6765 ** [SQLITE_STMTSTATUS counters] that measure the number | 7051 ** [SQLITE_STMTSTATUS counters] that measure the number |
| 6766 ** of times it has performed specific operations.)^ These counters can | 7052 ** of times it has performed specific operations.)^ These counters can |
| 6767 ** be used to monitor the performance characteristics of the prepared | 7053 ** be used to monitor the performance characteristics of the prepared |
| 6768 ** statements. For example, if the number of table steps greatly exceeds | 7054 ** statements. For example, if the number of table steps greatly exceeds |
| 6769 ** the number of table searches or result rows, that would tend to indicate | 7055 ** the number of table searches or result rows, that would tend to indicate |
| 6770 ** that the prepared statement is using a full table scan rather than | 7056 ** that the prepared statement is using a full table scan rather than |
| 6771 ** an index. | 7057 ** an index. |
| 6772 ** | 7058 ** |
| 6773 ** ^(This interface is used to retrieve and reset counter values from | 7059 ** ^(This interface is used to retrieve and reset counter values from |
| 6774 ** a [prepared statement]. The first argument is the prepared statement | 7060 ** a [prepared statement]. The first argument is the prepared statement |
| 6775 ** object to be interrogated. The second argument | 7061 ** object to be interrogated. The second argument |
| 6776 ** is an integer code for a specific [SQLITE_STMTSTATUS counter] | 7062 ** is an integer code for a specific [SQLITE_STMTSTATUS counter] |
| 6777 ** to be interrogated.)^ | 7063 ** to be interrogated.)^ |
| 6778 ** ^The current value of the requested counter is returned. | 7064 ** ^The current value of the requested counter is returned. |
| 6779 ** ^If the resetFlg is true, then the counter is reset to zero after this | 7065 ** ^If the resetFlg is true, then the counter is reset to zero after this |
| 6780 ** interface call returns. | 7066 ** interface call returns. |
| 6781 ** | 7067 ** |
| 6782 ** See also: [sqlite3_status()] and [sqlite3_db_status()]. | 7068 ** See also: [sqlite3_status()] and [sqlite3_db_status()]. |
| 6783 */ | 7069 */ |
| 6784 SQLITE_API int SQLITE_STDCALL sqlite3_stmt_status(sqlite3_stmt*, int op,int rese
tFlg); | 7070 SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg); |
| 6785 | 7071 |
| 6786 /* | 7072 /* |
| 6787 ** CAPI3REF: Status Parameters for prepared statements | 7073 ** CAPI3REF: Status Parameters for prepared statements |
| 6788 ** KEYWORDS: {SQLITE_STMTSTATUS counter} {SQLITE_STMTSTATUS counters} | 7074 ** KEYWORDS: {SQLITE_STMTSTATUS counter} {SQLITE_STMTSTATUS counters} |
| 6789 ** | 7075 ** |
| 6790 ** These preprocessor macros define integer codes that name counter | 7076 ** These preprocessor macros define integer codes that name counter |
| 6791 ** values associated with the [sqlite3_stmt_status()] interface. | 7077 ** values associated with the [sqlite3_stmt_status()] interface. |
| 6792 ** The meanings of the various counters are as follows: | 7078 ** The meanings of the various counters are as follows: |
| 6793 ** | 7079 ** |
| 6794 ** <dl> | 7080 ** <dl> |
| (...skipping 306 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 7101 ** ^The database name is "main" for the main database, "temp" for the | 7387 ** ^The database name is "main" for the main database, "temp" for the |
| 7102 ** temporary database, or the name specified after the AS keyword in | 7388 ** temporary database, or the name specified after the AS keyword in |
| 7103 ** an [ATTACH] statement for an attached database. | 7389 ** an [ATTACH] statement for an attached database. |
| 7104 ** ^The S and M arguments passed to | 7390 ** ^The S and M arguments passed to |
| 7105 ** sqlite3_backup_init(D,N,S,M) identify the [database connection] | 7391 ** sqlite3_backup_init(D,N,S,M) identify the [database connection] |
| 7106 ** and database name of the source database, respectively. | 7392 ** and database name of the source database, respectively. |
| 7107 ** ^The source and destination [database connections] (parameters S and D) | 7393 ** ^The source and destination [database connections] (parameters S and D) |
| 7108 ** must be different or else sqlite3_backup_init(D,N,S,M) will fail with | 7394 ** must be different or else sqlite3_backup_init(D,N,S,M) will fail with |
| 7109 ** an error. | 7395 ** an error. |
| 7110 ** | 7396 ** |
| 7111 ** ^A call to sqlite3_backup_init() will fail, returning SQLITE_ERROR, if | 7397 ** ^A call to sqlite3_backup_init() will fail, returning NULL, if |
| 7112 ** there is already a read or read-write transaction open on the | 7398 ** there is already a read or read-write transaction open on the |
| 7113 ** destination database. | 7399 ** destination database. |
| 7114 ** | 7400 ** |
| 7115 ** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is | 7401 ** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is |
| 7116 ** returned and an error code and error message are stored in the | 7402 ** returned and an error code and error message are stored in the |
| 7117 ** destination [database connection] D. | 7403 ** destination [database connection] D. |
| 7118 ** ^The error code and message for the failed call to sqlite3_backup_init() | 7404 ** ^The error code and message for the failed call to sqlite3_backup_init() |
| 7119 ** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or | 7405 ** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or |
| 7120 ** [sqlite3_errmsg16()] functions. | 7406 ** [sqlite3_errmsg16()] functions. |
| 7121 ** ^A successful call to sqlite3_backup_init() returns a pointer to an | 7407 ** ^A successful call to sqlite3_backup_init() returns a pointer to an |
| (...skipping 121 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 7243 ** backed up to is not accessed by any connection within the process, | 7529 ** backed up to is not accessed by any connection within the process, |
| 7244 ** not just the specific connection that was passed to sqlite3_backup_init(). | 7530 ** not just the specific connection that was passed to sqlite3_backup_init(). |
| 7245 ** | 7531 ** |
| 7246 ** The [sqlite3_backup] object itself is partially threadsafe. Multiple | 7532 ** The [sqlite3_backup] object itself is partially threadsafe. Multiple |
| 7247 ** threads may safely make multiple concurrent calls to sqlite3_backup_step(). | 7533 ** threads may safely make multiple concurrent calls to sqlite3_backup_step(). |
| 7248 ** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount() | 7534 ** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount() |
| 7249 ** APIs are not strictly speaking threadsafe. If they are invoked at the | 7535 ** APIs are not strictly speaking threadsafe. If they are invoked at the |
| 7250 ** same time as another thread is invoking sqlite3_backup_step() it is | 7536 ** same time as another thread is invoking sqlite3_backup_step() it is |
| 7251 ** possible that they return invalid values. | 7537 ** possible that they return invalid values. |
| 7252 */ | 7538 */ |
| 7253 SQLITE_API sqlite3_backup *SQLITE_STDCALL sqlite3_backup_init( | 7539 SQLITE_API sqlite3_backup *sqlite3_backup_init( |
| 7254 sqlite3 *pDest, /* Destination database handle */ | 7540 sqlite3 *pDest, /* Destination database handle */ |
| 7255 const char *zDestName, /* Destination database name */ | 7541 const char *zDestName, /* Destination database name */ |
| 7256 sqlite3 *pSource, /* Source database handle */ | 7542 sqlite3 *pSource, /* Source database handle */ |
| 7257 const char *zSourceName /* Source database name */ | 7543 const char *zSourceName /* Source database name */ |
| 7258 ); | 7544 ); |
| 7259 SQLITE_API int SQLITE_STDCALL sqlite3_backup_step(sqlite3_backup *p, int nPage); | 7545 SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage); |
| 7260 SQLITE_API int SQLITE_STDCALL sqlite3_backup_finish(sqlite3_backup *p); | 7546 SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p); |
| 7261 SQLITE_API int SQLITE_STDCALL sqlite3_backup_remaining(sqlite3_backup *p); | 7547 SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p); |
| 7262 SQLITE_API int SQLITE_STDCALL sqlite3_backup_pagecount(sqlite3_backup *p); | 7548 SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p); |
| 7263 | 7549 |
| 7264 /* | 7550 /* |
| 7265 ** CAPI3REF: Unlock Notification | 7551 ** CAPI3REF: Unlock Notification |
| 7266 ** METHOD: sqlite3 | 7552 ** METHOD: sqlite3 |
| 7267 ** | 7553 ** |
| 7268 ** ^When running in shared-cache mode, a database operation may fail with | 7554 ** ^When running in shared-cache mode, a database operation may fail with |
| 7269 ** an [SQLITE_LOCKED] error if the required locks on the shared-cache or | 7555 ** an [SQLITE_LOCKED] error if the required locks on the shared-cache or |
| 7270 ** individual tables within the shared-cache cannot be obtained. See | 7556 ** individual tables within the shared-cache cannot be obtained. See |
| 7271 ** [SQLite Shared-Cache Mode] for a description of shared-cache locking. | 7557 ** [SQLite Shared-Cache Mode] for a description of shared-cache locking. |
| 7272 ** ^This API may be used to register a callback that SQLite will invoke | 7558 ** ^This API may be used to register a callback that SQLite will invoke |
| (...skipping 96 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 7369 ** sqlite3_unlock_notify() results in the unlock-notify callback being | 7655 ** sqlite3_unlock_notify() results in the unlock-notify callback being |
| 7370 ** invoked immediately. If the application then re-attempts the "DROP TABLE" | 7656 ** invoked immediately. If the application then re-attempts the "DROP TABLE" |
| 7371 ** or "DROP INDEX" query, an infinite loop might be the result. | 7657 ** or "DROP INDEX" query, an infinite loop might be the result. |
| 7372 ** | 7658 ** |
| 7373 ** One way around this problem is to check the extended error code returned | 7659 ** One way around this problem is to check the extended error code returned |
| 7374 ** by an sqlite3_step() call. ^(If there is a blocking connection, then the | 7660 ** by an sqlite3_step() call. ^(If there is a blocking connection, then the |
| 7375 ** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in | 7661 ** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in |
| 7376 ** the special "DROP TABLE/INDEX" case, the extended error code is just | 7662 ** the special "DROP TABLE/INDEX" case, the extended error code is just |
| 7377 ** SQLITE_LOCKED.)^ | 7663 ** SQLITE_LOCKED.)^ |
| 7378 */ | 7664 */ |
| 7379 SQLITE_API int SQLITE_STDCALL sqlite3_unlock_notify( | 7665 SQLITE_API int sqlite3_unlock_notify( |
| 7380 sqlite3 *pBlocked, /* Waiting connection */ | 7666 sqlite3 *pBlocked, /* Waiting connection */ |
| 7381 void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */ | 7667 void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */ |
| 7382 void *pNotifyArg /* Argument to pass to xNotify */ | 7668 void *pNotifyArg /* Argument to pass to xNotify */ |
| 7383 ); | 7669 ); |
| 7384 | 7670 |
| 7385 | 7671 |
| 7386 /* | 7672 /* |
| 7387 ** CAPI3REF: String Comparison | 7673 ** CAPI3REF: String Comparison |
| 7388 ** | 7674 ** |
| 7389 ** ^The [sqlite3_stricmp()] and [sqlite3_strnicmp()] APIs allow applications | 7675 ** ^The [sqlite3_stricmp()] and [sqlite3_strnicmp()] APIs allow applications |
| 7390 ** and extensions to compare the contents of two buffers containing UTF-8 | 7676 ** and extensions to compare the contents of two buffers containing UTF-8 |
| 7391 ** strings in a case-independent fashion, using the same definition of "case | 7677 ** strings in a case-independent fashion, using the same definition of "case |
| 7392 ** independence" that SQLite uses internally when comparing identifiers. | 7678 ** independence" that SQLite uses internally when comparing identifiers. |
| 7393 */ | 7679 */ |
| 7394 SQLITE_API int SQLITE_STDCALL sqlite3_stricmp(const char *, const char *); | 7680 SQLITE_API int sqlite3_stricmp(const char *, const char *); |
| 7395 SQLITE_API int SQLITE_STDCALL sqlite3_strnicmp(const char *, const char *, int); | 7681 SQLITE_API int sqlite3_strnicmp(const char *, const char *, int); |
| 7396 | 7682 |
| 7397 /* | 7683 /* |
| 7398 ** CAPI3REF: String Globbing | 7684 ** CAPI3REF: String Globbing |
| 7399 * | 7685 * |
| 7400 ** ^The [sqlite3_strglob(P,X)] interface returns zero if and only if | 7686 ** ^The [sqlite3_strglob(P,X)] interface returns zero if and only if |
| 7401 ** string X matches the [GLOB] pattern P. | 7687 ** string X matches the [GLOB] pattern P. |
| 7402 ** ^The definition of [GLOB] pattern matching used in | 7688 ** ^The definition of [GLOB] pattern matching used in |
| 7403 ** [sqlite3_strglob(P,X)] is the same as for the "X GLOB P" operator in the | 7689 ** [sqlite3_strglob(P,X)] is the same as for the "X GLOB P" operator in the |
| 7404 ** SQL dialect understood by SQLite. ^The [sqlite3_strglob(P,X)] function | 7690 ** SQL dialect understood by SQLite. ^The [sqlite3_strglob(P,X)] function |
| 7405 ** is case sensitive. | 7691 ** is case sensitive. |
| 7406 ** | 7692 ** |
| 7407 ** Note that this routine returns zero on a match and non-zero if the strings | 7693 ** Note that this routine returns zero on a match and non-zero if the strings |
| 7408 ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()]. | 7694 ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()]. |
| 7409 ** | 7695 ** |
| 7410 ** See also: [sqlite3_strlike()]. | 7696 ** See also: [sqlite3_strlike()]. |
| 7411 */ | 7697 */ |
| 7412 SQLITE_API int SQLITE_STDCALL sqlite3_strglob(const char *zGlob, const char *zSt
r); | 7698 SQLITE_API int sqlite3_strglob(const char *zGlob, const char *zStr); |
| 7413 | 7699 |
| 7414 /* Begin WebDatabase patch for Chromium */ | 7700 /* Begin WebDatabase patch for Chromium */ |
| 7415 /* Expose some SQLite internals for the WebDatabase vfs. | 7701 /* Expose some SQLite internals for the WebDatabase vfs. |
| 7416 ** DO NOT EXTEND THE USE OF THIS. | 7702 ** DO NOT EXTEND THE USE OF THIS. |
| 7417 */ | 7703 */ |
| 7418 #ifndef CHROMIUM_SQLITE_API | 7704 #ifndef CHROMIUM_SQLITE_API |
| 7419 #define CHROMIUM_SQLITE_API SQLITE_API | 7705 #define CHROMIUM_SQLITE_API SQLITE_API |
| 7420 #endif | 7706 #endif |
| 7421 #if defined(CHROMIUM_SQLITE_INTERNALS) | 7707 #if defined(CHROMIUM_SQLITE_INTERNALS) |
| 7422 #ifdef _WIN32 | 7708 #ifdef _WIN32 |
| (...skipping 25 matching lines...) Expand all Loading... |
| 7448 ** one another. | 7734 ** one another. |
| 7449 ** | 7735 ** |
| 7450 ** ^The [sqlite3_strlike(P,X,E)] function matches Unicode characters, though | 7736 ** ^The [sqlite3_strlike(P,X,E)] function matches Unicode characters, though |
| 7451 ** only ASCII characters are case folded. | 7737 ** only ASCII characters are case folded. |
| 7452 ** | 7738 ** |
| 7453 ** Note that this routine returns zero on a match and non-zero if the strings | 7739 ** Note that this routine returns zero on a match and non-zero if the strings |
| 7454 ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()]. | 7740 ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()]. |
| 7455 ** | 7741 ** |
| 7456 ** See also: [sqlite3_strglob()]. | 7742 ** See also: [sqlite3_strglob()]. |
| 7457 */ | 7743 */ |
| 7458 SQLITE_API int SQLITE_STDCALL sqlite3_strlike(const char *zGlob, const char *zSt
r, unsigned int cEsc); | 7744 SQLITE_API int sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int
cEsc); |
| 7459 | 7745 |
| 7460 /* | 7746 /* |
| 7461 ** CAPI3REF: Error Logging Interface | 7747 ** CAPI3REF: Error Logging Interface |
| 7462 ** | 7748 ** |
| 7463 ** ^The [sqlite3_log()] interface writes a message into the [error log] | 7749 ** ^The [sqlite3_log()] interface writes a message into the [error log] |
| 7464 ** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()]. | 7750 ** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()]. |
| 7465 ** ^If logging is enabled, the zFormat string and subsequent arguments are | 7751 ** ^If logging is enabled, the zFormat string and subsequent arguments are |
| 7466 ** used with [sqlite3_snprintf()] to generate the final output string. | 7752 ** used with [sqlite3_snprintf()] to generate the final output string. |
| 7467 ** | 7753 ** |
| 7468 ** The sqlite3_log() interface is intended for use by extensions such as | 7754 ** The sqlite3_log() interface is intended for use by extensions such as |
| 7469 ** virtual tables, collating functions, and SQL functions. While there is | 7755 ** virtual tables, collating functions, and SQL functions. While there is |
| 7470 ** nothing to prevent an application from calling sqlite3_log(), doing so | 7756 ** nothing to prevent an application from calling sqlite3_log(), doing so |
| 7471 ** is considered bad form. | 7757 ** is considered bad form. |
| 7472 ** | 7758 ** |
| 7473 ** The zFormat string must not be NULL. | 7759 ** The zFormat string must not be NULL. |
| 7474 ** | 7760 ** |
| 7475 ** To avoid deadlocks and other threading problems, the sqlite3_log() routine | 7761 ** To avoid deadlocks and other threading problems, the sqlite3_log() routine |
| 7476 ** will not use dynamically allocated memory. The log message is stored in | 7762 ** will not use dynamically allocated memory. The log message is stored in |
| 7477 ** a fixed-length buffer on the stack. If the log message is longer than | 7763 ** a fixed-length buffer on the stack. If the log message is longer than |
| 7478 ** a few hundred characters, it will be truncated to the length of the | 7764 ** a few hundred characters, it will be truncated to the length of the |
| 7479 ** buffer. | 7765 ** buffer. |
| 7480 */ | 7766 */ |
| 7481 SQLITE_API void SQLITE_CDECL sqlite3_log(int iErrCode, const char *zFormat, ...)
; | 7767 SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...); |
| 7482 | 7768 |
| 7483 /* | 7769 /* |
| 7484 ** CAPI3REF: Write-Ahead Log Commit Hook | 7770 ** CAPI3REF: Write-Ahead Log Commit Hook |
| 7485 ** METHOD: sqlite3 | 7771 ** METHOD: sqlite3 |
| 7486 ** | 7772 ** |
| 7487 ** ^The [sqlite3_wal_hook()] function is used to register a callback that | 7773 ** ^The [sqlite3_wal_hook()] function is used to register a callback that |
| 7488 ** is invoked each time data is committed to a database in wal mode. | 7774 ** is invoked each time data is committed to a database in wal mode. |
| 7489 ** | 7775 ** |
| 7490 ** ^(The callback is invoked by SQLite after the commit has taken place and | 7776 ** ^(The callback is invoked by SQLite after the commit has taken place and |
| 7491 ** the associated write-lock on the database released)^, so the implementation | 7777 ** the associated write-lock on the database released)^, so the implementation |
| (...skipping 13 matching lines...) Expand all Loading... |
| 7505 ** to report an error, though the commit will have still occurred. If the | 7791 ** to report an error, though the commit will have still occurred. If the |
| 7506 ** callback returns [SQLITE_ROW] or [SQLITE_DONE], or if it returns a value | 7792 ** callback returns [SQLITE_ROW] or [SQLITE_DONE], or if it returns a value |
| 7507 ** that does not correspond to any valid SQLite error code, the results | 7793 ** that does not correspond to any valid SQLite error code, the results |
| 7508 ** are undefined. | 7794 ** are undefined. |
| 7509 ** | 7795 ** |
| 7510 ** A single database handle may have at most a single write-ahead log callback | 7796 ** A single database handle may have at most a single write-ahead log callback |
| 7511 ** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any | 7797 ** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any |
| 7512 ** previously registered write-ahead log callback. ^Note that the | 7798 ** previously registered write-ahead log callback. ^Note that the |
| 7513 ** [sqlite3_wal_autocheckpoint()] interface and the | 7799 ** [sqlite3_wal_autocheckpoint()] interface and the |
| 7514 ** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will | 7800 ** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will |
| 7515 ** those overwrite any prior [sqlite3_wal_hook()] settings. | 7801 ** overwrite any prior [sqlite3_wal_hook()] settings. |
| 7516 */ | 7802 */ |
| 7517 SQLITE_API void *SQLITE_STDCALL sqlite3_wal_hook( | 7803 SQLITE_API void *sqlite3_wal_hook( |
| 7518 sqlite3*, | 7804 sqlite3*, |
| 7519 int(*)(void *,sqlite3*,const char*,int), | 7805 int(*)(void *,sqlite3*,const char*,int), |
| 7520 void* | 7806 void* |
| 7521 ); | 7807 ); |
| 7522 | 7808 |
| 7523 /* | 7809 /* |
| 7524 ** CAPI3REF: Configure an auto-checkpoint | 7810 ** CAPI3REF: Configure an auto-checkpoint |
| 7525 ** METHOD: sqlite3 | 7811 ** METHOD: sqlite3 |
| 7526 ** | 7812 ** |
| 7527 ** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around | 7813 ** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around |
| (...skipping 14 matching lines...) Expand all Loading... |
| 7542 ** | 7828 ** |
| 7543 ** ^Checkpoints initiated by this mechanism are | 7829 ** ^Checkpoints initiated by this mechanism are |
| 7544 ** [sqlite3_wal_checkpoint_v2|PASSIVE]. | 7830 ** [sqlite3_wal_checkpoint_v2|PASSIVE]. |
| 7545 ** | 7831 ** |
| 7546 ** ^Every new [database connection] defaults to having the auto-checkpoint | 7832 ** ^Every new [database connection] defaults to having the auto-checkpoint |
| 7547 ** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT] | 7833 ** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT] |
| 7548 ** pages. The use of this interface | 7834 ** pages. The use of this interface |
| 7549 ** is only necessary if the default setting is found to be suboptimal | 7835 ** is only necessary if the default setting is found to be suboptimal |
| 7550 ** for a particular application. | 7836 ** for a particular application. |
| 7551 */ | 7837 */ |
| 7552 SQLITE_API int SQLITE_STDCALL sqlite3_wal_autocheckpoint(sqlite3 *db, int N); | 7838 SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N); |
| 7553 | 7839 |
| 7554 /* | 7840 /* |
| 7555 ** CAPI3REF: Checkpoint a database | 7841 ** CAPI3REF: Checkpoint a database |
| 7556 ** METHOD: sqlite3 | 7842 ** METHOD: sqlite3 |
| 7557 ** | 7843 ** |
| 7558 ** ^(The sqlite3_wal_checkpoint(D,X) is equivalent to | 7844 ** ^(The sqlite3_wal_checkpoint(D,X) is equivalent to |
| 7559 ** [sqlite3_wal_checkpoint_v2](D,X,[SQLITE_CHECKPOINT_PASSIVE],0,0).)^ | 7845 ** [sqlite3_wal_checkpoint_v2](D,X,[SQLITE_CHECKPOINT_PASSIVE],0,0).)^ |
| 7560 ** | 7846 ** |
| 7561 ** In brief, sqlite3_wal_checkpoint(D,X) causes the content in the | 7847 ** In brief, sqlite3_wal_checkpoint(D,X) causes the content in the |
| 7562 ** [write-ahead log] for database X on [database connection] D to be | 7848 ** [write-ahead log] for database X on [database connection] D to be |
| 7563 ** transferred into the database file and for the write-ahead log to | 7849 ** transferred into the database file and for the write-ahead log to |
| 7564 ** be reset. See the [checkpointing] documentation for addition | 7850 ** be reset. See the [checkpointing] documentation for addition |
| 7565 ** information. | 7851 ** information. |
| 7566 ** | 7852 ** |
| 7567 ** This interface used to be the only way to cause a checkpoint to | 7853 ** This interface used to be the only way to cause a checkpoint to |
| 7568 ** occur. But then the newer and more powerful [sqlite3_wal_checkpoint_v2()] | 7854 ** occur. But then the newer and more powerful [sqlite3_wal_checkpoint_v2()] |
| 7569 ** interface was added. This interface is retained for backwards | 7855 ** interface was added. This interface is retained for backwards |
| 7570 ** compatibility and as a convenience for applications that need to manually | 7856 ** compatibility and as a convenience for applications that need to manually |
| 7571 ** start a callback but which do not need the full power (and corresponding | 7857 ** start a callback but which do not need the full power (and corresponding |
| 7572 ** complication) of [sqlite3_wal_checkpoint_v2()]. | 7858 ** complication) of [sqlite3_wal_checkpoint_v2()]. |
| 7573 */ | 7859 */ |
| 7574 SQLITE_API int SQLITE_STDCALL sqlite3_wal_checkpoint(sqlite3 *db, const char *zD
b); | 7860 SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb); |
| 7575 | 7861 |
| 7576 /* | 7862 /* |
| 7577 ** CAPI3REF: Checkpoint a database | 7863 ** CAPI3REF: Checkpoint a database |
| 7578 ** METHOD: sqlite3 | 7864 ** METHOD: sqlite3 |
| 7579 ** | 7865 ** |
| 7580 ** ^(The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint | 7866 ** ^(The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint |
| 7581 ** operation on database X of [database connection] D in mode M. Status | 7867 ** operation on database X of [database connection] D in mode M. Status |
| 7582 ** information is written back into integers pointed to by L and C.)^ | 7868 ** information is written back into integers pointed to by L and C.)^ |
| 7583 ** ^(The M parameter must be a valid [checkpoint mode]:)^ | 7869 ** ^(The M parameter must be a valid [checkpoint mode]:)^ |
| 7584 ** | 7870 ** |
| (...skipping 73 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 7658 ** attached database, SQLITE_ERROR is returned to the caller. | 7944 ** attached database, SQLITE_ERROR is returned to the caller. |
| 7659 ** | 7945 ** |
| 7660 ** ^Unless it returns SQLITE_MISUSE, | 7946 ** ^Unless it returns SQLITE_MISUSE, |
| 7661 ** the sqlite3_wal_checkpoint_v2() interface | 7947 ** the sqlite3_wal_checkpoint_v2() interface |
| 7662 ** sets the error information that is queried by | 7948 ** sets the error information that is queried by |
| 7663 ** [sqlite3_errcode()] and [sqlite3_errmsg()]. | 7949 ** [sqlite3_errcode()] and [sqlite3_errmsg()]. |
| 7664 ** | 7950 ** |
| 7665 ** ^The [PRAGMA wal_checkpoint] command can be used to invoke this interface | 7951 ** ^The [PRAGMA wal_checkpoint] command can be used to invoke this interface |
| 7666 ** from SQL. | 7952 ** from SQL. |
| 7667 */ | 7953 */ |
| 7668 SQLITE_API int SQLITE_STDCALL sqlite3_wal_checkpoint_v2( | 7954 SQLITE_API int sqlite3_wal_checkpoint_v2( |
| 7669 sqlite3 *db, /* Database handle */ | 7955 sqlite3 *db, /* Database handle */ |
| 7670 const char *zDb, /* Name of attached database (or NULL) */ | 7956 const char *zDb, /* Name of attached database (or NULL) */ |
| 7671 int eMode, /* SQLITE_CHECKPOINT_* value */ | 7957 int eMode, /* SQLITE_CHECKPOINT_* value */ |
| 7672 int *pnLog, /* OUT: Size of WAL log in frames */ | 7958 int *pnLog, /* OUT: Size of WAL log in frames */ |
| 7673 int *pnCkpt /* OUT: Total number of frames checkpointed */ | 7959 int *pnCkpt /* OUT: Total number of frames checkpointed */ |
| 7674 ); | 7960 ); |
| 7675 | 7961 |
| 7676 /* | 7962 /* |
| 7677 ** CAPI3REF: Checkpoint Mode Values | 7963 ** CAPI3REF: Checkpoint Mode Values |
| 7678 ** KEYWORDS: {checkpoint mode} | 7964 ** KEYWORDS: {checkpoint mode} |
| (...skipping 15 matching lines...) Expand all Loading... |
| 7694 ** of a [virtual table] implementation to configure | 7980 ** of a [virtual table] implementation to configure |
| 7695 ** various facets of the virtual table interface. | 7981 ** various facets of the virtual table interface. |
| 7696 ** | 7982 ** |
| 7697 ** If this interface is invoked outside the context of an xConnect or | 7983 ** If this interface is invoked outside the context of an xConnect or |
| 7698 ** xCreate virtual table method then the behavior is undefined. | 7984 ** xCreate virtual table method then the behavior is undefined. |
| 7699 ** | 7985 ** |
| 7700 ** At present, there is only one option that may be configured using | 7986 ** At present, there is only one option that may be configured using |
| 7701 ** this function. (See [SQLITE_VTAB_CONSTRAINT_SUPPORT].) Further options | 7987 ** this function. (See [SQLITE_VTAB_CONSTRAINT_SUPPORT].) Further options |
| 7702 ** may be added in the future. | 7988 ** may be added in the future. |
| 7703 */ | 7989 */ |
| 7704 SQLITE_API int SQLITE_CDECL sqlite3_vtab_config(sqlite3*, int op, ...); | 7990 SQLITE_API int sqlite3_vtab_config(sqlite3*, int op, ...); |
| 7705 | 7991 |
| 7706 /* | 7992 /* |
| 7707 ** CAPI3REF: Virtual Table Configuration Options | 7993 ** CAPI3REF: Virtual Table Configuration Options |
| 7708 ** | 7994 ** |
| 7709 ** These macros define the various options to the | 7995 ** These macros define the various options to the |
| 7710 ** [sqlite3_vtab_config()] interface that [virtual table] implementations | 7996 ** [sqlite3_vtab_config()] interface that [virtual table] implementations |
| 7711 ** can use to customize and optimize their behavior. | 7997 ** can use to customize and optimize their behavior. |
| 7712 ** | 7998 ** |
| 7713 ** <dl> | 7999 ** <dl> |
| 7714 ** <dt>SQLITE_VTAB_CONSTRAINT_SUPPORT | 8000 ** <dt>SQLITE_VTAB_CONSTRAINT_SUPPORT |
| (...skipping 32 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 7747 /* | 8033 /* |
| 7748 ** CAPI3REF: Determine The Virtual Table Conflict Policy | 8034 ** CAPI3REF: Determine The Virtual Table Conflict Policy |
| 7749 ** | 8035 ** |
| 7750 ** This function may only be called from within a call to the [xUpdate] method | 8036 ** This function may only be called from within a call to the [xUpdate] method |
| 7751 ** of a [virtual table] implementation for an INSERT or UPDATE operation. ^The | 8037 ** of a [virtual table] implementation for an INSERT or UPDATE operation. ^The |
| 7752 ** value returned is one of [SQLITE_ROLLBACK], [SQLITE_IGNORE], [SQLITE_FAIL], | 8038 ** value returned is one of [SQLITE_ROLLBACK], [SQLITE_IGNORE], [SQLITE_FAIL], |
| 7753 ** [SQLITE_ABORT], or [SQLITE_REPLACE], according to the [ON CONFLICT] mode | 8039 ** [SQLITE_ABORT], or [SQLITE_REPLACE], according to the [ON CONFLICT] mode |
| 7754 ** of the SQL statement that triggered the call to the [xUpdate] method of the | 8040 ** of the SQL statement that triggered the call to the [xUpdate] method of the |
| 7755 ** [virtual table]. | 8041 ** [virtual table]. |
| 7756 */ | 8042 */ |
| 7757 SQLITE_API int SQLITE_STDCALL sqlite3_vtab_on_conflict(sqlite3 *); | 8043 SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *); |
| 7758 | 8044 |
| 7759 /* | 8045 /* |
| 7760 ** CAPI3REF: Conflict resolution modes | 8046 ** CAPI3REF: Conflict resolution modes |
| 7761 ** KEYWORDS: {conflict resolution mode} | 8047 ** KEYWORDS: {conflict resolution mode} |
| 7762 ** | 8048 ** |
| 7763 ** These constants are returned by [sqlite3_vtab_on_conflict()] to | 8049 ** These constants are returned by [sqlite3_vtab_on_conflict()] to |
| 7764 ** inform a [virtual table] implementation what the [ON CONFLICT] mode | 8050 ** inform a [virtual table] implementation what the [ON CONFLICT] mode |
| 7765 ** is for the SQL statement being evaluated. | 8051 ** is for the SQL statement being evaluated. |
| 7766 ** | 8052 ** |
| 7767 ** Note that the [SQLITE_IGNORE] constant is also used as a potential | 8053 ** Note that the [SQLITE_IGNORE] constant is also used as a potential |
| (...skipping 84 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 7852 ** the statement - a non-zero value is returned and the variable that pOut | 8138 ** the statement - a non-zero value is returned and the variable that pOut |
| 7853 ** points to is unchanged. | 8139 ** points to is unchanged. |
| 7854 ** | 8140 ** |
| 7855 ** ^Statistics might not be available for all loops in all statements. ^In cases | 8141 ** ^Statistics might not be available for all loops in all statements. ^In cases |
| 7856 ** where there exist loops with no available statistics, this function behaves | 8142 ** where there exist loops with no available statistics, this function behaves |
| 7857 ** as if the loop did not exist - it returns non-zero and leave the variable | 8143 ** as if the loop did not exist - it returns non-zero and leave the variable |
| 7858 ** that pOut points to unchanged. | 8144 ** that pOut points to unchanged. |
| 7859 ** | 8145 ** |
| 7860 ** See also: [sqlite3_stmt_scanstatus_reset()] | 8146 ** See also: [sqlite3_stmt_scanstatus_reset()] |
| 7861 */ | 8147 */ |
| 7862 SQLITE_API int SQLITE_STDCALL sqlite3_stmt_scanstatus( | 8148 SQLITE_API int sqlite3_stmt_scanstatus( |
| 7863 sqlite3_stmt *pStmt, /* Prepared statement for which info desired */ | 8149 sqlite3_stmt *pStmt, /* Prepared statement for which info desired */ |
| 7864 int idx, /* Index of loop to report on */ | 8150 int idx, /* Index of loop to report on */ |
| 7865 int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */ | 8151 int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */ |
| 7866 void *pOut /* Result written here */ | 8152 void *pOut /* Result written here */ |
| 7867 ); | 8153 ); |
| 7868 | 8154 |
| 7869 /* | 8155 /* |
| 7870 ** CAPI3REF: Zero Scan-Status Counters | 8156 ** CAPI3REF: Zero Scan-Status Counters |
| 7871 ** METHOD: sqlite3_stmt | 8157 ** METHOD: sqlite3_stmt |
| 7872 ** | 8158 ** |
| 7873 ** ^Zero all [sqlite3_stmt_scanstatus()] related event counters. | 8159 ** ^Zero all [sqlite3_stmt_scanstatus()] related event counters. |
| 7874 ** | 8160 ** |
| 7875 ** This API is only available if the library is built with pre-processor | 8161 ** This API is only available if the library is built with pre-processor |
| 7876 ** symbol [SQLITE_ENABLE_STMT_SCANSTATUS] defined. | 8162 ** symbol [SQLITE_ENABLE_STMT_SCANSTATUS] defined. |
| 7877 */ | 8163 */ |
| 7878 SQLITE_API void SQLITE_STDCALL sqlite3_stmt_scanstatus_reset(sqlite3_stmt*); | 8164 SQLITE_API void sqlite3_stmt_scanstatus_reset(sqlite3_stmt*); |
| 7879 | 8165 |
| 7880 /* | 8166 /* |
| 7881 ** CAPI3REF: Flush caches to disk mid-transaction | 8167 ** CAPI3REF: Flush caches to disk mid-transaction |
| 7882 ** | 8168 ** |
| 7883 ** ^If a write-transaction is open on [database connection] D when the | 8169 ** ^If a write-transaction is open on [database connection] D when the |
| 7884 ** [sqlite3_db_cacheflush(D)] interface invoked, any dirty | 8170 ** [sqlite3_db_cacheflush(D)] interface invoked, any dirty |
| 7885 ** pages in the pager-cache that are not currently in use are written out | 8171 ** pages in the pager-cache that are not currently in use are written out |
| 7886 ** to disk. A dirty page may be in use if a database cursor created by an | 8172 ** to disk. A dirty page may be in use if a database cursor created by an |
| 7887 ** active SQL statement is reading from it, or if it is page 1 of a database | 8173 ** active SQL statement is reading from it, or if it is page 1 of a database |
| 7888 ** file (page 1 is always "in use"). ^The [sqlite3_db_cacheflush(D)] | 8174 ** file (page 1 is always "in use"). ^The [sqlite3_db_cacheflush(D)] |
| (...skipping 11 matching lines...) Expand all Loading... |
| 7900 ** | 8186 ** |
| 7901 ** ^If any other error occurs while flushing dirty pages to disk (for | 8187 ** ^If any other error occurs while flushing dirty pages to disk (for |
| 7902 ** example an IO error or out-of-memory condition), then processing is | 8188 ** example an IO error or out-of-memory condition), then processing is |
| 7903 ** abandoned and an SQLite [error code] is returned to the caller immediately. | 8189 ** abandoned and an SQLite [error code] is returned to the caller immediately. |
| 7904 ** | 8190 ** |
| 7905 ** ^Otherwise, if no error occurs, [sqlite3_db_cacheflush()] returns SQLITE_OK. | 8191 ** ^Otherwise, if no error occurs, [sqlite3_db_cacheflush()] returns SQLITE_OK. |
| 7906 ** | 8192 ** |
| 7907 ** ^This function does not set the database handle error code or message | 8193 ** ^This function does not set the database handle error code or message |
| 7908 ** returned by the [sqlite3_errcode()] and [sqlite3_errmsg()] functions. | 8194 ** returned by the [sqlite3_errcode()] and [sqlite3_errmsg()] functions. |
| 7909 */ | 8195 */ |
| 7910 SQLITE_API int SQLITE_STDCALL sqlite3_db_cacheflush(sqlite3*); | 8196 SQLITE_API int sqlite3_db_cacheflush(sqlite3*); |
| 8197 |
| 8198 /* |
| 8199 ** CAPI3REF: The pre-update hook. |
| 8200 ** |
| 8201 ** ^These interfaces are only available if SQLite is compiled using the |
| 8202 ** [SQLITE_ENABLE_PREUPDATE_HOOK] compile-time option. |
| 8203 ** |
| 8204 ** ^The [sqlite3_preupdate_hook()] interface registers a callback function |
| 8205 ** that is invoked prior to each [INSERT], [UPDATE], and [DELETE] operation |
| 8206 ** on a database table. |
| 8207 ** ^At most one preupdate hook may be registered at a time on a single |
| 8208 ** [database connection]; each call to [sqlite3_preupdate_hook()] overrides |
| 8209 ** the previous setting. |
| 8210 ** ^The preupdate hook is disabled by invoking [sqlite3_preupdate_hook()] |
| 8211 ** with a NULL pointer as the second parameter. |
| 8212 ** ^The third parameter to [sqlite3_preupdate_hook()] is passed through as |
| 8213 ** the first parameter to callbacks. |
| 8214 ** |
| 8215 ** ^The preupdate hook only fires for changes to real database tables; the |
| 8216 ** preupdate hook is not invoked for changes to [virtual tables] or to |
| 8217 ** system tables like sqlite_master or sqlite_stat1. |
| 8218 ** |
| 8219 ** ^The second parameter to the preupdate callback is a pointer to |
| 8220 ** the [database connection] that registered the preupdate hook. |
| 8221 ** ^The third parameter to the preupdate callback is one of the constants |
| 8222 ** [SQLITE_INSERT], [SQLITE_DELETE], or [SQLITE_UPDATE] to identify the |
| 8223 ** kind of update operation that is about to occur. |
| 8224 ** ^(The fourth parameter to the preupdate callback is the name of the |
| 8225 ** database within the database connection that is being modified. This |
| 8226 ** will be "main" for the main database or "temp" for TEMP tables or |
| 8227 ** the name given after the AS keyword in the [ATTACH] statement for attached |
| 8228 ** databases.)^ |
| 8229 ** ^The fifth parameter to the preupdate callback is the name of the |
| 8230 ** table that is being modified. |
| 8231 ** |
| 8232 ** For an UPDATE or DELETE operation on a [rowid table], the sixth |
| 8233 ** parameter passed to the preupdate callback is the initial [rowid] of the |
| 8234 ** row being modified or deleted. For an INSERT operation on a rowid table, |
| 8235 ** or any operation on a WITHOUT ROWID table, the value of the sixth |
| 8236 ** parameter is undefined. For an INSERT or UPDATE on a rowid table the |
| 8237 ** seventh parameter is the final rowid value of the row being inserted |
| 8238 ** or updated. The value of the seventh parameter passed to the callback |
| 8239 ** function is not defined for operations on WITHOUT ROWID tables, or for |
| 8240 ** INSERT operations on rowid tables. |
| 8241 ** |
| 8242 ** The [sqlite3_preupdate_old()], [sqlite3_preupdate_new()], |
| 8243 ** [sqlite3_preupdate_count()], and [sqlite3_preupdate_depth()] interfaces |
| 8244 ** provide additional information about a preupdate event. These routines |
| 8245 ** may only be called from within a preupdate callback. Invoking any of |
| 8246 ** these routines from outside of a preupdate callback or with a |
| 8247 ** [database connection] pointer that is different from the one supplied |
| 8248 ** to the preupdate callback results in undefined and probably undesirable |
| 8249 ** behavior. |
| 8250 ** |
| 8251 ** ^The [sqlite3_preupdate_count(D)] interface returns the number of columns |
| 8252 ** in the row that is being inserted, updated, or deleted. |
| 8253 ** |
| 8254 ** ^The [sqlite3_preupdate_old(D,N,P)] interface writes into P a pointer to |
| 8255 ** a [protected sqlite3_value] that contains the value of the Nth column of |
| 8256 ** the table row before it is updated. The N parameter must be between 0 |
| 8257 ** and one less than the number of columns or the behavior will be |
| 8258 ** undefined. This must only be used within SQLITE_UPDATE and SQLITE_DELETE |
| 8259 ** preupdate callbacks; if it is used by an SQLITE_INSERT callback then the |
| 8260 ** behavior is undefined. The [sqlite3_value] that P points to |
| 8261 ** will be destroyed when the preupdate callback returns. |
| 8262 ** |
| 8263 ** ^The [sqlite3_preupdate_new(D,N,P)] interface writes into P a pointer to |
| 8264 ** a [protected sqlite3_value] that contains the value of the Nth column of |
| 8265 ** the table row after it is updated. The N parameter must be between 0 |
| 8266 ** and one less than the number of columns or the behavior will be |
| 8267 ** undefined. This must only be used within SQLITE_INSERT and SQLITE_UPDATE |
| 8268 ** preupdate callbacks; if it is used by an SQLITE_DELETE callback then the |
| 8269 ** behavior is undefined. The [sqlite3_value] that P points to |
| 8270 ** will be destroyed when the preupdate callback returns. |
| 8271 ** |
| 8272 ** ^The [sqlite3_preupdate_depth(D)] interface returns 0 if the preupdate |
| 8273 ** callback was invoked as a result of a direct insert, update, or delete |
| 8274 ** operation; or 1 for inserts, updates, or deletes invoked by top-level |
| 8275 ** triggers; or 2 for changes resulting from triggers called by top-level |
| 8276 ** triggers; and so forth. |
| 8277 ** |
| 8278 ** See also: [sqlite3_update_hook()] |
| 8279 */ |
| 8280 #if defined(SQLITE_ENABLE_PREUPDATE_HOOK) |
| 8281 SQLITE_API void *sqlite3_preupdate_hook( |
| 8282 sqlite3 *db, |
| 8283 void(*xPreUpdate)( |
| 8284 void *pCtx, /* Copy of third arg to preupdate_hook() */ |
| 8285 sqlite3 *db, /* Database handle */ |
| 8286 int op, /* SQLITE_UPDATE, DELETE or INSERT */ |
| 8287 char const *zDb, /* Database name */ |
| 8288 char const *zName, /* Table name */ |
| 8289 sqlite3_int64 iKey1, /* Rowid of row about to be deleted/updated */ |
| 8290 sqlite3_int64 iKey2 /* New rowid value (for a rowid UPDATE) */ |
| 8291 ), |
| 8292 void* |
| 8293 ); |
| 8294 SQLITE_API int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **); |
| 8295 SQLITE_API int sqlite3_preupdate_count(sqlite3 *); |
| 8296 SQLITE_API int sqlite3_preupdate_depth(sqlite3 *); |
| 8297 SQLITE_API int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **); |
| 8298 #endif |
| 8299 |
| 8300 /* |
| 8301 ** CAPI3REF: Low-level system error code |
| 8302 ** |
| 8303 ** ^Attempt to return the underlying operating system error code or error |
| 8304 ** number that caused the most recent I/O error or failure to open a file. |
| 8305 ** The return value is OS-dependent. For example, on unix systems, after |
| 8306 ** [sqlite3_open_v2()] returns [SQLITE_CANTOPEN], this interface could be |
| 8307 ** called to get back the underlying "errno" that caused the problem, such |
| 8308 ** as ENOSPC, EAUTH, EISDIR, and so forth. |
| 8309 */ |
| 8310 SQLITE_API int sqlite3_system_errno(sqlite3*); |
| 7911 | 8311 |
| 7912 /* | 8312 /* |
| 7913 ** CAPI3REF: Database Snapshot | 8313 ** CAPI3REF: Database Snapshot |
| 7914 ** KEYWORDS: {snapshot} | 8314 ** KEYWORDS: {snapshot} {sqlite3_snapshot} |
| 7915 ** EXPERIMENTAL | 8315 ** EXPERIMENTAL |
| 7916 ** | 8316 ** |
| 7917 ** An instance of the snapshot object records the state of a [WAL mode] | 8317 ** An instance of the snapshot object records the state of a [WAL mode] |
| 7918 ** database for some specific point in history. | 8318 ** database for some specific point in history. |
| 7919 ** | 8319 ** |
| 7920 ** In [WAL mode], multiple [database connections] that are open on the | 8320 ** In [WAL mode], multiple [database connections] that are open on the |
| 7921 ** same database file can each be reading a different historical version | 8321 ** same database file can each be reading a different historical version |
| 7922 ** of the database file. When a [database connection] begins a read | 8322 ** of the database file. When a [database connection] begins a read |
| 7923 ** transaction, that connection sees an unchanging copy of the database | 8323 ** transaction, that connection sees an unchanging copy of the database |
| 7924 ** as it existed for the point in time when the transaction first started. | 8324 ** as it existed for the point in time when the transaction first started. |
| 7925 ** Subsequent changes to the database from other connections are not seen | 8325 ** Subsequent changes to the database from other connections are not seen |
| 7926 ** by the reader until a new read transaction is started. | 8326 ** by the reader until a new read transaction is started. |
| 7927 ** | 8327 ** |
| 7928 ** The sqlite3_snapshot object records state information about an historical | 8328 ** The sqlite3_snapshot object records state information about an historical |
| 7929 ** version of the database file so that it is possible to later open a new read | 8329 ** version of the database file so that it is possible to later open a new read |
| 7930 ** transaction that sees that historical version of the database rather than | 8330 ** transaction that sees that historical version of the database rather than |
| 7931 ** the most recent version. | 8331 ** the most recent version. |
| 7932 ** | 8332 ** |
| 7933 ** The constructor for this object is [sqlite3_snapshot_get()]. The | 8333 ** The constructor for this object is [sqlite3_snapshot_get()]. The |
| 7934 ** [sqlite3_snapshot_open()] method causes a fresh read transaction to refer | 8334 ** [sqlite3_snapshot_open()] method causes a fresh read transaction to refer |
| 7935 ** to an historical snapshot (if possible). The destructor for | 8335 ** to an historical snapshot (if possible). The destructor for |
| 7936 ** sqlite3_snapshot objects is [sqlite3_snapshot_free()]. | 8336 ** sqlite3_snapshot objects is [sqlite3_snapshot_free()]. |
| 7937 */ | 8337 */ |
| 7938 typedef struct sqlite3_snapshot sqlite3_snapshot; | 8338 typedef struct sqlite3_snapshot { |
| 8339 unsigned char hidden[48]; |
| 8340 } sqlite3_snapshot; |
| 7939 | 8341 |
| 7940 /* | 8342 /* |
| 7941 ** CAPI3REF: Record A Database Snapshot | 8343 ** CAPI3REF: Record A Database Snapshot |
| 7942 ** EXPERIMENTAL | 8344 ** EXPERIMENTAL |
| 7943 ** | 8345 ** |
| 7944 ** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a | 8346 ** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a |
| 7945 ** new [sqlite3_snapshot] object that records the current state of | 8347 ** new [sqlite3_snapshot] object that records the current state of |
| 7946 ** schema S in database connection D. ^On success, the | 8348 ** schema S in database connection D. ^On success, the |
| 7947 ** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly | 8349 ** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly |
| 7948 ** created [sqlite3_snapshot] object into *P and returns SQLITE_OK. | 8350 ** created [sqlite3_snapshot] object into *P and returns SQLITE_OK. |
| 7949 ** ^If schema S of [database connection] D is not a [WAL mode] database | 8351 ** If there is not already a read-transaction open on schema S when |
| 7950 ** that is in a read transaction, then [sqlite3_snapshot_get(D,S,P)] | 8352 ** this function is called, one is opened automatically. |
| 7951 ** leaves the *P value unchanged and returns an appropriate [error code]. | 8353 ** |
| 8354 ** The following must be true for this function to succeed. If any of |
| 8355 ** the following statements are false when sqlite3_snapshot_get() is |
| 8356 ** called, SQLITE_ERROR is returned. The final value of *P is undefined |
| 8357 ** in this case. |
| 8358 ** |
| 8359 ** <ul> |
| 8360 ** <li> The database handle must be in [autocommit mode]. |
| 8361 ** |
| 8362 ** <li> Schema S of [database connection] D must be a [WAL mode] database. |
| 8363 ** |
| 8364 ** <li> There must not be a write transaction open on schema S of database |
| 8365 ** connection D. |
| 8366 ** |
| 8367 ** <li> One or more transactions must have been written to the current wal |
| 8368 ** file since it was created on disk (by any connection). This means |
| 8369 ** that a snapshot cannot be taken on a wal mode database with no wal |
| 8370 ** file immediately after it is first opened. At least one transaction |
| 8371 ** must be written to it first. |
| 8372 ** </ul> |
| 8373 ** |
| 8374 ** This function may also return SQLITE_NOMEM. If it is called with the |
| 8375 ** database handle in autocommit mode but fails for some other reason, |
| 8376 ** whether or not a read transaction is opened on schema S is undefined. |
| 7952 ** | 8377 ** |
| 7953 ** The [sqlite3_snapshot] object returned from a successful call to | 8378 ** The [sqlite3_snapshot] object returned from a successful call to |
| 7954 ** [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()] | 8379 ** [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()] |
| 7955 ** to avoid a memory leak. | 8380 ** to avoid a memory leak. |
| 7956 ** | 8381 ** |
| 7957 ** The [sqlite3_snapshot_get()] interface is only available when the | 8382 ** The [sqlite3_snapshot_get()] interface is only available when the |
| 7958 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used. | 8383 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used. |
| 7959 */ | 8384 */ |
| 7960 SQLITE_API SQLITE_EXPERIMENTAL int SQLITE_STDCALL sqlite3_snapshot_get( | 8385 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_get( |
| 7961 sqlite3 *db, | 8386 sqlite3 *db, |
| 7962 const char *zSchema, | 8387 const char *zSchema, |
| 7963 sqlite3_snapshot **ppSnapshot | 8388 sqlite3_snapshot **ppSnapshot |
| 7964 ); | 8389 ); |
| 7965 | 8390 |
| 7966 /* | 8391 /* |
| 7967 ** CAPI3REF: Start a read transaction on an historical snapshot | 8392 ** CAPI3REF: Start a read transaction on an historical snapshot |
| 7968 ** EXPERIMENTAL | 8393 ** EXPERIMENTAL |
| 7969 ** | 8394 ** |
| 7970 ** ^The [sqlite3_snapshot_open(D,S,P)] interface attempts to move the | 8395 ** ^The [sqlite3_snapshot_open(D,S,P)] interface starts a |
| 7971 ** read transaction that is currently open on schema S of | 8396 ** read transaction for schema S of |
| 7972 ** [database connection] D so that it refers to historical [snapshot] P. | 8397 ** [database connection] D such that the read transaction |
| 8398 ** refers to historical [snapshot] P, rather than the most |
| 8399 ** recent change to the database. |
| 7973 ** ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK on success | 8400 ** ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK on success |
| 7974 ** or an appropriate [error code] if it fails. | 8401 ** or an appropriate [error code] if it fails. |
| 7975 ** | 8402 ** |
| 7976 ** ^In order to succeed, a call to [sqlite3_snapshot_open(D,S,P)] must be | 8403 ** ^In order to succeed, a call to [sqlite3_snapshot_open(D,S,P)] must be |
| 7977 ** the first operation, apart from other sqlite3_snapshot_open() calls, | 8404 ** the first operation following the [BEGIN] that takes the schema S |
| 7978 ** following the [BEGIN] that starts a new read transaction. | 8405 ** out of [autocommit mode]. |
| 7979 ** ^A [snapshot] will fail to open if it has been overwritten by a | 8406 ** ^In other words, schema S must not currently be in |
| 7980 ** [checkpoint]. | 8407 ** a transaction for [sqlite3_snapshot_open(D,S,P)] to work, but the |
| 8408 ** database connection D must be out of [autocommit mode]. |
| 8409 ** ^A [snapshot] will fail to open if it has been overwritten by a |
| 8410 ** [checkpoint]. |
| 8411 ** ^(A call to [sqlite3_snapshot_open(D,S,P)] will fail if the |
| 8412 ** database connection D does not know that the database file for |
| 8413 ** schema S is in [WAL mode]. A database connection might not know |
| 8414 ** that the database file is in [WAL mode] if there has been no prior |
| 8415 ** I/O on that database connection, or if the database entered [WAL mode] |
| 8416 ** after the most recent I/O on the database connection.)^ |
| 8417 ** (Hint: Run "[PRAGMA application_id]" against a newly opened |
| 8418 ** database connection in order to make it ready to use snapshots.) |
| 7981 ** | 8419 ** |
| 7982 ** The [sqlite3_snapshot_open()] interface is only available when the | 8420 ** The [sqlite3_snapshot_open()] interface is only available when the |
| 7983 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used. | 8421 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used. |
| 7984 */ | 8422 */ |
| 7985 SQLITE_API SQLITE_EXPERIMENTAL int SQLITE_STDCALL sqlite3_snapshot_open( | 8423 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_open( |
| 7986 sqlite3 *db, | 8424 sqlite3 *db, |
| 7987 const char *zSchema, | 8425 const char *zSchema, |
| 7988 sqlite3_snapshot *pSnapshot | 8426 sqlite3_snapshot *pSnapshot |
| 7989 ); | 8427 ); |
| 7990 | 8428 |
| 7991 /* | 8429 /* |
| 7992 ** CAPI3REF: Destroy a snapshot | 8430 ** CAPI3REF: Destroy a snapshot |
| 7993 ** EXPERIMENTAL | 8431 ** EXPERIMENTAL |
| 7994 ** | 8432 ** |
| 7995 ** ^The [sqlite3_snapshot_free(P)] interface destroys [sqlite3_snapshot] P. | 8433 ** ^The [sqlite3_snapshot_free(P)] interface destroys [sqlite3_snapshot] P. |
| 7996 ** The application must eventually free every [sqlite3_snapshot] object | 8434 ** The application must eventually free every [sqlite3_snapshot] object |
| 7997 ** using this routine to avoid a memory leak. | 8435 ** using this routine to avoid a memory leak. |
| 7998 ** | 8436 ** |
| 7999 ** The [sqlite3_snapshot_free()] interface is only available when the | 8437 ** The [sqlite3_snapshot_free()] interface is only available when the |
| 8000 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used. | 8438 ** SQLITE_ENABLE_SNAPSHOT compile-time option is used. |
| 8001 */ | 8439 */ |
| 8002 SQLITE_API SQLITE_EXPERIMENTAL void SQLITE_STDCALL sqlite3_snapshot_free(sqlite3
_snapshot*); | 8440 SQLITE_API SQLITE_EXPERIMENTAL void sqlite3_snapshot_free(sqlite3_snapshot*); |
| 8441 |
| 8442 /* |
| 8443 ** CAPI3REF: Compare the ages of two snapshot handles. |
| 8444 ** EXPERIMENTAL |
| 8445 ** |
| 8446 ** The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages |
| 8447 ** of two valid snapshot handles. |
| 8448 ** |
| 8449 ** If the two snapshot handles are not associated with the same database |
| 8450 ** file, the result of the comparison is undefined. |
| 8451 ** |
| 8452 ** Additionally, the result of the comparison is only valid if both of the |
| 8453 ** snapshot handles were obtained by calling sqlite3_snapshot_get() since the |
| 8454 ** last time the wal file was deleted. The wal file is deleted when the |
| 8455 ** database is changed back to rollback mode or when the number of database |
| 8456 ** clients drops to zero. If either snapshot handle was obtained before the |
| 8457 ** wal file was last deleted, the value returned by this function |
| 8458 ** is undefined. |
| 8459 ** |
| 8460 ** Otherwise, this API returns a negative value if P1 refers to an older |
| 8461 ** snapshot than P2, zero if the two handles refer to the same database |
| 8462 ** snapshot, and a positive value if P1 is a newer snapshot than P2. |
| 8463 */ |
| 8464 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_cmp( |
| 8465 sqlite3_snapshot *p1, |
| 8466 sqlite3_snapshot *p2 |
| 8467 ); |
| 8468 |
| 8469 /* |
| 8470 ** CAPI3REF: Recover snapshots from a wal file |
| 8471 ** EXPERIMENTAL |
| 8472 ** |
| 8473 ** If all connections disconnect from a database file but do not perform |
| 8474 ** a checkpoint, the existing wal file is opened along with the database |
| 8475 ** file the next time the database is opened. At this point it is only |
| 8476 ** possible to successfully call sqlite3_snapshot_open() to open the most |
| 8477 ** recent snapshot of the database (the one at the head of the wal file), |
| 8478 ** even though the wal file may contain other valid snapshots for which |
| 8479 ** clients have sqlite3_snapshot handles. |
| 8480 ** |
| 8481 ** This function attempts to scan the wal file associated with database zDb |
| 8482 ** of database handle db and make all valid snapshots available to |
| 8483 ** sqlite3_snapshot_open(). It is an error if there is already a read |
| 8484 ** transaction open on the database, or if the database is not a wal mode |
| 8485 ** database. |
| 8486 ** |
| 8487 ** SQLITE_OK is returned if successful, or an SQLite error code otherwise. |
| 8488 */ |
| 8489 SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_recover(sqlite3 *db, const c
har *zDb); |
| 8003 | 8490 |
| 8004 /* | 8491 /* |
| 8005 ** Undo the hack that converts floating point types to integer for | 8492 ** Undo the hack that converts floating point types to integer for |
| 8006 ** builds on processors without floating point support. | 8493 ** builds on processors without floating point support. |
| 8007 */ | 8494 */ |
| 8008 #ifdef SQLITE_OMIT_FLOATING_POINT | 8495 #ifdef SQLITE_OMIT_FLOATING_POINT |
| 8009 # undef double | 8496 # undef double |
| 8010 #endif | 8497 #endif |
| 8011 | 8498 |
| 8012 #ifdef __cplusplus | 8499 #ifdef __cplusplus |
| 8013 } /* End of the 'extern "C"' block */ | 8500 } /* End of the 'extern "C"' block */ |
| 8014 #endif | 8501 #endif |
| 8015 #endif /* _SQLITE3_H_ */ | 8502 #endif /* SQLITE3_H */ |
| 8016 | 8503 |
| 8504 /******** Begin file sqlite3rtree.h *********/ |
| 8017 /* | 8505 /* |
| 8018 ** 2010 August 30 | 8506 ** 2010 August 30 |
| 8019 ** | 8507 ** |
| 8020 ** The author disclaims copyright to this source code. In place of | 8508 ** The author disclaims copyright to this source code. In place of |
| 8021 ** a legal notice, here is a blessing: | 8509 ** a legal notice, here is a blessing: |
| 8022 ** | 8510 ** |
| 8023 ** May you do good and not evil. | 8511 ** May you do good and not evil. |
| 8024 ** May you find forgiveness for yourself and forgive others. | 8512 ** May you find forgiveness for yourself and forgive others. |
| 8025 ** May you share freely, never taking more than you give. | 8513 ** May you share freely, never taking more than you give. |
| 8026 ** | 8514 ** |
| (...skipping 19 matching lines...) Expand all Loading... |
| 8046 #else | 8534 #else |
| 8047 typedef double sqlite3_rtree_dbl; | 8535 typedef double sqlite3_rtree_dbl; |
| 8048 #endif | 8536 #endif |
| 8049 | 8537 |
| 8050 /* | 8538 /* |
| 8051 ** Register a geometry callback named zGeom that can be used as part of an | 8539 ** Register a geometry callback named zGeom that can be used as part of an |
| 8052 ** R-Tree geometry query as follows: | 8540 ** R-Tree geometry query as follows: |
| 8053 ** | 8541 ** |
| 8054 ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...) | 8542 ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...) |
| 8055 */ | 8543 */ |
| 8056 SQLITE_API int SQLITE_STDCALL sqlite3_rtree_geometry_callback( | 8544 SQLITE_API int sqlite3_rtree_geometry_callback( |
| 8057 sqlite3 *db, | 8545 sqlite3 *db, |
| 8058 const char *zGeom, | 8546 const char *zGeom, |
| 8059 int (*xGeom)(sqlite3_rtree_geometry*, int, sqlite3_rtree_dbl*,int*), | 8547 int (*xGeom)(sqlite3_rtree_geometry*, int, sqlite3_rtree_dbl*,int*), |
| 8060 void *pContext | 8548 void *pContext |
| 8061 ); | 8549 ); |
| 8062 | 8550 |
| 8063 | 8551 |
| 8064 /* | 8552 /* |
| 8065 ** A pointer to a structure of the following type is passed as the first | 8553 ** A pointer to a structure of the following type is passed as the first |
| 8066 ** argument to callbacks registered using rtree_geometry_callback(). | 8554 ** argument to callbacks registered using rtree_geometry_callback(). |
| 8067 */ | 8555 */ |
| 8068 struct sqlite3_rtree_geometry { | 8556 struct sqlite3_rtree_geometry { |
| 8069 void *pContext; /* Copy of pContext passed to s_r_g_c() */ | 8557 void *pContext; /* Copy of pContext passed to s_r_g_c() */ |
| 8070 int nParam; /* Size of array aParam[] */ | 8558 int nParam; /* Size of array aParam[] */ |
| 8071 sqlite3_rtree_dbl *aParam; /* Parameters passed to SQL geom function */ | 8559 sqlite3_rtree_dbl *aParam; /* Parameters passed to SQL geom function */ |
| 8072 void *pUser; /* Callback implementation user data */ | 8560 void *pUser; /* Callback implementation user data */ |
| 8073 void (*xDelUser)(void *); /* Called by SQLite to clean up pUser */ | 8561 void (*xDelUser)(void *); /* Called by SQLite to clean up pUser */ |
| 8074 }; | 8562 }; |
| 8075 | 8563 |
| 8076 /* | 8564 /* |
| 8077 ** Register a 2nd-generation geometry callback named zScore that can be | 8565 ** Register a 2nd-generation geometry callback named zScore that can be |
| 8078 ** used as part of an R-Tree geometry query as follows: | 8566 ** used as part of an R-Tree geometry query as follows: |
| 8079 ** | 8567 ** |
| 8080 ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zQueryFunc(... params ...) | 8568 ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zQueryFunc(... params ...) |
| 8081 */ | 8569 */ |
| 8082 SQLITE_API int SQLITE_STDCALL sqlite3_rtree_query_callback( | 8570 SQLITE_API int sqlite3_rtree_query_callback( |
| 8083 sqlite3 *db, | 8571 sqlite3 *db, |
| 8084 const char *zQueryFunc, | 8572 const char *zQueryFunc, |
| 8085 int (*xQueryFunc)(sqlite3_rtree_query_info*), | 8573 int (*xQueryFunc)(sqlite3_rtree_query_info*), |
| 8086 void *pContext, | 8574 void *pContext, |
| 8087 void (*xDestructor)(void*) | 8575 void (*xDestructor)(void*) |
| 8088 ); | 8576 ); |
| 8089 | 8577 |
| 8090 | 8578 |
| 8091 /* | 8579 /* |
| 8092 ** A pointer to a structure of the following type is passed as the | 8580 ** A pointer to a structure of the following type is passed as the |
| (...skipping 31 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 8124 #define PARTLY_WITHIN 1 /* Object partially overlaps query region */ | 8612 #define PARTLY_WITHIN 1 /* Object partially overlaps query region */ |
| 8125 #define FULLY_WITHIN 2 /* Object fully contained within query region */ | 8613 #define FULLY_WITHIN 2 /* Object fully contained within query region */ |
| 8126 | 8614 |
| 8127 | 8615 |
| 8128 #ifdef __cplusplus | 8616 #ifdef __cplusplus |
| 8129 } /* end of the 'extern "C"' block */ | 8617 } /* end of the 'extern "C"' block */ |
| 8130 #endif | 8618 #endif |
| 8131 | 8619 |
| 8132 #endif /* ifndef _SQLITE3RTREE_H_ */ | 8620 #endif /* ifndef _SQLITE3RTREE_H_ */ |
| 8133 | 8621 |
| 8622 /******** End of sqlite3rtree.h *********/ |
| 8623 /******** Begin file sqlite3session.h *********/ |
| 8624 |
| 8625 #if !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION) |
| 8626 #define __SQLITESESSION_H_ 1 |
| 8627 |
| 8628 /* |
| 8629 ** Make sure we can call this stuff from C++. |
| 8630 */ |
| 8631 #ifdef __cplusplus |
| 8632 extern "C" { |
| 8633 #endif |
| 8634 |
| 8635 |
| 8636 /* |
| 8637 ** CAPI3REF: Session Object Handle |
| 8638 */ |
| 8639 typedef struct sqlite3_session sqlite3_session; |
| 8640 |
| 8641 /* |
| 8642 ** CAPI3REF: Changeset Iterator Handle |
| 8643 */ |
| 8644 typedef struct sqlite3_changeset_iter sqlite3_changeset_iter; |
| 8645 |
| 8646 /* |
| 8647 ** CAPI3REF: Create A New Session Object |
| 8648 ** |
| 8649 ** Create a new session object attached to database handle db. If successful, |
| 8650 ** a pointer to the new object is written to *ppSession and SQLITE_OK is |
| 8651 ** returned. If an error occurs, *ppSession is set to NULL and an SQLite |
| 8652 ** error code (e.g. SQLITE_NOMEM) is returned. |
| 8653 ** |
| 8654 ** It is possible to create multiple session objects attached to a single |
| 8655 ** database handle. |
| 8656 ** |
| 8657 ** Session objects created using this function should be deleted using the |
| 8658 ** [sqlite3session_delete()] function before the database handle that they |
| 8659 ** are attached to is itself closed. If the database handle is closed before |
| 8660 ** the session object is deleted, then the results of calling any session |
| 8661 ** module function, including [sqlite3session_delete()] on the session object |
| 8662 ** are undefined. |
| 8663 ** |
| 8664 ** Because the session module uses the [sqlite3_preupdate_hook()] API, it |
| 8665 ** is not possible for an application to register a pre-update hook on a |
| 8666 ** database handle that has one or more session objects attached. Nor is |
| 8667 ** it possible to create a session object attached to a database handle for |
| 8668 ** which a pre-update hook is already defined. The results of attempting |
| 8669 ** either of these things are undefined. |
| 8670 ** |
| 8671 ** The session object will be used to create changesets for tables in |
| 8672 ** database zDb, where zDb is either "main", or "temp", or the name of an |
| 8673 ** attached database. It is not an error if database zDb is not attached |
| 8674 ** to the database when the session object is created. |
| 8675 */ |
| 8676 SQLITE_API int sqlite3session_create( |
| 8677 sqlite3 *db, /* Database handle */ |
| 8678 const char *zDb, /* Name of db (e.g. "main") */ |
| 8679 sqlite3_session **ppSession /* OUT: New session object */ |
| 8680 ); |
| 8681 |
| 8682 /* |
| 8683 ** CAPI3REF: Delete A Session Object |
| 8684 ** |
| 8685 ** Delete a session object previously allocated using |
| 8686 ** [sqlite3session_create()]. Once a session object has been deleted, the |
| 8687 ** results of attempting to use pSession with any other session module |
| 8688 ** function are undefined. |
| 8689 ** |
| 8690 ** Session objects must be deleted before the database handle to which they |
| 8691 ** are attached is closed. Refer to the documentation for |
| 8692 ** [sqlite3session_create()] for details. |
| 8693 */ |
| 8694 SQLITE_API void sqlite3session_delete(sqlite3_session *pSession); |
| 8695 |
| 8696 |
| 8697 /* |
| 8698 ** CAPI3REF: Enable Or Disable A Session Object |
| 8699 ** |
| 8700 ** Enable or disable the recording of changes by a session object. When |
| 8701 ** enabled, a session object records changes made to the database. When |
| 8702 ** disabled - it does not. A newly created session object is enabled. |
| 8703 ** Refer to the documentation for [sqlite3session_changeset()] for further |
| 8704 ** details regarding how enabling and disabling a session object affects |
| 8705 ** the eventual changesets. |
| 8706 ** |
| 8707 ** Passing zero to this function disables the session. Passing a value |
| 8708 ** greater than zero enables it. Passing a value less than zero is a |
| 8709 ** no-op, and may be used to query the current state of the session. |
| 8710 ** |
| 8711 ** The return value indicates the final state of the session object: 0 if |
| 8712 ** the session is disabled, or 1 if it is enabled. |
| 8713 */ |
| 8714 SQLITE_API int sqlite3session_enable(sqlite3_session *pSession, int bEnable); |
| 8715 |
| 8716 /* |
| 8717 ** CAPI3REF: Set Or Clear the Indirect Change Flag |
| 8718 ** |
| 8719 ** Each change recorded by a session object is marked as either direct or |
| 8720 ** indirect. A change is marked as indirect if either: |
| 8721 ** |
| 8722 ** <ul> |
| 8723 ** <li> The session object "indirect" flag is set when the change is |
| 8724 ** made, or |
| 8725 ** <li> The change is made by an SQL trigger or foreign key action |
| 8726 ** instead of directly as a result of a users SQL statement. |
| 8727 ** </ul> |
| 8728 ** |
| 8729 ** If a single row is affected by more than one operation within a session, |
| 8730 ** then the change is considered indirect if all operations meet the criteria |
| 8731 ** for an indirect change above, or direct otherwise. |
| 8732 ** |
| 8733 ** This function is used to set, clear or query the session object indirect |
| 8734 ** flag. If the second argument passed to this function is zero, then the |
| 8735 ** indirect flag is cleared. If it is greater than zero, the indirect flag |
| 8736 ** is set. Passing a value less than zero does not modify the current value |
| 8737 ** of the indirect flag, and may be used to query the current state of the |
| 8738 ** indirect flag for the specified session object. |
| 8739 ** |
| 8740 ** The return value indicates the final state of the indirect flag: 0 if |
| 8741 ** it is clear, or 1 if it is set. |
| 8742 */ |
| 8743 SQLITE_API int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect)
; |
| 8744 |
| 8745 /* |
| 8746 ** CAPI3REF: Attach A Table To A Session Object |
| 8747 ** |
| 8748 ** If argument zTab is not NULL, then it is the name of a table to attach |
| 8749 ** to the session object passed as the first argument. All subsequent changes |
| 8750 ** made to the table while the session object is enabled will be recorded. See |
| 8751 ** documentation for [sqlite3session_changeset()] for further details. |
| 8752 ** |
| 8753 ** Or, if argument zTab is NULL, then changes are recorded for all tables |
| 8754 ** in the database. If additional tables are added to the database (by |
| 8755 ** executing "CREATE TABLE" statements) after this call is made, changes for |
| 8756 ** the new tables are also recorded. |
| 8757 ** |
| 8758 ** Changes can only be recorded for tables that have a PRIMARY KEY explicitly |
| 8759 ** defined as part of their CREATE TABLE statement. It does not matter if the |
| 8760 ** PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY |
| 8761 ** KEY may consist of a single column, or may be a composite key. |
| 8762 ** |
| 8763 ** It is not an error if the named table does not exist in the database. Nor |
| 8764 ** is it an error if the named table does not have a PRIMARY KEY. However, |
| 8765 ** no changes will be recorded in either of these scenarios. |
| 8766 ** |
| 8767 ** Changes are not recorded for individual rows that have NULL values stored |
| 8768 ** in one or more of their PRIMARY KEY columns. |
| 8769 ** |
| 8770 ** SQLITE_OK is returned if the call completes without error. Or, if an error |
| 8771 ** occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned. |
| 8772 */ |
| 8773 SQLITE_API int sqlite3session_attach( |
| 8774 sqlite3_session *pSession, /* Session object */ |
| 8775 const char *zTab /* Table name */ |
| 8776 ); |
| 8777 |
| 8778 /* |
| 8779 ** CAPI3REF: Set a table filter on a Session Object. |
| 8780 ** |
| 8781 ** The second argument (xFilter) is the "filter callback". For changes to rows |
| 8782 ** in tables that are not attached to the Session object, the filter is called |
| 8783 ** to determine whether changes to the table's rows should be tracked or not. |
| 8784 ** If xFilter returns 0, changes is not tracked. Note that once a table is |
| 8785 ** attached, xFilter will not be called again. |
| 8786 */ |
| 8787 SQLITE_API void sqlite3session_table_filter( |
| 8788 sqlite3_session *pSession, /* Session object */ |
| 8789 int(*xFilter)( |
| 8790 void *pCtx, /* Copy of third arg to _filter_table() */ |
| 8791 const char *zTab /* Table name */ |
| 8792 ), |
| 8793 void *pCtx /* First argument passed to xFilter */ |
| 8794 ); |
| 8795 |
| 8796 /* |
| 8797 ** CAPI3REF: Generate A Changeset From A Session Object |
| 8798 ** |
| 8799 ** Obtain a changeset containing changes to the tables attached to the |
| 8800 ** session object passed as the first argument. If successful, |
| 8801 ** set *ppChangeset to point to a buffer containing the changeset |
| 8802 ** and *pnChangeset to the size of the changeset in bytes before returning |
| 8803 ** SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to |
| 8804 ** zero and return an SQLite error code. |
| 8805 ** |
| 8806 ** A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes, |
| 8807 ** each representing a change to a single row of an attached table. An INSERT |
| 8808 ** change contains the values of each field of a new database row. A DELETE |
| 8809 ** contains the original values of each field of a deleted database row. An |
| 8810 ** UPDATE change contains the original values of each field of an updated |
| 8811 ** database row along with the updated values for each updated non-primary-key |
| 8812 ** column. It is not possible for an UPDATE change to represent a change that |
| 8813 ** modifies the values of primary key columns. If such a change is made, it |
| 8814 ** is represented in a changeset as a DELETE followed by an INSERT. |
| 8815 ** |
| 8816 ** Changes are not recorded for rows that have NULL values stored in one or |
| 8817 ** more of their PRIMARY KEY columns. If such a row is inserted or deleted, |
| 8818 ** no corresponding change is present in the changesets returned by this |
| 8819 ** function. If an existing row with one or more NULL values stored in |
| 8820 ** PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL, |
| 8821 ** only an INSERT is appears in the changeset. Similarly, if an existing row |
| 8822 ** with non-NULL PRIMARY KEY values is updated so that one or more of its |
| 8823 ** PRIMARY KEY columns are set to NULL, the resulting changeset contains a |
| 8824 ** DELETE change only. |
| 8825 ** |
| 8826 ** The contents of a changeset may be traversed using an iterator created |
| 8827 ** using the [sqlite3changeset_start()] API. A changeset may be applied to |
| 8828 ** a database with a compatible schema using the [sqlite3changeset_apply()] |
| 8829 ** API. |
| 8830 ** |
| 8831 ** Within a changeset generated by this function, all changes related to a |
| 8832 ** single table are grouped together. In other words, when iterating through |
| 8833 ** a changeset or when applying a changeset to a database, all changes related |
| 8834 ** to a single table are processed before moving on to the next table. Tables |
| 8835 ** are sorted in the same order in which they were attached (or auto-attached) |
| 8836 ** to the sqlite3_session object. The order in which the changes related to |
| 8837 ** a single table are stored is undefined. |
| 8838 ** |
| 8839 ** Following a successful call to this function, it is the responsibility of |
| 8840 ** the caller to eventually free the buffer that *ppChangeset points to using |
| 8841 ** [sqlite3_free()]. |
| 8842 ** |
| 8843 ** <h3>Changeset Generation</h3> |
| 8844 ** |
| 8845 ** Once a table has been attached to a session object, the session object |
| 8846 ** records the primary key values of all new rows inserted into the table. |
| 8847 ** It also records the original primary key and other column values of any |
| 8848 ** deleted or updated rows. For each unique primary key value, data is only |
| 8849 ** recorded once - the first time a row with said primary key is inserted, |
| 8850 ** updated or deleted in the lifetime of the session. |
| 8851 ** |
| 8852 ** There is one exception to the previous paragraph: when a row is inserted, |
| 8853 ** updated or deleted, if one or more of its primary key columns contain a |
| 8854 ** NULL value, no record of the change is made. |
| 8855 ** |
| 8856 ** The session object therefore accumulates two types of records - those |
| 8857 ** that consist of primary key values only (created when the user inserts |
| 8858 ** a new record) and those that consist of the primary key values and the |
| 8859 ** original values of other table columns (created when the users deletes |
| 8860 ** or updates a record). |
| 8861 ** |
| 8862 ** When this function is called, the requested changeset is created using |
| 8863 ** both the accumulated records and the current contents of the database |
| 8864 ** file. Specifically: |
| 8865 ** |
| 8866 ** <ul> |
| 8867 ** <li> For each record generated by an insert, the database is queried |
| 8868 ** for a row with a matching primary key. If one is found, an INSERT |
| 8869 ** change is added to the changeset. If no such row is found, no change |
| 8870 ** is added to the changeset. |
| 8871 ** |
| 8872 ** <li> For each record generated by an update or delete, the database is |
| 8873 ** queried for a row with a matching primary key. If such a row is |
| 8874 ** found and one or more of the non-primary key fields have been |
| 8875 ** modified from their original values, an UPDATE change is added to |
| 8876 ** the changeset. Or, if no such row is found in the table, a DELETE |
| 8877 ** change is added to the changeset. If there is a row with a matching |
| 8878 ** primary key in the database, but all fields contain their original |
| 8879 ** values, no change is added to the changeset. |
| 8880 ** </ul> |
| 8881 ** |
| 8882 ** This means, amongst other things, that if a row is inserted and then later |
| 8883 ** deleted while a session object is active, neither the insert nor the delete |
| 8884 ** will be present in the changeset. Or if a row is deleted and then later a |
| 8885 ** row with the same primary key values inserted while a session object is |
| 8886 ** active, the resulting changeset will contain an UPDATE change instead of |
| 8887 ** a DELETE and an INSERT. |
| 8888 ** |
| 8889 ** When a session object is disabled (see the [sqlite3session_enable()] API), |
| 8890 ** it does not accumulate records when rows are inserted, updated or deleted. |
| 8891 ** This may appear to have some counter-intuitive effects if a single row |
| 8892 ** is written to more than once during a session. For example, if a row |
| 8893 ** is inserted while a session object is enabled, then later deleted while |
| 8894 ** the same session object is disabled, no INSERT record will appear in the |
| 8895 ** changeset, even though the delete took place while the session was disabled. |
| 8896 ** Or, if one field of a row is updated while a session is disabled, and |
| 8897 ** another field of the same row is updated while the session is enabled, the |
| 8898 ** resulting changeset will contain an UPDATE change that updates both fields. |
| 8899 */ |
| 8900 SQLITE_API int sqlite3session_changeset( |
| 8901 sqlite3_session *pSession, /* Session object */ |
| 8902 int *pnChangeset, /* OUT: Size of buffer at *ppChangeset */ |
| 8903 void **ppChangeset /* OUT: Buffer containing changeset */ |
| 8904 ); |
| 8905 |
| 8906 /* |
| 8907 ** CAPI3REF: Load The Difference Between Tables Into A Session |
| 8908 ** |
| 8909 ** If it is not already attached to the session object passed as the first |
| 8910 ** argument, this function attaches table zTbl in the same manner as the |
| 8911 ** [sqlite3session_attach()] function. If zTbl does not exist, or if it |
| 8912 ** does not have a primary key, this function is a no-op (but does not return |
| 8913 ** an error). |
| 8914 ** |
| 8915 ** Argument zFromDb must be the name of a database ("main", "temp" etc.) |
| 8916 ** attached to the same database handle as the session object that contains |
| 8917 ** a table compatible with the table attached to the session by this function. |
| 8918 ** A table is considered compatible if it: |
| 8919 ** |
| 8920 ** <ul> |
| 8921 ** <li> Has the same name, |
| 8922 ** <li> Has the same set of columns declared in the same order, and |
| 8923 ** <li> Has the same PRIMARY KEY definition. |
| 8924 ** </ul> |
| 8925 ** |
| 8926 ** If the tables are not compatible, SQLITE_SCHEMA is returned. If the tables |
| 8927 ** are compatible but do not have any PRIMARY KEY columns, it is not an error |
| 8928 ** but no changes are added to the session object. As with other session |
| 8929 ** APIs, tables without PRIMARY KEYs are simply ignored. |
| 8930 ** |
| 8931 ** This function adds a set of changes to the session object that could be |
| 8932 ** used to update the table in database zFrom (call this the "from-table") |
| 8933 ** so that its content is the same as the table attached to the session |
| 8934 ** object (call this the "to-table"). Specifically: |
| 8935 ** |
| 8936 ** <ul> |
| 8937 ** <li> For each row (primary key) that exists in the to-table but not in |
| 8938 ** the from-table, an INSERT record is added to the session object. |
| 8939 ** |
| 8940 ** <li> For each row (primary key) that exists in the to-table but not in |
| 8941 ** the from-table, a DELETE record is added to the session object. |
| 8942 ** |
| 8943 ** <li> For each row (primary key) that exists in both tables, but features |
| 8944 ** different non-PK values in each, an UPDATE record is added to the |
| 8945 ** session. |
| 8946 ** </ul> |
| 8947 ** |
| 8948 ** To clarify, if this function is called and then a changeset constructed |
| 8949 ** using [sqlite3session_changeset()], then after applying that changeset to |
| 8950 ** database zFrom the contents of the two compatible tables would be |
| 8951 ** identical. |
| 8952 ** |
| 8953 ** It an error if database zFrom does not exist or does not contain the |
| 8954 ** required compatible table. |
| 8955 ** |
| 8956 ** If the operation successful, SQLITE_OK is returned. Otherwise, an SQLite |
| 8957 ** error code. In this case, if argument pzErrMsg is not NULL, *pzErrMsg |
| 8958 ** may be set to point to a buffer containing an English language error |
| 8959 ** message. It is the responsibility of the caller to free this buffer using |
| 8960 ** sqlite3_free(). |
| 8961 */ |
| 8962 SQLITE_API int sqlite3session_diff( |
| 8963 sqlite3_session *pSession, |
| 8964 const char *zFromDb, |
| 8965 const char *zTbl, |
| 8966 char **pzErrMsg |
| 8967 ); |
| 8968 |
| 8969 |
| 8970 /* |
| 8971 ** CAPI3REF: Generate A Patchset From A Session Object |
| 8972 ** |
| 8973 ** The differences between a patchset and a changeset are that: |
| 8974 ** |
| 8975 ** <ul> |
| 8976 ** <li> DELETE records consist of the primary key fields only. The |
| 8977 ** original values of other fields are omitted. |
| 8978 ** <li> The original values of any modified fields are omitted from |
| 8979 ** UPDATE records. |
| 8980 ** </ul> |
| 8981 ** |
| 8982 ** A patchset blob may be used with up to date versions of all |
| 8983 ** sqlite3changeset_xxx API functions except for sqlite3changeset_invert(), |
| 8984 ** which returns SQLITE_CORRUPT if it is passed a patchset. Similarly, |
| 8985 ** attempting to use a patchset blob with old versions of the |
| 8986 ** sqlite3changeset_xxx APIs also provokes an SQLITE_CORRUPT error. |
| 8987 ** |
| 8988 ** Because the non-primary key "old.*" fields are omitted, no |
| 8989 ** SQLITE_CHANGESET_DATA conflicts can be detected or reported if a patchset |
| 8990 ** is passed to the sqlite3changeset_apply() API. Other conflict types work |
| 8991 ** in the same way as for changesets. |
| 8992 ** |
| 8993 ** Changes within a patchset are ordered in the same way as for changesets |
| 8994 ** generated by the sqlite3session_changeset() function (i.e. all changes for |
| 8995 ** a single table are grouped together, tables appear in the order in which |
| 8996 ** they were attached to the session object). |
| 8997 */ |
| 8998 SQLITE_API int sqlite3session_patchset( |
| 8999 sqlite3_session *pSession, /* Session object */ |
| 9000 int *pnPatchset, /* OUT: Size of buffer at *ppChangeset */ |
| 9001 void **ppPatchset /* OUT: Buffer containing changeset */ |
| 9002 ); |
| 9003 |
| 9004 /* |
| 9005 ** CAPI3REF: Test if a changeset has recorded any changes. |
| 9006 ** |
| 9007 ** Return non-zero if no changes to attached tables have been recorded by |
| 9008 ** the session object passed as the first argument. Otherwise, if one or |
| 9009 ** more changes have been recorded, return zero. |
| 9010 ** |
| 9011 ** Even if this function returns zero, it is possible that calling |
| 9012 ** [sqlite3session_changeset()] on the session handle may still return a |
| 9013 ** changeset that contains no changes. This can happen when a row in |
| 9014 ** an attached table is modified and then later on the original values |
| 9015 ** are restored. However, if this function returns non-zero, then it is |
| 9016 ** guaranteed that a call to sqlite3session_changeset() will return a |
| 9017 ** changeset containing zero changes. |
| 9018 */ |
| 9019 SQLITE_API int sqlite3session_isempty(sqlite3_session *pSession); |
| 9020 |
| 9021 /* |
| 9022 ** CAPI3REF: Create An Iterator To Traverse A Changeset |
| 9023 ** |
| 9024 ** Create an iterator used to iterate through the contents of a changeset. |
| 9025 ** If successful, *pp is set to point to the iterator handle and SQLITE_OK |
| 9026 ** is returned. Otherwise, if an error occurs, *pp is set to zero and an |
| 9027 ** SQLite error code is returned. |
| 9028 ** |
| 9029 ** The following functions can be used to advance and query a changeset |
| 9030 ** iterator created by this function: |
| 9031 ** |
| 9032 ** <ul> |
| 9033 ** <li> [sqlite3changeset_next()] |
| 9034 ** <li> [sqlite3changeset_op()] |
| 9035 ** <li> [sqlite3changeset_new()] |
| 9036 ** <li> [sqlite3changeset_old()] |
| 9037 ** </ul> |
| 9038 ** |
| 9039 ** It is the responsibility of the caller to eventually destroy the iterator |
| 9040 ** by passing it to [sqlite3changeset_finalize()]. The buffer containing the |
| 9041 ** changeset (pChangeset) must remain valid until after the iterator is |
| 9042 ** destroyed. |
| 9043 ** |
| 9044 ** Assuming the changeset blob was created by one of the |
| 9045 ** [sqlite3session_changeset()], [sqlite3changeset_concat()] or |
| 9046 ** [sqlite3changeset_invert()] functions, all changes within the changeset |
| 9047 ** that apply to a single table are grouped together. This means that when |
| 9048 ** an application iterates through a changeset using an iterator created by |
| 9049 ** this function, all changes that relate to a single table are visited |
| 9050 ** consecutively. There is no chance that the iterator will visit a change |
| 9051 ** the applies to table X, then one for table Y, and then later on visit |
| 9052 ** another change for table X. |
| 9053 */ |
| 9054 SQLITE_API int sqlite3changeset_start( |
| 9055 sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */ |
| 9056 int nChangeset, /* Size of changeset blob in bytes */ |
| 9057 void *pChangeset /* Pointer to blob containing changeset */ |
| 9058 ); |
| 9059 |
| 9060 |
| 9061 /* |
| 9062 ** CAPI3REF: Advance A Changeset Iterator |
| 9063 ** |
| 9064 ** This function may only be used with iterators created by function |
| 9065 ** [sqlite3changeset_start()]. If it is called on an iterator passed to |
| 9066 ** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE |
| 9067 ** is returned and the call has no effect. |
| 9068 ** |
| 9069 ** Immediately after an iterator is created by sqlite3changeset_start(), it |
| 9070 ** does not point to any change in the changeset. Assuming the changeset |
| 9071 ** is not empty, the first call to this function advances the iterator to |
| 9072 ** point to the first change in the changeset. Each subsequent call advances |
| 9073 ** the iterator to point to the next change in the changeset (if any). If |
| 9074 ** no error occurs and the iterator points to a valid change after a call |
| 9075 ** to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned. |
| 9076 ** Otherwise, if all changes in the changeset have already been visited, |
| 9077 ** SQLITE_DONE is returned. |
| 9078 ** |
| 9079 ** If an error occurs, an SQLite error code is returned. Possible error |
| 9080 ** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or |
| 9081 ** SQLITE_NOMEM. |
| 9082 */ |
| 9083 SQLITE_API int sqlite3changeset_next(sqlite3_changeset_iter *pIter); |
| 9084 |
| 9085 /* |
| 9086 ** CAPI3REF: Obtain The Current Operation From A Changeset Iterator |
| 9087 ** |
| 9088 ** The pIter argument passed to this function may either be an iterator |
| 9089 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator |
| 9090 ** created by [sqlite3changeset_start()]. In the latter case, the most recent |
| 9091 ** call to [sqlite3changeset_next()] must have returned [SQLITE_ROW]. If this |
| 9092 ** is not the case, this function returns [SQLITE_MISUSE]. |
| 9093 ** |
| 9094 ** If argument pzTab is not NULL, then *pzTab is set to point to a |
| 9095 ** nul-terminated utf-8 encoded string containing the name of the table |
| 9096 ** affected by the current change. The buffer remains valid until either |
| 9097 ** sqlite3changeset_next() is called on the iterator or until the |
| 9098 ** conflict-handler function returns. If pnCol is not NULL, then *pnCol is |
| 9099 ** set to the number of columns in the table affected by the change. If |
| 9100 ** pbIncorrect is not NULL, then *pbIndirect is set to true (1) if the change |
| 9101 ** is an indirect change, or false (0) otherwise. See the documentation for |
| 9102 ** [sqlite3session_indirect()] for a description of direct and indirect |
| 9103 ** changes. Finally, if pOp is not NULL, then *pOp is set to one of |
| 9104 ** [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], depending on the |
| 9105 ** type of change that the iterator currently points to. |
| 9106 ** |
| 9107 ** If no error occurs, SQLITE_OK is returned. If an error does occur, an |
| 9108 ** SQLite error code is returned. The values of the output variables may not |
| 9109 ** be trusted in this case. |
| 9110 */ |
| 9111 SQLITE_API int sqlite3changeset_op( |
| 9112 sqlite3_changeset_iter *pIter, /* Iterator object */ |
| 9113 const char **pzTab, /* OUT: Pointer to table name */ |
| 9114 int *pnCol, /* OUT: Number of columns in table */ |
| 9115 int *pOp, /* OUT: SQLITE_INSERT, DELETE or UPDATE */ |
| 9116 int *pbIndirect /* OUT: True for an 'indirect' change */ |
| 9117 ); |
| 9118 |
| 9119 /* |
| 9120 ** CAPI3REF: Obtain The Primary Key Definition Of A Table |
| 9121 ** |
| 9122 ** For each modified table, a changeset includes the following: |
| 9123 ** |
| 9124 ** <ul> |
| 9125 ** <li> The number of columns in the table, and |
| 9126 ** <li> Which of those columns make up the tables PRIMARY KEY. |
| 9127 ** </ul> |
| 9128 ** |
| 9129 ** This function is used to find which columns comprise the PRIMARY KEY of |
| 9130 ** the table modified by the change that iterator pIter currently points to. |
| 9131 ** If successful, *pabPK is set to point to an array of nCol entries, where |
| 9132 ** nCol is the number of columns in the table. Elements of *pabPK are set to |
| 9133 ** 0x01 if the corresponding column is part of the tables primary key, or |
| 9134 ** 0x00 if it is not. |
| 9135 ** |
| 9136 ** If argument pnCol is not NULL, then *pnCol is set to the number of columns |
| 9137 ** in the table. |
| 9138 ** |
| 9139 ** If this function is called when the iterator does not point to a valid |
| 9140 ** entry, SQLITE_MISUSE is returned and the output variables zeroed. Otherwise, |
| 9141 ** SQLITE_OK is returned and the output variables populated as described |
| 9142 ** above. |
| 9143 */ |
| 9144 SQLITE_API int sqlite3changeset_pk( |
| 9145 sqlite3_changeset_iter *pIter, /* Iterator object */ |
| 9146 unsigned char **pabPK, /* OUT: Array of boolean - true for PK cols */ |
| 9147 int *pnCol /* OUT: Number of entries in output array */ |
| 9148 ); |
| 9149 |
| 9150 /* |
| 9151 ** CAPI3REF: Obtain old.* Values From A Changeset Iterator |
| 9152 ** |
| 9153 ** The pIter argument passed to this function may either be an iterator |
| 9154 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator |
| 9155 ** created by [sqlite3changeset_start()]. In the latter case, the most recent |
| 9156 ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW. |
| 9157 ** Furthermore, it may only be called if the type of change that the iterator |
| 9158 ** currently points to is either [SQLITE_DELETE] or [SQLITE_UPDATE]. Otherwise, |
| 9159 ** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL. |
| 9160 ** |
| 9161 ** Argument iVal must be greater than or equal to 0, and less than the number |
| 9162 ** of columns in the table affected by the current change. Otherwise, |
| 9163 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL. |
| 9164 ** |
| 9165 ** If successful, this function sets *ppValue to point to a protected |
| 9166 ** sqlite3_value object containing the iVal'th value from the vector of |
| 9167 ** original row values stored as part of the UPDATE or DELETE change and |
| 9168 ** returns SQLITE_OK. The name of the function comes from the fact that this |
| 9169 ** is similar to the "old.*" columns available to update or delete triggers. |
| 9170 ** |
| 9171 ** If some other error occurs (e.g. an OOM condition), an SQLite error code |
| 9172 ** is returned and *ppValue is set to NULL. |
| 9173 */ |
| 9174 SQLITE_API int sqlite3changeset_old( |
| 9175 sqlite3_changeset_iter *pIter, /* Changeset iterator */ |
| 9176 int iVal, /* Column number */ |
| 9177 sqlite3_value **ppValue /* OUT: Old value (or NULL pointer) */ |
| 9178 ); |
| 9179 |
| 9180 /* |
| 9181 ** CAPI3REF: Obtain new.* Values From A Changeset Iterator |
| 9182 ** |
| 9183 ** The pIter argument passed to this function may either be an iterator |
| 9184 ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator |
| 9185 ** created by [sqlite3changeset_start()]. In the latter case, the most recent |
| 9186 ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW. |
| 9187 ** Furthermore, it may only be called if the type of change that the iterator |
| 9188 ** currently points to is either [SQLITE_UPDATE] or [SQLITE_INSERT]. Otherwise, |
| 9189 ** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL. |
| 9190 ** |
| 9191 ** Argument iVal must be greater than or equal to 0, and less than the number |
| 9192 ** of columns in the table affected by the current change. Otherwise, |
| 9193 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL. |
| 9194 ** |
| 9195 ** If successful, this function sets *ppValue to point to a protected |
| 9196 ** sqlite3_value object containing the iVal'th value from the vector of |
| 9197 ** new row values stored as part of the UPDATE or INSERT change and |
| 9198 ** returns SQLITE_OK. If the change is an UPDATE and does not include |
| 9199 ** a new value for the requested column, *ppValue is set to NULL and |
| 9200 ** SQLITE_OK returned. The name of the function comes from the fact that |
| 9201 ** this is similar to the "new.*" columns available to update or delete |
| 9202 ** triggers. |
| 9203 ** |
| 9204 ** If some other error occurs (e.g. an OOM condition), an SQLite error code |
| 9205 ** is returned and *ppValue is set to NULL. |
| 9206 */ |
| 9207 SQLITE_API int sqlite3changeset_new( |
| 9208 sqlite3_changeset_iter *pIter, /* Changeset iterator */ |
| 9209 int iVal, /* Column number */ |
| 9210 sqlite3_value **ppValue /* OUT: New value (or NULL pointer) */ |
| 9211 ); |
| 9212 |
| 9213 /* |
| 9214 ** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator |
| 9215 ** |
| 9216 ** This function should only be used with iterator objects passed to a |
| 9217 ** conflict-handler callback by [sqlite3changeset_apply()] with either |
| 9218 ** [SQLITE_CHANGESET_DATA] or [SQLITE_CHANGESET_CONFLICT]. If this function |
| 9219 ** is called on any other iterator, [SQLITE_MISUSE] is returned and *ppValue |
| 9220 ** is set to NULL. |
| 9221 ** |
| 9222 ** Argument iVal must be greater than or equal to 0, and less than the number |
| 9223 ** of columns in the table affected by the current change. Otherwise, |
| 9224 ** [SQLITE_RANGE] is returned and *ppValue is set to NULL. |
| 9225 ** |
| 9226 ** If successful, this function sets *ppValue to point to a protected |
| 9227 ** sqlite3_value object containing the iVal'th value from the |
| 9228 ** "conflicting row" associated with the current conflict-handler callback |
| 9229 ** and returns SQLITE_OK. |
| 9230 ** |
| 9231 ** If some other error occurs (e.g. an OOM condition), an SQLite error code |
| 9232 ** is returned and *ppValue is set to NULL. |
| 9233 */ |
| 9234 SQLITE_API int sqlite3changeset_conflict( |
| 9235 sqlite3_changeset_iter *pIter, /* Changeset iterator */ |
| 9236 int iVal, /* Column number */ |
| 9237 sqlite3_value **ppValue /* OUT: Value from conflicting row */ |
| 9238 ); |
| 9239 |
| 9240 /* |
| 9241 ** CAPI3REF: Determine The Number Of Foreign Key Constraint Violations |
| 9242 ** |
| 9243 ** This function may only be called with an iterator passed to an |
| 9244 ** SQLITE_CHANGESET_FOREIGN_KEY conflict handler callback. In this case |
| 9245 ** it sets the output variable to the total number of known foreign key |
| 9246 ** violations in the destination database and returns SQLITE_OK. |
| 9247 ** |
| 9248 ** In all other cases this function returns SQLITE_MISUSE. |
| 9249 */ |
| 9250 SQLITE_API int sqlite3changeset_fk_conflicts( |
| 9251 sqlite3_changeset_iter *pIter, /* Changeset iterator */ |
| 9252 int *pnOut /* OUT: Number of FK violations */ |
| 9253 ); |
| 9254 |
| 9255 |
| 9256 /* |
| 9257 ** CAPI3REF: Finalize A Changeset Iterator |
| 9258 ** |
| 9259 ** This function is used to finalize an iterator allocated with |
| 9260 ** [sqlite3changeset_start()]. |
| 9261 ** |
| 9262 ** This function should only be called on iterators created using the |
| 9263 ** [sqlite3changeset_start()] function. If an application calls this |
| 9264 ** function with an iterator passed to a conflict-handler by |
| 9265 ** [sqlite3changeset_apply()], [SQLITE_MISUSE] is immediately returned and the |
| 9266 ** call has no effect. |
| 9267 ** |
| 9268 ** If an error was encountered within a call to an sqlite3changeset_xxx() |
| 9269 ** function (for example an [SQLITE_CORRUPT] in [sqlite3changeset_next()] or an |
| 9270 ** [SQLITE_NOMEM] in [sqlite3changeset_new()]) then an error code corresponding |
| 9271 ** to that error is returned by this function. Otherwise, SQLITE_OK is |
| 9272 ** returned. This is to allow the following pattern (pseudo-code): |
| 9273 ** |
| 9274 ** sqlite3changeset_start(); |
| 9275 ** while( SQLITE_ROW==sqlite3changeset_next() ){ |
| 9276 ** // Do something with change. |
| 9277 ** } |
| 9278 ** rc = sqlite3changeset_finalize(); |
| 9279 ** if( rc!=SQLITE_OK ){ |
| 9280 ** // An error has occurred |
| 9281 ** } |
| 9282 */ |
| 9283 SQLITE_API int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter); |
| 9284 |
| 9285 /* |
| 9286 ** CAPI3REF: Invert A Changeset |
| 9287 ** |
| 9288 ** This function is used to "invert" a changeset object. Applying an inverted |
| 9289 ** changeset to a database reverses the effects of applying the uninverted |
| 9290 ** changeset. Specifically: |
| 9291 ** |
| 9292 ** <ul> |
| 9293 ** <li> Each DELETE change is changed to an INSERT, and |
| 9294 ** <li> Each INSERT change is changed to a DELETE, and |
| 9295 ** <li> For each UPDATE change, the old.* and new.* values are exchanged. |
| 9296 ** </ul> |
| 9297 ** |
| 9298 ** This function does not change the order in which changes appear within |
| 9299 ** the changeset. It merely reverses the sense of each individual change. |
| 9300 ** |
| 9301 ** If successful, a pointer to a buffer containing the inverted changeset |
| 9302 ** is stored in *ppOut, the size of the same buffer is stored in *pnOut, and |
| 9303 ** SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are |
| 9304 ** zeroed and an SQLite error code returned. |
| 9305 ** |
| 9306 ** It is the responsibility of the caller to eventually call sqlite3_free() |
| 9307 ** on the *ppOut pointer to free the buffer allocation following a successful |
| 9308 ** call to this function. |
| 9309 ** |
| 9310 ** WARNING/TODO: This function currently assumes that the input is a valid |
| 9311 ** changeset. If it is not, the results are undefined. |
| 9312 */ |
| 9313 SQLITE_API int sqlite3changeset_invert( |
| 9314 int nIn, const void *pIn, /* Input changeset */ |
| 9315 int *pnOut, void **ppOut /* OUT: Inverse of input */ |
| 9316 ); |
| 9317 |
| 9318 /* |
| 9319 ** CAPI3REF: Concatenate Two Changeset Objects |
| 9320 ** |
| 9321 ** This function is used to concatenate two changesets, A and B, into a |
| 9322 ** single changeset. The result is a changeset equivalent to applying |
| 9323 ** changeset A followed by changeset B. |
| 9324 ** |
| 9325 ** This function combines the two input changesets using an |
| 9326 ** sqlite3_changegroup object. Calling it produces similar results as the |
| 9327 ** following code fragment: |
| 9328 ** |
| 9329 ** sqlite3_changegroup *pGrp; |
| 9330 ** rc = sqlite3_changegroup_new(&pGrp); |
| 9331 ** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nA, pA); |
| 9332 ** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nB, pB); |
| 9333 ** if( rc==SQLITE_OK ){ |
| 9334 ** rc = sqlite3changegroup_output(pGrp, pnOut, ppOut); |
| 9335 ** }else{ |
| 9336 ** *ppOut = 0; |
| 9337 ** *pnOut = 0; |
| 9338 ** } |
| 9339 ** |
| 9340 ** Refer to the sqlite3_changegroup documentation below for details. |
| 9341 */ |
| 9342 SQLITE_API int sqlite3changeset_concat( |
| 9343 int nA, /* Number of bytes in buffer pA */ |
| 9344 void *pA, /* Pointer to buffer containing changeset A */ |
| 9345 int nB, /* Number of bytes in buffer pB */ |
| 9346 void *pB, /* Pointer to buffer containing changeset B */ |
| 9347 int *pnOut, /* OUT: Number of bytes in output changeset */ |
| 9348 void **ppOut /* OUT: Buffer containing output changeset */ |
| 9349 ); |
| 9350 |
| 9351 |
| 9352 /* |
| 9353 ** CAPI3REF: Changegroup Handle |
| 9354 */ |
| 9355 typedef struct sqlite3_changegroup sqlite3_changegroup; |
| 9356 |
| 9357 /* |
| 9358 ** CAPI3REF: Create A New Changegroup Object |
| 9359 ** |
| 9360 ** An sqlite3_changegroup object is used to combine two or more changesets |
| 9361 ** (or patchsets) into a single changeset (or patchset). A single changegroup |
| 9362 ** object may combine changesets or patchsets, but not both. The output is |
| 9363 ** always in the same format as the input. |
| 9364 ** |
| 9365 ** If successful, this function returns SQLITE_OK and populates (*pp) with |
| 9366 ** a pointer to a new sqlite3_changegroup object before returning. The caller |
| 9367 ** should eventually free the returned object using a call to |
| 9368 ** sqlite3changegroup_delete(). If an error occurs, an SQLite error code |
| 9369 ** (i.e. SQLITE_NOMEM) is returned and *pp is set to NULL. |
| 9370 ** |
| 9371 ** The usual usage pattern for an sqlite3_changegroup object is as follows: |
| 9372 ** |
| 9373 ** <ul> |
| 9374 ** <li> It is created using a call to sqlite3changegroup_new(). |
| 9375 ** |
| 9376 ** <li> Zero or more changesets (or patchsets) are added to the object |
| 9377 ** by calling sqlite3changegroup_add(). |
| 9378 ** |
| 9379 ** <li> The result of combining all input changesets together is obtained |
| 9380 ** by the application via a call to sqlite3changegroup_output(). |
| 9381 ** |
| 9382 ** <li> The object is deleted using a call to sqlite3changegroup_delete(). |
| 9383 ** </ul> |
| 9384 ** |
| 9385 ** Any number of calls to add() and output() may be made between the calls to |
| 9386 ** new() and delete(), and in any order. |
| 9387 ** |
| 9388 ** As well as the regular sqlite3changegroup_add() and |
| 9389 ** sqlite3changegroup_output() functions, also available are the streaming |
| 9390 ** versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm(). |
| 9391 */ |
| 9392 int sqlite3changegroup_new(sqlite3_changegroup **pp); |
| 9393 |
| 9394 /* |
| 9395 ** CAPI3REF: Add A Changeset To A Changegroup |
| 9396 ** |
| 9397 ** Add all changes within the changeset (or patchset) in buffer pData (size |
| 9398 ** nData bytes) to the changegroup. |
| 9399 ** |
| 9400 ** If the buffer contains a patchset, then all prior calls to this function |
| 9401 ** on the same changegroup object must also have specified patchsets. Or, if |
| 9402 ** the buffer contains a changeset, so must have the earlier calls to this |
| 9403 ** function. Otherwise, SQLITE_ERROR is returned and no changes are added |
| 9404 ** to the changegroup. |
| 9405 ** |
| 9406 ** Rows within the changeset and changegroup are identified by the values in |
| 9407 ** their PRIMARY KEY columns. A change in the changeset is considered to |
| 9408 ** apply to the same row as a change already present in the changegroup if |
| 9409 ** the two rows have the same primary key. |
| 9410 ** |
| 9411 ** Changes to rows that do not already appear in the changegroup are |
| 9412 ** simply copied into it. Or, if both the new changeset and the changegroup |
| 9413 ** contain changes that apply to a single row, the final contents of the |
| 9414 ** changegroup depends on the type of each change, as follows: |
| 9415 ** |
| 9416 ** <table border=1 style="margin-left:8ex;margin-right:8ex"> |
| 9417 ** <tr><th style="white-space:pre">Existing Change </th> |
| 9418 ** <th style="white-space:pre">New Change </th> |
| 9419 ** <th>Output Change |
| 9420 ** <tr><td>INSERT <td>INSERT <td> |
| 9421 ** The new change is ignored. This case does not occur if the new |
| 9422 ** changeset was recorded immediately after the changesets already |
| 9423 ** added to the changegroup. |
| 9424 ** <tr><td>INSERT <td>UPDATE <td> |
| 9425 ** The INSERT change remains in the changegroup. The values in the |
| 9426 ** INSERT change are modified as if the row was inserted by the |
| 9427 ** existing change and then updated according to the new change. |
| 9428 ** <tr><td>INSERT <td>DELETE <td> |
| 9429 ** The existing INSERT is removed from the changegroup. The DELETE is |
| 9430 ** not added. |
| 9431 ** <tr><td>UPDATE <td>INSERT <td> |
| 9432 ** The new change is ignored. This case does not occur if the new |
| 9433 ** changeset was recorded immediately after the changesets already |
| 9434 ** added to the changegroup. |
| 9435 ** <tr><td>UPDATE <td>UPDATE <td> |
| 9436 ** The existing UPDATE remains within the changegroup. It is amended |
| 9437 ** so that the accompanying values are as if the row was updated once |
| 9438 ** by the existing change and then again by the new change. |
| 9439 ** <tr><td>UPDATE <td>DELETE <td> |
| 9440 ** The existing UPDATE is replaced by the new DELETE within the |
| 9441 ** changegroup. |
| 9442 ** <tr><td>DELETE <td>INSERT <td> |
| 9443 ** If one or more of the column values in the row inserted by the |
| 9444 ** new change differ from those in the row deleted by the existing |
| 9445 ** change, the existing DELETE is replaced by an UPDATE within the |
| 9446 ** changegroup. Otherwise, if the inserted row is exactly the same |
| 9447 ** as the deleted row, the existing DELETE is simply discarded. |
| 9448 ** <tr><td>DELETE <td>UPDATE <td> |
| 9449 ** The new change is ignored. This case does not occur if the new |
| 9450 ** changeset was recorded immediately after the changesets already |
| 9451 ** added to the changegroup. |
| 9452 ** <tr><td>DELETE <td>DELETE <td> |
| 9453 ** The new change is ignored. This case does not occur if the new |
| 9454 ** changeset was recorded immediately after the changesets already |
| 9455 ** added to the changegroup. |
| 9456 ** </table> |
| 9457 ** |
| 9458 ** If the new changeset contains changes to a table that is already present |
| 9459 ** in the changegroup, then the number of columns and the position of the |
| 9460 ** primary key columns for the table must be consistent. If this is not the |
| 9461 ** case, this function fails with SQLITE_SCHEMA. If the input changeset |
| 9462 ** appears to be corrupt and the corruption is detected, SQLITE_CORRUPT is |
| 9463 ** returned. Or, if an out-of-memory condition occurs during processing, this |
| 9464 ** function returns SQLITE_NOMEM. In all cases, if an error occurs the |
| 9465 ** final contents of the changegroup is undefined. |
| 9466 ** |
| 9467 ** If no error occurs, SQLITE_OK is returned. |
| 9468 */ |
| 9469 int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pData); |
| 9470 |
| 9471 /* |
| 9472 ** CAPI3REF: Obtain A Composite Changeset From A Changegroup |
| 9473 ** |
| 9474 ** Obtain a buffer containing a changeset (or patchset) representing the |
| 9475 ** current contents of the changegroup. If the inputs to the changegroup |
| 9476 ** were themselves changesets, the output is a changeset. Or, if the |
| 9477 ** inputs were patchsets, the output is also a patchset. |
| 9478 ** |
| 9479 ** As with the output of the sqlite3session_changeset() and |
| 9480 ** sqlite3session_patchset() functions, all changes related to a single |
| 9481 ** table are grouped together in the output of this function. Tables appear |
| 9482 ** in the same order as for the very first changeset added to the changegroup. |
| 9483 ** If the second or subsequent changesets added to the changegroup contain |
| 9484 ** changes for tables that do not appear in the first changeset, they are |
| 9485 ** appended onto the end of the output changeset, again in the order in |
| 9486 ** which they are first encountered. |
| 9487 ** |
| 9488 ** If an error occurs, an SQLite error code is returned and the output |
| 9489 ** variables (*pnData) and (*ppData) are set to 0. Otherwise, SQLITE_OK |
| 9490 ** is returned and the output variables are set to the size of and a |
| 9491 ** pointer to the output buffer, respectively. In this case it is the |
| 9492 ** responsibility of the caller to eventually free the buffer using a |
| 9493 ** call to sqlite3_free(). |
| 9494 */ |
| 9495 int sqlite3changegroup_output( |
| 9496 sqlite3_changegroup*, |
| 9497 int *pnData, /* OUT: Size of output buffer in bytes */ |
| 9498 void **ppData /* OUT: Pointer to output buffer */ |
| 9499 ); |
| 9500 |
| 9501 /* |
| 9502 ** CAPI3REF: Delete A Changegroup Object |
| 9503 */ |
| 9504 void sqlite3changegroup_delete(sqlite3_changegroup*); |
| 9505 |
| 9506 /* |
| 9507 ** CAPI3REF: Apply A Changeset To A Database |
| 9508 ** |
| 9509 ** Apply a changeset to a database. This function attempts to update the |
| 9510 ** "main" database attached to handle db with the changes found in the |
| 9511 ** changeset passed via the second and third arguments. |
| 9512 ** |
| 9513 ** The fourth argument (xFilter) passed to this function is the "filter |
| 9514 ** callback". If it is not NULL, then for each table affected by at least one |
| 9515 ** change in the changeset, the filter callback is invoked with |
| 9516 ** the table name as the second argument, and a copy of the context pointer |
| 9517 ** passed as the sixth argument to this function as the first. If the "filter |
| 9518 ** callback" returns zero, then no attempt is made to apply any changes to |
| 9519 ** the table. Otherwise, if the return value is non-zero or the xFilter |
| 9520 ** argument to this function is NULL, all changes related to the table are |
| 9521 ** attempted. |
| 9522 ** |
| 9523 ** For each table that is not excluded by the filter callback, this function |
| 9524 ** tests that the target database contains a compatible table. A table is |
| 9525 ** considered compatible if all of the following are true: |
| 9526 ** |
| 9527 ** <ul> |
| 9528 ** <li> The table has the same name as the name recorded in the |
| 9529 ** changeset, and |
| 9530 ** <li> The table has at least as many columns as recorded in the |
| 9531 ** changeset, and |
| 9532 ** <li> The table has primary key columns in the same position as |
| 9533 ** recorded in the changeset. |
| 9534 ** </ul> |
| 9535 ** |
| 9536 ** If there is no compatible table, it is not an error, but none of the |
| 9537 ** changes associated with the table are applied. A warning message is issued |
| 9538 ** via the sqlite3_log() mechanism with the error code SQLITE_SCHEMA. At most |
| 9539 ** one such warning is issued for each table in the changeset. |
| 9540 ** |
| 9541 ** For each change for which there is a compatible table, an attempt is made |
| 9542 ** to modify the table contents according to the UPDATE, INSERT or DELETE |
| 9543 ** change. If a change cannot be applied cleanly, the conflict handler |
| 9544 ** function passed as the fifth argument to sqlite3changeset_apply() may be |
| 9545 ** invoked. A description of exactly when the conflict handler is invoked for |
| 9546 ** each type of change is below. |
| 9547 ** |
| 9548 ** Unlike the xFilter argument, xConflict may not be passed NULL. The results |
| 9549 ** of passing anything other than a valid function pointer as the xConflict |
| 9550 ** argument are undefined. |
| 9551 ** |
| 9552 ** Each time the conflict handler function is invoked, it must return one |
| 9553 ** of [SQLITE_CHANGESET_OMIT], [SQLITE_CHANGESET_ABORT] or |
| 9554 ** [SQLITE_CHANGESET_REPLACE]. SQLITE_CHANGESET_REPLACE may only be returned |
| 9555 ** if the second argument passed to the conflict handler is either |
| 9556 ** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler |
| 9557 ** returns an illegal value, any changes already made are rolled back and |
| 9558 ** the call to sqlite3changeset_apply() returns SQLITE_MISUSE. Different |
| 9559 ** actions are taken by sqlite3changeset_apply() depending on the value |
| 9560 ** returned by each invocation of the conflict-handler function. Refer to |
| 9561 ** the documentation for the three |
| 9562 ** [SQLITE_CHANGESET_OMIT|available return values] for details. |
| 9563 ** |
| 9564 ** <dl> |
| 9565 ** <dt>DELETE Changes<dd> |
| 9566 ** For each DELETE change, this function checks if the target database |
| 9567 ** contains a row with the same primary key value (or values) as the |
| 9568 ** original row values stored in the changeset. If it does, and the values |
| 9569 ** stored in all non-primary key columns also match the values stored in |
| 9570 ** the changeset the row is deleted from the target database. |
| 9571 ** |
| 9572 ** If a row with matching primary key values is found, but one or more of |
| 9573 ** the non-primary key fields contains a value different from the original |
| 9574 ** row value stored in the changeset, the conflict-handler function is |
| 9575 ** invoked with [SQLITE_CHANGESET_DATA] as the second argument. If the |
| 9576 ** database table has more columns than are recorded in the changeset, |
| 9577 ** only the values of those non-primary key fields are compared against |
| 9578 ** the current database contents - any trailing database table columns |
| 9579 ** are ignored. |
| 9580 ** |
| 9581 ** If no row with matching primary key values is found in the database, |
| 9582 ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND] |
| 9583 ** passed as the second argument. |
| 9584 ** |
| 9585 ** If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT |
| 9586 ** (which can only happen if a foreign key constraint is violated), the |
| 9587 ** conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT] |
| 9588 ** passed as the second argument. This includes the case where the DELETE |
| 9589 ** operation is attempted because an earlier call to the conflict handler |
| 9590 ** function returned [SQLITE_CHANGESET_REPLACE]. |
| 9591 ** |
| 9592 ** <dt>INSERT Changes<dd> |
| 9593 ** For each INSERT change, an attempt is made to insert the new row into |
| 9594 ** the database. If the changeset row contains fewer fields than the |
| 9595 ** database table, the trailing fields are populated with their default |
| 9596 ** values. |
| 9597 ** |
| 9598 ** If the attempt to insert the row fails because the database already |
| 9599 ** contains a row with the same primary key values, the conflict handler |
| 9600 ** function is invoked with the second argument set to |
| 9601 ** [SQLITE_CHANGESET_CONFLICT]. |
| 9602 ** |
| 9603 ** If the attempt to insert the row fails because of some other constraint |
| 9604 ** violation (e.g. NOT NULL or UNIQUE), the conflict handler function is |
| 9605 ** invoked with the second argument set to [SQLITE_CHANGESET_CONSTRAINT]. |
| 9606 ** This includes the case where the INSERT operation is re-attempted because |
| 9607 ** an earlier call to the conflict handler function returned |
| 9608 ** [SQLITE_CHANGESET_REPLACE]. |
| 9609 ** |
| 9610 ** <dt>UPDATE Changes<dd> |
| 9611 ** For each UPDATE change, this function checks if the target database |
| 9612 ** contains a row with the same primary key value (or values) as the |
| 9613 ** original row values stored in the changeset. If it does, and the values |
| 9614 ** stored in all modified non-primary key columns also match the values |
| 9615 ** stored in the changeset the row is updated within the target database. |
| 9616 ** |
| 9617 ** If a row with matching primary key values is found, but one or more of |
| 9618 ** the modified non-primary key fields contains a value different from an |
| 9619 ** original row value stored in the changeset, the conflict-handler function |
| 9620 ** is invoked with [SQLITE_CHANGESET_DATA] as the second argument. Since |
| 9621 ** UPDATE changes only contain values for non-primary key fields that are |
| 9622 ** to be modified, only those fields need to match the original values to |
| 9623 ** avoid the SQLITE_CHANGESET_DATA conflict-handler callback. |
| 9624 ** |
| 9625 ** If no row with matching primary key values is found in the database, |
| 9626 ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND] |
| 9627 ** passed as the second argument. |
| 9628 ** |
| 9629 ** If the UPDATE operation is attempted, but SQLite returns |
| 9630 ** SQLITE_CONSTRAINT, the conflict-handler function is invoked with |
| 9631 ** [SQLITE_CHANGESET_CONSTRAINT] passed as the second argument. |
| 9632 ** This includes the case where the UPDATE operation is attempted after |
| 9633 ** an earlier call to the conflict handler function returned |
| 9634 ** [SQLITE_CHANGESET_REPLACE]. |
| 9635 ** </dl> |
| 9636 ** |
| 9637 ** It is safe to execute SQL statements, including those that write to the |
| 9638 ** table that the callback related to, from within the xConflict callback. |
| 9639 ** This can be used to further customize the applications conflict |
| 9640 ** resolution strategy. |
| 9641 ** |
| 9642 ** All changes made by this function are enclosed in a savepoint transaction. |
| 9643 ** If any other error (aside from a constraint failure when attempting to |
| 9644 ** write to the target database) occurs, then the savepoint transaction is |
| 9645 ** rolled back, restoring the target database to its original state, and an |
| 9646 ** SQLite error code returned. |
| 9647 */ |
| 9648 SQLITE_API int sqlite3changeset_apply( |
| 9649 sqlite3 *db, /* Apply change to "main" db of this handle */ |
| 9650 int nChangeset, /* Size of changeset in bytes */ |
| 9651 void *pChangeset, /* Changeset blob */ |
| 9652 int(*xFilter)( |
| 9653 void *pCtx, /* Copy of sixth arg to _apply() */ |
| 9654 const char *zTab /* Table name */ |
| 9655 ), |
| 9656 int(*xConflict)( |
| 9657 void *pCtx, /* Copy of sixth arg to _apply() */ |
| 9658 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */ |
| 9659 sqlite3_changeset_iter *p /* Handle describing change and conflict */ |
| 9660 ), |
| 9661 void *pCtx /* First argument passed to xConflict */ |
| 9662 ); |
| 9663 |
| 9664 /* |
| 9665 ** CAPI3REF: Constants Passed To The Conflict Handler |
| 9666 ** |
| 9667 ** Values that may be passed as the second argument to a conflict-handler. |
| 9668 ** |
| 9669 ** <dl> |
| 9670 ** <dt>SQLITE_CHANGESET_DATA<dd> |
| 9671 ** The conflict handler is invoked with CHANGESET_DATA as the second argument |
| 9672 ** when processing a DELETE or UPDATE change if a row with the required |
| 9673 ** PRIMARY KEY fields is present in the database, but one or more other |
| 9674 ** (non primary-key) fields modified by the update do not contain the |
| 9675 ** expected "before" values. |
| 9676 ** |
| 9677 ** The conflicting row, in this case, is the database row with the matching |
| 9678 ** primary key. |
| 9679 ** |
| 9680 ** <dt>SQLITE_CHANGESET_NOTFOUND<dd> |
| 9681 ** The conflict handler is invoked with CHANGESET_NOTFOUND as the second |
| 9682 ** argument when processing a DELETE or UPDATE change if a row with the |
| 9683 ** required PRIMARY KEY fields is not present in the database. |
| 9684 ** |
| 9685 ** There is no conflicting row in this case. The results of invoking the |
| 9686 ** sqlite3changeset_conflict() API are undefined. |
| 9687 ** |
| 9688 ** <dt>SQLITE_CHANGESET_CONFLICT<dd> |
| 9689 ** CHANGESET_CONFLICT is passed as the second argument to the conflict |
| 9690 ** handler while processing an INSERT change if the operation would result |
| 9691 ** in duplicate primary key values. |
| 9692 ** |
| 9693 ** The conflicting row in this case is the database row with the matching |
| 9694 ** primary key. |
| 9695 ** |
| 9696 ** <dt>SQLITE_CHANGESET_FOREIGN_KEY<dd> |
| 9697 ** If foreign key handling is enabled, and applying a changeset leaves the |
| 9698 ** database in a state containing foreign key violations, the conflict |
| 9699 ** handler is invoked with CHANGESET_FOREIGN_KEY as the second argument |
| 9700 ** exactly once before the changeset is committed. If the conflict handler |
| 9701 ** returns CHANGESET_OMIT, the changes, including those that caused the |
| 9702 ** foreign key constraint violation, are committed. Or, if it returns |
| 9703 ** CHANGESET_ABORT, the changeset is rolled back. |
| 9704 ** |
| 9705 ** No current or conflicting row information is provided. The only function |
| 9706 ** it is possible to call on the supplied sqlite3_changeset_iter handle |
| 9707 ** is sqlite3changeset_fk_conflicts(). |
| 9708 ** |
| 9709 ** <dt>SQLITE_CHANGESET_CONSTRAINT<dd> |
| 9710 ** If any other constraint violation occurs while applying a change (i.e. |
| 9711 ** a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is |
| 9712 ** invoked with CHANGESET_CONSTRAINT as the second argument. |
| 9713 ** |
| 9714 ** There is no conflicting row in this case. The results of invoking the |
| 9715 ** sqlite3changeset_conflict() API are undefined. |
| 9716 ** |
| 9717 ** </dl> |
| 9718 */ |
| 9719 #define SQLITE_CHANGESET_DATA 1 |
| 9720 #define SQLITE_CHANGESET_NOTFOUND 2 |
| 9721 #define SQLITE_CHANGESET_CONFLICT 3 |
| 9722 #define SQLITE_CHANGESET_CONSTRAINT 4 |
| 9723 #define SQLITE_CHANGESET_FOREIGN_KEY 5 |
| 9724 |
| 9725 /* |
| 9726 ** CAPI3REF: Constants Returned By The Conflict Handler |
| 9727 ** |
| 9728 ** A conflict handler callback must return one of the following three values. |
| 9729 ** |
| 9730 ** <dl> |
| 9731 ** <dt>SQLITE_CHANGESET_OMIT<dd> |
| 9732 ** If a conflict handler returns this value no special action is taken. The |
| 9733 ** change that caused the conflict is not applied. The session module |
| 9734 ** continues to the next change in the changeset. |
| 9735 ** |
| 9736 ** <dt>SQLITE_CHANGESET_REPLACE<dd> |
| 9737 ** This value may only be returned if the second argument to the conflict |
| 9738 ** handler was SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this |
| 9739 ** is not the case, any changes applied so far are rolled back and the |
| 9740 ** call to sqlite3changeset_apply() returns SQLITE_MISUSE. |
| 9741 ** |
| 9742 ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_DATA conflict |
| 9743 ** handler, then the conflicting row is either updated or deleted, depending |
| 9744 ** on the type of change. |
| 9745 ** |
| 9746 ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_CONFLICT conflict |
| 9747 ** handler, then the conflicting row is removed from the database and a |
| 9748 ** second attempt to apply the change is made. If this second attempt fails, |
| 9749 ** the original row is restored to the database before continuing. |
| 9750 ** |
| 9751 ** <dt>SQLITE_CHANGESET_ABORT<dd> |
| 9752 ** If this value is returned, any changes applied so far are rolled back |
| 9753 ** and the call to sqlite3changeset_apply() returns SQLITE_ABORT. |
| 9754 ** </dl> |
| 9755 */ |
| 9756 #define SQLITE_CHANGESET_OMIT 0 |
| 9757 #define SQLITE_CHANGESET_REPLACE 1 |
| 9758 #define SQLITE_CHANGESET_ABORT 2 |
| 9759 |
| 9760 /* |
| 9761 ** CAPI3REF: Streaming Versions of API functions. |
| 9762 ** |
| 9763 ** The six streaming API xxx_strm() functions serve similar purposes to the |
| 9764 ** corresponding non-streaming API functions: |
| 9765 ** |
| 9766 ** <table border=1 style="margin-left:8ex;margin-right:8ex"> |
| 9767 ** <tr><th>Streaming function<th>Non-streaming equivalent</th> |
| 9768 ** <tr><td>sqlite3changeset_apply_str<td>[sqlite3changeset_apply] |
| 9769 ** <tr><td>sqlite3changeset_concat_str<td>[sqlite3changeset_concat] |
| 9770 ** <tr><td>sqlite3changeset_invert_str<td>[sqlite3changeset_invert] |
| 9771 ** <tr><td>sqlite3changeset_start_str<td>[sqlite3changeset_start] |
| 9772 ** <tr><td>sqlite3session_changeset_str<td>[sqlite3session_changeset] |
| 9773 ** <tr><td>sqlite3session_patchset_str<td>[sqlite3session_patchset] |
| 9774 ** </table> |
| 9775 ** |
| 9776 ** Non-streaming functions that accept changesets (or patchsets) as input |
| 9777 ** require that the entire changeset be stored in a single buffer in memory. |
| 9778 ** Similarly, those that return a changeset or patchset do so by returning |
| 9779 ** a pointer to a single large buffer allocated using sqlite3_malloc(). |
| 9780 ** Normally this is convenient. However, if an application running in a |
| 9781 ** low-memory environment is required to handle very large changesets, the |
| 9782 ** large contiguous memory allocations required can become onerous. |
| 9783 ** |
| 9784 ** In order to avoid this problem, instead of a single large buffer, input |
| 9785 ** is passed to a streaming API functions by way of a callback function that |
| 9786 ** the sessions module invokes to incrementally request input data as it is |
| 9787 ** required. In all cases, a pair of API function parameters such as |
| 9788 ** |
| 9789 ** <pre> |
| 9790 ** int nChangeset, |
| 9791 ** void *pChangeset, |
| 9792 ** </pre> |
| 9793 ** |
| 9794 ** Is replaced by: |
| 9795 ** |
| 9796 ** <pre> |
| 9797 ** int (*xInput)(void *pIn, void *pData, int *pnData), |
| 9798 ** void *pIn, |
| 9799 ** </pre> |
| 9800 ** |
| 9801 ** Each time the xInput callback is invoked by the sessions module, the first |
| 9802 ** argument passed is a copy of the supplied pIn context pointer. The second |
| 9803 ** argument, pData, points to a buffer (*pnData) bytes in size. Assuming no |
| 9804 ** error occurs the xInput method should copy up to (*pnData) bytes of data |
| 9805 ** into the buffer and set (*pnData) to the actual number of bytes copied |
| 9806 ** before returning SQLITE_OK. If the input is completely exhausted, (*pnData) |
| 9807 ** should be set to zero to indicate this. Or, if an error occurs, an SQLite |
| 9808 ** error code should be returned. In all cases, if an xInput callback returns |
| 9809 ** an error, all processing is abandoned and the streaming API function |
| 9810 ** returns a copy of the error code to the caller. |
| 9811 ** |
| 9812 ** In the case of sqlite3changeset_start_strm(), the xInput callback may be |
| 9813 ** invoked by the sessions module at any point during the lifetime of the |
| 9814 ** iterator. If such an xInput callback returns an error, the iterator enters |
| 9815 ** an error state, whereby all subsequent calls to iterator functions |
| 9816 ** immediately fail with the same error code as returned by xInput. |
| 9817 ** |
| 9818 ** Similarly, streaming API functions that return changesets (or patchsets) |
| 9819 ** return them in chunks by way of a callback function instead of via a |
| 9820 ** pointer to a single large buffer. In this case, a pair of parameters such |
| 9821 ** as: |
| 9822 ** |
| 9823 ** <pre> |
| 9824 ** int *pnChangeset, |
| 9825 ** void **ppChangeset, |
| 9826 ** </pre> |
| 9827 ** |
| 9828 ** Is replaced by: |
| 9829 ** |
| 9830 ** <pre> |
| 9831 ** int (*xOutput)(void *pOut, const void *pData, int nData), |
| 9832 ** void *pOut |
| 9833 ** </pre> |
| 9834 ** |
| 9835 ** The xOutput callback is invoked zero or more times to return data to |
| 9836 ** the application. The first parameter passed to each call is a copy of the |
| 9837 ** pOut pointer supplied by the application. The second parameter, pData, |
| 9838 ** points to a buffer nData bytes in size containing the chunk of output |
| 9839 ** data being returned. If the xOutput callback successfully processes the |
| 9840 ** supplied data, it should return SQLITE_OK to indicate success. Otherwise, |
| 9841 ** it should return some other SQLite error code. In this case processing |
| 9842 ** is immediately abandoned and the streaming API function returns a copy |
| 9843 ** of the xOutput error code to the application. |
| 9844 ** |
| 9845 ** The sessions module never invokes an xOutput callback with the third |
| 9846 ** parameter set to a value less than or equal to zero. Other than this, |
| 9847 ** no guarantees are made as to the size of the chunks of data returned. |
| 9848 */ |
| 9849 SQLITE_API int sqlite3changeset_apply_strm( |
| 9850 sqlite3 *db, /* Apply change to "main" db of this handle */ |
| 9851 int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */ |
| 9852 void *pIn, /* First arg for xInput */ |
| 9853 int(*xFilter)( |
| 9854 void *pCtx, /* Copy of sixth arg to _apply() */ |
| 9855 const char *zTab /* Table name */ |
| 9856 ), |
| 9857 int(*xConflict)( |
| 9858 void *pCtx, /* Copy of sixth arg to _apply() */ |
| 9859 int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */ |
| 9860 sqlite3_changeset_iter *p /* Handle describing change and conflict */ |
| 9861 ), |
| 9862 void *pCtx /* First argument passed to xConflict */ |
| 9863 ); |
| 9864 SQLITE_API int sqlite3changeset_concat_strm( |
| 9865 int (*xInputA)(void *pIn, void *pData, int *pnData), |
| 9866 void *pInA, |
| 9867 int (*xInputB)(void *pIn, void *pData, int *pnData), |
| 9868 void *pInB, |
| 9869 int (*xOutput)(void *pOut, const void *pData, int nData), |
| 9870 void *pOut |
| 9871 ); |
| 9872 SQLITE_API int sqlite3changeset_invert_strm( |
| 9873 int (*xInput)(void *pIn, void *pData, int *pnData), |
| 9874 void *pIn, |
| 9875 int (*xOutput)(void *pOut, const void *pData, int nData), |
| 9876 void *pOut |
| 9877 ); |
| 9878 SQLITE_API int sqlite3changeset_start_strm( |
| 9879 sqlite3_changeset_iter **pp, |
| 9880 int (*xInput)(void *pIn, void *pData, int *pnData), |
| 9881 void *pIn |
| 9882 ); |
| 9883 SQLITE_API int sqlite3session_changeset_strm( |
| 9884 sqlite3_session *pSession, |
| 9885 int (*xOutput)(void *pOut, const void *pData, int nData), |
| 9886 void *pOut |
| 9887 ); |
| 9888 SQLITE_API int sqlite3session_patchset_strm( |
| 9889 sqlite3_session *pSession, |
| 9890 int (*xOutput)(void *pOut, const void *pData, int nData), |
| 9891 void *pOut |
| 9892 ); |
| 9893 int sqlite3changegroup_add_strm(sqlite3_changegroup*, |
| 9894 int (*xInput)(void *pIn, void *pData, int *pnData), |
| 9895 void *pIn |
| 9896 ); |
| 9897 int sqlite3changegroup_output_strm(sqlite3_changegroup*, |
| 9898 int (*xOutput)(void *pOut, const void *pData, int nData), |
| 9899 void *pOut |
| 9900 ); |
| 9901 |
| 9902 |
| 9903 /* |
| 9904 ** Make sure we can call this stuff from C++. |
| 9905 */ |
| 9906 #ifdef __cplusplus |
| 9907 } |
| 9908 #endif |
| 9909 |
| 9910 #endif /* !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION) */ |
| 9911 |
| 9912 /******** End of sqlite3session.h *********/ |
| 9913 /******** Begin file fts5.h *********/ |
| 8134 /* | 9914 /* |
| 8135 ** 2014 May 31 | 9915 ** 2014 May 31 |
| 8136 ** | 9916 ** |
| 8137 ** The author disclaims copyright to this source code. In place of | 9917 ** The author disclaims copyright to this source code. In place of |
| 8138 ** a legal notice, here is a blessing: | 9918 ** a legal notice, here is a blessing: |
| 8139 ** | 9919 ** |
| 8140 ** May you do good and not evil. | 9920 ** May you do good and not evil. |
| 8141 ** May you find forgiveness for yourself and forgive others. | 9921 ** May you find forgiveness for yourself and forgive others. |
| 8142 ** May you share freely, never taking more than you give. | 9922 ** May you share freely, never taking more than you give. |
| 8143 ** | 9923 ** |
| (...skipping 65 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 8209 ** If parameter iCol is less than zero, set output variable *pnToken | 9989 ** If parameter iCol is less than zero, set output variable *pnToken |
| 8210 ** to the total number of tokens in the current row. Or, if iCol is | 9990 ** to the total number of tokens in the current row. Or, if iCol is |
| 8211 ** non-negative but less than the number of columns in the table, set | 9991 ** non-negative but less than the number of columns in the table, set |
| 8212 ** *pnToken to the number of tokens in column iCol of the current row. | 9992 ** *pnToken to the number of tokens in column iCol of the current row. |
| 8213 ** | 9993 ** |
| 8214 ** If parameter iCol is greater than or equal to the number of columns | 9994 ** If parameter iCol is greater than or equal to the number of columns |
| 8215 ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g. | 9995 ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g. |
| 8216 ** an OOM condition or IO error), an appropriate SQLite error code is | 9996 ** an OOM condition or IO error), an appropriate SQLite error code is |
| 8217 ** returned. | 9997 ** returned. |
| 8218 ** | 9998 ** |
| 9999 ** This function may be quite inefficient if used with an FTS5 table |
| 10000 ** created with the "columnsize=0" option. |
| 10001 ** |
| 8219 ** xColumnText: | 10002 ** xColumnText: |
| 8220 ** This function attempts to retrieve the text of column iCol of the | 10003 ** This function attempts to retrieve the text of column iCol of the |
| 8221 ** current document. If successful, (*pz) is set to point to a buffer | 10004 ** current document. If successful, (*pz) is set to point to a buffer |
| 8222 ** containing the text in utf-8 encoding, (*pn) is set to the size in bytes | 10005 ** containing the text in utf-8 encoding, (*pn) is set to the size in bytes |
| 8223 ** (not characters) of the buffer and SQLITE_OK is returned. Otherwise, | 10006 ** (not characters) of the buffer and SQLITE_OK is returned. Otherwise, |
| 8224 ** if an error occurs, an SQLite error code is returned and the final values | 10007 ** if an error occurs, an SQLite error code is returned and the final values |
| 8225 ** of (*pz) and (*pn) are undefined. | 10008 ** of (*pz) and (*pn) are undefined. |
| 8226 ** | 10009 ** |
| 8227 ** xPhraseCount: | 10010 ** xPhraseCount: |
| 8228 ** Returns the number of phrases in the current query expression. | 10011 ** Returns the number of phrases in the current query expression. |
| 8229 ** | 10012 ** |
| 8230 ** xPhraseSize: | 10013 ** xPhraseSize: |
| 8231 ** Returns the number of tokens in phrase iPhrase of the query. Phrases | 10014 ** Returns the number of tokens in phrase iPhrase of the query. Phrases |
| 8232 ** are numbered starting from zero. | 10015 ** are numbered starting from zero. |
| 8233 ** | 10016 ** |
| 8234 ** xInstCount: | 10017 ** xInstCount: |
| 8235 ** Set *pnInst to the total number of occurrences of all phrases within | 10018 ** Set *pnInst to the total number of occurrences of all phrases within |
| 8236 ** the query within the current row. Return SQLITE_OK if successful, or | 10019 ** the query within the current row. Return SQLITE_OK if successful, or |
| 8237 ** an error code (i.e. SQLITE_NOMEM) if an error occurs. | 10020 ** an error code (i.e. SQLITE_NOMEM) if an error occurs. |
| 8238 ** | 10021 ** |
| 10022 ** This API can be quite slow if used with an FTS5 table created with the |
| 10023 ** "detail=none" or "detail=column" option. If the FTS5 table is created |
| 10024 ** with either "detail=none" or "detail=column" and "content=" option |
| 10025 ** (i.e. if it is a contentless table), then this API always returns 0. |
| 10026 ** |
| 8239 ** xInst: | 10027 ** xInst: |
| 8240 ** Query for the details of phrase match iIdx within the current row. | 10028 ** Query for the details of phrase match iIdx within the current row. |
| 8241 ** Phrase matches are numbered starting from zero, so the iIdx argument | 10029 ** Phrase matches are numbered starting from zero, so the iIdx argument |
| 8242 ** should be greater than or equal to zero and smaller than the value | 10030 ** should be greater than or equal to zero and smaller than the value |
| 8243 ** output by xInstCount(). | 10031 ** output by xInstCount(). |
| 8244 ** | 10032 ** |
| 10033 ** Usually, output parameter *piPhrase is set to the phrase number, *piCol |
| 10034 ** to the column in which it occurs and *piOff the token offset of the |
| 10035 ** first token of the phrase. The exception is if the table was created |
| 10036 ** with the offsets=0 option specified. In this case *piOff is always |
| 10037 ** set to -1. |
| 10038 ** |
| 8245 ** Returns SQLITE_OK if successful, or an error code (i.e. SQLITE_NOMEM) | 10039 ** Returns SQLITE_OK if successful, or an error code (i.e. SQLITE_NOMEM) |
| 8246 ** if an error occurs. | 10040 ** if an error occurs. |
| 8247 ** | 10041 ** |
| 10042 ** This API can be quite slow if used with an FTS5 table created with the |
| 10043 ** "detail=none" or "detail=column" option. |
| 10044 ** |
| 8248 ** xRowid: | 10045 ** xRowid: |
| 8249 ** Returns the rowid of the current row. | 10046 ** Returns the rowid of the current row. |
| 8250 ** | 10047 ** |
| 8251 ** xTokenize: | 10048 ** xTokenize: |
| 8252 ** Tokenize text using the tokenizer belonging to the FTS5 table. | 10049 ** Tokenize text using the tokenizer belonging to the FTS5 table. |
| 8253 ** | 10050 ** |
| 8254 ** xQueryPhrase(pFts5, iPhrase, pUserData, xCallback): | 10051 ** xQueryPhrase(pFts5, iPhrase, pUserData, xCallback): |
| 8255 ** This API function is used to query the FTS table for phrase iPhrase | 10052 ** This API function is used to query the FTS table for phrase iPhrase |
| 8256 ** of the current query. Specifically, a query equivalent to: | 10053 ** of the current query. Specifically, a query equivalent to: |
| 8257 ** | 10054 ** |
| 8258 ** ... FROM ftstable WHERE ftstable MATCH $p ORDER BY rowid | 10055 ** ... FROM ftstable WHERE ftstable MATCH $p ORDER BY rowid |
| 8259 ** | 10056 ** |
| 8260 ** with $p set to a phrase equivalent to the phrase iPhrase of the | 10057 ** with $p set to a phrase equivalent to the phrase iPhrase of the |
| 8261 ** current query is executed. For each row visited, the callback function | 10058 ** current query is executed. Any column filter that applies to |
| 8262 ** passed as the fourth argument is invoked. The context and API objects | 10059 ** phrase iPhrase of the current query is included in $p. For each |
| 8263 ** passed to the callback function may be used to access the properties of | 10060 ** row visited, the callback function passed as the fourth argument |
| 8264 ** each matched row. Invoking Api.xUserData() returns a copy of the pointer | 10061 ** is invoked. The context and API objects passed to the callback |
| 8265 ** passed as the third argument to pUserData. | 10062 ** function may be used to access the properties of each matched row. |
| 10063 ** Invoking Api.xUserData() returns a copy of the pointer passed as |
| 10064 ** the third argument to pUserData. |
| 8266 ** | 10065 ** |
| 8267 ** If the callback function returns any value other than SQLITE_OK, the | 10066 ** If the callback function returns any value other than SQLITE_OK, the |
| 8268 ** query is abandoned and the xQueryPhrase function returns immediately. | 10067 ** query is abandoned and the xQueryPhrase function returns immediately. |
| 8269 ** If the returned value is SQLITE_DONE, xQueryPhrase returns SQLITE_OK. | 10068 ** If the returned value is SQLITE_DONE, xQueryPhrase returns SQLITE_OK. |
| 8270 ** Otherwise, the error code is propagated upwards. | 10069 ** Otherwise, the error code is propagated upwards. |
| 8271 ** | 10070 ** |
| 8272 ** If the query runs to completion without incident, SQLITE_OK is returned. | 10071 ** If the query runs to completion without incident, SQLITE_OK is returned. |
| 8273 ** Or, if some error occurs before the query completes or is aborted by | 10072 ** Or, if some error occurs before the query completes or is aborted by |
| 8274 ** the callback, an SQLite error code is returned. | 10073 ** the callback, an SQLite error code is returned. |
| 8275 ** | 10074 ** |
| (...skipping 45 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 8321 ** This function is used, along with type Fts5PhraseIter and the xPhraseNext | 10120 ** This function is used, along with type Fts5PhraseIter and the xPhraseNext |
| 8322 ** method, to iterate through all instances of a single query phrase within | 10121 ** method, to iterate through all instances of a single query phrase within |
| 8323 ** the current row. This is the same information as is accessible via the | 10122 ** the current row. This is the same information as is accessible via the |
| 8324 ** xInstCount/xInst APIs. While the xInstCount/xInst APIs are more convenient | 10123 ** xInstCount/xInst APIs. While the xInstCount/xInst APIs are more convenient |
| 8325 ** to use, this API may be faster under some circumstances. To iterate | 10124 ** to use, this API may be faster under some circumstances. To iterate |
| 8326 ** through instances of phrase iPhrase, use the following code: | 10125 ** through instances of phrase iPhrase, use the following code: |
| 8327 ** | 10126 ** |
| 8328 ** Fts5PhraseIter iter; | 10127 ** Fts5PhraseIter iter; |
| 8329 ** int iCol, iOff; | 10128 ** int iCol, iOff; |
| 8330 ** for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff); | 10129 ** for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff); |
| 8331 ** iOff>=0; | 10130 ** iCol>=0; |
| 8332 ** pApi->xPhraseNext(pFts, &iter, &iCol, &iOff) | 10131 ** pApi->xPhraseNext(pFts, &iter, &iCol, &iOff) |
| 8333 ** ){ | 10132 ** ){ |
| 8334 ** // An instance of phrase iPhrase at offset iOff of column iCol | 10133 ** // An instance of phrase iPhrase at offset iOff of column iCol |
| 8335 ** } | 10134 ** } |
| 8336 ** | 10135 ** |
| 8337 ** The Fts5PhraseIter structure is defined above. Applications should not | 10136 ** The Fts5PhraseIter structure is defined above. Applications should not |
| 8338 ** modify this structure directly - it should only be used as shown above | 10137 ** modify this structure directly - it should only be used as shown above |
| 8339 ** with the xPhraseFirst() and xPhraseNext() API methods. | 10138 ** with the xPhraseFirst() and xPhraseNext() API methods (and by |
| 10139 ** xPhraseFirstColumn() and xPhraseNextColumn() as illustrated below). |
| 10140 ** |
| 10141 ** This API can be quite slow if used with an FTS5 table created with the |
| 10142 ** "detail=none" or "detail=column" option. If the FTS5 table is created |
| 10143 ** with either "detail=none" or "detail=column" and "content=" option |
| 10144 ** (i.e. if it is a contentless table), then this API always iterates |
| 10145 ** through an empty set (all calls to xPhraseFirst() set iCol to -1). |
| 8340 ** | 10146 ** |
| 8341 ** xPhraseNext() | 10147 ** xPhraseNext() |
| 8342 ** See xPhraseFirst above. | 10148 ** See xPhraseFirst above. |
| 10149 ** |
| 10150 ** xPhraseFirstColumn() |
| 10151 ** This function and xPhraseNextColumn() are similar to the xPhraseFirst() |
| 10152 ** and xPhraseNext() APIs described above. The difference is that instead |
| 10153 ** of iterating through all instances of a phrase in the current row, these |
| 10154 ** APIs are used to iterate through the set of columns in the current row |
| 10155 ** that contain one or more instances of a specified phrase. For example: |
| 10156 ** |
| 10157 ** Fts5PhraseIter iter; |
| 10158 ** int iCol; |
| 10159 ** for(pApi->xPhraseFirstColumn(pFts, iPhrase, &iter, &iCol); |
| 10160 ** iCol>=0; |
| 10161 ** pApi->xPhraseNextColumn(pFts, &iter, &iCol) |
| 10162 ** ){ |
| 10163 ** // Column iCol contains at least one instance of phrase iPhrase |
| 10164 ** } |
| 10165 ** |
| 10166 ** This API can be quite slow if used with an FTS5 table created with the |
| 10167 ** "detail=none" option. If the FTS5 table is created with either |
| 10168 ** "detail=none" "content=" option (i.e. if it is a contentless table), |
| 10169 ** then this API always iterates through an empty set (all calls to |
| 10170 ** xPhraseFirstColumn() set iCol to -1). |
| 10171 ** |
| 10172 ** The information accessed using this API and its companion |
| 10173 ** xPhraseFirstColumn() may also be obtained using xPhraseFirst/xPhraseNext |
| 10174 ** (or xInst/xInstCount). The chief advantage of this API is that it is |
| 10175 ** significantly more efficient than those alternatives when used with |
| 10176 ** "detail=column" tables. |
| 10177 ** |
| 10178 ** xPhraseNextColumn() |
| 10179 ** See xPhraseFirstColumn above. |
| 8343 */ | 10180 */ |
| 8344 struct Fts5ExtensionApi { | 10181 struct Fts5ExtensionApi { |
| 8345 int iVersion; /* Currently always set to 1 */ | 10182 int iVersion; /* Currently always set to 3 */ |
| 8346 | 10183 |
| 8347 void *(*xUserData)(Fts5Context*); | 10184 void *(*xUserData)(Fts5Context*); |
| 8348 | 10185 |
| 8349 int (*xColumnCount)(Fts5Context*); | 10186 int (*xColumnCount)(Fts5Context*); |
| 8350 int (*xRowCount)(Fts5Context*, sqlite3_int64 *pnRow); | 10187 int (*xRowCount)(Fts5Context*, sqlite3_int64 *pnRow); |
| 8351 int (*xColumnTotalSize)(Fts5Context*, int iCol, sqlite3_int64 *pnToken); | 10188 int (*xColumnTotalSize)(Fts5Context*, int iCol, sqlite3_int64 *pnToken); |
| 8352 | 10189 |
| 8353 int (*xTokenize)(Fts5Context*, | 10190 int (*xTokenize)(Fts5Context*, |
| 8354 const char *pText, int nText, /* Text to tokenize */ | 10191 const char *pText, int nText, /* Text to tokenize */ |
| 8355 void *pCtx, /* Context passed to xToken() */ | 10192 void *pCtx, /* Context passed to xToken() */ |
| 8356 int (*xToken)(void*, int, const char*, int, int, int) /* Callback */ | 10193 int (*xToken)(void*, int, const char*, int, int, int) /* Callback */ |
| 8357 ); | 10194 ); |
| 8358 | 10195 |
| 8359 int (*xPhraseCount)(Fts5Context*); | 10196 int (*xPhraseCount)(Fts5Context*); |
| 8360 int (*xPhraseSize)(Fts5Context*, int iPhrase); | 10197 int (*xPhraseSize)(Fts5Context*, int iPhrase); |
| 8361 | 10198 |
| 8362 int (*xInstCount)(Fts5Context*, int *pnInst); | 10199 int (*xInstCount)(Fts5Context*, int *pnInst); |
| 8363 int (*xInst)(Fts5Context*, int iIdx, int *piPhrase, int *piCol, int *piOff); | 10200 int (*xInst)(Fts5Context*, int iIdx, int *piPhrase, int *piCol, int *piOff); |
| 8364 | 10201 |
| 8365 sqlite3_int64 (*xRowid)(Fts5Context*); | 10202 sqlite3_int64 (*xRowid)(Fts5Context*); |
| 8366 int (*xColumnText)(Fts5Context*, int iCol, const char **pz, int *pn); | 10203 int (*xColumnText)(Fts5Context*, int iCol, const char **pz, int *pn); |
| 8367 int (*xColumnSize)(Fts5Context*, int iCol, int *pnToken); | 10204 int (*xColumnSize)(Fts5Context*, int iCol, int *pnToken); |
| 8368 | 10205 |
| 8369 int (*xQueryPhrase)(Fts5Context*, int iPhrase, void *pUserData, | 10206 int (*xQueryPhrase)(Fts5Context*, int iPhrase, void *pUserData, |
| 8370 int(*)(const Fts5ExtensionApi*,Fts5Context*,void*) | 10207 int(*)(const Fts5ExtensionApi*,Fts5Context*,void*) |
| 8371 ); | 10208 ); |
| 8372 int (*xSetAuxdata)(Fts5Context*, void *pAux, void(*xDelete)(void*)); | 10209 int (*xSetAuxdata)(Fts5Context*, void *pAux, void(*xDelete)(void*)); |
| 8373 void *(*xGetAuxdata)(Fts5Context*, int bClear); | 10210 void *(*xGetAuxdata)(Fts5Context*, int bClear); |
| 8374 | 10211 |
| 8375 void (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*); | 10212 int (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*); |
| 8376 void (*xPhraseNext)(Fts5Context*, Fts5PhraseIter*, int *piCol, int *piOff); | 10213 void (*xPhraseNext)(Fts5Context*, Fts5PhraseIter*, int *piCol, int *piOff); |
| 10214 |
| 10215 int (*xPhraseFirstColumn)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*); |
| 10216 void (*xPhraseNextColumn)(Fts5Context*, Fts5PhraseIter*, int *piCol); |
| 8377 }; | 10217 }; |
| 8378 | 10218 |
| 8379 /* | 10219 /* |
| 8380 ** CUSTOM AUXILIARY FUNCTIONS | 10220 ** CUSTOM AUXILIARY FUNCTIONS |
| 8381 *************************************************************************/ | 10221 *************************************************************************/ |
| 8382 | 10222 |
| 8383 /************************************************************************* | 10223 /************************************************************************* |
| 8384 ** CUSTOM TOKENIZERS | 10224 ** CUSTOM TOKENIZERS |
| 8385 ** | 10225 ** |
| 8386 ** Applications may also register custom tokenizer types. A tokenizer | 10226 ** Applications may also register custom tokenizer types. A tokenizer |
| 8387 ** is registered by providing fts5 with a populated instance of the | 10227 ** is registered by providing fts5 with a populated instance of the |
| 8388 ** following structure. All structure methods must be defined, setting | 10228 ** following structure. All structure methods must be defined, setting |
| 8389 ** any member of the fts5_tokenizer struct to NULL leads to undefined | 10229 ** any member of the fts5_tokenizer struct to NULL leads to undefined |
| 8390 ** behaviour. The structure methods are expected to function as follows: | 10230 ** behaviour. The structure methods are expected to function as follows: |
| 8391 ** | 10231 ** |
| 8392 ** xCreate: | 10232 ** xCreate: |
| 8393 ** This function is used to allocate and inititalize a tokenizer instance. | 10233 ** This function is used to allocate and initialize a tokenizer instance. |
| 8394 ** A tokenizer instance is required to actually tokenize text. | 10234 ** A tokenizer instance is required to actually tokenize text. |
| 8395 ** | 10235 ** |
| 8396 ** The first argument passed to this function is a copy of the (void*) | 10236 ** The first argument passed to this function is a copy of the (void*) |
| 8397 ** pointer provided by the application when the fts5_tokenizer object | 10237 ** pointer provided by the application when the fts5_tokenizer object |
| 8398 ** was registered with FTS5 (the third argument to xCreateTokenizer()). | 10238 ** was registered with FTS5 (the third argument to xCreateTokenizer()). |
| 8399 ** The second and third arguments are an array of nul-terminated strings | 10239 ** The second and third arguments are an array of nul-terminated strings |
| 8400 ** containing the tokenizer arguments, if any, specified following the | 10240 ** containing the tokenizer arguments, if any, specified following the |
| 8401 ** tokenizer name as part of the CREATE VIRTUAL TABLE statement used | 10241 ** tokenizer name as part of the CREATE VIRTUAL TABLE statement used |
| 8402 ** to create the FTS5 table. | 10242 ** to create the FTS5 table. |
| 8403 ** | 10243 ** |
| (...skipping 239 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 8643 /* | 10483 /* |
| 8644 ** END OF REGISTRATION API | 10484 ** END OF REGISTRATION API |
| 8645 *************************************************************************/ | 10485 *************************************************************************/ |
| 8646 | 10486 |
| 8647 #ifdef __cplusplus | 10487 #ifdef __cplusplus |
| 8648 } /* end of the 'extern "C"' block */ | 10488 } /* end of the 'extern "C"' block */ |
| 8649 #endif | 10489 #endif |
| 8650 | 10490 |
| 8651 #endif /* _FTS5_H */ | 10491 #endif /* _FTS5_H */ |
| 8652 | 10492 |
| 8653 | 10493 /******** End of fts5.h *********/ |
| OLD | NEW |