Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(974)

Side by Side Diff: third_party/sqlite/amalgamation/sqlite3.h

Issue 2751253002: [sql] Import SQLite 3.17.0. (Closed)
Patch Set: also clang on Linux i386 Created 3 years, 9 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
OLDNEW
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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 ** &nbsp; int xEntryPoint( 5750 ** &nbsp; int xEntryPoint(
5491 ** &nbsp; sqlite3 *db, 5751 ** &nbsp; sqlite3 *db,
5492 ** &nbsp; const char **pzErrMsg, 5752 ** &nbsp; const char **pzErrMsg,
5493 ** &nbsp; const struct sqlite3_api_routines *pThunk 5753 ** &nbsp; const struct sqlite3_api_routines *pThunk
5494 ** &nbsp; ); 5754 ** &nbsp; );
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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 ** &nbsp; int nChangeset,
9791 ** &nbsp; void *pChangeset,
9792 ** </pre>
9793 **
9794 ** Is replaced by:
9795 **
9796 ** <pre>
9797 ** &nbsp; int (*xInput)(void *pIn, void *pData, int *pnData),
9798 ** &nbsp; 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 ** &nbsp; int *pnChangeset,
9825 ** &nbsp; void **ppChangeset,
9826 ** </pre>
9827 **
9828 ** Is replaced by:
9829 **
9830 ** <pre>
9831 ** &nbsp; int (*xOutput)(void *pOut, const void *pData, int nData),
9832 ** &nbsp; 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
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
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
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 *********/
OLDNEW
« no previous file with comments | « third_party/sqlite/README.chromium ('k') | third_party/sqlite/patches/0001-test-SQLite-tests-compiling-on-Linux.patch » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698