Annotation of elwix/files/sqlite/dist/sqlite3.h, revision 1.4.2.2
1.2 misho 1: /*
1.4.2.2 ! misho 2: ** 2001-09-15
1.2 misho 3: **
4: ** The author disclaims copyright to this source code. In place of
5: ** a legal notice, here is a blessing:
6: **
7: ** May you do good and not evil.
8: ** May you find forgiveness for yourself and forgive others.
9: ** May you share freely, never taking more than you give.
10: **
11: *************************************************************************
12: ** This header file defines the interface that the SQLite library
13: ** presents to client programs. If a C-function, structure, datatype,
14: ** or constant definition does not appear in this file, then it is
15: ** not a published API of SQLite, is subject to change without
16: ** notice, and should not be referenced by programs that use SQLite.
17: **
18: ** Some of the definitions that are in this file are marked as
19: ** "experimental". Experimental interfaces are normally new
20: ** features recently added to SQLite. We do not anticipate changes
21: ** to experimental interfaces but reserve the right to make minor changes
22: ** if experience from use "in the wild" suggest such changes are prudent.
23: **
24: ** The official C-language API documentation for SQLite is derived
25: ** from comments in this file. This file is the authoritative source
1.4 misho 26: ** on how SQLite interfaces are supposed to operate.
1.2 misho 27: **
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
30: ** the version number) and changes its name to "sqlite3.h" as
31: ** part of the build process.
32: */
1.4 misho 33: #ifndef SQLITE3_H
34: #define SQLITE3_H
1.2 misho 35: #include <stdarg.h> /* Needed for the definition of va_list */
36:
37: /*
38: ** Make sure we can call this stuff from C++.
39: */
40: #ifdef __cplusplus
41: extern "C" {
42: #endif
43:
44:
45: /*
1.4 misho 46: ** Provide the ability to override linkage features of the interface.
1.2 misho 47: */
48: #ifndef SQLITE_EXTERN
49: # define SQLITE_EXTERN extern
50: #endif
51: #ifndef SQLITE_API
52: # define SQLITE_API
53: #endif
1.4 misho 54: #ifndef SQLITE_CDECL
55: # define SQLITE_CDECL
56: #endif
57: #ifndef SQLITE_APICALL
58: # define SQLITE_APICALL
59: #endif
60: #ifndef 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
68: #endif
1.2 misho 69:
70: /*
71: ** These no-op macros are used in front of interfaces to mark those
72: ** interfaces as either deprecated or experimental. New applications
1.4 misho 73: ** should not use deprecated interfaces - they are supported for backwards
1.2 misho 74: ** compatibility only. Application writers should be aware that
75: ** experimental interfaces are subject to change in point releases.
76: **
77: ** These macros used to resolve to various kinds of compiler magic that
78: ** would generate warning messages when they were used. But that
79: ** compiler magic ended up generating such a flurry of bug reports
80: ** that we have taken it all out and gone back to using simple
81: ** noop macros.
82: */
83: #define SQLITE_DEPRECATED
84: #define SQLITE_EXPERIMENTAL
85:
86: /*
87: ** Ensure these symbols were not defined by some previous header file.
88: */
89: #ifdef SQLITE_VERSION
90: # undef SQLITE_VERSION
91: #endif
92: #ifdef SQLITE_VERSION_NUMBER
93: # undef SQLITE_VERSION_NUMBER
94: #endif
95:
96: /*
97: ** CAPI3REF: Compile-Time Library Version Numbers
98: **
99: ** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header
100: ** evaluates to a string literal that is the SQLite version in the
101: ** format "X.Y.Z" where X is the major version number (always 3 for
102: ** SQLite3) and Y is the minor version number and Z is the release number.)^
103: ** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer
104: ** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
105: ** numbers used in [SQLITE_VERSION].)^
106: ** The SQLITE_VERSION_NUMBER for any given release of SQLite will also
107: ** be larger than the release from which it is derived. Either Y will
108: ** be held constant and Z will be incremented or else Y will be incremented
109: ** and Z will be reset to zero.
110: **
1.4.2.1 misho 111: ** Since [version 3.6.18] ([dateof:3.6.18]),
112: ** SQLite source code has been stored in the
1.2 misho 113: ** <a href="http://www.fossil-scm.org/">Fossil configuration management
114: ** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to
115: ** a string which identifies a particular check-in of SQLite
116: ** within its configuration management system. ^The SQLITE_SOURCE_ID
1.4.2.1 misho 117: ** string contains the date and time of the check-in (UTC) and a SHA1
1.4.2.2 ! misho 118: ** or SHA3-256 hash of the entire source tree. If the source code has
! 119: ** been edited in any way since it was last checked in, then the last
! 120: ** four hexadecimal digits of the hash may be modified.
1.2 misho 121: **
122: ** See also: [sqlite3_libversion()],
123: ** [sqlite3_libversion_number()], [sqlite3_sourceid()],
124: ** [sqlite_version()] and [sqlite_source_id()].
125: */
1.4.2.2 ! misho 126: #define SQLITE_VERSION "3.29.0"
! 127: #define SQLITE_VERSION_NUMBER 3029000
! 128: #define SQLITE_SOURCE_ID "2019-07-10 17:32:03 fc82b73eaac8b36950e527f12c4b5dc1e147e6f4ad2217ae43ad82882a88bfa6"
1.2 misho 129:
130: /*
131: ** CAPI3REF: Run-Time Library Version Numbers
1.4.2.1 misho 132: ** KEYWORDS: sqlite3_version sqlite3_sourceid
1.2 misho 133: **
134: ** These interfaces provide the same information as the [SQLITE_VERSION],
135: ** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
136: ** but are associated with the library instead of the header file. ^(Cautious
137: ** programmers might include assert() statements in their application to
138: ** verify that values returned by these interfaces match the macros in
1.4 misho 139: ** the header, and thus ensure that the application is
1.2 misho 140: ** compiled with matching library and header files.
141: **
142: ** <blockquote><pre>
143: ** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
1.4.2.2 ! misho 144: ** assert( strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 );
1.2 misho 145: ** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
146: ** </pre></blockquote>)^
147: **
148: ** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
149: ** macro. ^The sqlite3_libversion() function returns a pointer to the
150: ** to the sqlite3_version[] string constant. The sqlite3_libversion()
151: ** function is provided for use in DLLs since DLL users usually do not have
152: ** direct access to string constants within the DLL. ^The
153: ** sqlite3_libversion_number() function returns an integer equal to
1.4.2.2 ! misho 154: ** [SQLITE_VERSION_NUMBER]. ^(The sqlite3_sourceid() function returns
1.2 misho 155: ** a pointer to a string constant whose value is the same as the
1.4.2.2 ! misho 156: ** [SQLITE_SOURCE_ID] C preprocessor macro. Except if SQLite is built
! 157: ** using an edited copy of [the amalgamation], then the last four characters
! 158: ** of the hash might be different from [SQLITE_SOURCE_ID].)^
1.2 misho 159: **
160: ** See also: [sqlite_version()] and [sqlite_source_id()].
161: */
162: SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
163: SQLITE_API const char *sqlite3_libversion(void);
164: SQLITE_API const char *sqlite3_sourceid(void);
165: SQLITE_API int sqlite3_libversion_number(void);
166:
167: /*
168: ** CAPI3REF: Run-Time Library Compilation Options Diagnostics
169: **
170: ** ^The sqlite3_compileoption_used() function returns 0 or 1
171: ** indicating whether the specified option was defined at
172: ** compile time. ^The SQLITE_ prefix may be omitted from the
173: ** option name passed to sqlite3_compileoption_used().
174: **
175: ** ^The sqlite3_compileoption_get() function allows iterating
176: ** over the list of options that were defined at compile time by
177: ** returning the N-th compile time option string. ^If N is out of range,
178: ** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_
179: ** prefix is omitted from any strings returned by
180: ** sqlite3_compileoption_get().
181: **
182: ** ^Support for the diagnostic functions sqlite3_compileoption_used()
183: ** and sqlite3_compileoption_get() may be omitted by specifying the
184: ** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
185: **
186: ** See also: SQL functions [sqlite_compileoption_used()] and
187: ** [sqlite_compileoption_get()] and the [compile_options pragma].
188: */
189: #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
190: SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
191: SQLITE_API const char *sqlite3_compileoption_get(int N);
1.4.2.2 ! misho 192: #else
! 193: # define sqlite3_compileoption_used(X) 0
! 194: # define sqlite3_compileoption_get(X) ((void*)0)
1.2 misho 195: #endif
196:
197: /*
198: ** CAPI3REF: Test To See If The Library Is Threadsafe
199: **
200: ** ^The sqlite3_threadsafe() function returns zero if and only if
201: ** SQLite was compiled with mutexing code omitted due to the
202: ** [SQLITE_THREADSAFE] compile-time option being set to 0.
203: **
204: ** SQLite can be compiled with or without mutexes. When
205: ** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
206: ** are enabled and SQLite is threadsafe. When the
207: ** [SQLITE_THREADSAFE] macro is 0,
208: ** the mutexes are omitted. Without the mutexes, it is not safe
209: ** to use SQLite concurrently from more than one thread.
210: **
211: ** Enabling mutexes incurs a measurable performance penalty.
212: ** So if speed is of utmost importance, it makes sense to disable
213: ** the mutexes. But for maximum safety, mutexes should be enabled.
214: ** ^The default behavior is for mutexes to be enabled.
215: **
216: ** This interface can be used by an application to make sure that the
217: ** version of SQLite that it is linking against was compiled with
218: ** the desired setting of the [SQLITE_THREADSAFE] macro.
219: **
220: ** This interface only reports on the compile-time mutex setting
221: ** of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with
222: ** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
223: ** can be fully or partially disabled using a call to [sqlite3_config()]
224: ** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
1.4 misho 225: ** or [SQLITE_CONFIG_SERIALIZED]. ^(The return value of the
1.2 misho 226: ** sqlite3_threadsafe() function shows only the compile-time setting of
227: ** thread safety, not any run-time changes to that setting made by
228: ** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
229: ** is unchanged by calls to sqlite3_config().)^
230: **
231: ** See the [threading mode] documentation for additional information.
232: */
233: SQLITE_API int sqlite3_threadsafe(void);
234:
235: /*
236: ** CAPI3REF: Database Connection Handle
237: ** KEYWORDS: {database connection} {database connections}
238: **
239: ** Each open SQLite database is represented by a pointer to an instance of
240: ** the opaque structure named "sqlite3". It is useful to think of an sqlite3
241: ** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and
242: ** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
1.3 misho 243: ** and [sqlite3_close_v2()] are its destructors. There are many other
244: ** interfaces (such as
1.2 misho 245: ** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
246: ** [sqlite3_busy_timeout()] to name but three) that are methods on an
247: ** sqlite3 object.
248: */
249: typedef struct sqlite3 sqlite3;
250:
251: /*
252: ** CAPI3REF: 64-Bit Integer Types
253: ** KEYWORDS: sqlite_int64 sqlite_uint64
254: **
255: ** Because there is no cross-platform way to specify 64-bit integer types
256: ** SQLite includes typedefs for 64-bit signed and unsigned integers.
257: **
258: ** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
259: ** The sqlite_int64 and sqlite_uint64 types are supported for backwards
260: ** compatibility only.
261: **
262: ** ^The sqlite3_int64 and sqlite_int64 types can store integer values
263: ** between -9223372036854775808 and +9223372036854775807 inclusive. ^The
264: ** sqlite3_uint64 and sqlite_uint64 types can store integer values
265: ** between 0 and +18446744073709551615 inclusive.
266: */
267: #ifdef SQLITE_INT64_TYPE
268: typedef SQLITE_INT64_TYPE sqlite_int64;
1.4.2.1 misho 269: # ifdef SQLITE_UINT64_TYPE
270: typedef SQLITE_UINT64_TYPE sqlite_uint64;
271: # else
272: typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
273: # endif
1.2 misho 274: #elif defined(_MSC_VER) || defined(__BORLANDC__)
275: typedef __int64 sqlite_int64;
276: typedef unsigned __int64 sqlite_uint64;
277: #else
278: typedef long long int sqlite_int64;
279: typedef unsigned long long int sqlite_uint64;
280: #endif
281: typedef sqlite_int64 sqlite3_int64;
282: typedef sqlite_uint64 sqlite3_uint64;
283:
284: /*
285: ** If compiling for a processor that lacks floating point support,
286: ** substitute integer for floating-point.
287: */
288: #ifdef SQLITE_OMIT_FLOATING_POINT
289: # define double sqlite3_int64
290: #endif
291:
292: /*
293: ** CAPI3REF: Closing A Database Connection
1.4 misho 294: ** DESTRUCTOR: sqlite3
1.2 misho 295: **
1.3 misho 296: ** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
297: ** for the [sqlite3] object.
1.4 misho 298: ** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if
1.3 misho 299: ** the [sqlite3] object is successfully destroyed and all associated
300: ** resources are deallocated.
301: **
302: ** ^If the database connection is associated with unfinalized prepared
303: ** statements or unfinished sqlite3_backup objects then sqlite3_close()
304: ** will leave the database connection open and return [SQLITE_BUSY].
305: ** ^If sqlite3_close_v2() is called with unfinalized prepared statements
1.4 misho 306: ** and/or unfinished sqlite3_backups, then the database connection becomes
1.3 misho 307: ** an unusable "zombie" which will automatically be deallocated when the
308: ** last prepared statement is finalized or the last sqlite3_backup is
309: ** finished. The sqlite3_close_v2() interface is intended for use with
310: ** host languages that are garbage collected, and where the order in which
311: ** destructors are called is arbitrary.
312: **
313: ** Applications should [sqlite3_finalize | finalize] all [prepared statements],
314: ** [sqlite3_blob_close | close] all [BLOB handles], and
315: ** [sqlite3_backup_finish | finish] all [sqlite3_backup] objects associated
316: ** with the [sqlite3] object prior to attempting to close the object. ^If
1.4 misho 317: ** sqlite3_close_v2() is called on a [database connection] that still has
1.3 misho 318: ** outstanding [prepared statements], [BLOB handles], and/or
1.4 misho 319: ** [sqlite3_backup] objects then it returns [SQLITE_OK] and the deallocation
1.3 misho 320: ** of resources is deferred until all [prepared statements], [BLOB handles],
321: ** and [sqlite3_backup] objects are also destroyed.
1.2 misho 322: **
1.3 misho 323: ** ^If an [sqlite3] object is destroyed while a transaction is open,
1.2 misho 324: ** the transaction is automatically rolled back.
325: **
1.3 misho 326: ** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)]
327: ** must be either a NULL
1.2 misho 328: ** pointer or an [sqlite3] object pointer obtained
329: ** from [sqlite3_open()], [sqlite3_open16()], or
330: ** [sqlite3_open_v2()], and not previously closed.
1.3 misho 331: ** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer
332: ** argument is a harmless no-op.
1.2 misho 333: */
1.3 misho 334: SQLITE_API int sqlite3_close(sqlite3*);
335: SQLITE_API int sqlite3_close_v2(sqlite3*);
1.2 misho 336:
337: /*
338: ** The type for a callback function.
339: ** This is legacy and deprecated. It is included for historical
340: ** compatibility and is not documented.
341: */
342: typedef int (*sqlite3_callback)(void*,int,char**, char**);
343:
344: /*
345: ** CAPI3REF: One-Step Query Execution Interface
1.4 misho 346: ** METHOD: sqlite3
1.2 misho 347: **
348: ** The sqlite3_exec() interface is a convenience wrapper around
349: ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
350: ** that allows an application to run multiple statements of SQL
351: ** without having to use a lot of C code.
352: **
353: ** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
354: ** semicolon-separate SQL statements passed into its 2nd argument,
355: ** in the context of the [database connection] passed in as its 1st
356: ** argument. ^If the callback function of the 3rd argument to
357: ** sqlite3_exec() is not NULL, then it is invoked for each result row
358: ** coming out of the evaluated SQL statements. ^The 4th argument to
359: ** sqlite3_exec() is relayed through to the 1st argument of each
360: ** callback invocation. ^If the callback pointer to sqlite3_exec()
361: ** is NULL, then no callback is ever invoked and result rows are
362: ** ignored.
363: **
364: ** ^If an error occurs while evaluating the SQL statements passed into
365: ** sqlite3_exec(), then execution of the current statement stops and
366: ** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec()
367: ** is not NULL then any error message is written into memory obtained
368: ** from [sqlite3_malloc()] and passed back through the 5th parameter.
369: ** To avoid memory leaks, the application should invoke [sqlite3_free()]
370: ** on error message strings returned through the 5th parameter of
1.4 misho 371: ** sqlite3_exec() after the error message string is no longer needed.
1.2 misho 372: ** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
373: ** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
374: ** NULL before returning.
375: **
376: ** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
377: ** routine returns SQLITE_ABORT without invoking the callback again and
378: ** without running any subsequent SQL statements.
379: **
380: ** ^The 2nd argument to the sqlite3_exec() callback function is the
381: ** number of columns in the result. ^The 3rd argument to the sqlite3_exec()
382: ** callback is an array of pointers to strings obtained as if from
383: ** [sqlite3_column_text()], one for each column. ^If an element of a
384: ** result row is NULL then the corresponding string pointer for the
385: ** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the
386: ** sqlite3_exec() callback is an array of pointers to strings where each
387: ** entry represents the name of corresponding result column as obtained
388: ** from [sqlite3_column_name()].
389: **
390: ** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
391: ** to an empty string, or a pointer that contains only whitespace and/or
392: ** SQL comments, then no SQL statements are evaluated and the database
393: ** is not changed.
394: **
395: ** Restrictions:
396: **
397: ** <ul>
1.4 misho 398: ** <li> The application must ensure that the 1st parameter to sqlite3_exec()
1.2 misho 399: ** is a valid and open [database connection].
1.4 misho 400: ** <li> The application must not close the [database connection] specified by
1.2 misho 401: ** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
402: ** <li> The application must not modify the SQL statement text passed into
403: ** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
404: ** </ul>
405: */
406: SQLITE_API int sqlite3_exec(
407: sqlite3*, /* An open database */
408: const char *sql, /* SQL to be evaluated */
409: int (*callback)(void*,int,char**,char**), /* Callback function */
410: void *, /* 1st argument to callback */
411: char **errmsg /* Error msg written here */
412: );
413:
414: /*
415: ** CAPI3REF: Result Codes
1.4 misho 416: ** KEYWORDS: {result code definitions}
1.2 misho 417: **
418: ** Many SQLite functions return an integer result code from the set shown
419: ** here in order to indicate success or failure.
420: **
421: ** New error codes may be added in future versions of SQLite.
422: **
1.4 misho 423: ** See also: [extended result code definitions]
1.2 misho 424: */
425: #define SQLITE_OK 0 /* Successful result */
426: /* beginning-of-error-codes */
1.4.2.2 ! misho 427: #define SQLITE_ERROR 1 /* Generic error */
1.2 misho 428: #define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */
429: #define SQLITE_PERM 3 /* Access permission denied */
430: #define SQLITE_ABORT 4 /* Callback routine requested an abort */
431: #define SQLITE_BUSY 5 /* The database file is locked */
432: #define SQLITE_LOCKED 6 /* A table in the database is locked */
433: #define SQLITE_NOMEM 7 /* A malloc() failed */
434: #define SQLITE_READONLY 8 /* Attempt to write a readonly database */
435: #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
436: #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
437: #define SQLITE_CORRUPT 11 /* The database disk image is malformed */
438: #define SQLITE_NOTFOUND 12 /* Unknown opcode in sqlite3_file_control() */
439: #define SQLITE_FULL 13 /* Insertion failed because database is full */
440: #define SQLITE_CANTOPEN 14 /* Unable to open the database file */
441: #define SQLITE_PROTOCOL 15 /* Database lock protocol error */
1.4.2.2 ! misho 442: #define SQLITE_EMPTY 16 /* Internal use only */
1.2 misho 443: #define SQLITE_SCHEMA 17 /* The database schema changed */
444: #define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
445: #define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
446: #define SQLITE_MISMATCH 20 /* Data type mismatch */
447: #define SQLITE_MISUSE 21 /* Library used incorrectly */
448: #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
449: #define SQLITE_AUTH 23 /* Authorization denied */
1.4.2.2 ! misho 450: #define SQLITE_FORMAT 24 /* Not used */
1.2 misho 451: #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
452: #define SQLITE_NOTADB 26 /* File opened that is not a database file */
1.4 misho 453: #define SQLITE_NOTICE 27 /* Notifications from sqlite3_log() */
454: #define SQLITE_WARNING 28 /* Warnings from sqlite3_log() */
1.2 misho 455: #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
456: #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
457: /* end-of-error-codes */
458:
459: /*
460: ** CAPI3REF: Extended Result Codes
1.4 misho 461: ** KEYWORDS: {extended result code definitions}
1.2 misho 462: **
1.4 misho 463: ** In its default configuration, SQLite API routines return one of 30 integer
464: ** [result codes]. However, experience has shown that many of
1.2 misho 465: ** these result codes are too coarse-grained. They do not provide as
466: ** much information about problems as programmers might like. In an effort to
1.4.2.1 misho 467: ** address this, newer versions of SQLite (version 3.3.8 [dateof:3.3.8]
468: ** and later) include
1.2 misho 469: ** support for additional result codes that provide more detailed information
1.4 misho 470: ** about errors. These [extended result codes] are enabled or disabled
1.2 misho 471: ** on a per database connection basis using the
1.4 misho 472: ** [sqlite3_extended_result_codes()] API. Or, the extended code for
473: ** the most recent error can be obtained using
474: ** [sqlite3_extended_errcode()].
1.2 misho 475: */
1.4.2.2 ! misho 476: #define SQLITE_ERROR_MISSING_COLLSEQ (SQLITE_ERROR | (1<<8))
! 477: #define SQLITE_ERROR_RETRY (SQLITE_ERROR | (2<<8))
! 478: #define SQLITE_ERROR_SNAPSHOT (SQLITE_ERROR | (3<<8))
1.2 misho 479: #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))
480: #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))
481: #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8))
482: #define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8))
483: #define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8))
484: #define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8))
485: #define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8))
486: #define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8))
487: #define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8))
488: #define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8))
489: #define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8))
490: #define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8))
491: #define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8))
492: #define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
493: #define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8))
494: #define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8))
495: #define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8))
496: #define SQLITE_IOERR_SHMOPEN (SQLITE_IOERR | (18<<8))
497: #define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR | (19<<8))
498: #define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR | (20<<8))
499: #define SQLITE_IOERR_SHMMAP (SQLITE_IOERR | (21<<8))
500: #define SQLITE_IOERR_SEEK (SQLITE_IOERR | (22<<8))
1.3 misho 501: #define SQLITE_IOERR_DELETE_NOENT (SQLITE_IOERR | (23<<8))
1.4 misho 502: #define SQLITE_IOERR_MMAP (SQLITE_IOERR | (24<<8))
503: #define SQLITE_IOERR_GETTEMPPATH (SQLITE_IOERR | (25<<8))
504: #define SQLITE_IOERR_CONVPATH (SQLITE_IOERR | (26<<8))
505: #define SQLITE_IOERR_VNODE (SQLITE_IOERR | (27<<8))
506: #define SQLITE_IOERR_AUTH (SQLITE_IOERR | (28<<8))
1.4.2.2 ! misho 507: #define SQLITE_IOERR_BEGIN_ATOMIC (SQLITE_IOERR | (29<<8))
! 508: #define SQLITE_IOERR_COMMIT_ATOMIC (SQLITE_IOERR | (30<<8))
! 509: #define SQLITE_IOERR_ROLLBACK_ATOMIC (SQLITE_IOERR | (31<<8))
1.2 misho 510: #define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8))
1.4.2.2 ! misho 511: #define SQLITE_LOCKED_VTAB (SQLITE_LOCKED | (2<<8))
1.2 misho 512: #define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8))
1.4 misho 513: #define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8))
1.2 misho 514: #define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8))
1.3 misho 515: #define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8))
516: #define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3<<8))
1.4 misho 517: #define SQLITE_CANTOPEN_CONVPATH (SQLITE_CANTOPEN | (4<<8))
1.4.2.2 ! misho 518: #define SQLITE_CANTOPEN_DIRTYWAL (SQLITE_CANTOPEN | (5<<8)) /* Not Used */
1.2 misho 519: #define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8))
1.4.2.2 ! misho 520: #define SQLITE_CORRUPT_SEQUENCE (SQLITE_CORRUPT | (2<<8))
1.2 misho 521: #define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8))
522: #define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8))
1.4 misho 523: #define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3<<8))
524: #define SQLITE_READONLY_DBMOVED (SQLITE_READONLY | (4<<8))
1.4.2.2 ! misho 525: #define SQLITE_READONLY_CANTINIT (SQLITE_READONLY | (5<<8))
! 526: #define SQLITE_READONLY_DIRECTORY (SQLITE_READONLY | (6<<8))
1.3 misho 527: #define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT | (2<<8))
1.4 misho 528: #define SQLITE_CONSTRAINT_CHECK (SQLITE_CONSTRAINT | (1<<8))
529: #define SQLITE_CONSTRAINT_COMMITHOOK (SQLITE_CONSTRAINT | (2<<8))
530: #define SQLITE_CONSTRAINT_FOREIGNKEY (SQLITE_CONSTRAINT | (3<<8))
531: #define SQLITE_CONSTRAINT_FUNCTION (SQLITE_CONSTRAINT | (4<<8))
532: #define SQLITE_CONSTRAINT_NOTNULL (SQLITE_CONSTRAINT | (5<<8))
533: #define SQLITE_CONSTRAINT_PRIMARYKEY (SQLITE_CONSTRAINT | (6<<8))
534: #define SQLITE_CONSTRAINT_TRIGGER (SQLITE_CONSTRAINT | (7<<8))
535: #define SQLITE_CONSTRAINT_UNIQUE (SQLITE_CONSTRAINT | (8<<8))
536: #define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT | (9<<8))
537: #define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT |(10<<8))
538: #define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1<<8))
539: #define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8))
540: #define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8))
541: #define SQLITE_AUTH_USER (SQLITE_AUTH | (1<<8))
542: #define SQLITE_OK_LOAD_PERMANENTLY (SQLITE_OK | (1<<8))
1.2 misho 543:
544: /*
545: ** CAPI3REF: Flags For File Open Operations
546: **
547: ** These bit values are intended for use in the
548: ** 3rd parameter to the [sqlite3_open_v2()] interface and
549: ** in the 4th parameter to the [sqlite3_vfs.xOpen] method.
550: */
551: #define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */
552: #define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */
553: #define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */
554: #define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */
555: #define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */
556: #define SQLITE_OPEN_AUTOPROXY 0x00000020 /* VFS only */
557: #define SQLITE_OPEN_URI 0x00000040 /* Ok for sqlite3_open_v2() */
1.3 misho 558: #define SQLITE_OPEN_MEMORY 0x00000080 /* Ok for sqlite3_open_v2() */
1.2 misho 559: #define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */
560: #define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */
561: #define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */
562: #define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */
563: #define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */
564: #define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */
565: #define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 /* VFS only */
566: #define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */
567: #define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */
568: #define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */
569: #define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */
570: #define SQLITE_OPEN_WAL 0x00080000 /* VFS only */
571:
572: /* Reserved: 0x00F00000 */
573:
574: /*
575: ** CAPI3REF: Device Characteristics
576: **
577: ** The xDeviceCharacteristics method of the [sqlite3_io_methods]
1.3 misho 578: ** object returns an integer which is a vector of these
1.2 misho 579: ** bit values expressing I/O characteristics of the mass storage
580: ** device that holds the file that the [sqlite3_io_methods]
581: ** refers to.
582: **
583: ** The SQLITE_IOCAP_ATOMIC property means that all writes of
584: ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
585: ** mean that writes of blocks that are nnn bytes in size and
586: ** are aligned to an address which is an integer multiple of
587: ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
588: ** that when data is appended to a file, the data is appended
589: ** first then the size of the file is extended, never the other
590: ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
591: ** information is written to disk in the same order as calls
592: ** to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that
593: ** after reboot following a crash or power loss, the only bytes in a
594: ** file that were written at the application level might have changed
595: ** and that adjacent bytes, even bytes within the same sector are
1.4 misho 596: ** guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
1.4.2.1 misho 597: ** flag indicates that a file cannot be deleted when open. The
1.4 misho 598: ** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
599: ** read-only media and cannot be changed even by processes with
600: ** elevated privileges.
1.4.2.2 ! misho 601: **
! 602: ** The SQLITE_IOCAP_BATCH_ATOMIC property means that the underlying
! 603: ** filesystem supports doing multiple write operations atomically when those
! 604: ** write operations are bracketed by [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] and
! 605: ** [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE].
1.2 misho 606: */
607: #define SQLITE_IOCAP_ATOMIC 0x00000001
608: #define SQLITE_IOCAP_ATOMIC512 0x00000002
609: #define SQLITE_IOCAP_ATOMIC1K 0x00000004
610: #define SQLITE_IOCAP_ATOMIC2K 0x00000008
611: #define SQLITE_IOCAP_ATOMIC4K 0x00000010
612: #define SQLITE_IOCAP_ATOMIC8K 0x00000020
613: #define SQLITE_IOCAP_ATOMIC16K 0x00000040
614: #define SQLITE_IOCAP_ATOMIC32K 0x00000080
615: #define SQLITE_IOCAP_ATOMIC64K 0x00000100
616: #define SQLITE_IOCAP_SAFE_APPEND 0x00000200
617: #define SQLITE_IOCAP_SEQUENTIAL 0x00000400
618: #define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800
619: #define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000
1.4 misho 620: #define SQLITE_IOCAP_IMMUTABLE 0x00002000
1.4.2.2 ! misho 621: #define SQLITE_IOCAP_BATCH_ATOMIC 0x00004000
1.2 misho 622:
623: /*
624: ** CAPI3REF: File Locking Levels
625: **
626: ** SQLite uses one of these integer values as the second
627: ** argument to calls it makes to the xLock() and xUnlock() methods
628: ** of an [sqlite3_io_methods] object.
629: */
630: #define SQLITE_LOCK_NONE 0
631: #define SQLITE_LOCK_SHARED 1
632: #define SQLITE_LOCK_RESERVED 2
633: #define SQLITE_LOCK_PENDING 3
634: #define SQLITE_LOCK_EXCLUSIVE 4
635:
636: /*
637: ** CAPI3REF: Synchronization Type Flags
638: **
639: ** When SQLite invokes the xSync() method of an
640: ** [sqlite3_io_methods] object it uses a combination of
641: ** these integer values as the second argument.
642: **
643: ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
644: ** sync operation only needs to flush data to mass storage. Inode
645: ** information need not be flushed. If the lower four bits of the flag
646: ** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
647: ** If the lower four bits equal SQLITE_SYNC_FULL, that means
648: ** to use Mac OS X style fullsync instead of fsync().
649: **
650: ** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
651: ** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL
652: ** settings. The [synchronous pragma] determines when calls to the
653: ** xSync VFS method occur and applies uniformly across all platforms.
654: ** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
655: ** energetic or rigorous or forceful the sync operations are and
656: ** only make a difference on Mac OSX for the default SQLite code.
657: ** (Third-party VFS implementations might also make the distinction
658: ** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
659: ** operating systems natively supported by SQLite, only Mac OSX
660: ** cares about the difference.)
661: */
662: #define SQLITE_SYNC_NORMAL 0x00002
663: #define SQLITE_SYNC_FULL 0x00003
664: #define SQLITE_SYNC_DATAONLY 0x00010
665:
666: /*
667: ** CAPI3REF: OS Interface Open File Handle
668: **
669: ** An [sqlite3_file] object represents an open file in the
670: ** [sqlite3_vfs | OS interface layer]. Individual OS interface
671: ** implementations will
672: ** want to subclass this object by appending additional fields
673: ** for their own use. The pMethods entry is a pointer to an
674: ** [sqlite3_io_methods] object that defines methods for performing
675: ** I/O operations on the open file.
676: */
677: typedef struct sqlite3_file sqlite3_file;
678: struct sqlite3_file {
679: const struct sqlite3_io_methods *pMethods; /* Methods for an open file */
680: };
681:
682: /*
683: ** CAPI3REF: OS Interface File Virtual Methods Object
684: **
685: ** Every file opened by the [sqlite3_vfs.xOpen] method populates an
686: ** [sqlite3_file] object (or, more commonly, a subclass of the
687: ** [sqlite3_file] object) with a pointer to an instance of this object.
688: ** This object defines the methods used to perform various operations
689: ** against the open file represented by the [sqlite3_file] object.
690: **
691: ** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element
692: ** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
693: ** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed. The
694: ** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]
695: ** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
696: ** to NULL.
697: **
698: ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
699: ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
700: ** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY]
701: ** flag may be ORed in to indicate that only the data of the file
702: ** and not its inode needs to be synced.
703: **
704: ** The integer values to xLock() and xUnlock() are one of
705: ** <ul>
706: ** <li> [SQLITE_LOCK_NONE],
707: ** <li> [SQLITE_LOCK_SHARED],
708: ** <li> [SQLITE_LOCK_RESERVED],
709: ** <li> [SQLITE_LOCK_PENDING], or
710: ** <li> [SQLITE_LOCK_EXCLUSIVE].
711: ** </ul>
712: ** xLock() increases the lock. xUnlock() decreases the lock.
713: ** The xCheckReservedLock() method checks whether any database connection,
714: ** either in this process or in some other process, is holding a RESERVED,
715: ** PENDING, or EXCLUSIVE lock on the file. It returns true
716: ** if such a lock exists and false otherwise.
717: **
718: ** The xFileControl() method is a generic interface that allows custom
719: ** VFS implementations to directly control an open file using the
720: ** [sqlite3_file_control()] interface. The second "op" argument is an
721: ** integer opcode. The third argument is a generic pointer intended to
722: ** point to a structure that may contain arguments or space in which to
723: ** write return values. Potential uses for xFileControl() might be
724: ** functions to enable blocking locks with timeouts, to change the
725: ** locking strategy (for example to use dot-file locks), to inquire
726: ** about the status of a lock, or to break stale locks. The SQLite
727: ** core reserves all opcodes less than 100 for its own use.
1.4 misho 728: ** A [file control opcodes | list of opcodes] less than 100 is available.
1.2 misho 729: ** Applications that define a custom xFileControl method should use opcodes
730: ** greater than 100 to avoid conflicts. VFS implementations should
731: ** return [SQLITE_NOTFOUND] for file control opcodes that they do not
732: ** recognize.
733: **
734: ** The xSectorSize() method returns the sector size of the
735: ** device that underlies the file. The sector size is the
736: ** minimum write that can be performed without disturbing
737: ** other bytes in the file. The xDeviceCharacteristics()
738: ** method returns a bit vector describing behaviors of the
739: ** underlying device:
740: **
741: ** <ul>
742: ** <li> [SQLITE_IOCAP_ATOMIC]
743: ** <li> [SQLITE_IOCAP_ATOMIC512]
744: ** <li> [SQLITE_IOCAP_ATOMIC1K]
745: ** <li> [SQLITE_IOCAP_ATOMIC2K]
746: ** <li> [SQLITE_IOCAP_ATOMIC4K]
747: ** <li> [SQLITE_IOCAP_ATOMIC8K]
748: ** <li> [SQLITE_IOCAP_ATOMIC16K]
749: ** <li> [SQLITE_IOCAP_ATOMIC32K]
750: ** <li> [SQLITE_IOCAP_ATOMIC64K]
751: ** <li> [SQLITE_IOCAP_SAFE_APPEND]
752: ** <li> [SQLITE_IOCAP_SEQUENTIAL]
1.4.2.1 misho 753: ** <li> [SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN]
754: ** <li> [SQLITE_IOCAP_POWERSAFE_OVERWRITE]
755: ** <li> [SQLITE_IOCAP_IMMUTABLE]
1.4.2.2 ! misho 756: ** <li> [SQLITE_IOCAP_BATCH_ATOMIC]
1.2 misho 757: ** </ul>
758: **
759: ** The SQLITE_IOCAP_ATOMIC property means that all writes of
760: ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
761: ** mean that writes of blocks that are nnn bytes in size and
762: ** are aligned to an address which is an integer multiple of
763: ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
764: ** that when data is appended to a file, the data is appended
765: ** first then the size of the file is extended, never the other
766: ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
767: ** information is written to disk in the same order as calls
768: ** to xWrite().
769: **
770: ** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
771: ** in the unread portions of the buffer with zeros. A VFS that
772: ** fails to zero-fill short reads might seem to work. However,
773: ** failure to zero-fill short reads will eventually lead to
774: ** database corruption.
775: */
776: typedef struct sqlite3_io_methods sqlite3_io_methods;
777: struct sqlite3_io_methods {
778: int iVersion;
779: int (*xClose)(sqlite3_file*);
780: int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
781: int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
782: int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
783: int (*xSync)(sqlite3_file*, int flags);
784: int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
785: int (*xLock)(sqlite3_file*, int);
786: int (*xUnlock)(sqlite3_file*, int);
787: int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
788: int (*xFileControl)(sqlite3_file*, int op, void *pArg);
789: int (*xSectorSize)(sqlite3_file*);
790: int (*xDeviceCharacteristics)(sqlite3_file*);
791: /* Methods above are valid for version 1 */
792: int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
793: int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
794: void (*xShmBarrier)(sqlite3_file*);
795: int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
796: /* Methods above are valid for version 2 */
1.4 misho 797: int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
798: int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
799: /* Methods above are valid for version 3 */
1.2 misho 800: /* Additional methods may be added in future releases */
801: };
802:
803: /*
804: ** CAPI3REF: Standard File Control Opcodes
1.4 misho 805: ** KEYWORDS: {file control opcodes} {file control opcode}
1.2 misho 806: **
807: ** These integer constants are opcodes for the xFileControl method
808: ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
809: ** interface.
810: **
1.4 misho 811: ** <ul>
812: ** <li>[[SQLITE_FCNTL_LOCKSTATE]]
1.2 misho 813: ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
814: ** opcode causes the xFileControl method to write the current state of
815: ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
816: ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
817: ** into an integer that the pArg argument points to. This capability
1.4 misho 818: ** is used during testing and is only available when the SQLITE_TEST
819: ** compile-time option is used.
820: **
1.3 misho 821: ** <li>[[SQLITE_FCNTL_SIZE_HINT]]
1.2 misho 822: ** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
823: ** layer a hint of how large the database file will grow to be during the
824: ** current transaction. This hint is not guaranteed to be accurate but it
825: ** is often close. The underlying VFS might choose to preallocate database
826: ** file space based on this hint in order to help writes to the database
827: ** file run faster.
828: **
1.4.2.2 ! misho 829: ** <li>[[SQLITE_FCNTL_SIZE_LIMIT]]
! 830: ** The [SQLITE_FCNTL_SIZE_LIMIT] opcode is used by in-memory VFS that
! 831: ** implements [sqlite3_deserialize()] to set an upper bound on the size
! 832: ** of the in-memory database. The argument is a pointer to a [sqlite3_int64].
! 833: ** If the integer pointed to is negative, then it is filled in with the
! 834: ** current limit. Otherwise the limit is set to the larger of the value
! 835: ** of the integer pointed to and the current database size. The integer
! 836: ** pointed to is set to the new limit.
! 837: **
1.3 misho 838: ** <li>[[SQLITE_FCNTL_CHUNK_SIZE]]
1.2 misho 839: ** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
840: ** extends and truncates the database file in chunks of a size specified
841: ** by the user. The fourth argument to [sqlite3_file_control()] should
842: ** point to an integer (type int) containing the new chunk-size to use
843: ** for the nominated database. Allocating database file space in large
844: ** chunks (say 1MB at a time), may reduce file-system fragmentation and
845: ** improve performance on some systems.
846: **
1.3 misho 847: ** <li>[[SQLITE_FCNTL_FILE_POINTER]]
1.2 misho 848: ** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
849: ** to the [sqlite3_file] object associated with a particular database
1.4 misho 850: ** connection. See also [SQLITE_FCNTL_JOURNAL_POINTER].
851: **
852: ** <li>[[SQLITE_FCNTL_JOURNAL_POINTER]]
853: ** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer
854: ** to the [sqlite3_file] object associated with the journal file (either
855: ** the [rollback journal] or the [write-ahead log]) for a particular database
856: ** connection. See also [SQLITE_FCNTL_FILE_POINTER].
1.2 misho 857: **
1.3 misho 858: ** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]
1.4 misho 859: ** No longer in use.
860: **
861: ** <li>[[SQLITE_FCNTL_SYNC]]
862: ** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and
863: ** sent to the VFS immediately before the xSync method is invoked on a
864: ** database file descriptor. Or, if the xSync method is not invoked
865: ** because the user has configured SQLite with
866: ** [PRAGMA synchronous | PRAGMA synchronous=OFF] it is invoked in place
867: ** of the xSync method. In most cases, the pointer argument passed with
868: ** this file-control is NULL. However, if the database file is being synced
869: ** as part of a multi-database commit, the argument points to a nul-terminated
870: ** string containing the transactions master-journal file name. VFSes that
871: ** do not need this signal should silently ignore this opcode. Applications
872: ** should not call [sqlite3_file_control()] with this opcode as doing so may
873: ** disrupt the operation of the specialized VFSes that do require it.
874: **
875: ** <li>[[SQLITE_FCNTL_COMMIT_PHASETWO]]
876: ** The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite
877: ** and sent to the VFS after a transaction has been committed immediately
878: ** but before the database is unlocked. VFSes that do not need this signal
879: ** should silently ignore this opcode. Applications should not call
880: ** [sqlite3_file_control()] with this opcode as doing so may disrupt the
881: ** operation of the specialized VFSes that do require it.
1.2 misho 882: **
1.3 misho 883: ** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]]
1.2 misho 884: ** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
885: ** retry counts and intervals for certain disk I/O operations for the
886: ** windows [VFS] in order to provide robustness in the presence of
887: ** anti-virus programs. By default, the windows VFS will retry file read,
888: ** file write, and file delete operations up to 10 times, with a delay
889: ** of 25 milliseconds before the first retry and with the delay increasing
890: ** by an additional 25 milliseconds with each subsequent retry. This
891: ** opcode allows these two values (10 retries and 25 milliseconds of delay)
892: ** to be adjusted. The values are changed for all database connections
893: ** within the same process. The argument is a pointer to an array of two
1.4.2.1 misho 894: ** integers where the first integer is the new retry count and the second
1.2 misho 895: ** integer is the delay. If either integer is negative, then the setting
896: ** is not changed but instead the prior value of that setting is written
897: ** into the array entry, allowing the current retry settings to be
898: ** interrogated. The zDbName parameter is ignored.
899: **
1.3 misho 900: ** <li>[[SQLITE_FCNTL_PERSIST_WAL]]
1.2 misho 901: ** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
1.3 misho 902: ** persistent [WAL | Write Ahead Log] setting. By default, the auxiliary
1.4.2.2 ! misho 903: ** write ahead log ([WAL file]) and shared memory
! 904: ** files used for transaction control
1.2 misho 905: ** are automatically deleted when the latest connection to the database
906: ** closes. Setting persistent WAL mode causes those files to persist after
907: ** close. Persisting the files is useful when other processes that do not
908: ** have write permission on the directory containing the database file want
909: ** to read the database file, as the WAL and shared memory files must exist
910: ** in order for the database to be readable. The fourth parameter to
911: ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
912: ** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
913: ** WAL mode. If the integer is -1, then it is overwritten with the current
914: ** WAL persistence setting.
915: **
1.3 misho 916: ** <li>[[SQLITE_FCNTL_POWERSAFE_OVERWRITE]]
1.2 misho 917: ** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the
918: ** persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting
919: ** determines the [SQLITE_IOCAP_POWERSAFE_OVERWRITE] bit of the
920: ** xDeviceCharacteristics methods. The fourth parameter to
921: ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
922: ** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
923: ** mode. If the integer is -1, then it is overwritten with the current
924: ** zero-damage mode setting.
925: **
1.3 misho 926: ** <li>[[SQLITE_FCNTL_OVERWRITE]]
1.2 misho 927: ** ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening
928: ** a write transaction to indicate that, unless it is rolled back for some
929: ** reason, the entire database file will be overwritten by the current
930: ** transaction. This is used by VACUUM operations.
931: **
1.3 misho 932: ** <li>[[SQLITE_FCNTL_VFSNAME]]
1.2 misho 933: ** ^The [SQLITE_FCNTL_VFSNAME] opcode can be used to obtain the names of
934: ** all [VFSes] in the VFS stack. The names are of all VFS shims and the
935: ** final bottom-level VFS are written into memory obtained from
936: ** [sqlite3_malloc()] and the result is stored in the char* variable
937: ** that the fourth parameter of [sqlite3_file_control()] points to.
938: ** The caller is responsible for freeing the memory when done. As with
939: ** all file-control actions, there is no guarantee that this will actually
940: ** do anything. Callers should initialize the char* variable to a NULL
941: ** pointer in case this file-control is not implemented. This file-control
942: ** is intended for diagnostic use only.
1.3 misho 943: **
1.4 misho 944: ** <li>[[SQLITE_FCNTL_VFS_POINTER]]
945: ** ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level
946: ** [VFSes] currently in use. ^(The argument X in
947: ** sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be
948: ** of type "[sqlite3_vfs] **". This opcodes will set *X
949: ** to a pointer to the top-level VFS.)^
950: ** ^When there are multiple VFS shims in the stack, this opcode finds the
951: ** upper-most shim only.
952: **
1.3 misho 953: ** <li>[[SQLITE_FCNTL_PRAGMA]]
954: ** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA]
955: ** file control is sent to the open [sqlite3_file] object corresponding
956: ** to the database file to which the pragma statement refers. ^The argument
957: ** to the [SQLITE_FCNTL_PRAGMA] file control is an array of
958: ** pointers to strings (char**) in which the second element of the array
959: ** is the name of the pragma and the third element is the argument to the
960: ** pragma or NULL if the pragma has no argument. ^The handler for an
961: ** [SQLITE_FCNTL_PRAGMA] file control can optionally make the first element
962: ** of the char** argument point to a string obtained from [sqlite3_mprintf()]
963: ** or the equivalent and that string will become the result of the pragma or
964: ** the error message if the pragma fails. ^If the
965: ** [SQLITE_FCNTL_PRAGMA] file control returns [SQLITE_NOTFOUND], then normal
966: ** [PRAGMA] processing continues. ^If the [SQLITE_FCNTL_PRAGMA]
967: ** file control returns [SQLITE_OK], then the parser assumes that the
968: ** VFS has handled the PRAGMA itself and the parser generates a no-op
1.4 misho 969: ** prepared statement if result string is NULL, or that returns a copy
970: ** of the result string if the string is non-NULL.
971: ** ^If the [SQLITE_FCNTL_PRAGMA] file control returns
1.3 misho 972: ** any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means
973: ** that the VFS encountered an error while handling the [PRAGMA] and the
974: ** compilation of the PRAGMA fails with an error. ^The [SQLITE_FCNTL_PRAGMA]
975: ** file control occurs at the beginning of pragma statement analysis and so
976: ** it is able to override built-in [PRAGMA] statements.
977: **
978: ** <li>[[SQLITE_FCNTL_BUSYHANDLER]]
1.4 misho 979: ** ^The [SQLITE_FCNTL_BUSYHANDLER]
980: ** file-control may be invoked by SQLite on the database file handle
1.3 misho 981: ** shortly after it is opened in order to provide a custom VFS with access
982: ** to the connections busy-handler callback. The argument is of type (void **)
983: ** - an array of two (void *) values. The first (void *) actually points
984: ** to a function of type (int (*)(void *)). In order to invoke the connections
985: ** busy-handler, this function should be invoked with the second (void *) in
986: ** the array as the only argument. If it returns non-zero, then the operation
987: ** should be retried. If it returns zero, the custom VFS should abandon the
988: ** current operation.
989: **
990: ** <li>[[SQLITE_FCNTL_TEMPFILENAME]]
1.4 misho 991: ** ^Application can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control
992: ** to have SQLite generate a
1.3 misho 993: ** temporary filename using the same algorithm that is followed to generate
994: ** temporary filenames for TEMP tables and other internal uses. The
995: ** argument should be a char** which will be filled with the filename
996: ** written into memory obtained from [sqlite3_malloc()]. The caller should
997: ** invoke [sqlite3_free()] on the result to avoid a memory leak.
998: **
1.4 misho 999: ** <li>[[SQLITE_FCNTL_MMAP_SIZE]]
1000: ** The [SQLITE_FCNTL_MMAP_SIZE] file control is used to query or set the
1001: ** maximum number of bytes that will be used for memory-mapped I/O.
1002: ** The argument is a pointer to a value of type sqlite3_int64 that
1003: ** is an advisory maximum number of bytes in the file to memory map. The
1004: ** pointer is overwritten with the old value. The limit is not changed if
1005: ** the value originally pointed to is negative, and so the current limit
1006: ** can be queried by passing in a pointer to a negative number. This
1007: ** file-control is used internally to implement [PRAGMA mmap_size].
1008: **
1009: ** <li>[[SQLITE_FCNTL_TRACE]]
1010: ** The [SQLITE_FCNTL_TRACE] file control provides advisory information
1011: ** to the VFS about what the higher layers of the SQLite stack are doing.
1012: ** This file control is used by some VFS activity tracing [shims].
1013: ** The argument is a zero-terminated string. Higher layers in the
1014: ** SQLite stack may generate instances of this file control if
1015: ** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
1016: **
1017: ** <li>[[SQLITE_FCNTL_HAS_MOVED]]
1018: ** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a
1019: ** pointer to an integer and it writes a boolean into that integer depending
1020: ** on whether or not the file has been renamed, moved, or deleted since it
1021: ** was first opened.
1022: **
1.4.2.1 misho 1023: ** <li>[[SQLITE_FCNTL_WIN32_GET_HANDLE]]
1024: ** The [SQLITE_FCNTL_WIN32_GET_HANDLE] opcode can be used to obtain the
1025: ** underlying native file handle associated with a file handle. This file
1026: ** control interprets its argument as a pointer to a native file handle and
1027: ** writes the resulting value there.
1028: **
1.4 misho 1029: ** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]]
1030: ** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This
1031: ** opcode causes the xFileControl method to swap the file handle with the one
1032: ** pointed to by the pArg argument. This capability is used during testing
1033: ** and only needs to be supported when SQLITE_TEST is defined.
1034: **
1035: ** <li>[[SQLITE_FCNTL_WAL_BLOCK]]
1036: ** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might
1037: ** be advantageous to block on the next WAL lock if the lock is not immediately
1038: ** available. The WAL subsystem issues this signal during rare
1039: ** circumstances in order to fix a problem with priority inversion.
1040: ** Applications should <em>not</em> use this file-control.
1041: **
1042: ** <li>[[SQLITE_FCNTL_ZIPVFS]]
1043: ** The [SQLITE_FCNTL_ZIPVFS] opcode is implemented by zipvfs only. All other
1044: ** VFS should return SQLITE_NOTFOUND for this opcode.
1045: **
1046: ** <li>[[SQLITE_FCNTL_RBU]]
1047: ** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by
1048: ** the RBU extension only. All other VFS should return SQLITE_NOTFOUND for
1049: ** this opcode.
1.4.2.2 ! misho 1050: **
! 1051: ** <li>[[SQLITE_FCNTL_BEGIN_ATOMIC_WRITE]]
! 1052: ** If the [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] opcode returns SQLITE_OK, then
! 1053: ** the file descriptor is placed in "batch write mode", which
! 1054: ** means all subsequent write operations will be deferred and done
! 1055: ** atomically at the next [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]. Systems
! 1056: ** that do not support batch atomic writes will return SQLITE_NOTFOUND.
! 1057: ** ^Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to
! 1058: ** the closing [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] or
! 1059: ** [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE], SQLite will make
! 1060: ** no VFS interface calls on the same [sqlite3_file] file descriptor
! 1061: ** except for calls to the xWrite method and the xFileControl method
! 1062: ** with [SQLITE_FCNTL_SIZE_HINT].
! 1063: **
! 1064: ** <li>[[SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]]
! 1065: ** The [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] opcode causes all write
! 1066: ** operations since the previous successful call to
! 1067: ** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be performed atomically.
! 1068: ** This file control returns [SQLITE_OK] if and only if the writes were
! 1069: ** all performed successfully and have been committed to persistent storage.
! 1070: ** ^Regardless of whether or not it is successful, this file control takes
! 1071: ** the file descriptor out of batch write mode so that all subsequent
! 1072: ** write operations are independent.
! 1073: ** ^SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without
! 1074: ** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
! 1075: **
! 1076: ** <li>[[SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE]]
! 1077: ** The [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE] opcode causes all write
! 1078: ** operations since the previous successful call to
! 1079: ** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be rolled back.
! 1080: ** ^This file control takes the file descriptor out of batch write mode
! 1081: ** so that all subsequent write operations are independent.
! 1082: ** ^SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without
! 1083: ** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
! 1084: **
! 1085: ** <li>[[SQLITE_FCNTL_LOCK_TIMEOUT]]
! 1086: ** The [SQLITE_FCNTL_LOCK_TIMEOUT] opcode causes attempts to obtain
! 1087: ** a file lock using the xLock or xShmLock methods of the VFS to wait
! 1088: ** for up to M milliseconds before failing, where M is the single
! 1089: ** unsigned integer parameter.
! 1090: **
! 1091: ** <li>[[SQLITE_FCNTL_DATA_VERSION]]
! 1092: ** The [SQLITE_FCNTL_DATA_VERSION] opcode is used to detect changes to
! 1093: ** a database file. The argument is a pointer to a 32-bit unsigned integer.
! 1094: ** The "data version" for the pager is written into the pointer. The
! 1095: ** "data version" changes whenever any change occurs to the corresponding
! 1096: ** database file, either through SQL statements on the same database
! 1097: ** connection or through transactions committed by separate database
! 1098: ** connections possibly in other processes. The [sqlite3_total_changes()]
! 1099: ** interface can be used to find if any database on the connection has changed,
! 1100: ** but that interface responds to changes on TEMP as well as MAIN and does
! 1101: ** not provide a mechanism to detect changes to MAIN only. Also, the
! 1102: ** [sqlite3_total_changes()] interface responds to internal changes only and
! 1103: ** omits changes made by other database connections. The
! 1104: ** [PRAGMA data_version] command provide a mechanism to detect changes to
! 1105: ** a single attached database that occur due to other database connections,
! 1106: ** but omits changes implemented by the database connection on which it is
! 1107: ** called. This file control is the only mechanism to detect changes that
! 1108: ** happen either internally or externally and that are associated with
! 1109: ** a particular attached database.
1.3 misho 1110: ** </ul>
1.2 misho 1111: */
1112: #define SQLITE_FCNTL_LOCKSTATE 1
1.4 misho 1113: #define SQLITE_FCNTL_GET_LOCKPROXYFILE 2
1114: #define SQLITE_FCNTL_SET_LOCKPROXYFILE 3
1115: #define SQLITE_FCNTL_LAST_ERRNO 4
1.2 misho 1116: #define SQLITE_FCNTL_SIZE_HINT 5
1117: #define SQLITE_FCNTL_CHUNK_SIZE 6
1118: #define SQLITE_FCNTL_FILE_POINTER 7
1119: #define SQLITE_FCNTL_SYNC_OMITTED 8
1120: #define SQLITE_FCNTL_WIN32_AV_RETRY 9
1121: #define SQLITE_FCNTL_PERSIST_WAL 10
1122: #define SQLITE_FCNTL_OVERWRITE 11
1123: #define SQLITE_FCNTL_VFSNAME 12
1124: #define SQLITE_FCNTL_POWERSAFE_OVERWRITE 13
1.3 misho 1125: #define SQLITE_FCNTL_PRAGMA 14
1126: #define SQLITE_FCNTL_BUSYHANDLER 15
1127: #define SQLITE_FCNTL_TEMPFILENAME 16
1.4 misho 1128: #define SQLITE_FCNTL_MMAP_SIZE 18
1129: #define SQLITE_FCNTL_TRACE 19
1130: #define SQLITE_FCNTL_HAS_MOVED 20
1131: #define SQLITE_FCNTL_SYNC 21
1132: #define SQLITE_FCNTL_COMMIT_PHASETWO 22
1133: #define SQLITE_FCNTL_WIN32_SET_HANDLE 23
1134: #define SQLITE_FCNTL_WAL_BLOCK 24
1135: #define SQLITE_FCNTL_ZIPVFS 25
1136: #define SQLITE_FCNTL_RBU 26
1137: #define SQLITE_FCNTL_VFS_POINTER 27
1138: #define SQLITE_FCNTL_JOURNAL_POINTER 28
1.4.2.1 misho 1139: #define SQLITE_FCNTL_WIN32_GET_HANDLE 29
1140: #define SQLITE_FCNTL_PDB 30
1.4.2.2 ! misho 1141: #define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 31
! 1142: #define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE 32
! 1143: #define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE 33
! 1144: #define SQLITE_FCNTL_LOCK_TIMEOUT 34
! 1145: #define SQLITE_FCNTL_DATA_VERSION 35
! 1146: #define SQLITE_FCNTL_SIZE_LIMIT 36
1.4 misho 1147:
1148: /* deprecated names */
1149: #define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE
1150: #define SQLITE_SET_LOCKPROXYFILE SQLITE_FCNTL_SET_LOCKPROXYFILE
1151: #define SQLITE_LAST_ERRNO SQLITE_FCNTL_LAST_ERRNO
1152:
1.2 misho 1153:
1154: /*
1155: ** CAPI3REF: Mutex Handle
1156: **
1157: ** The mutex module within SQLite defines [sqlite3_mutex] to be an
1158: ** abstract type for a mutex object. The SQLite core never looks
1159: ** at the internal representation of an [sqlite3_mutex]. It only
1160: ** deals with pointers to the [sqlite3_mutex] object.
1161: **
1162: ** Mutexes are created using [sqlite3_mutex_alloc()].
1163: */
1164: typedef struct sqlite3_mutex sqlite3_mutex;
1165:
1166: /*
1.4 misho 1167: ** CAPI3REF: Loadable Extension Thunk
1168: **
1169: ** A pointer to the opaque sqlite3_api_routines structure is passed as
1170: ** the third parameter to entry points of [loadable extensions]. This
1171: ** structure must be typedefed in order to work around compiler warnings
1172: ** on some platforms.
1173: */
1174: typedef struct sqlite3_api_routines sqlite3_api_routines;
1175:
1176: /*
1.2 misho 1177: ** CAPI3REF: OS Interface Object
1178: **
1179: ** An instance of the sqlite3_vfs object defines the interface between
1180: ** the SQLite core and the underlying operating system. The "vfs"
1181: ** in the name of the object stands for "virtual file system". See
1182: ** the [VFS | VFS documentation] for further information.
1183: **
1.4.2.2 ! misho 1184: ** The VFS interface is sometimes extended by adding new methods onto
! 1185: ** the end. Each time such an extension occurs, the iVersion field
! 1186: ** is incremented. The iVersion value started out as 1 in
! 1187: ** SQLite [version 3.5.0] on [dateof:3.5.0], then increased to 2
! 1188: ** with SQLite [version 3.7.0] on [dateof:3.7.0], and then increased
! 1189: ** to 3 with SQLite [version 3.7.6] on [dateof:3.7.6]. Additional fields
! 1190: ** may be appended to the sqlite3_vfs object and the iVersion value
! 1191: ** may increase again in future versions of SQLite.
! 1192: ** Note that the structure
! 1193: ** of the sqlite3_vfs object changes in the transition from
! 1194: ** SQLite [version 3.5.9] to [version 3.6.0] on [dateof:3.6.0]
! 1195: ** and yet the iVersion field was not modified.
1.2 misho 1196: **
1197: ** The szOsFile field is the size of the subclassed [sqlite3_file]
1198: ** structure used by this VFS. mxPathname is the maximum length of
1199: ** a pathname in this VFS.
1200: **
1201: ** Registered sqlite3_vfs objects are kept on a linked list formed by
1202: ** the pNext pointer. The [sqlite3_vfs_register()]
1203: ** and [sqlite3_vfs_unregister()] interfaces manage this list
1204: ** in a thread-safe way. The [sqlite3_vfs_find()] interface
1205: ** searches the list. Neither the application code nor the VFS
1206: ** implementation should use the pNext pointer.
1207: **
1208: ** The pNext field is the only field in the sqlite3_vfs
1209: ** structure that SQLite will ever modify. SQLite will only access
1210: ** or modify this field while holding a particular static mutex.
1211: ** The application should never modify anything within the sqlite3_vfs
1212: ** object once the object has been registered.
1213: **
1214: ** The zName field holds the name of the VFS module. The name must
1215: ** be unique across all VFS modules.
1216: **
1217: ** [[sqlite3_vfs.xOpen]]
1218: ** ^SQLite guarantees that the zFilename parameter to xOpen
1219: ** is either a NULL pointer or string obtained
1220: ** from xFullPathname() with an optional suffix added.
1221: ** ^If a suffix is added to the zFilename parameter, it will
1222: ** consist of a single "-" character followed by no more than
1223: ** 11 alphanumeric and/or "-" characters.
1224: ** ^SQLite further guarantees that
1225: ** the string will be valid and unchanged until xClose() is
1226: ** called. Because of the previous sentence,
1227: ** the [sqlite3_file] can safely store a pointer to the
1228: ** filename if it needs to remember the filename for some reason.
1229: ** If the zFilename parameter to xOpen is a NULL pointer then xOpen
1230: ** must invent its own temporary name for the file. ^Whenever the
1231: ** xFilename parameter is NULL it will also be the case that the
1232: ** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
1233: **
1234: ** The flags argument to xOpen() includes all bits set in
1235: ** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()]
1236: ** or [sqlite3_open16()] is used, then flags includes at least
1237: ** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
1238: ** If xOpen() opens a file read-only then it sets *pOutFlags to
1239: ** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set.
1240: **
1241: ** ^(SQLite will also add one of the following flags to the xOpen()
1242: ** call, depending on the object being opened:
1243: **
1244: ** <ul>
1245: ** <li> [SQLITE_OPEN_MAIN_DB]
1246: ** <li> [SQLITE_OPEN_MAIN_JOURNAL]
1247: ** <li> [SQLITE_OPEN_TEMP_DB]
1248: ** <li> [SQLITE_OPEN_TEMP_JOURNAL]
1249: ** <li> [SQLITE_OPEN_TRANSIENT_DB]
1250: ** <li> [SQLITE_OPEN_SUBJOURNAL]
1251: ** <li> [SQLITE_OPEN_MASTER_JOURNAL]
1252: ** <li> [SQLITE_OPEN_WAL]
1253: ** </ul>)^
1254: **
1255: ** The file I/O implementation can use the object type flags to
1256: ** change the way it deals with files. For example, an application
1257: ** that does not care about crash recovery or rollback might make
1258: ** the open of a journal file a no-op. Writes to this journal would
1259: ** also be no-ops, and any attempt to read the journal would return
1260: ** SQLITE_IOERR. Or the implementation might recognize that a database
1261: ** file will be doing page-aligned sector reads and writes in a random
1262: ** order and set up its I/O subsystem accordingly.
1263: **
1264: ** SQLite might also add one of the following flags to the xOpen method:
1265: **
1266: ** <ul>
1267: ** <li> [SQLITE_OPEN_DELETEONCLOSE]
1268: ** <li> [SQLITE_OPEN_EXCLUSIVE]
1269: ** </ul>
1270: **
1271: ** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
1272: ** deleted when it is closed. ^The [SQLITE_OPEN_DELETEONCLOSE]
1273: ** will be set for TEMP databases and their journals, transient
1274: ** databases, and subjournals.
1275: **
1276: ** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
1277: ** with the [SQLITE_OPEN_CREATE] flag, which are both directly
1278: ** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
1279: ** API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the
1280: ** SQLITE_OPEN_CREATE, is used to indicate that file should always
1281: ** be created, and that it is an error if it already exists.
1282: ** It is <i>not</i> used to indicate the file should be opened
1283: ** for exclusive access.
1284: **
1285: ** ^At least szOsFile bytes of memory are allocated by SQLite
1286: ** to hold the [sqlite3_file] structure passed as the third
1287: ** argument to xOpen. The xOpen method does not have to
1288: ** allocate the structure; it should just fill it in. Note that
1289: ** the xOpen method must set the sqlite3_file.pMethods to either
1290: ** a valid [sqlite3_io_methods] object or to NULL. xOpen must do
1291: ** this even if the open fails. SQLite expects that the sqlite3_file.pMethods
1292: ** element will be valid after xOpen returns regardless of the success
1293: ** or failure of the xOpen call.
1294: **
1295: ** [[sqlite3_vfs.xAccess]]
1296: ** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
1297: ** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
1298: ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
1.4.2.2 ! misho 1299: ** to test whether a file is at least readable. The SQLITE_ACCESS_READ
! 1300: ** flag is never actually used and is not implemented in the built-in
! 1301: ** VFSes of SQLite. The file is named by the second argument and can be a
! 1302: ** directory. The xAccess method returns [SQLITE_OK] on success or some
! 1303: ** non-zero error code if there is an I/O error or if the name of
! 1304: ** the file given in the second argument is illegal. If SQLITE_OK
! 1305: ** is returned, then non-zero or zero is written into *pResOut to indicate
! 1306: ** whether or not the file is accessible.
1.2 misho 1307: **
1308: ** ^SQLite will always allocate at least mxPathname+1 bytes for the
1309: ** output buffer xFullPathname. The exact size of the output buffer
1310: ** is also passed as a parameter to both methods. If the output buffer
1311: ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
1312: ** handled as a fatal error by SQLite, vfs implementations should endeavor
1313: ** to prevent this by setting mxPathname to a sufficiently large value.
1314: **
1315: ** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
1316: ** interfaces are not strictly a part of the filesystem, but they are
1317: ** included in the VFS structure for completeness.
1318: ** The xRandomness() function attempts to return nBytes bytes
1319: ** of good-quality randomness into zOut. The return value is
1320: ** the actual number of bytes of randomness obtained.
1321: ** The xSleep() method causes the calling thread to sleep for at
1322: ** least the number of microseconds given. ^The xCurrentTime()
1323: ** method returns a Julian Day Number for the current date and time as
1324: ** a floating point value.
1325: ** ^The xCurrentTimeInt64() method returns, as an integer, the Julian
1326: ** Day Number multiplied by 86400000 (the number of milliseconds in
1327: ** a 24-hour day).
1328: ** ^SQLite will use the xCurrentTimeInt64() method to get the current
1329: ** date and time if that method is available (if iVersion is 2 or
1330: ** greater and the function pointer is not NULL) and will fall back
1331: ** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
1332: **
1333: ** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
1334: ** are not used by the SQLite core. These optional interfaces are provided
1335: ** by some VFSes to facilitate testing of the VFS code. By overriding
1336: ** system calls with functions under its control, a test program can
1337: ** simulate faults and error conditions that would otherwise be difficult
1338: ** or impossible to induce. The set of system calls that can be overridden
1339: ** varies from one VFS to another, and from one version of the same VFS to the
1340: ** next. Applications that use these interfaces must be prepared for any
1341: ** or all of these interfaces to be NULL or for their behavior to change
1342: ** from one release to the next. Applications must not attempt to access
1343: ** any of these methods if the iVersion of the VFS is less than 3.
1344: */
1345: typedef struct sqlite3_vfs sqlite3_vfs;
1346: typedef void (*sqlite3_syscall_ptr)(void);
1347: struct sqlite3_vfs {
1348: int iVersion; /* Structure version number (currently 3) */
1349: int szOsFile; /* Size of subclassed sqlite3_file */
1350: int mxPathname; /* Maximum file pathname length */
1351: sqlite3_vfs *pNext; /* Next registered VFS */
1352: const char *zName; /* Name of this virtual file system */
1353: void *pAppData; /* Pointer to application-specific data */
1354: int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
1355: int flags, int *pOutFlags);
1356: int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
1357: int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
1358: int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
1359: void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
1360: void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
1361: void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
1362: void (*xDlClose)(sqlite3_vfs*, void*);
1363: int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
1364: int (*xSleep)(sqlite3_vfs*, int microseconds);
1365: int (*xCurrentTime)(sqlite3_vfs*, double*);
1366: int (*xGetLastError)(sqlite3_vfs*, int, char *);
1367: /*
1368: ** The methods above are in version 1 of the sqlite_vfs object
1369: ** definition. Those that follow are added in version 2 or later
1370: */
1371: int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
1372: /*
1373: ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
1374: ** Those below are for version 3 and greater.
1375: */
1376: int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
1377: sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
1378: const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
1379: /*
1380: ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
1.4 misho 1381: ** New fields may be appended in future versions. The iVersion
1.2 misho 1382: ** value will increment whenever this happens.
1383: */
1384: };
1385:
1386: /*
1387: ** CAPI3REF: Flags for the xAccess VFS method
1388: **
1389: ** These integer constants can be used as the third parameter to
1390: ** the xAccess method of an [sqlite3_vfs] object. They determine
1391: ** what kind of permissions the xAccess method is looking for.
1392: ** With SQLITE_ACCESS_EXISTS, the xAccess method
1393: ** simply checks whether the file exists.
1394: ** With SQLITE_ACCESS_READWRITE, the xAccess method
1395: ** checks whether the named directory is both readable and writable
1396: ** (in other words, if files can be added, removed, and renamed within
1397: ** the directory).
1398: ** The SQLITE_ACCESS_READWRITE constant is currently used only by the
1399: ** [temp_store_directory pragma], though this could change in a future
1400: ** release of SQLite.
1401: ** With SQLITE_ACCESS_READ, the xAccess method
1402: ** checks whether the file is readable. The SQLITE_ACCESS_READ constant is
1403: ** currently unused, though it might be used in a future release of
1404: ** SQLite.
1405: */
1406: #define SQLITE_ACCESS_EXISTS 0
1407: #define SQLITE_ACCESS_READWRITE 1 /* Used by PRAGMA temp_store_directory */
1408: #define SQLITE_ACCESS_READ 2 /* Unused */
1409:
1410: /*
1411: ** CAPI3REF: Flags for the xShmLock VFS method
1412: **
1413: ** These integer constants define the various locking operations
1414: ** allowed by the xShmLock method of [sqlite3_io_methods]. The
1415: ** following are the only legal combinations of flags to the
1416: ** xShmLock method:
1417: **
1418: ** <ul>
1419: ** <li> SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
1420: ** <li> SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
1421: ** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
1422: ** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE
1423: ** </ul>
1424: **
1425: ** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
1.4 misho 1426: ** was given on the corresponding lock.
1.2 misho 1427: **
1428: ** The xShmLock method can transition between unlocked and SHARED or
1429: ** between unlocked and EXCLUSIVE. It cannot transition between SHARED
1430: ** and EXCLUSIVE.
1431: */
1432: #define SQLITE_SHM_UNLOCK 1
1433: #define SQLITE_SHM_LOCK 2
1434: #define SQLITE_SHM_SHARED 4
1435: #define SQLITE_SHM_EXCLUSIVE 8
1436:
1437: /*
1438: ** CAPI3REF: Maximum xShmLock index
1439: **
1440: ** The xShmLock method on [sqlite3_io_methods] may use values
1441: ** between 0 and this upper bound as its "offset" argument.
1442: ** The SQLite core will never attempt to acquire or release a
1443: ** lock outside of this range
1444: */
1445: #define SQLITE_SHM_NLOCK 8
1446:
1447:
1448: /*
1449: ** CAPI3REF: Initialize The SQLite Library
1450: **
1451: ** ^The sqlite3_initialize() routine initializes the
1452: ** SQLite library. ^The sqlite3_shutdown() routine
1453: ** deallocates any resources that were allocated by sqlite3_initialize().
1454: ** These routines are designed to aid in process initialization and
1455: ** shutdown on embedded systems. Workstation applications using
1456: ** SQLite normally do not need to invoke either of these routines.
1457: **
1458: ** A call to sqlite3_initialize() is an "effective" call if it is
1459: ** the first time sqlite3_initialize() is invoked during the lifetime of
1460: ** the process, or if it is the first time sqlite3_initialize() is invoked
1461: ** following a call to sqlite3_shutdown(). ^(Only an effective call
1462: ** of sqlite3_initialize() does any initialization. All other calls
1463: ** are harmless no-ops.)^
1464: **
1465: ** A call to sqlite3_shutdown() is an "effective" call if it is the first
1466: ** call to sqlite3_shutdown() since the last sqlite3_initialize(). ^(Only
1467: ** an effective call to sqlite3_shutdown() does any deinitialization.
1468: ** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
1469: **
1470: ** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
1471: ** is not. The sqlite3_shutdown() interface must only be called from a
1472: ** single thread. All open [database connections] must be closed and all
1473: ** other SQLite resources must be deallocated prior to invoking
1474: ** sqlite3_shutdown().
1475: **
1476: ** Among other things, ^sqlite3_initialize() will invoke
1477: ** sqlite3_os_init(). Similarly, ^sqlite3_shutdown()
1478: ** will invoke sqlite3_os_end().
1479: **
1480: ** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.
1481: ** ^If for some reason, sqlite3_initialize() is unable to initialize
1482: ** the library (perhaps it is unable to allocate a needed resource such
1483: ** as a mutex) it returns an [error code] other than [SQLITE_OK].
1484: **
1485: ** ^The sqlite3_initialize() routine is called internally by many other
1486: ** SQLite interfaces so that an application usually does not need to
1487: ** invoke sqlite3_initialize() directly. For example, [sqlite3_open()]
1488: ** calls sqlite3_initialize() so the SQLite library will be automatically
1489: ** initialized when [sqlite3_open()] is called if it has not be initialized
1490: ** already. ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
1491: ** compile-time option, then the automatic calls to sqlite3_initialize()
1492: ** are omitted and the application must call sqlite3_initialize() directly
1493: ** prior to using any other SQLite interface. For maximum portability,
1494: ** it is recommended that applications always invoke sqlite3_initialize()
1495: ** directly prior to using any other SQLite interface. Future releases
1496: ** of SQLite may require this. In other words, the behavior exhibited
1497: ** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
1498: ** default behavior in some future release of SQLite.
1499: **
1500: ** The sqlite3_os_init() routine does operating-system specific
1501: ** initialization of the SQLite library. The sqlite3_os_end()
1502: ** routine undoes the effect of sqlite3_os_init(). Typical tasks
1503: ** performed by these routines include allocation or deallocation
1504: ** of static resources, initialization of global variables,
1505: ** setting up a default [sqlite3_vfs] module, or setting up
1506: ** a default configuration using [sqlite3_config()].
1507: **
1508: ** The application should never invoke either sqlite3_os_init()
1509: ** or sqlite3_os_end() directly. The application should only invoke
1510: ** sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init()
1511: ** interface is called automatically by sqlite3_initialize() and
1512: ** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate
1513: ** implementations for sqlite3_os_init() and sqlite3_os_end()
1514: ** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
1515: ** When [custom builds | built for other platforms]
1516: ** (using the [SQLITE_OS_OTHER=1] compile-time
1517: ** option) the application must supply a suitable implementation for
1518: ** sqlite3_os_init() and sqlite3_os_end(). An application-supplied
1519: ** implementation of sqlite3_os_init() or sqlite3_os_end()
1520: ** must return [SQLITE_OK] on success and some other [error code] upon
1521: ** failure.
1522: */
1523: SQLITE_API int sqlite3_initialize(void);
1524: SQLITE_API int sqlite3_shutdown(void);
1525: SQLITE_API int sqlite3_os_init(void);
1526: SQLITE_API int sqlite3_os_end(void);
1527:
1528: /*
1529: ** CAPI3REF: Configuring The SQLite Library
1530: **
1531: ** The sqlite3_config() interface is used to make global configuration
1532: ** changes to SQLite in order to tune SQLite to the specific needs of
1533: ** the application. The default configuration is recommended for most
1534: ** applications and so this routine is usually not necessary. It is
1535: ** provided to support rare applications with unusual needs.
1536: **
1.4 misho 1537: ** <b>The sqlite3_config() interface is not threadsafe. The application
1538: ** must ensure that no other SQLite interfaces are invoked by other
1539: ** threads while sqlite3_config() is running.</b>
1540: **
1541: ** The sqlite3_config() interface
1.2 misho 1542: ** may only be invoked prior to library initialization using
1543: ** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
1544: ** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
1545: ** [sqlite3_shutdown()] then it will return SQLITE_MISUSE.
1546: ** Note, however, that ^sqlite3_config() can be called as part of the
1547: ** implementation of an application-defined [sqlite3_os_init()].
1548: **
1549: ** The first argument to sqlite3_config() is an integer
1550: ** [configuration option] that determines
1551: ** what property of SQLite is to be configured. Subsequent arguments
1552: ** vary depending on the [configuration option]
1553: ** in the first argument.
1554: **
1555: ** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
1556: ** ^If the option is unknown or SQLite is unable to set the option
1557: ** then this routine returns a non-zero [error code].
1558: */
1559: SQLITE_API int sqlite3_config(int, ...);
1560:
1561: /*
1562: ** CAPI3REF: Configure database connections
1.4 misho 1563: ** METHOD: sqlite3
1.2 misho 1564: **
1565: ** The sqlite3_db_config() interface is used to make configuration
1566: ** changes to a [database connection]. The interface is similar to
1567: ** [sqlite3_config()] except that the changes apply to a single
1568: ** [database connection] (specified in the first argument).
1569: **
1570: ** The second argument to sqlite3_db_config(D,V,...) is the
1571: ** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code
1572: ** that indicates what aspect of the [database connection] is being configured.
1573: ** Subsequent arguments vary depending on the configuration verb.
1574: **
1575: ** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
1576: ** the call is considered successful.
1577: */
1578: SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
1579:
1580: /*
1581: ** CAPI3REF: Memory Allocation Routines
1582: **
1583: ** An instance of this object defines the interface between SQLite
1584: ** and low-level memory allocation routines.
1585: **
1586: ** This object is used in only one place in the SQLite interface.
1587: ** A pointer to an instance of this object is the argument to
1588: ** [sqlite3_config()] when the configuration option is
1589: ** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].
1590: ** By creating an instance of this object
1591: ** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
1592: ** during configuration, an application can specify an alternative
1593: ** memory allocation subsystem for SQLite to use for all of its
1594: ** dynamic memory needs.
1595: **
1596: ** Note that SQLite comes with several [built-in memory allocators]
1597: ** that are perfectly adequate for the overwhelming majority of applications
1598: ** and that this object is only useful to a tiny minority of applications
1599: ** with specialized memory allocation requirements. This object is
1600: ** also used during testing of SQLite in order to specify an alternative
1601: ** memory allocator that simulates memory out-of-memory conditions in
1602: ** order to verify that SQLite recovers gracefully from such
1603: ** conditions.
1604: **
1605: ** The xMalloc, xRealloc, and xFree methods must work like the
1606: ** malloc(), realloc() and free() functions from the standard C library.
1607: ** ^SQLite guarantees that the second argument to
1608: ** xRealloc is always a value returned by a prior call to xRoundup.
1609: **
1610: ** xSize should return the allocated size of a memory allocation
1611: ** previously obtained from xMalloc or xRealloc. The allocated size
1612: ** is always at least as big as the requested size but may be larger.
1613: **
1614: ** The xRoundup method returns what would be the allocated size of
1615: ** a memory allocation given a particular requested size. Most memory
1616: ** allocators round up memory allocations at least to the next multiple
1617: ** of 8. Some allocators round up to a larger multiple or to a power of 2.
1618: ** Every memory allocation request coming in through [sqlite3_malloc()]
1619: ** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0,
1620: ** that causes the corresponding memory allocation to fail.
1621: **
1.4 misho 1622: ** The xInit method initializes the memory allocator. For example,
1.2 misho 1623: ** it might allocate any require mutexes or initialize internal data
1624: ** structures. The xShutdown method is invoked (indirectly) by
1625: ** [sqlite3_shutdown()] and should deallocate any resources acquired
1626: ** by xInit. The pAppData pointer is used as the only parameter to
1627: ** xInit and xShutdown.
1628: **
1629: ** SQLite holds the [SQLITE_MUTEX_STATIC_MASTER] mutex when it invokes
1630: ** the xInit method, so the xInit method need not be threadsafe. The
1631: ** xShutdown method is only called from [sqlite3_shutdown()] so it does
1632: ** not need to be threadsafe either. For all other methods, SQLite
1633: ** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the
1634: ** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
1635: ** it is by default) and so the methods are automatically serialized.
1636: ** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
1637: ** methods must be threadsafe or else make their own arrangements for
1638: ** serialization.
1639: **
1640: ** SQLite will never invoke xInit() more than once without an intervening
1641: ** call to xShutdown().
1642: */
1643: typedef struct sqlite3_mem_methods sqlite3_mem_methods;
1644: struct sqlite3_mem_methods {
1645: void *(*xMalloc)(int); /* Memory allocation function */
1646: void (*xFree)(void*); /* Free a prior allocation */
1647: void *(*xRealloc)(void*,int); /* Resize an allocation */
1648: int (*xSize)(void*); /* Return the size of an allocation */
1649: int (*xRoundup)(int); /* Round up request size to allocation size */
1650: int (*xInit)(void*); /* Initialize the memory allocator */
1651: void (*xShutdown)(void*); /* Deinitialize the memory allocator */
1652: void *pAppData; /* Argument to xInit() and xShutdown() */
1653: };
1654:
1655: /*
1656: ** CAPI3REF: Configuration Options
1657: ** KEYWORDS: {configuration option}
1658: **
1659: ** These constants are the available integer configuration options that
1660: ** can be passed as the first argument to the [sqlite3_config()] interface.
1661: **
1662: ** New configuration options may be added in future releases of SQLite.
1663: ** Existing configuration options might be discontinued. Applications
1664: ** should check the return code from [sqlite3_config()] to make sure that
1665: ** the call worked. The [sqlite3_config()] interface will return a
1666: ** non-zero [error code] if a discontinued or unsupported configuration option
1667: ** is invoked.
1668: **
1669: ** <dl>
1670: ** [[SQLITE_CONFIG_SINGLETHREAD]] <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
1671: ** <dd>There are no arguments to this option. ^This option sets the
1672: ** [threading mode] to Single-thread. In other words, it disables
1673: ** all mutexing and puts SQLite into a mode where it can only be used
1674: ** by a single thread. ^If SQLite is compiled with
1675: ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1676: ** it is not possible to change the [threading mode] from its default
1677: ** value of Single-thread and so [sqlite3_config()] will return
1678: ** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD
1679: ** configuration option.</dd>
1680: **
1681: ** [[SQLITE_CONFIG_MULTITHREAD]] <dt>SQLITE_CONFIG_MULTITHREAD</dt>
1682: ** <dd>There are no arguments to this option. ^This option sets the
1683: ** [threading mode] to Multi-thread. In other words, it disables
1684: ** mutexing on [database connection] and [prepared statement] objects.
1685: ** The application is responsible for serializing access to
1686: ** [database connections] and [prepared statements]. But other mutexes
1687: ** are enabled so that SQLite will be safe to use in a multi-threaded
1688: ** environment as long as no two threads attempt to use the same
1689: ** [database connection] at the same time. ^If SQLite is compiled with
1690: ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1691: ** it is not possible to set the Multi-thread [threading mode] and
1692: ** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1693: ** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>
1694: **
1695: ** [[SQLITE_CONFIG_SERIALIZED]] <dt>SQLITE_CONFIG_SERIALIZED</dt>
1696: ** <dd>There are no arguments to this option. ^This option sets the
1697: ** [threading mode] to Serialized. In other words, this option enables
1698: ** all mutexes including the recursive
1699: ** mutexes on [database connection] and [prepared statement] objects.
1700: ** In this mode (which is the default when SQLite is compiled with
1701: ** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
1702: ** to [database connections] and [prepared statements] so that the
1703: ** application is free to use the same [database connection] or the
1704: ** same [prepared statement] in different threads at the same time.
1705: ** ^If SQLite is compiled with
1706: ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1707: ** it is not possible to set the Serialized [threading mode] and
1708: ** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1709: ** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
1710: **
1711: ** [[SQLITE_CONFIG_MALLOC]] <dt>SQLITE_CONFIG_MALLOC</dt>
1.4 misho 1712: ** <dd> ^(The SQLITE_CONFIG_MALLOC option takes a single argument which is
1713: ** a pointer to an instance of the [sqlite3_mem_methods] structure.
1714: ** The argument specifies
1.2 misho 1715: ** alternative low-level memory allocation routines to be used in place of
1716: ** the memory allocation routines built into SQLite.)^ ^SQLite makes
1717: ** its own private copy of the content of the [sqlite3_mem_methods] structure
1718: ** before the [sqlite3_config()] call returns.</dd>
1719: **
1720: ** [[SQLITE_CONFIG_GETMALLOC]] <dt>SQLITE_CONFIG_GETMALLOC</dt>
1.4 misho 1721: ** <dd> ^(The SQLITE_CONFIG_GETMALLOC option takes a single argument which
1722: ** is a pointer to an instance of the [sqlite3_mem_methods] structure.
1723: ** The [sqlite3_mem_methods]
1.2 misho 1724: ** structure is filled with the currently defined memory allocation routines.)^
1725: ** This option can be used to overload the default memory allocation
1726: ** routines with a wrapper that simulations memory allocation failure or
1727: ** tracks memory usage, for example. </dd>
1728: **
1.4.2.2 ! misho 1729: ** [[SQLITE_CONFIG_SMALL_MALLOC]] <dt>SQLITE_CONFIG_SMALL_MALLOC</dt>
! 1730: ** <dd> ^The SQLITE_CONFIG_SMALL_MALLOC option takes single argument of
! 1731: ** type int, interpreted as a boolean, which if true provides a hint to
! 1732: ** SQLite that it should avoid large memory allocations if possible.
! 1733: ** SQLite will run faster if it is free to make large memory allocations,
! 1734: ** but some application might prefer to run slower in exchange for
! 1735: ** guarantees about memory fragmentation that are possible if large
! 1736: ** allocations are avoided. This hint is normally off.
! 1737: ** </dd>
! 1738: **
1.2 misho 1739: ** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
1.4 misho 1740: ** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
1741: ** interpreted as a boolean, which enables or disables the collection of
1742: ** memory allocation statistics. ^(When memory allocation statistics are
1743: ** disabled, the following SQLite interfaces become non-operational:
1.2 misho 1744: ** <ul>
1745: ** <li> [sqlite3_memory_used()]
1746: ** <li> [sqlite3_memory_highwater()]
1747: ** <li> [sqlite3_soft_heap_limit64()]
1.4 misho 1748: ** <li> [sqlite3_status64()]
1.2 misho 1749: ** </ul>)^
1750: ** ^Memory allocation statistics are enabled by default unless SQLite is
1751: ** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
1752: ** allocation statistics are disabled by default.
1753: ** </dd>
1754: **
1755: ** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>
1.4.2.2 ! misho 1756: ** <dd> The SQLITE_CONFIG_SCRATCH option is no longer used.
1.4 misho 1757: ** </dd>
1.2 misho 1758: **
1759: ** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
1.4 misho 1760: ** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
1761: ** that SQLite can use for the database page cache with the default page
1762: ** cache implementation.
1763: ** This configuration option is a no-op if an application-define page
1764: ** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2].
1765: ** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
1766: ** 8-byte aligned memory (pMem), the size of each page cache line (sz),
1767: ** and the number of cache lines (N).
1.2 misho 1768: ** The sz argument should be the size of the largest database page
1.4 misho 1769: ** (a power of two between 512 and 65536) plus some extra bytes for each
1770: ** page header. ^The number of extra bytes needed by the page header
1771: ** can be determined using [SQLITE_CONFIG_PCACHE_HDRSZ].
1772: ** ^It is harmless, apart from the wasted memory,
1773: ** for the sz parameter to be larger than necessary. The pMem
1774: ** argument must be either a NULL pointer or a pointer to an 8-byte
1775: ** aligned block of memory of at least sz*N bytes, otherwise
1776: ** subsequent behavior is undefined.
1777: ** ^When pMem is not NULL, SQLite will strive to use the memory provided
1778: ** to satisfy page cache needs, falling back to [sqlite3_malloc()] if
1779: ** a page cache line is larger than sz bytes or if all of the pMem buffer
1780: ** is exhausted.
1781: ** ^If pMem is NULL and N is non-zero, then each database connection
1782: ** does an initial bulk allocation for page cache memory
1783: ** from [sqlite3_malloc()] sufficient for N cache lines if N is positive or
1784: ** of -1024*N bytes if N is negative, . ^If additional
1785: ** page cache memory is needed beyond what is provided by the initial
1786: ** allocation, then SQLite goes to [sqlite3_malloc()] separately for each
1787: ** additional cache line. </dd>
1.2 misho 1788: **
1789: ** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
1.4 misho 1790: ** <dd> ^The SQLITE_CONFIG_HEAP option specifies a static memory buffer
1791: ** that SQLite will use for all of its dynamic memory allocation needs
1.4.2.2 ! misho 1792: ** beyond those provided for by [SQLITE_CONFIG_PAGECACHE].
1.4 misho 1793: ** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
1794: ** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns
1795: ** [SQLITE_ERROR] if invoked otherwise.
1796: ** ^There are three arguments to SQLITE_CONFIG_HEAP:
1797: ** An 8-byte aligned pointer to the memory,
1.2 misho 1798: ** the number of bytes in the memory buffer, and the minimum allocation size.
1799: ** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
1800: ** to using its default memory allocator (the system malloc() implementation),
1801: ** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. ^If the
1.4 misho 1802: ** memory pointer is not NULL then the alternative memory
1.2 misho 1803: ** allocator is engaged to handle all of SQLites memory allocation needs.
1804: ** The first pointer (the memory pointer) must be aligned to an 8-byte
1805: ** boundary or subsequent behavior of SQLite will be undefined.
1806: ** The minimum allocation size is capped at 2**12. Reasonable values
1807: ** for the minimum allocation size are 2**5 through 2**8.</dd>
1808: **
1809: ** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>
1.4 misho 1810: ** <dd> ^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a
1811: ** pointer to an instance of the [sqlite3_mutex_methods] structure.
1812: ** The argument specifies alternative low-level mutex routines to be used
1813: ** in place the mutex routines built into SQLite.)^ ^SQLite makes a copy of
1814: ** the content of the [sqlite3_mutex_methods] structure before the call to
1.2 misho 1815: ** [sqlite3_config()] returns. ^If SQLite is compiled with
1816: ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1817: ** the entire mutexing subsystem is omitted from the build and hence calls to
1818: ** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
1819: ** return [SQLITE_ERROR].</dd>
1820: **
1821: ** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>
1.4 misho 1822: ** <dd> ^(The SQLITE_CONFIG_GETMUTEX option takes a single argument which
1823: ** is a pointer to an instance of the [sqlite3_mutex_methods] structure. The
1.2 misho 1824: ** [sqlite3_mutex_methods]
1825: ** structure is filled with the currently defined mutex routines.)^
1826: ** This option can be used to overload the default mutex allocation
1827: ** routines with a wrapper used to track mutex usage for performance
1828: ** profiling or testing, for example. ^If SQLite is compiled with
1829: ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1830: ** the entire mutexing subsystem is omitted from the build and hence calls to
1831: ** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
1832: ** return [SQLITE_ERROR].</dd>
1833: **
1834: ** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt>
1.4 misho 1835: ** <dd> ^(The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine
1836: ** the default size of lookaside memory on each [database connection].
1837: ** The first argument is the
1.2 misho 1838: ** size of each lookaside buffer slot and the second is the number of
1.4 misho 1839: ** slots allocated to each database connection.)^ ^(SQLITE_CONFIG_LOOKASIDE
1840: ** sets the <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
1841: ** option to [sqlite3_db_config()] can be used to change the lookaside
1.2 misho 1842: ** configuration on individual connections.)^ </dd>
1843: **
1844: ** [[SQLITE_CONFIG_PCACHE2]] <dt>SQLITE_CONFIG_PCACHE2</dt>
1.4 misho 1845: ** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
1846: ** a pointer to an [sqlite3_pcache_methods2] object. This object specifies
1847: ** the interface to a custom page cache implementation.)^
1848: ** ^SQLite makes a copy of the [sqlite3_pcache_methods2] object.</dd>
1.2 misho 1849: **
1850: ** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>
1.4 misho 1851: ** <dd> ^(The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
1852: ** is a pointer to an [sqlite3_pcache_methods2] object. SQLite copies of
1853: ** the current page cache implementation into that object.)^ </dd>
1.2 misho 1854: **
1855: ** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
1.4 misho 1856: ** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
1857: ** global [error log].
1858: ** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
1.2 misho 1859: ** function with a call signature of void(*)(void*,int,const char*),
1860: ** and a pointer to void. ^If the function pointer is not NULL, it is
1861: ** invoked by [sqlite3_log()] to process each logging event. ^If the
1862: ** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
1863: ** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
1864: ** passed through as the first parameter to the application-defined logger
1865: ** function whenever that function is invoked. ^The second parameter to
1866: ** the logger function is a copy of the first parameter to the corresponding
1867: ** [sqlite3_log()] call and is intended to be a [result code] or an
1868: ** [extended result code]. ^The third parameter passed to the logger is
1869: ** log message after formatting via [sqlite3_snprintf()].
1870: ** The SQLite logging interface is not reentrant; the logger function
1871: ** supplied by the application must not invoke any SQLite interface.
1872: ** In a multi-threaded application, the application-defined logger
1873: ** function must be threadsafe. </dd>
1874: **
1875: ** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
1.4 misho 1876: ** <dd>^(The SQLITE_CONFIG_URI option takes a single argument of type int.
1877: ** If non-zero, then URI handling is globally enabled. If the parameter is zero,
1878: ** then URI handling is globally disabled.)^ ^If URI handling is globally
1879: ** enabled, all filenames passed to [sqlite3_open()], [sqlite3_open_v2()],
1880: ** [sqlite3_open16()] or
1.2 misho 1881: ** specified as part of [ATTACH] commands are interpreted as URIs, regardless
1882: ** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
1.4 misho 1883: ** connection is opened. ^If it is globally disabled, filenames are
1.2 misho 1884: ** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
1.4 misho 1885: ** database connection is opened. ^(By default, URI handling is globally
1.2 misho 1886: ** disabled. The default value may be changed by compiling with the
1.4 misho 1887: ** [SQLITE_USE_URI] symbol defined.)^
1.2 misho 1888: **
1.3 misho 1889: ** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
1.4 misho 1890: ** <dd>^The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer
1891: ** argument which is interpreted as a boolean in order to enable or disable
1892: ** the use of covering indices for full table scans in the query optimizer.
1893: ** ^The default setting is determined
1.3 misho 1894: ** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
1895: ** if that compile-time option is omitted.
1896: ** The ability to disable the use of covering indices for full table scans
1897: ** is because some incorrectly coded legacy applications might malfunction
1.4 misho 1898: ** when the optimization is enabled. Providing the ability to
1.3 misho 1899: ** disable the optimization allows the older, buggy application code to work
1900: ** without change even with newer versions of SQLite.
1901: **
1.2 misho 1902: ** [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]]
1.3 misho 1903: ** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
1.2 misho 1904: ** <dd> These options are obsolete and should not be used by new code.
1905: ** They are retained for backwards compatibility but are now no-ops.
1.4 misho 1906: ** </dd>
1.3 misho 1907: **
1908: ** [[SQLITE_CONFIG_SQLLOG]]
1909: ** <dt>SQLITE_CONFIG_SQLLOG
1910: ** <dd>This option is only available if sqlite is compiled with the
1.4 misho 1911: ** [SQLITE_ENABLE_SQLLOG] pre-processor macro defined. The first argument should
1.3 misho 1912: ** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
1913: ** The second should be of type (void*). The callback is invoked by the library
1914: ** in three separate circumstances, identified by the value passed as the
1915: ** fourth parameter. If the fourth parameter is 0, then the database connection
1916: ** passed as the second argument has just been opened. The third argument
1917: ** points to a buffer containing the name of the main database file. If the
1918: ** fourth parameter is 1, then the SQL statement that the third parameter
1919: ** points to has just been executed. Or, if the fourth parameter is 2, then
1920: ** the connection being passed as the second parameter is being closed. The
1.4 misho 1921: ** third parameter is passed NULL In this case. An example of using this
1922: ** configuration option can be seen in the "test_sqllog.c" source file in
1923: ** the canonical SQLite source tree.</dd>
1924: **
1925: ** [[SQLITE_CONFIG_MMAP_SIZE]]
1926: ** <dt>SQLITE_CONFIG_MMAP_SIZE
1927: ** <dd>^SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
1928: ** that are the default mmap size limit (the default setting for
1929: ** [PRAGMA mmap_size]) and the maximum allowed mmap size limit.
1930: ** ^The default setting can be overridden by each database connection using
1931: ** either the [PRAGMA mmap_size] command, or by using the
1932: ** [SQLITE_FCNTL_MMAP_SIZE] file control. ^(The maximum allowed mmap size
1933: ** will be silently truncated if necessary so that it does not exceed the
1934: ** compile-time maximum mmap size set by the
1935: ** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
1936: ** ^If either argument to this option is negative, then that argument is
1937: ** changed to its compile-time default.
1938: **
1939: ** [[SQLITE_CONFIG_WIN32_HEAPSIZE]]
1940: ** <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
1941: ** <dd>^The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
1942: ** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro
1943: ** defined. ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
1944: ** that specifies the maximum size of the created heap.
1945: **
1946: ** [[SQLITE_CONFIG_PCACHE_HDRSZ]]
1947: ** <dt>SQLITE_CONFIG_PCACHE_HDRSZ
1948: ** <dd>^The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
1949: ** is a pointer to an integer and writes into that integer the number of extra
1950: ** bytes per page required for each page in [SQLITE_CONFIG_PAGECACHE].
1951: ** The amount of extra space required can change depending on the compiler,
1952: ** target platform, and SQLite version.
1953: **
1954: ** [[SQLITE_CONFIG_PMASZ]]
1955: ** <dt>SQLITE_CONFIG_PMASZ
1956: ** <dd>^The SQLITE_CONFIG_PMASZ option takes a single parameter which
1957: ** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
1958: ** sorter to that integer. The default minimum PMA Size is set by the
1959: ** [SQLITE_SORTER_PMASZ] compile-time option. New threads are launched
1960: ** to help with sort operations when multithreaded sorting
1961: ** is enabled (using the [PRAGMA threads] command) and the amount of content
1962: ** to be sorted exceeds the page size times the minimum of the
1963: ** [PRAGMA cache_size] setting and this value.
1964: **
1965: ** [[SQLITE_CONFIG_STMTJRNL_SPILL]]
1966: ** <dt>SQLITE_CONFIG_STMTJRNL_SPILL
1967: ** <dd>^The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which
1968: ** becomes the [statement journal] spill-to-disk threshold.
1969: ** [Statement journals] are held in memory until their size (in bytes)
1970: ** exceeds this threshold, at which point they are written to disk.
1971: ** Or if the threshold is -1, statement journals are always held
1972: ** exclusively in memory.
1973: ** Since many statement journals never become large, setting the spill
1974: ** threshold to a value such as 64KiB can greatly reduce the amount of
1975: ** I/O required to support statement rollback.
1976: ** The default value for this setting is controlled by the
1977: ** [SQLITE_STMTJRNL_SPILL] compile-time option.
1.4.2.2 ! misho 1978: **
! 1979: ** [[SQLITE_CONFIG_SORTERREF_SIZE]]
! 1980: ** <dt>SQLITE_CONFIG_SORTERREF_SIZE
! 1981: ** <dd>The SQLITE_CONFIG_SORTERREF_SIZE option accepts a single parameter
! 1982: ** of type (int) - the new value of the sorter-reference size threshold.
! 1983: ** Usually, when SQLite uses an external sort to order records according
! 1984: ** to an ORDER BY clause, all fields required by the caller are present in the
! 1985: ** sorted records. However, if SQLite determines based on the declared type
! 1986: ** of a table column that its values are likely to be very large - larger
! 1987: ** than the configured sorter-reference size threshold - then a reference
! 1988: ** is stored in each sorted record and the required column values loaded
! 1989: ** from the database as records are returned in sorted order. The default
! 1990: ** value for this option is to never use this optimization. Specifying a
! 1991: ** negative value for this option restores the default behaviour.
! 1992: ** This option is only available if SQLite is compiled with the
! 1993: ** [SQLITE_ENABLE_SORTER_REFERENCES] compile-time option.
! 1994: **
! 1995: ** [[SQLITE_CONFIG_MEMDB_MAXSIZE]]
! 1996: ** <dt>SQLITE_CONFIG_MEMDB_MAXSIZE
! 1997: ** <dd>The SQLITE_CONFIG_MEMDB_MAXSIZE option accepts a single parameter
! 1998: ** [sqlite3_int64] parameter which is the default maximum size for an in-memory
! 1999: ** database created using [sqlite3_deserialize()]. This default maximum
! 2000: ** size can be adjusted up or down for individual databases using the
! 2001: ** [SQLITE_FCNTL_SIZE_LIMIT] [sqlite3_file_control|file-control]. If this
! 2002: ** configuration setting is never used, then the default maximum is determined
! 2003: ** by the [SQLITE_MEMDB_DEFAULT_MAXSIZE] compile-time option. If that
! 2004: ** compile-time option is not set, then the default maximum is 1073741824.
1.3 misho 2005: ** </dl>
1.2 misho 2006: */
2007: #define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
2008: #define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
2009: #define SQLITE_CONFIG_SERIALIZED 3 /* nil */
2010: #define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
2011: #define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
1.4.2.2 ! misho 2012: #define SQLITE_CONFIG_SCRATCH 6 /* No longer used */
1.2 misho 2013: #define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
2014: #define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
2015: #define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
2016: #define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
2017: #define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
2018: /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
2019: #define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
2020: #define SQLITE_CONFIG_PCACHE 14 /* no-op */
2021: #define SQLITE_CONFIG_GETPCACHE 15 /* no-op */
2022: #define SQLITE_CONFIG_LOG 16 /* xFunc, void* */
2023: #define SQLITE_CONFIG_URI 17 /* int */
2024: #define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */
2025: #define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */
1.3 misho 2026: #define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */
2027: #define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */
1.4 misho 2028: #define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */
2029: #define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */
2030: #define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */
2031: #define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */
2032: #define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */
1.4.2.2 ! misho 2033: #define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */
! 2034: #define SQLITE_CONFIG_SORTERREF_SIZE 28 /* int nByte */
! 2035: #define SQLITE_CONFIG_MEMDB_MAXSIZE 29 /* sqlite3_int64 */
1.2 misho 2036:
2037: /*
2038: ** CAPI3REF: Database Connection Configuration Options
2039: **
2040: ** These constants are the available integer configuration options that
2041: ** can be passed as the second argument to the [sqlite3_db_config()] interface.
2042: **
2043: ** New configuration options may be added in future releases of SQLite.
2044: ** Existing configuration options might be discontinued. Applications
2045: ** should check the return code from [sqlite3_db_config()] to make sure that
2046: ** the call worked. ^The [sqlite3_db_config()] interface will return a
2047: ** non-zero [error code] if a discontinued or unsupported configuration option
2048: ** is invoked.
2049: **
2050: ** <dl>
1.4.2.2 ! misho 2051: ** [[SQLITE_DBCONFIG_LOOKASIDE]]
1.2 misho 2052: ** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
2053: ** <dd> ^This option takes three additional arguments that determine the
2054: ** [lookaside memory allocator] configuration for the [database connection].
2055: ** ^The first argument (the third parameter to [sqlite3_db_config()] is a
2056: ** pointer to a memory buffer to use for lookaside memory.
2057: ** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
2058: ** may be NULL in which case SQLite will allocate the
2059: ** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
2060: ** size of each lookaside buffer slot. ^The third argument is the number of
2061: ** slots. The size of the buffer in the first argument must be greater than
2062: ** or equal to the product of the second and third arguments. The buffer
2063: ** must be aligned to an 8-byte boundary. ^If the second argument to
2064: ** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
2065: ** rounded down to the next smaller multiple of 8. ^(The lookaside memory
2066: ** configuration for a database connection can only be changed when that
2067: ** connection is not currently using lookaside memory, or in other words
2068: ** when the "current value" returned by
2069: ** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero.
2070: ** Any attempt to change the lookaside memory configuration when lookaside
2071: ** memory is in use leaves the configuration unchanged and returns
2072: ** [SQLITE_BUSY].)^</dd>
2073: **
1.4.2.2 ! misho 2074: ** [[SQLITE_DBCONFIG_ENABLE_FKEY]]
1.2 misho 2075: ** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>
2076: ** <dd> ^This option is used to enable or disable the enforcement of
2077: ** [foreign key constraints]. There should be two additional arguments.
2078: ** The first argument is an integer which is 0 to disable FK enforcement,
2079: ** positive to enable FK enforcement or negative to leave FK enforcement
2080: ** unchanged. The second parameter is a pointer to an integer into which
2081: ** is written 0 or 1 to indicate whether FK enforcement is off or on
2082: ** following this call. The second parameter may be a NULL pointer, in
2083: ** which case the FK enforcement setting is not reported back. </dd>
2084: **
1.4.2.2 ! misho 2085: ** [[SQLITE_DBCONFIG_ENABLE_TRIGGER]]
1.2 misho 2086: ** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>
2087: ** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
2088: ** There should be two additional arguments.
2089: ** The first argument is an integer which is 0 to disable triggers,
2090: ** positive to enable triggers or negative to leave the setting unchanged.
2091: ** The second parameter is a pointer to an integer into which
2092: ** is written 0 or 1 to indicate whether triggers are disabled or enabled
2093: ** following this call. The second parameter may be a NULL pointer, in
2094: ** which case the trigger setting is not reported back. </dd>
2095: **
1.4.2.2 ! misho 2096: ** [[SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER]]
1.4 misho 2097: ** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt>
1.4.2.2 ! misho 2098: ** <dd> ^This option is used to enable or disable the
! 2099: ** [fts3_tokenizer()] function which is part of the
1.4 misho 2100: ** [FTS3] full-text search engine extension.
2101: ** There should be two additional arguments.
2102: ** The first argument is an integer which is 0 to disable fts3_tokenizer() or
2103: ** positive to enable fts3_tokenizer() or negative to leave the setting
2104: ** unchanged.
2105: ** The second parameter is a pointer to an integer into which
2106: ** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled
2107: ** following this call. The second parameter may be a NULL pointer, in
2108: ** which case the new setting is not reported back. </dd>
2109: **
1.4.2.2 ! misho 2110: ** [[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION]]
1.4 misho 2111: ** <dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt>
2112: ** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()]
2113: ** interface independently of the [load_extension()] SQL function.
2114: ** The [sqlite3_enable_load_extension()] API enables or disables both the
2115: ** C-API [sqlite3_load_extension()] and the SQL function [load_extension()].
2116: ** There should be two additional arguments.
2117: ** When the first argument to this interface is 1, then only the C-API is
2118: ** enabled and the SQL function remains disabled. If the first argument to
2119: ** this interface is 0, then both the C-API and the SQL function are disabled.
2120: ** If the first argument is -1, then no changes are made to state of either the
2121: ** C-API or the SQL function.
2122: ** The second parameter is a pointer to an integer into which
2123: ** is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface
2124: ** is disabled or enabled following this call. The second parameter may
2125: ** be a NULL pointer, in which case the new setting is not reported back.
2126: ** </dd>
2127: **
1.4.2.2 ! misho 2128: ** [[SQLITE_DBCONFIG_MAINDBNAME]] <dt>SQLITE_DBCONFIG_MAINDBNAME</dt>
1.4.2.1 misho 2129: ** <dd> ^This option is used to change the name of the "main" database
2130: ** schema. ^The sole argument is a pointer to a constant UTF8 string
2131: ** which will become the new schema name in place of "main". ^SQLite
2132: ** does not make a copy of the new main schema name string, so the application
2133: ** must ensure that the argument passed into this DBCONFIG option is unchanged
2134: ** until after the database connection closes.
2135: ** </dd>
2136: **
1.4.2.2 ! misho 2137: ** [[SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE]]
1.4.2.1 misho 2138: ** <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt>
2139: ** <dd> Usually, when a database in wal mode is closed or detached from a
2140: ** database handle, SQLite checks if this will mean that there are now no
2141: ** connections at all to the database. If so, it performs a checkpoint
2142: ** operation before closing the connection. This option may be used to
2143: ** override this behaviour. The first parameter passed to this operation
1.4.2.2 ! misho 2144: ** is an integer - positive to disable checkpoints-on-close, or zero (the
! 2145: ** default) to enable them, and negative to leave the setting unchanged.
! 2146: ** The second parameter is a pointer to an integer
1.4.2.1 misho 2147: ** into which is written 0 or 1 to indicate whether checkpoints-on-close
2148: ** have been disabled - 0 if they are not disabled, 1 if they are.
2149: ** </dd>
2150: **
1.4.2.2 ! misho 2151: ** [[SQLITE_DBCONFIG_ENABLE_QPSG]] <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt>
! 2152: ** <dd>^(The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates
! 2153: ** the [query planner stability guarantee] (QPSG). When the QPSG is active,
! 2154: ** a single SQL query statement will always use the same algorithm regardless
! 2155: ** of values of [bound parameters].)^ The QPSG disables some query optimizations
! 2156: ** that look at the values of bound parameters, which can make some queries
! 2157: ** slower. But the QPSG has the advantage of more predictable behavior. With
! 2158: ** the QPSG active, SQLite will always use the same query plan in the field as
! 2159: ** was used during testing in the lab.
! 2160: ** The first argument to this setting is an integer which is 0 to disable
! 2161: ** the QPSG, positive to enable QPSG, or negative to leave the setting
! 2162: ** unchanged. The second parameter is a pointer to an integer into which
! 2163: ** is written 0 or 1 to indicate whether the QPSG is disabled or enabled
! 2164: ** following this call.
! 2165: ** </dd>
! 2166: **
! 2167: ** [[SQLITE_DBCONFIG_TRIGGER_EQP]] <dt>SQLITE_DBCONFIG_TRIGGER_EQP</dt>
! 2168: ** <dd> By default, the output of EXPLAIN QUERY PLAN commands does not
! 2169: ** include output for any operations performed by trigger programs. This
! 2170: ** option is used to set or clear (the default) a flag that governs this
! 2171: ** behavior. The first parameter passed to this operation is an integer -
! 2172: ** positive to enable output for trigger programs, or zero to disable it,
! 2173: ** or negative to leave the setting unchanged.
! 2174: ** The second parameter is a pointer to an integer into which is written
! 2175: ** 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if
! 2176: ** it is not disabled, 1 if it is.
! 2177: ** </dd>
! 2178: **
! 2179: ** [[SQLITE_DBCONFIG_RESET_DATABASE]] <dt>SQLITE_DBCONFIG_RESET_DATABASE</dt>
! 2180: ** <dd> Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run
! 2181: ** [VACUUM] in order to reset a database back to an empty database
! 2182: ** with no schema and no content. The following process works even for
! 2183: ** a badly corrupted database file:
! 2184: ** <ol>
! 2185: ** <li> If the database connection is newly opened, make sure it has read the
! 2186: ** database schema by preparing then discarding some query against the
! 2187: ** database, or calling sqlite3_table_column_metadata(), ignoring any
! 2188: ** errors. This step is only necessary if the application desires to keep
! 2189: ** the database in WAL mode after the reset if it was in WAL mode before
! 2190: ** the reset.
! 2191: ** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0);
! 2192: ** <li> [sqlite3_exec](db, "[VACUUM]", 0, 0, 0);
! 2193: ** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0);
! 2194: ** </ol>
! 2195: ** Because resetting a database is destructive and irreversible, the
! 2196: ** process requires the use of this obscure API and multiple steps to help
! 2197: ** ensure that it does not happen by accident.
! 2198: **
! 2199: ** [[SQLITE_DBCONFIG_DEFENSIVE]] <dt>SQLITE_DBCONFIG_DEFENSIVE</dt>
! 2200: ** <dd>The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the
! 2201: ** "defensive" flag for a database connection. When the defensive
! 2202: ** flag is enabled, language features that allow ordinary SQL to
! 2203: ** deliberately corrupt the database file are disabled. The disabled
! 2204: ** features include but are not limited to the following:
! 2205: ** <ul>
! 2206: ** <li> The [PRAGMA writable_schema=ON] statement.
! 2207: ** <li> The [PRAGMA journal_mode=OFF] statement.
! 2208: ** <li> Writes to the [sqlite_dbpage] virtual table.
! 2209: ** <li> Direct writes to [shadow tables].
! 2210: ** </ul>
! 2211: ** </dd>
! 2212: **
! 2213: ** [[SQLITE_DBCONFIG_WRITABLE_SCHEMA]] <dt>SQLITE_DBCONFIG_WRITABLE_SCHEMA</dt>
! 2214: ** <dd>The SQLITE_DBCONFIG_WRITABLE_SCHEMA option activates or deactivates the
! 2215: ** "writable_schema" flag. This has the same effect and is logically equivalent
! 2216: ** to setting [PRAGMA writable_schema=ON] or [PRAGMA writable_schema=OFF].
! 2217: ** The first argument to this setting is an integer which is 0 to disable
! 2218: ** the writable_schema, positive to enable writable_schema, or negative to
! 2219: ** leave the setting unchanged. The second parameter is a pointer to an
! 2220: ** integer into which is written 0 or 1 to indicate whether the writable_schema
! 2221: ** is enabled or disabled following this call.
! 2222: ** </dd>
! 2223: **
! 2224: ** [[SQLITE_DBCONFIG_LEGACY_ALTER_TABLE]]
! 2225: ** <dt>SQLITE_DBCONFIG_LEGACY_ALTER_TABLE</dt>
! 2226: ** <dd>The SQLITE_DBCONFIG_LEGACY_ALTER_TABLE option activates or deactivates
! 2227: ** the legacy behavior of the [ALTER TABLE RENAME] command such it
! 2228: ** behaves as it did prior to [version 3.24.0] (2018-06-04). See the
! 2229: ** "Compatibility Notice" on the [ALTER TABLE RENAME documentation] for
! 2230: ** additional information. This feature can also be turned on and off
! 2231: ** using the [PRAGMA legacy_alter_table] statement.
! 2232: ** </dd>
! 2233: **
! 2234: ** [[SQLITE_DBCONFIG_DQS_DML]]
! 2235: ** <dt>SQLITE_DBCONFIG_DQS_DML</td>
! 2236: ** <dd>The SQLITE_DBCONFIG_DQS_DML option activates or deactivates
! 2237: ** the legacy [double-quoted string literal] misfeature for DML statement
! 2238: ** only, that is DELETE, INSERT, SELECT, and UPDATE statements. The
! 2239: ** default value of this setting is determined by the [-DSQLITE_DQS]
! 2240: ** compile-time option.
! 2241: ** </dd>
! 2242: **
! 2243: ** [[SQLITE_DBCONFIG_DQS_DDL]]
! 2244: ** <dt>SQLITE_DBCONFIG_DQS_DDL</td>
! 2245: ** <dd>The SQLITE_DBCONFIG_DQS option activates or deactivates
! 2246: ** the legacy [double-quoted string literal] misfeature for DDL statements,
! 2247: ** such as CREATE TABLE and CREATE INDEX. The
! 2248: ** default value of this setting is determined by the [-DSQLITE_DQS]
! 2249: ** compile-time option.
! 2250: ** </dd>
1.2 misho 2251: ** </dl>
2252: */
1.4.2.1 misho 2253: #define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */
1.4 misho 2254: #define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */
2255: #define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */
2256: #define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */
2257: #define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */
2258: #define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */
1.4.2.1 misho 2259: #define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */
1.4.2.2 ! misho 2260: #define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */
! 2261: #define SQLITE_DBCONFIG_TRIGGER_EQP 1008 /* int int* */
! 2262: #define SQLITE_DBCONFIG_RESET_DATABASE 1009 /* int int* */
! 2263: #define SQLITE_DBCONFIG_DEFENSIVE 1010 /* int int* */
! 2264: #define SQLITE_DBCONFIG_WRITABLE_SCHEMA 1011 /* int int* */
! 2265: #define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE 1012 /* int int* */
! 2266: #define SQLITE_DBCONFIG_DQS_DML 1013 /* int int* */
! 2267: #define SQLITE_DBCONFIG_DQS_DDL 1014 /* int int* */
! 2268: #define SQLITE_DBCONFIG_MAX 1014 /* Largest DBCONFIG */
1.2 misho 2269:
2270: /*
2271: ** CAPI3REF: Enable Or Disable Extended Result Codes
1.4 misho 2272: ** METHOD: sqlite3
1.2 misho 2273: **
2274: ** ^The sqlite3_extended_result_codes() routine enables or disables the
2275: ** [extended result codes] feature of SQLite. ^The extended result
2276: ** codes are disabled by default for historical compatibility.
2277: */
2278: SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
2279:
2280: /*
2281: ** CAPI3REF: Last Insert Rowid
1.4 misho 2282: ** METHOD: sqlite3
1.2 misho 2283: **
1.4 misho 2284: ** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables)
2285: ** has a unique 64-bit signed
1.2 misho 2286: ** integer key called the [ROWID | "rowid"]. ^The rowid is always available
2287: ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
2288: ** names are not also used by explicitly declared columns. ^If
2289: ** the table has a column of type [INTEGER PRIMARY KEY] then that column
2290: ** is another alias for the rowid.
2291: **
1.4.2.1 misho 2292: ** ^The sqlite3_last_insert_rowid(D) interface usually returns the [rowid] of
2293: ** the most recent successful [INSERT] into a rowid table or [virtual table]
2294: ** on database connection D. ^Inserts into [WITHOUT ROWID] tables are not
2295: ** recorded. ^If no successful [INSERT]s into rowid tables have ever occurred
2296: ** on the database connection D, then sqlite3_last_insert_rowid(D) returns
2297: ** zero.
2298: **
2299: ** As well as being set automatically as rows are inserted into database
2300: ** tables, the value returned by this function may be set explicitly by
2301: ** [sqlite3_set_last_insert_rowid()]
2302: **
2303: ** Some virtual table implementations may INSERT rows into rowid tables as
2304: ** part of committing a transaction (e.g. to flush data accumulated in memory
2305: ** to disk). In this case subsequent calls to this function return the rowid
2306: ** associated with these internal INSERT operations, which leads to
2307: ** unintuitive results. Virtual table implementations that do write to rowid
2308: ** tables in this way can avoid this problem by restoring the original
2309: ** rowid value using [sqlite3_set_last_insert_rowid()] before returning
2310: ** control to the user.
2311: **
2312: ** ^(If an [INSERT] occurs within a trigger then this routine will
2313: ** return the [rowid] of the inserted row as long as the trigger is
2314: ** running. Once the trigger program ends, the value returned
2315: ** by this routine reverts to what it was before the trigger was fired.)^
1.2 misho 2316: **
2317: ** ^An [INSERT] that fails due to a constraint violation is not a
2318: ** successful [INSERT] and does not change the value returned by this
2319: ** routine. ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
2320: ** and INSERT OR ABORT make no changes to the return value of this
2321: ** routine when their insertion fails. ^(When INSERT OR REPLACE
2322: ** encounters a constraint violation, it does not fail. The
2323: ** INSERT continues to completion after deleting rows that caused
2324: ** the constraint problem so INSERT OR REPLACE will always change
2325: ** the return value of this interface.)^
2326: **
2327: ** ^For the purposes of this routine, an [INSERT] is considered to
2328: ** be successful even if it is subsequently rolled back.
2329: **
2330: ** This function is accessible to SQL statements via the
2331: ** [last_insert_rowid() SQL function].
2332: **
2333: ** If a separate thread performs a new [INSERT] on the same
2334: ** database connection while the [sqlite3_last_insert_rowid()]
2335: ** function is running and thus changes the last insert [rowid],
2336: ** then the value returned by [sqlite3_last_insert_rowid()] is
2337: ** unpredictable and might not equal either the old or the new
2338: ** last insert [rowid].
2339: */
2340: SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
2341:
2342: /*
1.4.2.1 misho 2343: ** CAPI3REF: Set the Last Insert Rowid value.
2344: ** METHOD: sqlite3
2345: **
2346: ** The sqlite3_set_last_insert_rowid(D, R) method allows the application to
2347: ** set the value returned by calling sqlite3_last_insert_rowid(D) to R
2348: ** without inserting a row into the database.
2349: */
2350: SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
2351:
2352: /*
1.2 misho 2353: ** CAPI3REF: Count The Number Of Rows Modified
1.4 misho 2354: ** METHOD: sqlite3
1.2 misho 2355: **
1.4 misho 2356: ** ^This function returns the number of rows modified, inserted or
2357: ** deleted by the most recently completed INSERT, UPDATE or DELETE
2358: ** statement on the database connection specified by the only parameter.
2359: ** ^Executing any other type of SQL statement does not modify the value
2360: ** returned by this function.
2361: **
2362: ** ^Only changes made directly by the INSERT, UPDATE or DELETE statement are
2363: ** considered - auxiliary changes caused by [CREATE TRIGGER | triggers],
2364: ** [foreign key actions] or [REPLACE] constraint resolution are not counted.
2365: **
2366: ** Changes to a view that are intercepted by
2367: ** [INSTEAD OF trigger | INSTEAD OF triggers] are not counted. ^The value
2368: ** returned by sqlite3_changes() immediately after an INSERT, UPDATE or
2369: ** DELETE statement run on a view is always zero. Only changes made to real
2370: ** tables are counted.
2371: **
2372: ** Things are more complicated if the sqlite3_changes() function is
2373: ** executed while a trigger program is running. This may happen if the
2374: ** program uses the [changes() SQL function], or if some other callback
2375: ** function invokes sqlite3_changes() directly. Essentially:
2376: **
2377: ** <ul>
2378: ** <li> ^(Before entering a trigger program the value returned by
2379: ** sqlite3_changes() function is saved. After the trigger program
2380: ** has finished, the original value is restored.)^
2381: **
2382: ** <li> ^(Within a trigger program each INSERT, UPDATE and DELETE
2383: ** statement sets the value returned by sqlite3_changes()
2384: ** upon completion as normal. Of course, this value will not include
2385: ** any changes performed by sub-triggers, as the sqlite3_changes()
2386: ** value will be saved and restored after each sub-trigger has run.)^
2387: ** </ul>
2388: **
2389: ** ^This means that if the changes() SQL function (or similar) is used
2390: ** by the first INSERT, UPDATE or DELETE statement within a trigger, it
2391: ** returns the value as set when the calling statement began executing.
2392: ** ^If it is used by the second or subsequent such statement within a trigger
2393: ** program, the value returned reflects the number of rows modified by the
2394: ** previous INSERT, UPDATE or DELETE statement within the same trigger.
1.2 misho 2395: **
2396: ** If a separate thread makes changes on the same database connection
2397: ** while [sqlite3_changes()] is running then the value returned
2398: ** is unpredictable and not meaningful.
1.4.2.2 ! misho 2399: **
! 2400: ** See also:
! 2401: ** <ul>
! 2402: ** <li> the [sqlite3_total_changes()] interface
! 2403: ** <li> the [count_changes pragma]
! 2404: ** <li> the [changes() SQL function]
! 2405: ** <li> the [data_version pragma]
! 2406: ** </ul>
1.2 misho 2407: */
2408: SQLITE_API int sqlite3_changes(sqlite3*);
2409:
2410: /*
2411: ** CAPI3REF: Total Number Of Rows Modified
1.4 misho 2412: ** METHOD: sqlite3
1.2 misho 2413: **
1.4 misho 2414: ** ^This function returns the total number of rows inserted, modified or
2415: ** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed
2416: ** since the database connection was opened, including those executed as
2417: ** part of trigger programs. ^Executing any other type of SQL statement
2418: ** does not affect the value returned by sqlite3_total_changes().
2419: **
2420: ** ^Changes made as part of [foreign key actions] are included in the
2421: ** count, but those made as part of REPLACE constraint resolution are
2422: ** not. ^Changes to a view that are intercepted by INSTEAD OF triggers
2423: ** are not counted.
1.2 misho 2424: **
1.4.2.2 ! misho 2425: ** The [sqlite3_total_changes(D)] interface only reports the number
! 2426: ** of rows that changed due to SQL statement run against database
! 2427: ** connection D. Any changes by other database connections are ignored.
! 2428: ** To detect changes against a database file from other database
! 2429: ** connections use the [PRAGMA data_version] command or the
! 2430: ** [SQLITE_FCNTL_DATA_VERSION] [file control].
! 2431: **
1.2 misho 2432: ** If a separate thread makes changes on the same database connection
2433: ** while [sqlite3_total_changes()] is running then the value
2434: ** returned is unpredictable and not meaningful.
1.4.2.2 ! misho 2435: **
! 2436: ** See also:
! 2437: ** <ul>
! 2438: ** <li> the [sqlite3_changes()] interface
! 2439: ** <li> the [count_changes pragma]
! 2440: ** <li> the [changes() SQL function]
! 2441: ** <li> the [data_version pragma]
! 2442: ** <li> the [SQLITE_FCNTL_DATA_VERSION] [file control]
! 2443: ** </ul>
1.2 misho 2444: */
2445: SQLITE_API int sqlite3_total_changes(sqlite3*);
2446:
2447: /*
2448: ** CAPI3REF: Interrupt A Long-Running Query
1.4 misho 2449: ** METHOD: sqlite3
1.2 misho 2450: **
2451: ** ^This function causes any pending database operation to abort and
2452: ** return at its earliest opportunity. This routine is typically
2453: ** called in response to a user action such as pressing "Cancel"
2454: ** or Ctrl-C where the user wants a long query operation to halt
2455: ** immediately.
2456: **
2457: ** ^It is safe to call this routine from a thread different from the
2458: ** thread that is currently running the database operation. But it
2459: ** is not safe to call this routine with a [database connection] that
2460: ** is closed or might close before sqlite3_interrupt() returns.
2461: **
2462: ** ^If an SQL operation is very nearly finished at the time when
2463: ** sqlite3_interrupt() is called, then it might not have an opportunity
2464: ** to be interrupted and might continue to completion.
2465: **
2466: ** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
2467: ** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
2468: ** that is inside an explicit transaction, then the entire transaction
2469: ** will be rolled back automatically.
2470: **
2471: ** ^The sqlite3_interrupt(D) call is in effect until all currently running
2472: ** SQL statements on [database connection] D complete. ^Any new SQL statements
2473: ** that are started after the sqlite3_interrupt() call and before the
2474: ** running statements reaches zero are interrupted as if they had been
2475: ** running prior to the sqlite3_interrupt() call. ^New SQL statements
2476: ** that are started after the running statement count reaches zero are
2477: ** not effected by the sqlite3_interrupt().
2478: ** ^A call to sqlite3_interrupt(D) that occurs when there are no running
2479: ** SQL statements is a no-op and has no effect on SQL statements
2480: ** that are started after the sqlite3_interrupt() call returns.
2481: */
2482: SQLITE_API void sqlite3_interrupt(sqlite3*);
2483:
2484: /*
2485: ** CAPI3REF: Determine If An SQL Statement Is Complete
2486: **
2487: ** These routines are useful during command-line input to determine if the
2488: ** currently entered text seems to form a complete SQL statement or
2489: ** if additional input is needed before sending the text into
2490: ** SQLite for parsing. ^These routines return 1 if the input string
2491: ** appears to be a complete SQL statement. ^A statement is judged to be
2492: ** complete if it ends with a semicolon token and is not a prefix of a
2493: ** well-formed CREATE TRIGGER statement. ^Semicolons that are embedded within
2494: ** string literals or quoted identifier names or comments are not
2495: ** independent tokens (they are part of the token in which they are
2496: ** embedded) and thus do not count as a statement terminator. ^Whitespace
2497: ** and comments that follow the final semicolon are ignored.
2498: **
2499: ** ^These routines return 0 if the statement is incomplete. ^If a
2500: ** memory allocation fails, then SQLITE_NOMEM is returned.
2501: **
2502: ** ^These routines do not parse the SQL statements thus
2503: ** will not detect syntactically incorrect SQL.
2504: **
2505: ** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior
2506: ** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
2507: ** automatically by sqlite3_complete16(). If that initialization fails,
2508: ** then the return value from sqlite3_complete16() will be non-zero
2509: ** regardless of whether or not the input SQL is complete.)^
2510: **
2511: ** The input to [sqlite3_complete()] must be a zero-terminated
2512: ** UTF-8 string.
2513: **
2514: ** The input to [sqlite3_complete16()] must be a zero-terminated
2515: ** UTF-16 string in native byte order.
2516: */
2517: SQLITE_API int sqlite3_complete(const char *sql);
2518: SQLITE_API int sqlite3_complete16(const void *sql);
2519:
2520: /*
2521: ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
1.4 misho 2522: ** KEYWORDS: {busy-handler callback} {busy handler}
2523: ** METHOD: sqlite3
1.2 misho 2524: **
1.4 misho 2525: ** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
2526: ** that might be invoked with argument P whenever
2527: ** an attempt is made to access a database table associated with
2528: ** [database connection] D when another thread
2529: ** or process has the table locked.
2530: ** The sqlite3_busy_handler() interface is used to implement
2531: ** [sqlite3_busy_timeout()] and [PRAGMA busy_timeout].
1.2 misho 2532: **
1.4 misho 2533: ** ^If the busy callback is NULL, then [SQLITE_BUSY]
1.2 misho 2534: ** is returned immediately upon encountering the lock. ^If the busy callback
2535: ** is not NULL, then the callback might be invoked with two arguments.
2536: **
2537: ** ^The first argument to the busy handler is a copy of the void* pointer which
2538: ** is the third argument to sqlite3_busy_handler(). ^The second argument to
2539: ** the busy handler callback is the number of times that the busy handler has
1.4 misho 2540: ** been invoked previously for the same locking event. ^If the
1.2 misho 2541: ** busy callback returns 0, then no additional attempts are made to
1.4 misho 2542: ** access the database and [SQLITE_BUSY] is returned
2543: ** to the application.
1.2 misho 2544: ** ^If the callback returns non-zero, then another attempt
1.4 misho 2545: ** is made to access the database and the cycle repeats.
1.2 misho 2546: **
2547: ** The presence of a busy handler does not guarantee that it will be invoked
2548: ** when there is lock contention. ^If SQLite determines that invoking the busy
2549: ** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
1.4 misho 2550: ** to the application instead of invoking the
2551: ** busy handler.
1.2 misho 2552: ** Consider a scenario where one process is holding a read lock that
2553: ** it is trying to promote to a reserved lock and
2554: ** a second process is holding a reserved lock that it is trying
2555: ** to promote to an exclusive lock. The first process cannot proceed
2556: ** because it is blocked by the second and the second process cannot
2557: ** proceed because it is blocked by the first. If both processes
2558: ** invoke the busy handlers, neither will make any progress. Therefore,
2559: ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
2560: ** will induce the first process to release its read lock and allow
2561: ** the second process to proceed.
2562: **
2563: ** ^The default busy callback is NULL.
2564: **
2565: ** ^(There can only be a single busy handler defined for each
2566: ** [database connection]. Setting a new busy handler clears any
2567: ** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()]
1.4 misho 2568: ** or evaluating [PRAGMA busy_timeout=N] will change the
2569: ** busy handler and thus clear any previously set busy handler.
1.2 misho 2570: **
2571: ** The busy callback should not take any actions which modify the
1.4 misho 2572: ** database connection that invoked the busy handler. In other words,
2573: ** the busy handler is not reentrant. Any such actions
1.2 misho 2574: ** result in undefined behavior.
2575: **
2576: ** A busy handler must not close the database connection
2577: ** or [prepared statement] that invoked the busy handler.
2578: */
1.4 misho 2579: SQLITE_API int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*);
1.2 misho 2580:
2581: /*
2582: ** CAPI3REF: Set A Busy Timeout
1.4 misho 2583: ** METHOD: sqlite3
1.2 misho 2584: **
2585: ** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
2586: ** for a specified amount of time when a table is locked. ^The handler
2587: ** will sleep multiple times until at least "ms" milliseconds of sleeping
2588: ** have accumulated. ^After at least "ms" milliseconds of sleeping,
2589: ** the handler returns 0 which causes [sqlite3_step()] to return
1.4 misho 2590: ** [SQLITE_BUSY].
1.2 misho 2591: **
2592: ** ^Calling this routine with an argument less than or equal to zero
2593: ** turns off all busy handlers.
2594: **
2595: ** ^(There can only be a single busy handler for a particular
1.4 misho 2596: ** [database connection] at any given moment. If another busy handler
1.2 misho 2597: ** was defined (using [sqlite3_busy_handler()]) prior to calling
2598: ** this routine, that other busy handler is cleared.)^
1.4 misho 2599: **
2600: ** See also: [PRAGMA busy_timeout]
1.2 misho 2601: */
2602: SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
2603:
2604: /*
2605: ** CAPI3REF: Convenience Routines For Running Queries
1.4 misho 2606: ** METHOD: sqlite3
1.2 misho 2607: **
2608: ** This is a legacy interface that is preserved for backwards compatibility.
2609: ** Use of this interface is not recommended.
2610: **
2611: ** Definition: A <b>result table</b> is memory data structure created by the
2612: ** [sqlite3_get_table()] interface. A result table records the
2613: ** complete query results from one or more queries.
2614: **
2615: ** The table conceptually has a number of rows and columns. But
2616: ** these numbers are not part of the result table itself. These
2617: ** numbers are obtained separately. Let N be the number of rows
2618: ** and M be the number of columns.
2619: **
2620: ** A result table is an array of pointers to zero-terminated UTF-8 strings.
2621: ** There are (N+1)*M elements in the array. The first M pointers point
2622: ** to zero-terminated strings that contain the names of the columns.
2623: ** The remaining entries all point to query results. NULL values result
2624: ** in NULL pointers. All other values are in their UTF-8 zero-terminated
2625: ** string representation as returned by [sqlite3_column_text()].
2626: **
2627: ** A result table might consist of one or more memory allocations.
2628: ** It is not safe to pass a result table directly to [sqlite3_free()].
2629: ** A result table should be deallocated using [sqlite3_free_table()].
2630: **
2631: ** ^(As an example of the result table format, suppose a query result
2632: ** is as follows:
2633: **
2634: ** <blockquote><pre>
2635: ** Name | Age
2636: ** -----------------------
2637: ** Alice | 43
2638: ** Bob | 28
2639: ** Cindy | 21
2640: ** </pre></blockquote>
2641: **
2642: ** There are two column (M==2) and three rows (N==3). Thus the
2643: ** result table has 8 entries. Suppose the result table is stored
2644: ** in an array names azResult. Then azResult holds this content:
2645: **
2646: ** <blockquote><pre>
2647: ** azResult[0] = "Name";
2648: ** azResult[1] = "Age";
2649: ** azResult[2] = "Alice";
2650: ** azResult[3] = "43";
2651: ** azResult[4] = "Bob";
2652: ** azResult[5] = "28";
2653: ** azResult[6] = "Cindy";
2654: ** azResult[7] = "21";
2655: ** </pre></blockquote>)^
2656: **
2657: ** ^The sqlite3_get_table() function evaluates one or more
2658: ** semicolon-separated SQL statements in the zero-terminated UTF-8
2659: ** string of its 2nd parameter and returns a result table to the
2660: ** pointer given in its 3rd parameter.
2661: **
2662: ** After the application has finished with the result from sqlite3_get_table(),
2663: ** it must pass the result table pointer to sqlite3_free_table() in order to
2664: ** release the memory that was malloced. Because of the way the
2665: ** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
2666: ** function must not try to call [sqlite3_free()] directly. Only
2667: ** [sqlite3_free_table()] is able to release the memory properly and safely.
2668: **
2669: ** The sqlite3_get_table() interface is implemented as a wrapper around
2670: ** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access
2671: ** to any internal data structures of SQLite. It uses only the public
2672: ** interface defined here. As a consequence, errors that occur in the
2673: ** wrapper layer outside of the internal [sqlite3_exec()] call are not
2674: ** reflected in subsequent calls to [sqlite3_errcode()] or
2675: ** [sqlite3_errmsg()].
2676: */
2677: SQLITE_API int sqlite3_get_table(
2678: sqlite3 *db, /* An open database */
2679: const char *zSql, /* SQL to be evaluated */
2680: char ***pazResult, /* Results of the query */
2681: int *pnRow, /* Number of result rows written here */
2682: int *pnColumn, /* Number of result columns written here */
2683: char **pzErrmsg /* Error msg written here */
2684: );
2685: SQLITE_API void sqlite3_free_table(char **result);
2686:
2687: /*
2688: ** CAPI3REF: Formatted String Printing Functions
2689: **
2690: ** These routines are work-alikes of the "printf()" family of functions
2691: ** from the standard C library.
1.4.2.2 ! misho 2692: ** These routines understand most of the common formatting options from
! 2693: ** the standard library printf()
! 2694: ** plus some additional non-standard formats ([%q], [%Q], [%w], and [%z]).
! 2695: ** See the [built-in printf()] documentation for details.
1.2 misho 2696: **
2697: ** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
1.4.2.2 ! misho 2698: ** results into memory obtained from [sqlite3_malloc64()].
1.2 misho 2699: ** The strings returned by these two routines should be
2700: ** released by [sqlite3_free()]. ^Both routines return a
1.4.2.2 ! misho 2701: ** NULL pointer if [sqlite3_malloc64()] is unable to allocate enough
1.2 misho 2702: ** memory to hold the resulting string.
2703: **
2704: ** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
2705: ** the standard C library. The result is written into the
2706: ** buffer supplied as the second parameter whose size is given by
2707: ** the first parameter. Note that the order of the
2708: ** first two parameters is reversed from snprintf().)^ This is an
2709: ** historical accident that cannot be fixed without breaking
2710: ** backwards compatibility. ^(Note also that sqlite3_snprintf()
2711: ** returns a pointer to its buffer instead of the number of
2712: ** characters actually written into the buffer.)^ We admit that
2713: ** the number of characters written would be a more useful return
2714: ** value but we cannot change the implementation of sqlite3_snprintf()
2715: ** now without breaking compatibility.
2716: **
2717: ** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
2718: ** guarantees that the buffer is always zero-terminated. ^The first
2719: ** parameter "n" is the total size of the buffer, including space for
2720: ** the zero terminator. So the longest string that can be completely
2721: ** written will be n-1 characters.
2722: **
2723: ** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
2724: **
1.4.2.2 ! misho 2725: ** See also: [built-in printf()], [printf() SQL function]
1.2 misho 2726: */
2727: SQLITE_API char *sqlite3_mprintf(const char*,...);
2728: SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
2729: SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
2730: SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
2731:
2732: /*
2733: ** CAPI3REF: Memory Allocation Subsystem
2734: **
2735: ** The SQLite core uses these three routines for all of its own
2736: ** internal memory allocation needs. "Core" in the previous sentence
2737: ** does not include operating-system specific VFS implementation. The
2738: ** Windows VFS uses native malloc() and free() for some operations.
2739: **
2740: ** ^The sqlite3_malloc() routine returns a pointer to a block
2741: ** of memory at least N bytes in length, where N is the parameter.
2742: ** ^If sqlite3_malloc() is unable to obtain sufficient free
2743: ** memory, it returns a NULL pointer. ^If the parameter N to
2744: ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
2745: ** a NULL pointer.
2746: **
1.4 misho 2747: ** ^The sqlite3_malloc64(N) routine works just like
2748: ** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
2749: ** of a signed 32-bit integer.
2750: **
1.2 misho 2751: ** ^Calling sqlite3_free() with a pointer previously returned
2752: ** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
2753: ** that it might be reused. ^The sqlite3_free() routine is
2754: ** a no-op if is called with a NULL pointer. Passing a NULL pointer
2755: ** to sqlite3_free() is harmless. After being freed, memory
2756: ** should neither be read nor written. Even reading previously freed
2757: ** memory might result in a segmentation fault or other severe error.
2758: ** Memory corruption, a segmentation fault, or other severe error
2759: ** might result if sqlite3_free() is called with a non-NULL pointer that
2760: ** was not obtained from sqlite3_malloc() or sqlite3_realloc().
2761: **
1.4 misho 2762: ** ^The sqlite3_realloc(X,N) interface attempts to resize a
2763: ** prior memory allocation X to be at least N bytes.
2764: ** ^If the X parameter to sqlite3_realloc(X,N)
1.2 misho 2765: ** is a NULL pointer then its behavior is identical to calling
1.4 misho 2766: ** sqlite3_malloc(N).
2767: ** ^If the N parameter to sqlite3_realloc(X,N) is zero or
1.2 misho 2768: ** negative then the behavior is exactly the same as calling
1.4 misho 2769: ** sqlite3_free(X).
2770: ** ^sqlite3_realloc(X,N) returns a pointer to a memory allocation
2771: ** of at least N bytes in size or NULL if insufficient memory is available.
1.2 misho 2772: ** ^If M is the size of the prior allocation, then min(N,M) bytes
2773: ** of the prior allocation are copied into the beginning of buffer returned
1.4 misho 2774: ** by sqlite3_realloc(X,N) and the prior allocation is freed.
2775: ** ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the
2776: ** prior allocation is not freed.
2777: **
2778: ** ^The sqlite3_realloc64(X,N) interfaces works the same as
2779: ** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
2780: ** of a 32-bit signed integer.
2781: **
2782: ** ^If X is a memory allocation previously obtained from sqlite3_malloc(),
2783: ** sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then
2784: ** sqlite3_msize(X) returns the size of that memory allocation in bytes.
2785: ** ^The value returned by sqlite3_msize(X) might be larger than the number
2786: ** of bytes requested when X was allocated. ^If X is a NULL pointer then
2787: ** sqlite3_msize(X) returns zero. If X points to something that is not
2788: ** the beginning of memory allocation, or if it points to a formerly
2789: ** valid memory allocation that has now been freed, then the behavior
2790: ** of sqlite3_msize(X) is undefined and possibly harmful.
1.2 misho 2791: **
1.4 misho 2792: ** ^The memory returned by sqlite3_malloc(), sqlite3_realloc(),
2793: ** sqlite3_malloc64(), and sqlite3_realloc64()
1.2 misho 2794: ** is always aligned to at least an 8 byte boundary, or to a
2795: ** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
2796: ** option is used.
2797: **
2798: ** In SQLite version 3.5.0 and 3.5.1, it was possible to define
2799: ** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
2800: ** implementation of these routines to be omitted. That capability
2801: ** is no longer provided. Only built-in memory allocators can be used.
2802: **
1.3 misho 2803: ** Prior to SQLite version 3.7.10, the Windows OS interface layer called
1.2 misho 2804: ** the system malloc() and free() directly when converting
2805: ** filenames between the UTF-8 encoding used by SQLite
2806: ** and whatever filename encoding is used by the particular Windows
1.3 misho 2807: ** installation. Memory allocation errors were detected, but
2808: ** they were reported back as [SQLITE_CANTOPEN] or
1.2 misho 2809: ** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
2810: **
2811: ** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
2812: ** must be either NULL or else pointers obtained from a prior
2813: ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
2814: ** not yet been released.
2815: **
2816: ** The application must not read or write any part of
2817: ** a block of memory after it has been released using
2818: ** [sqlite3_free()] or [sqlite3_realloc()].
2819: */
2820: SQLITE_API void *sqlite3_malloc(int);
1.4 misho 2821: SQLITE_API void *sqlite3_malloc64(sqlite3_uint64);
1.2 misho 2822: SQLITE_API void *sqlite3_realloc(void*, int);
1.4 misho 2823: SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64);
1.2 misho 2824: SQLITE_API void sqlite3_free(void*);
1.4 misho 2825: SQLITE_API sqlite3_uint64 sqlite3_msize(void*);
1.2 misho 2826:
2827: /*
2828: ** CAPI3REF: Memory Allocator Statistics
2829: **
2830: ** SQLite provides these two interfaces for reporting on the status
2831: ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
2832: ** routines, which form the built-in memory allocation subsystem.
2833: **
2834: ** ^The [sqlite3_memory_used()] routine returns the number of bytes
2835: ** of memory currently outstanding (malloced but not freed).
2836: ** ^The [sqlite3_memory_highwater()] routine returns the maximum
2837: ** value of [sqlite3_memory_used()] since the high-water mark
2838: ** was last reset. ^The values returned by [sqlite3_memory_used()] and
2839: ** [sqlite3_memory_highwater()] include any overhead
2840: ** added by SQLite in its implementation of [sqlite3_malloc()],
2841: ** but not overhead added by the any underlying system library
2842: ** routines that [sqlite3_malloc()] may call.
2843: **
2844: ** ^The memory high-water mark is reset to the current value of
2845: ** [sqlite3_memory_used()] if and only if the parameter to
2846: ** [sqlite3_memory_highwater()] is true. ^The value returned
2847: ** by [sqlite3_memory_highwater(1)] is the high-water mark
2848: ** prior to the reset.
2849: */
2850: SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
2851: SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
2852:
2853: /*
2854: ** CAPI3REF: Pseudo-Random Number Generator
2855: **
2856: ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
2857: ** select random [ROWID | ROWIDs] when inserting new records into a table that
2858: ** already uses the largest possible [ROWID]. The PRNG is also used for
2859: ** the build-in random() and randomblob() SQL functions. This interface allows
2860: ** applications to access the same PRNG for other purposes.
2861: **
2862: ** ^A call to this routine stores N bytes of randomness into buffer P.
1.4 misho 2863: ** ^The P parameter can be a NULL pointer.
1.2 misho 2864: **
1.4 misho 2865: ** ^If this routine has not been previously called or if the previous
2866: ** call had N less than one or a NULL pointer for P, then the PRNG is
2867: ** seeded using randomness obtained from the xRandomness method of
2868: ** the default [sqlite3_vfs] object.
2869: ** ^If the previous call to this routine had an N of 1 or more and a
2870: ** non-NULL P then the pseudo-randomness is generated
1.2 misho 2871: ** internally and without recourse to the [sqlite3_vfs] xRandomness
2872: ** method.
2873: */
2874: SQLITE_API void sqlite3_randomness(int N, void *P);
2875:
2876: /*
2877: ** CAPI3REF: Compile-Time Authorization Callbacks
1.4 misho 2878: ** METHOD: sqlite3
1.4.2.1 misho 2879: ** KEYWORDS: {authorizer callback}
1.2 misho 2880: **
2881: ** ^This routine registers an authorizer callback with a particular
2882: ** [database connection], supplied in the first argument.
2883: ** ^The authorizer callback is invoked as SQL statements are being compiled
2884: ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
1.4.2.2 ! misho 2885: ** [sqlite3_prepare_v3()], [sqlite3_prepare16()], [sqlite3_prepare16_v2()],
! 2886: ** and [sqlite3_prepare16_v3()]. ^At various
1.2 misho 2887: ** points during the compilation process, as logic is being created
2888: ** to perform various actions, the authorizer callback is invoked to
2889: ** see if those actions are allowed. ^The authorizer callback should
2890: ** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
2891: ** specific action but allow the SQL statement to continue to be
2892: ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
2893: ** rejected with an error. ^If the authorizer callback returns
2894: ** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
2895: ** then the [sqlite3_prepare_v2()] or equivalent call that triggered
2896: ** the authorizer will fail with an error message.
2897: **
2898: ** When the callback returns [SQLITE_OK], that means the operation
2899: ** requested is ok. ^When the callback returns [SQLITE_DENY], the
2900: ** [sqlite3_prepare_v2()] or equivalent call that triggered the
2901: ** authorizer will fail with an error message explaining that
2902: ** access is denied.
2903: **
2904: ** ^The first parameter to the authorizer callback is a copy of the third
2905: ** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
2906: ** to the callback is an integer [SQLITE_COPY | action code] that specifies
2907: ** the particular action to be authorized. ^The third through sixth parameters
1.4.2.1 misho 2908: ** to the callback are either NULL pointers or zero-terminated strings
2909: ** that contain additional details about the action to be authorized.
2910: ** Applications must always be prepared to encounter a NULL pointer in any
2911: ** of the third through the sixth parameters of the authorization callback.
1.2 misho 2912: **
2913: ** ^If the action code is [SQLITE_READ]
2914: ** and the callback returns [SQLITE_IGNORE] then the
2915: ** [prepared statement] statement is constructed to substitute
2916: ** a NULL value in place of the table column that would have
2917: ** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE]
2918: ** return can be used to deny an untrusted user access to individual
2919: ** columns of a table.
1.4.2.1 misho 2920: ** ^When a table is referenced by a [SELECT] but no column values are
2921: ** extracted from that table (for example in a query like
2922: ** "SELECT count(*) FROM tab") then the [SQLITE_READ] authorizer callback
2923: ** is invoked once for that table with a column name that is an empty string.
1.2 misho 2924: ** ^If the action code is [SQLITE_DELETE] and the callback returns
2925: ** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
2926: ** [truncate optimization] is disabled and all rows are deleted individually.
2927: **
2928: ** An authorizer is used when [sqlite3_prepare | preparing]
2929: ** SQL statements from an untrusted source, to ensure that the SQL statements
2930: ** do not try to access data they are not allowed to see, or that they do not
2931: ** try to execute malicious statements that damage the database. For
2932: ** example, an application may allow a user to enter arbitrary
2933: ** SQL queries for evaluation by a database. But the application does
2934: ** not want the user to be able to make arbitrary changes to the
2935: ** database. An authorizer could then be put in place while the
2936: ** user-entered SQL is being [sqlite3_prepare | prepared] that
2937: ** disallows everything except [SELECT] statements.
2938: **
2939: ** Applications that need to process SQL from untrusted sources
2940: ** might also consider lowering resource limits using [sqlite3_limit()]
2941: ** and limiting database size using the [max_page_count] [PRAGMA]
2942: ** in addition to using an authorizer.
2943: **
2944: ** ^(Only a single authorizer can be in place on a database connection
2945: ** at a time. Each call to sqlite3_set_authorizer overrides the
2946: ** previous call.)^ ^Disable the authorizer by installing a NULL callback.
2947: ** The authorizer is disabled by default.
2948: **
2949: ** The authorizer callback must not do anything that will modify
2950: ** the database connection that invoked the authorizer callback.
2951: ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
2952: ** database connections for the meaning of "modify" in this paragraph.
2953: **
2954: ** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
2955: ** statement might be re-prepared during [sqlite3_step()] due to a
2956: ** schema change. Hence, the application should ensure that the
2957: ** correct authorizer callback remains in place during the [sqlite3_step()].
2958: **
2959: ** ^Note that the authorizer callback is invoked only during
2960: ** [sqlite3_prepare()] or its variants. Authorization is not
2961: ** performed during statement evaluation in [sqlite3_step()], unless
2962: ** as stated in the previous paragraph, sqlite3_step() invokes
2963: ** sqlite3_prepare_v2() to reprepare a statement after a schema change.
2964: */
2965: SQLITE_API int sqlite3_set_authorizer(
2966: sqlite3*,
2967: int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
2968: void *pUserData
2969: );
2970:
2971: /*
2972: ** CAPI3REF: Authorizer Return Codes
2973: **
2974: ** The [sqlite3_set_authorizer | authorizer callback function] must
2975: ** return either [SQLITE_OK] or one of these two constants in order
2976: ** to signal SQLite whether or not the action is permitted. See the
2977: ** [sqlite3_set_authorizer | authorizer documentation] for additional
2978: ** information.
2979: **
1.4 misho 2980: ** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]
2981: ** returned from the [sqlite3_vtab_on_conflict()] interface.
1.2 misho 2982: */
2983: #define SQLITE_DENY 1 /* Abort the SQL statement with an error */
2984: #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
2985:
2986: /*
2987: ** CAPI3REF: Authorizer Action Codes
2988: **
2989: ** The [sqlite3_set_authorizer()] interface registers a callback function
2990: ** that is invoked to authorize certain SQL statement actions. The
2991: ** second parameter to the callback is an integer code that specifies
2992: ** what action is being authorized. These are the integer action codes that
2993: ** the authorizer callback may be passed.
2994: **
2995: ** These action code values signify what kind of operation is to be
2996: ** authorized. The 3rd and 4th parameters to the authorization
2997: ** callback function will be parameters or NULL depending on which of these
2998: ** codes is used as the second parameter. ^(The 5th parameter to the
2999: ** authorizer callback is the name of the database ("main", "temp",
3000: ** etc.) if applicable.)^ ^The 6th parameter to the authorizer callback
3001: ** is the name of the inner-most trigger or view that is responsible for
3002: ** the access attempt or NULL if this access attempt is directly from
3003: ** top-level SQL code.
3004: */
3005: /******************************************* 3rd ************ 4th ***********/
3006: #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
3007: #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
3008: #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
3009: #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
3010: #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
3011: #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
3012: #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
3013: #define SQLITE_CREATE_VIEW 8 /* View Name NULL */
3014: #define SQLITE_DELETE 9 /* Table Name NULL */
3015: #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
3016: #define SQLITE_DROP_TABLE 11 /* Table Name NULL */
3017: #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
3018: #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
3019: #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
3020: #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
3021: #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
3022: #define SQLITE_DROP_VIEW 17 /* View Name NULL */
3023: #define SQLITE_INSERT 18 /* Table Name NULL */
3024: #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
3025: #define SQLITE_READ 20 /* Table Name Column Name */
3026: #define SQLITE_SELECT 21 /* NULL NULL */
3027: #define SQLITE_TRANSACTION 22 /* Operation NULL */
3028: #define SQLITE_UPDATE 23 /* Table Name Column Name */
3029: #define SQLITE_ATTACH 24 /* Filename NULL */
3030: #define SQLITE_DETACH 25 /* Database Name NULL */
3031: #define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */
3032: #define SQLITE_REINDEX 27 /* Index Name NULL */
3033: #define SQLITE_ANALYZE 28 /* Table Name NULL */
3034: #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
3035: #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
3036: #define SQLITE_FUNCTION 31 /* NULL Function Name */
3037: #define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */
3038: #define SQLITE_COPY 0 /* No longer used */
1.4 misho 3039: #define SQLITE_RECURSIVE 33 /* NULL NULL */
1.2 misho 3040:
3041: /*
3042: ** CAPI3REF: Tracing And Profiling Functions
1.4 misho 3043: ** METHOD: sqlite3
3044: **
3045: ** These routines are deprecated. Use the [sqlite3_trace_v2()] interface
3046: ** instead of the routines described here.
1.2 misho 3047: **
3048: ** These routines register callback functions that can be used for
3049: ** tracing and profiling the execution of SQL statements.
3050: **
3051: ** ^The callback function registered by sqlite3_trace() is invoked at
3052: ** various times when an SQL statement is being run by [sqlite3_step()].
3053: ** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
3054: ** SQL statement text as the statement first begins executing.
3055: ** ^(Additional sqlite3_trace() callbacks might occur
3056: ** as each triggered subprogram is entered. The callbacks for triggers
3057: ** contain a UTF-8 SQL comment that identifies the trigger.)^
3058: **
1.4 misho 3059: ** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit
3060: ** the length of [bound parameter] expansion in the output of sqlite3_trace().
3061: **
1.2 misho 3062: ** ^The callback function registered by sqlite3_profile() is invoked
3063: ** as each SQL statement finishes. ^The profile callback contains
3064: ** the original statement text and an estimate of wall-clock time
3065: ** of how long that statement took to run. ^The profile callback
3066: ** time is in units of nanoseconds, however the current implementation
3067: ** is only capable of millisecond resolution so the six least significant
3068: ** digits in the time are meaningless. Future versions of SQLite
1.4.2.2 ! misho 3069: ** might provide greater resolution on the profiler callback. Invoking
! 3070: ** either [sqlite3_trace()] or [sqlite3_trace_v2()] will cancel the
! 3071: ** profile callback.
1.2 misho 3072: */
1.4 misho 3073: SQLITE_API SQLITE_DEPRECATED void *sqlite3_trace(sqlite3*,
3074: void(*xTrace)(void*,const char*), void*);
3075: SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*,
1.2 misho 3076: void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
3077:
3078: /*
1.4 misho 3079: ** CAPI3REF: SQL Trace Event Codes
3080: ** KEYWORDS: SQLITE_TRACE
3081: **
3082: ** These constants identify classes of events that can be monitored
1.4.2.2 ! misho 3083: ** using the [sqlite3_trace_v2()] tracing logic. The M argument
! 3084: ** to [sqlite3_trace_v2(D,M,X,P)] is an OR-ed combination of one or more of
1.4 misho 3085: ** the following constants. ^The first argument to the trace callback
3086: ** is one of the following constants.
3087: **
3088: ** New tracing constants may be added in future releases.
3089: **
3090: ** ^A trace callback has four arguments: xCallback(T,C,P,X).
3091: ** ^The T argument is one of the integer type codes above.
3092: ** ^The C argument is a copy of the context pointer passed in as the
3093: ** fourth argument to [sqlite3_trace_v2()].
3094: ** The P and X arguments are pointers whose meanings depend on T.
3095: **
3096: ** <dl>
3097: ** [[SQLITE_TRACE_STMT]] <dt>SQLITE_TRACE_STMT</dt>
3098: ** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement
3099: ** first begins running and possibly at other times during the
3100: ** execution of the prepared statement, such as at the start of each
3101: ** trigger subprogram. ^The P argument is a pointer to the
3102: ** [prepared statement]. ^The X argument is a pointer to a string which
3103: ** is the unexpanded SQL text of the prepared statement or an SQL comment
3104: ** that indicates the invocation of a trigger. ^The callback can compute
3105: ** the same text that would have been returned by the legacy [sqlite3_trace()]
3106: ** interface by using the X argument when X begins with "--" and invoking
3107: ** [sqlite3_expanded_sql(P)] otherwise.
3108: **
3109: ** [[SQLITE_TRACE_PROFILE]] <dt>SQLITE_TRACE_PROFILE</dt>
3110: ** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same
3111: ** information as is provided by the [sqlite3_profile()] callback.
3112: ** ^The P argument is a pointer to the [prepared statement] and the
3113: ** X argument points to a 64-bit integer which is the estimated of
3114: ** the number of nanosecond that the prepared statement took to run.
3115: ** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.
3116: **
3117: ** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt>
3118: ** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared
3119: ** statement generates a single row of result.
3120: ** ^The P argument is a pointer to the [prepared statement] and the
3121: ** X argument is unused.
3122: **
3123: ** [[SQLITE_TRACE_CLOSE]] <dt>SQLITE_TRACE_CLOSE</dt>
3124: ** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database
3125: ** connection closes.
3126: ** ^The P argument is a pointer to the [database connection] object
3127: ** and the X argument is unused.
3128: ** </dl>
3129: */
3130: #define SQLITE_TRACE_STMT 0x01
3131: #define SQLITE_TRACE_PROFILE 0x02
3132: #define SQLITE_TRACE_ROW 0x04
3133: #define SQLITE_TRACE_CLOSE 0x08
3134:
3135: /*
3136: ** CAPI3REF: SQL Trace Hook
3137: ** METHOD: sqlite3
3138: **
3139: ** ^The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback
3140: ** function X against [database connection] D, using property mask M
3141: ** and context pointer P. ^If the X callback is
3142: ** NULL or if the M mask is zero, then tracing is disabled. The
3143: ** M argument should be the bitwise OR-ed combination of
3144: ** zero or more [SQLITE_TRACE] constants.
3145: **
3146: ** ^Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides
3147: ** (cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2().
3148: **
3149: ** ^The X callback is invoked whenever any of the events identified by
3150: ** mask M occur. ^The integer return value from the callback is currently
3151: ** ignored, though this may change in future releases. Callback
3152: ** implementations should return zero to ensure future compatibility.
3153: **
3154: ** ^A trace callback is invoked with four arguments: callback(T,C,P,X).
3155: ** ^The T argument is one of the [SQLITE_TRACE]
3156: ** constants to indicate why the callback was invoked.
3157: ** ^The C argument is a copy of the context pointer.
3158: ** The P and X arguments are pointers whose meanings depend on T.
3159: **
3160: ** The sqlite3_trace_v2() interface is intended to replace the legacy
3161: ** interfaces [sqlite3_trace()] and [sqlite3_profile()], both of which
3162: ** are deprecated.
3163: */
3164: SQLITE_API int sqlite3_trace_v2(
3165: sqlite3*,
3166: unsigned uMask,
3167: int(*xCallback)(unsigned,void*,void*,void*),
3168: void *pCtx
3169: );
3170:
3171: /*
1.2 misho 3172: ** CAPI3REF: Query Progress Callbacks
1.4 misho 3173: ** METHOD: sqlite3
1.2 misho 3174: **
3175: ** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
3176: ** function X to be invoked periodically during long running calls to
3177: ** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for
3178: ** database connection D. An example use for this
3179: ** interface is to keep a GUI updated during a large query.
3180: **
3181: ** ^The parameter P is passed through as the only parameter to the
1.4 misho 3182: ** callback function X. ^The parameter N is the approximate number of
1.2 misho 3183: ** [virtual machine instructions] that are evaluated between successive
1.4 misho 3184: ** invocations of the callback X. ^If N is less than one then the progress
3185: ** handler is disabled.
1.2 misho 3186: **
3187: ** ^Only a single progress handler may be defined at one time per
3188: ** [database connection]; setting a new progress handler cancels the
3189: ** old one. ^Setting parameter X to NULL disables the progress handler.
3190: ** ^The progress handler is also disabled by setting N to a value less
3191: ** than 1.
3192: **
3193: ** ^If the progress callback returns non-zero, the operation is
3194: ** interrupted. This feature can be used to implement a
3195: ** "Cancel" button on a GUI progress dialog box.
3196: **
3197: ** The progress handler callback must not do anything that will modify
3198: ** the database connection that invoked the progress handler.
3199: ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
3200: ** database connections for the meaning of "modify" in this paragraph.
3201: **
3202: */
3203: SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
3204:
3205: /*
3206: ** CAPI3REF: Opening A New Database Connection
1.4 misho 3207: ** CONSTRUCTOR: sqlite3
1.2 misho 3208: **
3209: ** ^These routines open an SQLite database file as specified by the
3210: ** filename argument. ^The filename argument is interpreted as UTF-8 for
3211: ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
3212: ** order for sqlite3_open16(). ^(A [database connection] handle is usually
3213: ** returned in *ppDb, even if an error occurs. The only exception is that
3214: ** if SQLite is unable to allocate memory to hold the [sqlite3] object,
3215: ** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
3216: ** object.)^ ^(If the database is opened (and/or created) successfully, then
3217: ** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The
3218: ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
3219: ** an English language description of the error following a failure of any
3220: ** of the sqlite3_open() routines.
3221: **
1.4 misho 3222: ** ^The default encoding will be UTF-8 for databases created using
3223: ** sqlite3_open() or sqlite3_open_v2(). ^The default encoding for databases
3224: ** created using sqlite3_open16() will be UTF-16 in the native byte order.
1.2 misho 3225: **
3226: ** Whether or not an error occurs when it is opened, resources
3227: ** associated with the [database connection] handle should be released by
3228: ** passing it to [sqlite3_close()] when it is no longer required.
3229: **
3230: ** The sqlite3_open_v2() interface works like sqlite3_open()
3231: ** except that it accepts two additional parameters for additional control
3232: ** over the new database connection. ^(The flags parameter to
3233: ** sqlite3_open_v2() can take one of
3234: ** the following three values, optionally combined with the
3235: ** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE],
3236: ** [SQLITE_OPEN_PRIVATECACHE], and/or [SQLITE_OPEN_URI] flags:)^
3237: **
3238: ** <dl>
3239: ** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
3240: ** <dd>The database is opened in read-only mode. If the database does not
3241: ** already exist, an error is returned.</dd>)^
3242: **
3243: ** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
3244: ** <dd>The database is opened for reading and writing if possible, or reading
3245: ** only if the file is write protected by the operating system. In either
3246: ** case the database must already exist, otherwise an error is returned.</dd>)^
3247: **
3248: ** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
3249: ** <dd>The database is opened for reading and writing, and is created if
3250: ** it does not already exist. This is the behavior that is always used for
3251: ** sqlite3_open() and sqlite3_open16().</dd>)^
3252: ** </dl>
3253: **
3254: ** If the 3rd parameter to sqlite3_open_v2() is not one of the
3255: ** combinations shown above optionally combined with other
3256: ** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits]
3257: ** then the behavior is undefined.
3258: **
3259: ** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
3260: ** opens in the multi-thread [threading mode] as long as the single-thread
3261: ** mode has not been set at compile-time or start-time. ^If the
3262: ** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
3263: ** in the serialized [threading mode] unless single-thread was
3264: ** previously selected at compile-time or start-time.
3265: ** ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be
3266: ** eligible to use [shared cache mode], regardless of whether or not shared
3267: ** cache is enabled using [sqlite3_enable_shared_cache()]. ^The
3268: ** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not
3269: ** participate in [shared cache mode] even if it is enabled.
3270: **
3271: ** ^The fourth parameter to sqlite3_open_v2() is the name of the
3272: ** [sqlite3_vfs] object that defines the operating system interface that
3273: ** the new database connection should use. ^If the fourth parameter is
3274: ** a NULL pointer then the default [sqlite3_vfs] object is used.
3275: **
3276: ** ^If the filename is ":memory:", then a private, temporary in-memory database
3277: ** is created for the connection. ^This in-memory database will vanish when
3278: ** the database connection is closed. Future versions of SQLite might
3279: ** make use of additional special filenames that begin with the ":" character.
3280: ** It is recommended that when a database filename actually does begin with
3281: ** a ":" character you should prefix the filename with a pathname such as
3282: ** "./" to avoid ambiguity.
3283: **
3284: ** ^If the filename is an empty string, then a private, temporary
3285: ** on-disk database will be created. ^This private database will be
3286: ** automatically deleted as soon as the database connection is closed.
3287: **
3288: ** [[URI filenames in sqlite3_open()]] <h3>URI Filenames</h3>
3289: **
3290: ** ^If [URI filename] interpretation is enabled, and the filename argument
3291: ** begins with "file:", then the filename is interpreted as a URI. ^URI
3292: ** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
1.4.2.2 ! misho 3293: ** set in the third argument to sqlite3_open_v2(), or if it has
1.2 misho 3294: ** been enabled globally using the [SQLITE_CONFIG_URI] option with the
3295: ** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
1.4.2.2 ! misho 3296: ** URI filename interpretation is turned off
1.2 misho 3297: ** by default, but future releases of SQLite might enable URI filename
3298: ** interpretation by default. See "[URI filenames]" for additional
3299: ** information.
3300: **
3301: ** URI filenames are parsed according to RFC 3986. ^If the URI contains an
3302: ** authority, then it must be either an empty string or the string
3303: ** "localhost". ^If the authority is not an empty string or "localhost", an
3304: ** error is returned to the caller. ^The fragment component of a URI, if
3305: ** present, is ignored.
3306: **
3307: ** ^SQLite uses the path component of the URI as the name of the disk file
3308: ** which contains the database. ^If the path begins with a '/' character,
3309: ** then it is interpreted as an absolute path. ^If the path does not begin
3310: ** with a '/' (meaning that the authority section is omitted from the URI)
3311: ** then the path is interpreted as a relative path.
1.4 misho 3312: ** ^(On windows, the first component of an absolute path
3313: ** is a drive specification (e.g. "C:").)^
1.2 misho 3314: **
3315: ** [[core URI query parameters]]
3316: ** The query component of a URI may contain parameters that are interpreted
3317: ** either by SQLite itself, or by a [VFS | custom VFS implementation].
1.4 misho 3318: ** SQLite and its built-in [VFSes] interpret the
3319: ** following query parameters:
1.2 misho 3320: **
3321: ** <ul>
3322: ** <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
3323: ** a VFS object that provides the operating system interface that should
3324: ** be used to access the database file on disk. ^If this option is set to
3325: ** an empty string the default VFS object is used. ^Specifying an unknown
3326: ** VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
3327: ** present, then the VFS specified by the option takes precedence over
3328: ** the value passed as the fourth parameter to sqlite3_open_v2().
3329: **
1.3 misho 3330: ** <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw",
3331: ** "rwc", or "memory". Attempting to set it to any other value is
3332: ** an error)^.
1.2 misho 3333: ** ^If "ro" is specified, then the database is opened for read-only
3334: ** access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the
1.3 misho 3335: ** third argument to sqlite3_open_v2(). ^If the mode option is set to
1.2 misho 3336: ** "rw", then the database is opened for read-write (but not create)
3337: ** access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had
3338: ** been set. ^Value "rwc" is equivalent to setting both
1.3 misho 3339: ** SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. ^If the mode option is
3340: ** set to "memory" then a pure [in-memory database] that never reads
3341: ** or writes from disk is used. ^It is an error to specify a value for
3342: ** the mode parameter that is less restrictive than that specified by
3343: ** the flags passed in the third parameter to sqlite3_open_v2().
1.2 misho 3344: **
3345: ** <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or
3346: ** "private". ^Setting it to "shared" is equivalent to setting the
3347: ** SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
3348: ** sqlite3_open_v2(). ^Setting the cache parameter to "private" is
3349: ** equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
3350: ** ^If sqlite3_open_v2() is used and the "cache" parameter is present in
1.4 misho 3351: ** a URI filename, its value overrides any behavior requested by setting
1.2 misho 3352: ** SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
1.4 misho 3353: **
3354: ** <li> <b>psow</b>: ^The psow parameter indicates whether or not the
3355: ** [powersafe overwrite] property does or does not apply to the
3356: ** storage media on which the database file resides.
3357: **
3358: ** <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter
3359: ** which if set disables file locking in rollback journal modes. This
3360: ** is useful for accessing a database on a filesystem that does not
3361: ** support locking. Caution: Database corruption might result if two
3362: ** or more processes write to the same database and any one of those
3363: ** processes uses nolock=1.
3364: **
3365: ** <li> <b>immutable</b>: ^The immutable parameter is a boolean query
3366: ** parameter that indicates that the database file is stored on
3367: ** read-only media. ^When immutable is set, SQLite assumes that the
3368: ** database file cannot be changed, even by a process with higher
3369: ** privilege, and so the database is opened read-only and all locking
3370: ** and change detection is disabled. Caution: Setting the immutable
3371: ** property on a database file that does in fact change can result
3372: ** in incorrect query results and/or [SQLITE_CORRUPT] errors.
3373: ** See also: [SQLITE_IOCAP_IMMUTABLE].
3374: **
1.2 misho 3375: ** </ul>
3376: **
3377: ** ^Specifying an unknown parameter in the query component of a URI is not an
3378: ** error. Future versions of SQLite might understand additional query
3379: ** parameters. See "[query parameters with special meaning to SQLite]" for
3380: ** additional information.
3381: **
3382: ** [[URI filename examples]] <h3>URI filename examples</h3>
3383: **
3384: ** <table border="1" align=center cellpadding=5>
3385: ** <tr><th> URI filenames <th> Results
3386: ** <tr><td> file:data.db <td>
3387: ** Open the file "data.db" in the current directory.
3388: ** <tr><td> file:/home/fred/data.db<br>
3389: ** file:///home/fred/data.db <br>
3390: ** file://localhost/home/fred/data.db <br> <td>
3391: ** Open the database file "/home/fred/data.db".
3392: ** <tr><td> file://darkstar/home/fred/data.db <td>
3393: ** An error. "darkstar" is not a recognized authority.
3394: ** <tr><td style="white-space:nowrap">
3395: ** file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
3396: ** <td> Windows only: Open the file "data.db" on fred's desktop on drive
3397: ** C:. Note that the %20 escaping in this example is not strictly
3398: ** necessary - space characters can be used literally
3399: ** in URI filenames.
3400: ** <tr><td> file:data.db?mode=ro&cache=private <td>
3401: ** Open file "data.db" in the current directory for read-only access.
3402: ** Regardless of whether or not shared-cache mode is enabled by
3403: ** default, use a private cache.
1.4 misho 3404: ** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
3405: ** Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
3406: ** that uses dot-files in place of posix advisory locking.
1.2 misho 3407: ** <tr><td> file:data.db?mode=readonly <td>
3408: ** An error. "readonly" is not a valid option for the "mode" parameter.
3409: ** </table>
3410: **
3411: ** ^URI hexadecimal escape sequences (%HH) are supported within the path and
3412: ** query components of a URI. A hexadecimal escape sequence consists of a
3413: ** percent sign - "%" - followed by exactly two hexadecimal digits
3414: ** specifying an octet value. ^Before the path or query components of a
3415: ** URI filename are interpreted, they are encoded using UTF-8 and all
3416: ** hexadecimal escape sequences replaced by a single byte containing the
3417: ** corresponding octet. If this process generates an invalid UTF-8 encoding,
3418: ** the results are undefined.
3419: **
3420: ** <b>Note to Windows users:</b> The encoding used for the filename argument
3421: ** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
3422: ** codepage is currently defined. Filenames containing international
3423: ** characters must be converted to UTF-8 prior to passing them into
3424: ** sqlite3_open() or sqlite3_open_v2().
1.3 misho 3425: **
3426: ** <b>Note to Windows Runtime users:</b> The temporary directory must be set
3427: ** prior to calling sqlite3_open() or sqlite3_open_v2(). Otherwise, various
3428: ** features that require the use of temporary files may fail.
3429: **
3430: ** See also: [sqlite3_temp_directory]
1.2 misho 3431: */
3432: SQLITE_API int sqlite3_open(
3433: const char *filename, /* Database filename (UTF-8) */
3434: sqlite3 **ppDb /* OUT: SQLite db handle */
3435: );
3436: SQLITE_API int sqlite3_open16(
3437: const void *filename, /* Database filename (UTF-16) */
3438: sqlite3 **ppDb /* OUT: SQLite db handle */
3439: );
3440: SQLITE_API int sqlite3_open_v2(
3441: const char *filename, /* Database filename (UTF-8) */
3442: sqlite3 **ppDb, /* OUT: SQLite db handle */
3443: int flags, /* Flags */
3444: const char *zVfs /* Name of VFS module to use */
3445: );
3446:
3447: /*
3448: ** CAPI3REF: Obtain Values For URI Parameters
3449: **
3450: ** These are utility routines, useful to VFS implementations, that check
3451: ** to see if a database file was a URI that contained a specific query
3452: ** parameter, and if so obtains the value of that query parameter.
3453: **
3454: ** If F is the database filename pointer passed into the xOpen() method of
3455: ** a VFS implementation when the flags parameter to xOpen() has one or
3456: ** more of the [SQLITE_OPEN_URI] or [SQLITE_OPEN_MAIN_DB] bits set and
3457: ** P is the name of the query parameter, then
3458: ** sqlite3_uri_parameter(F,P) returns the value of the P
3459: ** parameter if it exists or a NULL pointer if P does not appear as a
3460: ** query parameter on F. If P is a query parameter of F
3461: ** has no explicit value, then sqlite3_uri_parameter(F,P) returns
3462: ** a pointer to an empty string.
3463: **
3464: ** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
3465: ** parameter and returns true (1) or false (0) according to the value
1.3 misho 3466: ** of P. The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the
3467: ** value of query parameter P is one of "yes", "true", or "on" in any
3468: ** case or if the value begins with a non-zero number. The
3469: ** sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of
3470: ** query parameter P is one of "no", "false", or "off" in any case or
3471: ** if the value begins with a numeric zero. If P is not a query
3472: ** parameter on F or if the value of P is does not match any of the
3473: ** above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).
1.2 misho 3474: **
3475: ** The sqlite3_uri_int64(F,P,D) routine converts the value of P into a
3476: ** 64-bit signed integer and returns that integer, or D if P does not
3477: ** exist. If the value of P is something other than an integer, then
3478: ** zero is returned.
3479: **
3480: ** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
3481: ** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and
3482: ** is not a database file pathname pointer that SQLite passed into the xOpen
3483: ** VFS method, then the behavior of this routine is undefined and probably
3484: ** undesirable.
1.4.2.2 ! misho 3485: **
! 3486: ** See the [URI filename] documentation for additional information.
1.2 misho 3487: */
3488: SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam);
3489: SQLITE_API int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault);
3490: SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int64);
3491:
3492:
3493: /*
3494: ** CAPI3REF: Error Codes And Messages
1.4 misho 3495: ** METHOD: sqlite3
1.2 misho 3496: **
1.4 misho 3497: ** ^If the most recent sqlite3_* API call associated with
3498: ** [database connection] D failed, then the sqlite3_errcode(D) interface
3499: ** returns the numeric [result code] or [extended result code] for that
3500: ** API call.
3501: ** ^The sqlite3_extended_errcode()
1.2 misho 3502: ** interface is the same except that it always returns the
3503: ** [extended result code] even when extended result codes are
3504: ** disabled.
3505: **
1.4.2.2 ! misho 3506: ** The values returned by sqlite3_errcode() and/or
! 3507: ** sqlite3_extended_errcode() might change with each API call.
! 3508: ** Except, there are some interfaces that are guaranteed to never
! 3509: ** change the value of the error code. The error-code preserving
! 3510: ** interfaces are:
! 3511: **
! 3512: ** <ul>
! 3513: ** <li> sqlite3_errcode()
! 3514: ** <li> sqlite3_extended_errcode()
! 3515: ** <li> sqlite3_errmsg()
! 3516: ** <li> sqlite3_errmsg16()
! 3517: ** </ul>
! 3518: **
1.2 misho 3519: ** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
3520: ** text that describes the error, as either UTF-8 or UTF-16 respectively.
3521: ** ^(Memory to hold the error message string is managed internally.
3522: ** The application does not need to worry about freeing the result.
3523: ** However, the error string might be overwritten or deallocated by
3524: ** subsequent calls to other SQLite interface functions.)^
3525: **
1.3 misho 3526: ** ^The sqlite3_errstr() interface returns the English-language text
3527: ** that describes the [result code], as UTF-8.
3528: ** ^(Memory to hold the error message string is managed internally
3529: ** and must not be freed by the application)^.
3530: **
1.2 misho 3531: ** When the serialized [threading mode] is in use, it might be the
3532: ** case that a second error occurs on a separate thread in between
3533: ** the time of the first error and the call to these interfaces.
3534: ** When that happens, the second error will be reported since these
3535: ** interfaces always report the most recent result. To avoid
3536: ** this, each thread can obtain exclusive use of the [database connection] D
3537: ** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
3538: ** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
3539: ** all calls to the interfaces listed here are completed.
3540: **
3541: ** If an interface fails with SQLITE_MISUSE, that means the interface
3542: ** was invoked incorrectly by the application. In that case, the
3543: ** error code and message may or may not be set.
3544: */
3545: SQLITE_API int sqlite3_errcode(sqlite3 *db);
3546: SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
3547: SQLITE_API const char *sqlite3_errmsg(sqlite3*);
3548: SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
1.3 misho 3549: SQLITE_API const char *sqlite3_errstr(int);
1.2 misho 3550:
3551: /*
1.4 misho 3552: ** CAPI3REF: Prepared Statement Object
1.2 misho 3553: ** KEYWORDS: {prepared statement} {prepared statements}
3554: **
1.4 misho 3555: ** An instance of this object represents a single SQL statement that
3556: ** has been compiled into binary form and is ready to be evaluated.
3557: **
3558: ** Think of each SQL statement as a separate computer program. The
3559: ** original SQL text is source code. A prepared statement object
3560: ** is the compiled object code. All SQL must be converted into a
3561: ** prepared statement before it can be run.
1.2 misho 3562: **
1.4 misho 3563: ** The life-cycle of a prepared statement object usually goes like this:
1.2 misho 3564: **
3565: ** <ol>
1.4 misho 3566: ** <li> Create the prepared statement object using [sqlite3_prepare_v2()].
3567: ** <li> Bind values to [parameters] using the sqlite3_bind_*()
1.2 misho 3568: ** interfaces.
3569: ** <li> Run the SQL by calling [sqlite3_step()] one or more times.
1.4 misho 3570: ** <li> Reset the prepared statement using [sqlite3_reset()] then go back
1.2 misho 3571: ** to step 2. Do this zero or more times.
3572: ** <li> Destroy the object using [sqlite3_finalize()].
3573: ** </ol>
3574: */
3575: typedef struct sqlite3_stmt sqlite3_stmt;
3576:
3577: /*
3578: ** CAPI3REF: Run-time Limits
1.4 misho 3579: ** METHOD: sqlite3
1.2 misho 3580: **
3581: ** ^(This interface allows the size of various constructs to be limited
3582: ** on a connection by connection basis. The first parameter is the
3583: ** [database connection] whose limit is to be set or queried. The
3584: ** second parameter is one of the [limit categories] that define a
3585: ** class of constructs to be size limited. The third parameter is the
3586: ** new limit for that construct.)^
3587: **
3588: ** ^If the new limit is a negative number, the limit is unchanged.
3589: ** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a
3590: ** [limits | hard upper bound]
3591: ** set at compile-time by a C preprocessor macro called
3592: ** [limits | SQLITE_MAX_<i>NAME</i>].
3593: ** (The "_LIMIT_" in the name is changed to "_MAX_".))^
3594: ** ^Attempts to increase a limit above its hard upper bound are
3595: ** silently truncated to the hard upper bound.
3596: **
3597: ** ^Regardless of whether or not the limit was changed, the
3598: ** [sqlite3_limit()] interface returns the prior value of the limit.
3599: ** ^Hence, to find the current value of a limit without changing it,
3600: ** simply invoke this interface with the third parameter set to -1.
3601: **
3602: ** Run-time limits are intended for use in applications that manage
3603: ** both their own internal database and also databases that are controlled
3604: ** by untrusted external sources. An example application might be a
3605: ** web browser that has its own databases for storing history and
3606: ** separate databases controlled by JavaScript applications downloaded
3607: ** off the Internet. The internal databases can be given the
3608: ** large, default limits. Databases managed by external sources can
3609: ** be given much smaller limits designed to prevent a denial of service
3610: ** attack. Developers might also want to use the [sqlite3_set_authorizer()]
3611: ** interface to further control untrusted SQL. The size of the database
3612: ** created by an untrusted script can be contained using the
3613: ** [max_page_count] [PRAGMA].
3614: **
3615: ** New run-time limit categories may be added in future releases.
3616: */
3617: SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
3618:
3619: /*
3620: ** CAPI3REF: Run-Time Limit Categories
3621: ** KEYWORDS: {limit category} {*limit categories}
3622: **
3623: ** These constants define various performance limits
3624: ** that can be lowered at run-time using [sqlite3_limit()].
3625: ** The synopsis of the meanings of the various limits is shown below.
3626: ** Additional information is available at [limits | Limits in SQLite].
3627: **
3628: ** <dl>
3629: ** [[SQLITE_LIMIT_LENGTH]] ^(<dt>SQLITE_LIMIT_LENGTH</dt>
3630: ** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^
3631: **
3632: ** [[SQLITE_LIMIT_SQL_LENGTH]] ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>
3633: ** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
3634: **
3635: ** [[SQLITE_LIMIT_COLUMN]] ^(<dt>SQLITE_LIMIT_COLUMN</dt>
3636: ** <dd>The maximum number of columns in a table definition or in the
3637: ** result set of a [SELECT] or the maximum number of columns in an index
3638: ** or in an ORDER BY or GROUP BY clause.</dd>)^
3639: **
3640: ** [[SQLITE_LIMIT_EXPR_DEPTH]] ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
3641: ** <dd>The maximum depth of the parse tree on any expression.</dd>)^
3642: **
3643: ** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
3644: ** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
3645: **
3646: ** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
3647: ** <dd>The maximum number of instructions in a virtual machine program
1.4.2.1 misho 3648: ** used to implement an SQL statement. If [sqlite3_prepare_v2()] or
3649: ** the equivalent tries to allocate space for more than this many opcodes
3650: ** in a single prepared statement, an SQLITE_NOMEM error is returned.</dd>)^
1.2 misho 3651: **
3652: ** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
3653: ** <dd>The maximum number of arguments on a function.</dd>)^
3654: **
3655: ** [[SQLITE_LIMIT_ATTACHED]] ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
3656: ** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
3657: **
3658: ** [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]]
3659: ** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
3660: ** <dd>The maximum length of the pattern argument to the [LIKE] or
3661: ** [GLOB] operators.</dd>)^
3662: **
3663: ** [[SQLITE_LIMIT_VARIABLE_NUMBER]]
3664: ** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
3665: ** <dd>The maximum index number of any [parameter] in an SQL statement.)^
3666: **
3667: ** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
3668: ** <dd>The maximum depth of recursion for triggers.</dd>)^
1.4 misho 3669: **
3670: ** [[SQLITE_LIMIT_WORKER_THREADS]] ^(<dt>SQLITE_LIMIT_WORKER_THREADS</dt>
3671: ** <dd>The maximum number of auxiliary worker threads that a single
3672: ** [prepared statement] may start.</dd>)^
1.2 misho 3673: ** </dl>
3674: */
3675: #define SQLITE_LIMIT_LENGTH 0
3676: #define SQLITE_LIMIT_SQL_LENGTH 1
3677: #define SQLITE_LIMIT_COLUMN 2
3678: #define SQLITE_LIMIT_EXPR_DEPTH 3
3679: #define SQLITE_LIMIT_COMPOUND_SELECT 4
3680: #define SQLITE_LIMIT_VDBE_OP 5
3681: #define SQLITE_LIMIT_FUNCTION_ARG 6
3682: #define SQLITE_LIMIT_ATTACHED 7
3683: #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8
3684: #define SQLITE_LIMIT_VARIABLE_NUMBER 9
3685: #define SQLITE_LIMIT_TRIGGER_DEPTH 10
1.4 misho 3686: #define SQLITE_LIMIT_WORKER_THREADS 11
1.2 misho 3687:
1.4.2.2 ! misho 3688: /*
! 3689: ** CAPI3REF: Prepare Flags
! 3690: **
! 3691: ** These constants define various flags that can be passed into
! 3692: ** "prepFlags" parameter of the [sqlite3_prepare_v3()] and
! 3693: ** [sqlite3_prepare16_v3()] interfaces.
! 3694: **
! 3695: ** New flags may be added in future releases of SQLite.
! 3696: **
! 3697: ** <dl>
! 3698: ** [[SQLITE_PREPARE_PERSISTENT]] ^(<dt>SQLITE_PREPARE_PERSISTENT</dt>
! 3699: ** <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner
! 3700: ** that the prepared statement will be retained for a long time and
! 3701: ** probably reused many times.)^ ^Without this flag, [sqlite3_prepare_v3()]
! 3702: ** and [sqlite3_prepare16_v3()] assume that the prepared statement will
! 3703: ** be used just once or at most a few times and then destroyed using
! 3704: ** [sqlite3_finalize()] relatively soon. The current implementation acts
! 3705: ** on this hint by avoiding the use of [lookaside memory] so as not to
! 3706: ** deplete the limited store of lookaside memory. Future versions of
! 3707: ** SQLite may act on this hint differently.
! 3708: **
! 3709: ** [[SQLITE_PREPARE_NORMALIZE]] <dt>SQLITE_PREPARE_NORMALIZE</dt>
! 3710: ** <dd>The SQLITE_PREPARE_NORMALIZE flag is a no-op. This flag used
! 3711: ** to be required for any prepared statement that wanted to use the
! 3712: ** [sqlite3_normalized_sql()] interface. However, the
! 3713: ** [sqlite3_normalized_sql()] interface is now available to all
! 3714: ** prepared statements, regardless of whether or not they use this
! 3715: ** flag.
! 3716: **
! 3717: ** [[SQLITE_PREPARE_NO_VTAB]] <dt>SQLITE_PREPARE_NO_VTAB</dt>
! 3718: ** <dd>The SQLITE_PREPARE_NO_VTAB flag causes the SQL compiler
! 3719: ** to return an error (error code SQLITE_ERROR) if the statement uses
! 3720: ** any virtual tables.
! 3721: ** </dl>
! 3722: */
! 3723: #define SQLITE_PREPARE_PERSISTENT 0x01
! 3724: #define SQLITE_PREPARE_NORMALIZE 0x02
! 3725: #define SQLITE_PREPARE_NO_VTAB 0x04
1.4.2.1 misho 3726:
1.2 misho 3727: /*
3728: ** CAPI3REF: Compiling An SQL Statement
3729: ** KEYWORDS: {SQL statement compiler}
1.4 misho 3730: ** METHOD: sqlite3
3731: ** CONSTRUCTOR: sqlite3_stmt
1.2 misho 3732: **
1.4.2.2 ! misho 3733: ** To execute an SQL statement, it must first be compiled into a byte-code
! 3734: ** program using one of these routines. Or, in other words, these routines
! 3735: ** are constructors for the [prepared statement] object.
! 3736: **
! 3737: ** The preferred routine to use is [sqlite3_prepare_v2()]. The
! 3738: ** [sqlite3_prepare()] interface is legacy and should be avoided.
! 3739: ** [sqlite3_prepare_v3()] has an extra "prepFlags" option that is used
! 3740: ** for special purposes.
! 3741: **
! 3742: ** The use of the UTF-8 interfaces is preferred, as SQLite currently
! 3743: ** does all parsing using UTF-8. The UTF-16 interfaces are provided
! 3744: ** as a convenience. The UTF-16 interfaces work by converting the
! 3745: ** input text into UTF-8, then invoking the corresponding UTF-8 interface.
1.2 misho 3746: **
3747: ** The first argument, "db", is a [database connection] obtained from a
3748: ** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
3749: ** [sqlite3_open16()]. The database connection must not have been closed.
3750: **
3751: ** The second argument, "zSql", is the statement to be compiled, encoded
1.4.2.2 ! misho 3752: ** as either UTF-8 or UTF-16. The sqlite3_prepare(), sqlite3_prepare_v2(),
! 3753: ** and sqlite3_prepare_v3()
! 3754: ** interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(),
! 3755: ** and sqlite3_prepare16_v3() use UTF-16.
1.2 misho 3756: **
1.4 misho 3757: ** ^If the nByte argument is negative, then zSql is read up to the
3758: ** first zero terminator. ^If nByte is positive, then it is the
3759: ** number of bytes read from zSql. ^If nByte is zero, then no prepared
3760: ** statement is generated.
3761: ** If the caller knows that the supplied string is nul-terminated, then
3762: ** there is a small performance advantage to passing an nByte parameter that
3763: ** is the number of bytes in the input string <i>including</i>
3764: ** the nul-terminator.
1.2 misho 3765: **
3766: ** ^If pzTail is not NULL then *pzTail is made to point to the first byte
3767: ** past the end of the first SQL statement in zSql. These routines only
3768: ** compile the first statement in zSql, so *pzTail is left pointing to
3769: ** what remains uncompiled.
3770: **
3771: ** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
3772: ** executed using [sqlite3_step()]. ^If there is an error, *ppStmt is set
3773: ** to NULL. ^If the input text contains no SQL (if the input is an empty
3774: ** string or a comment) then *ppStmt is set to NULL.
3775: ** The calling procedure is responsible for deleting the compiled
3776: ** SQL statement using [sqlite3_finalize()] after it has finished with it.
3777: ** ppStmt may not be NULL.
3778: **
3779: ** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];
3780: ** otherwise an [error code] is returned.
3781: **
1.4.2.2 ! misho 3782: ** The sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2(),
! 3783: ** and sqlite3_prepare16_v3() interfaces are recommended for all new programs.
! 3784: ** The older interfaces (sqlite3_prepare() and sqlite3_prepare16())
! 3785: ** are retained for backwards compatibility, but their use is discouraged.
! 3786: ** ^In the "vX" interfaces, the prepared statement
1.2 misho 3787: ** that is returned (the [sqlite3_stmt] object) contains a copy of the
3788: ** original SQL text. This causes the [sqlite3_step()] interface to
3789: ** behave differently in three ways:
3790: **
3791: ** <ol>
3792: ** <li>
3793: ** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
3794: ** always used to do, [sqlite3_step()] will automatically recompile the SQL
1.4 misho 3795: ** statement and try to run it again. As many as [SQLITE_MAX_SCHEMA_RETRY]
3796: ** retries will occur before sqlite3_step() gives up and returns an error.
1.2 misho 3797: ** </li>
3798: **
3799: ** <li>
3800: ** ^When an error occurs, [sqlite3_step()] will return one of the detailed
3801: ** [error codes] or [extended error codes]. ^The legacy behavior was that
3802: ** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
3803: ** and the application would have to make a second call to [sqlite3_reset()]
3804: ** in order to find the underlying cause of the problem. With the "v2" prepare
3805: ** interfaces, the underlying reason for the error is returned immediately.
3806: ** </li>
3807: **
3808: ** <li>
3809: ** ^If the specific value bound to [parameter | host parameter] in the
3810: ** WHERE clause might influence the choice of query plan for a statement,
3811: ** then the statement will be automatically recompiled, as if there had been
3812: ** a schema change, on the first [sqlite3_step()] call following any change
3813: ** to the [sqlite3_bind_text | bindings] of that [parameter].
3814: ** ^The specific value of WHERE-clause [parameter] might influence the
3815: ** choice of query plan if the parameter is the left-hand side of a [LIKE]
3816: ** or [GLOB] operator or if the parameter is compared to an indexed column
3817: ** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled.
3818: ** </li>
3819: ** </ol>
1.4.2.2 ! misho 3820: **
! 3821: ** <p>^sqlite3_prepare_v3() differs from sqlite3_prepare_v2() only in having
! 3822: ** the extra prepFlags parameter, which is a bit array consisting of zero or
! 3823: ** more of the [SQLITE_PREPARE_PERSISTENT|SQLITE_PREPARE_*] flags. ^The
! 3824: ** sqlite3_prepare_v2() interface works exactly the same as
! 3825: ** sqlite3_prepare_v3() with a zero prepFlags parameter.
1.2 misho 3826: */
3827: SQLITE_API int sqlite3_prepare(
3828: sqlite3 *db, /* Database handle */
3829: const char *zSql, /* SQL statement, UTF-8 encoded */
3830: int nByte, /* Maximum length of zSql in bytes. */
3831: sqlite3_stmt **ppStmt, /* OUT: Statement handle */
3832: const char **pzTail /* OUT: Pointer to unused portion of zSql */
3833: );
3834: SQLITE_API int sqlite3_prepare_v2(
3835: sqlite3 *db, /* Database handle */
3836: const char *zSql, /* SQL statement, UTF-8 encoded */
3837: int nByte, /* Maximum length of zSql in bytes. */
3838: sqlite3_stmt **ppStmt, /* OUT: Statement handle */
3839: const char **pzTail /* OUT: Pointer to unused portion of zSql */
3840: );
1.4.2.2 ! misho 3841: SQLITE_API int sqlite3_prepare_v3(
! 3842: sqlite3 *db, /* Database handle */
! 3843: const char *zSql, /* SQL statement, UTF-8 encoded */
! 3844: int nByte, /* Maximum length of zSql in bytes. */
! 3845: unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
! 3846: sqlite3_stmt **ppStmt, /* OUT: Statement handle */
! 3847: const char **pzTail /* OUT: Pointer to unused portion of zSql */
! 3848: );
1.2 misho 3849: SQLITE_API int sqlite3_prepare16(
3850: sqlite3 *db, /* Database handle */
3851: const void *zSql, /* SQL statement, UTF-16 encoded */
3852: int nByte, /* Maximum length of zSql in bytes. */
3853: sqlite3_stmt **ppStmt, /* OUT: Statement handle */
3854: const void **pzTail /* OUT: Pointer to unused portion of zSql */
3855: );
3856: SQLITE_API int sqlite3_prepare16_v2(
3857: sqlite3 *db, /* Database handle */
3858: const void *zSql, /* SQL statement, UTF-16 encoded */
3859: int nByte, /* Maximum length of zSql in bytes. */
3860: sqlite3_stmt **ppStmt, /* OUT: Statement handle */
3861: const void **pzTail /* OUT: Pointer to unused portion of zSql */
3862: );
1.4.2.2 ! misho 3863: SQLITE_API int sqlite3_prepare16_v3(
! 3864: sqlite3 *db, /* Database handle */
! 3865: const void *zSql, /* SQL statement, UTF-16 encoded */
! 3866: int nByte, /* Maximum length of zSql in bytes. */
! 3867: unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
! 3868: sqlite3_stmt **ppStmt, /* OUT: Statement handle */
! 3869: const void **pzTail /* OUT: Pointer to unused portion of zSql */
! 3870: );
1.2 misho 3871:
3872: /*
3873: ** CAPI3REF: Retrieving Statement SQL
1.4 misho 3874: ** METHOD: sqlite3_stmt
1.2 misho 3875: **
1.4 misho 3876: ** ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8
3877: ** SQL text used to create [prepared statement] P if P was
1.4.2.2 ! misho 3878: ** created by [sqlite3_prepare_v2()], [sqlite3_prepare_v3()],
! 3879: ** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].
1.4 misho 3880: ** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8
3881: ** string containing the SQL text of prepared statement P with
3882: ** [bound parameters] expanded.
1.4.2.2 ! misho 3883: ** ^The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-8
! 3884: ** string containing the normalized SQL text of prepared statement P. The
! 3885: ** semantics used to normalize a SQL statement are unspecified and subject
! 3886: ** to change. At a minimum, literal values will be replaced with suitable
! 3887: ** placeholders.
1.4 misho 3888: **
3889: ** ^(For example, if a prepared statement is created using the SQL
3890: ** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
3891: ** and parameter :xyz is unbound, then sqlite3_sql() will return
3892: ** the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql()
3893: ** will return "SELECT 2345,NULL".)^
3894: **
3895: ** ^The sqlite3_expanded_sql() interface returns NULL if insufficient memory
3896: ** is available to hold the result, or if the result would exceed the
3897: ** the maximum string length determined by the [SQLITE_LIMIT_LENGTH].
3898: **
3899: ** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of
3900: ** bound parameter expansions. ^The [SQLITE_OMIT_TRACE] compile-time
3901: ** option causes sqlite3_expanded_sql() to always return NULL.
3902: **
1.4.2.2 ! misho 3903: ** ^The strings returned by sqlite3_sql(P) and sqlite3_normalized_sql(P)
! 3904: ** are managed by SQLite and are automatically freed when the prepared
! 3905: ** statement is finalized.
1.4 misho 3906: ** ^The string returned by sqlite3_expanded_sql(P), on the other hand,
3907: ** is obtained from [sqlite3_malloc()] and must be free by the application
3908: ** by passing it to [sqlite3_free()].
1.2 misho 3909: */
3910: SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
1.4 misho 3911: SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt);
1.4.2.2 ! misho 3912: SQLITE_API const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt);
1.2 misho 3913:
3914: /*
3915: ** CAPI3REF: Determine If An SQL Statement Writes The Database
1.4 misho 3916: ** METHOD: sqlite3_stmt
1.2 misho 3917: **
3918: ** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
3919: ** and only if the [prepared statement] X makes no direct changes to
3920: ** the content of the database file.
3921: **
3922: ** Note that [application-defined SQL functions] or
3923: ** [virtual tables] might change the database indirectly as a side effect.
3924: ** ^(For example, if an application defines a function "eval()" that
3925: ** calls [sqlite3_exec()], then the following SQL statement would
3926: ** change the database file through side-effects:
3927: **
3928: ** <blockquote><pre>
3929: ** SELECT eval('DELETE FROM t1') FROM t2;
3930: ** </pre></blockquote>
3931: **
3932: ** But because the [SELECT] statement does not change the database file
3933: ** directly, sqlite3_stmt_readonly() would still return true.)^
3934: **
3935: ** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK],
3936: ** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,
3937: ** since the statements themselves do not actually modify the database but
3938: ** rather they control the timing of when other statements modify the
3939: ** database. ^The [ATTACH] and [DETACH] statements also cause
3940: ** sqlite3_stmt_readonly() to return true since, while those statements
3941: ** change the configuration of a database connection, they do not make
3942: ** changes to the content of the database files on disk.
1.4.2.1 misho 3943: ** ^The sqlite3_stmt_readonly() interface returns true for [BEGIN] since
3944: ** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and
3945: ** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so
3946: ** sqlite3_stmt_readonly() returns false for those commands.
1.2 misho 3947: */
3948: SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
3949:
3950: /*
1.4.2.2 ! misho 3951: ** CAPI3REF: Query The EXPLAIN Setting For A Prepared Statement
! 3952: ** METHOD: sqlite3_stmt
! 3953: **
! 3954: ** ^The sqlite3_stmt_isexplain(S) interface returns 1 if the
! 3955: ** prepared statement S is an EXPLAIN statement, or 2 if the
! 3956: ** statement S is an EXPLAIN QUERY PLAN.
! 3957: ** ^The sqlite3_stmt_isexplain(S) interface returns 0 if S is
! 3958: ** an ordinary statement or a NULL pointer.
! 3959: */
! 3960: SQLITE_API int sqlite3_stmt_isexplain(sqlite3_stmt *pStmt);
! 3961:
! 3962: /*
1.2 misho 3963: ** CAPI3REF: Determine If A Prepared Statement Has Been Reset
1.4 misho 3964: ** METHOD: sqlite3_stmt
1.2 misho 3965: **
3966: ** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
3967: ** [prepared statement] S has been stepped at least once using
1.4 misho 3968: ** [sqlite3_step(S)] but has neither run to completion (returned
3969: ** [SQLITE_DONE] from [sqlite3_step(S)]) nor
1.2 misho 3970: ** been reset using [sqlite3_reset(S)]. ^The sqlite3_stmt_busy(S)
3971: ** interface returns false if S is a NULL pointer. If S is not a
3972: ** NULL pointer and is not a pointer to a valid [prepared statement]
3973: ** object, then the behavior is undefined and probably undesirable.
3974: **
3975: ** This interface can be used in combination [sqlite3_next_stmt()]
3976: ** to locate all prepared statements associated with a database
3977: ** connection that are in need of being reset. This can be used,
3978: ** for example, in diagnostic routines to search for prepared
3979: ** statements that are holding a transaction open.
3980: */
3981: SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*);
3982:
3983: /*
3984: ** CAPI3REF: Dynamically Typed Value Object
3985: ** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
3986: **
3987: ** SQLite uses the sqlite3_value object to represent all values
3988: ** that can be stored in a database table. SQLite uses dynamic typing
3989: ** for the values it stores. ^Values stored in sqlite3_value objects
3990: ** can be integers, floating point values, strings, BLOBs, or NULL.
3991: **
3992: ** An sqlite3_value object may be either "protected" or "unprotected".
3993: ** Some interfaces require a protected sqlite3_value. Other interfaces
3994: ** will accept either a protected or an unprotected sqlite3_value.
3995: ** Every interface that accepts sqlite3_value arguments specifies
1.4 misho 3996: ** whether or not it requires a protected sqlite3_value. The
3997: ** [sqlite3_value_dup()] interface can be used to construct a new
3998: ** protected sqlite3_value from an unprotected sqlite3_value.
1.2 misho 3999: **
4000: ** The terms "protected" and "unprotected" refer to whether or not
4001: ** a mutex is held. An internal mutex is held for a protected
4002: ** sqlite3_value object but no mutex is held for an unprotected
4003: ** sqlite3_value object. If SQLite is compiled to be single-threaded
4004: ** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
4005: ** or if SQLite is run in one of reduced mutex modes
4006: ** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
4007: ** then there is no distinction between protected and unprotected
4008: ** sqlite3_value objects and they can be used interchangeably. However,
4009: ** for maximum code portability it is recommended that applications
4010: ** still make the distinction between protected and unprotected
4011: ** sqlite3_value objects even when not strictly required.
4012: **
4013: ** ^The sqlite3_value objects that are passed as parameters into the
4014: ** implementation of [application-defined SQL functions] are protected.
4015: ** ^The sqlite3_value object returned by
4016: ** [sqlite3_column_value()] is unprotected.
1.4.2.2 ! misho 4017: ** Unprotected sqlite3_value objects may only be used as arguments
! 4018: ** to [sqlite3_result_value()], [sqlite3_bind_value()], and
! 4019: ** [sqlite3_value_dup()].
1.2 misho 4020: ** The [sqlite3_value_blob | sqlite3_value_type()] family of
4021: ** interfaces require protected sqlite3_value objects.
4022: */
1.4.2.1 misho 4023: typedef struct sqlite3_value sqlite3_value;
1.2 misho 4024:
4025: /*
4026: ** CAPI3REF: SQL Function Context Object
4027: **
4028: ** The context in which an SQL function executes is stored in an
4029: ** sqlite3_context object. ^A pointer to an sqlite3_context object
4030: ** is always first parameter to [application-defined SQL functions].
4031: ** The application-defined SQL function implementation will pass this
4032: ** pointer through into calls to [sqlite3_result_int | sqlite3_result()],
4033: ** [sqlite3_aggregate_context()], [sqlite3_user_data()],
4034: ** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],
4035: ** and/or [sqlite3_set_auxdata()].
4036: */
4037: typedef struct sqlite3_context sqlite3_context;
4038:
4039: /*
4040: ** CAPI3REF: Binding Values To Prepared Statements
4041: ** KEYWORDS: {host parameter} {host parameters} {host parameter name}
4042: ** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
1.4 misho 4043: ** METHOD: sqlite3_stmt
1.2 misho 4044: **
4045: ** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
4046: ** literals may be replaced by a [parameter] that matches one of following
4047: ** templates:
4048: **
4049: ** <ul>
4050: ** <li> ?
4051: ** <li> ?NNN
4052: ** <li> :VVV
4053: ** <li> @VVV
4054: ** <li> $VVV
4055: ** </ul>
4056: **
4057: ** In the templates above, NNN represents an integer literal,
4058: ** and VVV represents an alphanumeric identifier.)^ ^The values of these
4059: ** parameters (also called "host parameter names" or "SQL parameters")
4060: ** can be set using the sqlite3_bind_*() routines defined here.
4061: **
4062: ** ^The first argument to the sqlite3_bind_*() routines is always
4063: ** a pointer to the [sqlite3_stmt] object returned from
4064: ** [sqlite3_prepare_v2()] or its variants.
4065: **
4066: ** ^The second argument is the index of the SQL parameter to be set.
4067: ** ^The leftmost SQL parameter has an index of 1. ^When the same named
4068: ** SQL parameter is used more than once, second and subsequent
4069: ** occurrences have the same index as the first occurrence.
4070: ** ^The index for named parameters can be looked up using the
4071: ** [sqlite3_bind_parameter_index()] API if desired. ^The index
4072: ** for "?NNN" parameters is the value of NNN.
4073: ** ^The NNN value must be between 1 and the [sqlite3_limit()]
4074: ** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999).
4075: **
4076: ** ^The third argument is the value to bind to the parameter.
1.4 misho 4077: ** ^If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16()
4078: ** or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
4079: ** is ignored and the end result is the same as sqlite3_bind_null().
1.2 misho 4080: **
4081: ** ^(In those routines that have a fourth argument, its value is the
4082: ** number of bytes in the parameter. To be clear: the value is the
4083: ** number of <u>bytes</u> in the value, not the number of characters.)^
1.3 misho 4084: ** ^If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16()
4085: ** is negative, then the length of the string is
1.2 misho 4086: ** the number of bytes up to the first zero terminator.
1.3 misho 4087: ** If the fourth parameter to sqlite3_bind_blob() is negative, then
4088: ** the behavior is undefined.
1.2 misho 4089: ** If a non-negative fourth parameter is provided to sqlite3_bind_text()
1.4 misho 4090: ** or sqlite3_bind_text16() or sqlite3_bind_text64() then
4091: ** that parameter must be the byte offset
1.2 misho 4092: ** where the NUL terminator would occur assuming the string were NUL
4093: ** terminated. If any NUL characters occur at byte offsets less than
4094: ** the value of the fourth parameter then the resulting string value will
4095: ** contain embedded NULs. The result of expressions involving strings
4096: ** with embedded NULs is undefined.
4097: **
1.4 misho 4098: ** ^The fifth argument to the BLOB and string binding interfaces
4099: ** is a destructor used to dispose of the BLOB or
1.2 misho 4100: ** string after SQLite has finished with it. ^The destructor is called
1.4.2.2 ! misho 4101: ** to dispose of the BLOB or string even if the call to the bind API fails,
! 4102: ** except the destructor is not called if the third parameter is a NULL
! 4103: ** pointer or the fourth parameter is negative.
1.2 misho 4104: ** ^If the fifth argument is
4105: ** the special value [SQLITE_STATIC], then SQLite assumes that the
4106: ** information is in static, unmanaged space and does not need to be freed.
4107: ** ^If the fifth argument has the value [SQLITE_TRANSIENT], then
4108: ** SQLite makes its own private copy of the data immediately, before
4109: ** the sqlite3_bind_*() routine returns.
4110: **
1.4 misho 4111: ** ^The sixth argument to sqlite3_bind_text64() must be one of
4112: ** [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE]
4113: ** to specify the encoding of the text in the third parameter. If
4114: ** the sixth argument to sqlite3_bind_text64() is not one of the
4115: ** allowed values shown above, or if the text encoding is different
4116: ** from the encoding specified by the sixth parameter, then the behavior
4117: ** is undefined.
4118: **
1.2 misho 4119: ** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
4120: ** is filled with zeroes. ^A zeroblob uses a fixed amount of memory
4121: ** (just an integer to hold its size) while it is being processed.
4122: ** Zeroblobs are intended to serve as placeholders for BLOBs whose
4123: ** content is later written using
4124: ** [sqlite3_blob_open | incremental BLOB I/O] routines.
4125: ** ^A negative value for the zeroblob results in a zero-length BLOB.
4126: **
1.4.2.2 ! misho 4127: ** ^The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in
! 4128: ** [prepared statement] S to have an SQL value of NULL, but to also be
! 4129: ** associated with the pointer P of type T. ^D is either a NULL pointer or
! 4130: ** a pointer to a destructor function for P. ^SQLite will invoke the
! 4131: ** destructor D with a single argument of P when it is finished using
! 4132: ** P. The T parameter should be a static string, preferably a string
! 4133: ** literal. The sqlite3_bind_pointer() routine is part of the
! 4134: ** [pointer passing interface] added for SQLite 3.20.0.
! 4135: **
1.2 misho 4136: ** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
4137: ** for the [prepared statement] or with a prepared statement for which
4138: ** [sqlite3_step()] has been called more recently than [sqlite3_reset()],
4139: ** then the call will return [SQLITE_MISUSE]. If any sqlite3_bind_()
4140: ** routine is passed a [prepared statement] that has been finalized, the
4141: ** result is undefined and probably harmful.
4142: **
4143: ** ^Bindings are not cleared by the [sqlite3_reset()] routine.
4144: ** ^Unbound parameters are interpreted as NULL.
4145: **
4146: ** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an
4147: ** [error code] if anything goes wrong.
1.4 misho 4148: ** ^[SQLITE_TOOBIG] might be returned if the size of a string or BLOB
4149: ** exceeds limits imposed by [sqlite3_limit]([SQLITE_LIMIT_LENGTH]) or
4150: ** [SQLITE_MAX_LENGTH].
1.2 misho 4151: ** ^[SQLITE_RANGE] is returned if the parameter
4152: ** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails.
4153: **
4154: ** See also: [sqlite3_bind_parameter_count()],
4155: ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
4156: */
4157: SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
1.4 misho 4158: SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
4159: void(*)(void*));
1.2 misho 4160: SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
4161: SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);
4162: SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
4163: SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
1.4 misho 4164: SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
1.2 misho 4165: SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
1.4 misho 4166: SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
4167: void(*)(void*), unsigned char encoding);
1.2 misho 4168: SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
1.4.2.2 ! misho 4169: SQLITE_API int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*));
1.2 misho 4170: SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
1.4 misho 4171: SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);
1.2 misho 4172:
4173: /*
4174: ** CAPI3REF: Number Of SQL Parameters
1.4 misho 4175: ** METHOD: sqlite3_stmt
1.2 misho 4176: **
4177: ** ^This routine can be used to find the number of [SQL parameters]
4178: ** in a [prepared statement]. SQL parameters are tokens of the
4179: ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
4180: ** placeholders for values that are [sqlite3_bind_blob | bound]
4181: ** to the parameters at a later time.
4182: **
4183: ** ^(This routine actually returns the index of the largest (rightmost)
4184: ** parameter. For all forms except ?NNN, this will correspond to the
4185: ** number of unique parameters. If parameters of the ?NNN form are used,
4186: ** there may be gaps in the list.)^
4187: **
4188: ** See also: [sqlite3_bind_blob|sqlite3_bind()],
4189: ** [sqlite3_bind_parameter_name()], and
4190: ** [sqlite3_bind_parameter_index()].
4191: */
4192: SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
4193:
4194: /*
4195: ** CAPI3REF: Name Of A Host Parameter
1.4 misho 4196: ** METHOD: sqlite3_stmt
1.2 misho 4197: **
4198: ** ^The sqlite3_bind_parameter_name(P,N) interface returns
4199: ** the name of the N-th [SQL parameter] in the [prepared statement] P.
4200: ** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
4201: ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
4202: ** respectively.
4203: ** In other words, the initial ":" or "$" or "@" or "?"
4204: ** is included as part of the name.)^
4205: ** ^Parameters of the form "?" without a following integer have no name
4206: ** and are referred to as "nameless" or "anonymous parameters".
4207: **
4208: ** ^The first host parameter has an index of 1, not 0.
4209: **
4210: ** ^If the value N is out of range or if the N-th parameter is
4211: ** nameless, then NULL is returned. ^The returned string is
4212: ** always in UTF-8 encoding even if the named parameter was
1.4.2.2 ! misho 4213: ** originally specified as UTF-16 in [sqlite3_prepare16()],
! 4214: ** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].
1.2 misho 4215: **
4216: ** See also: [sqlite3_bind_blob|sqlite3_bind()],
4217: ** [sqlite3_bind_parameter_count()], and
4218: ** [sqlite3_bind_parameter_index()].
4219: */
4220: SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
4221:
4222: /*
4223: ** CAPI3REF: Index Of A Parameter With A Given Name
1.4 misho 4224: ** METHOD: sqlite3_stmt
1.2 misho 4225: **
4226: ** ^Return the index of an SQL parameter given its name. ^The
4227: ** index value returned is suitable for use as the second
4228: ** parameter to [sqlite3_bind_blob|sqlite3_bind()]. ^A zero
4229: ** is returned if no matching parameter is found. ^The parameter
4230: ** name must be given in UTF-8 even if the original statement
1.4.2.2 ! misho 4231: ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()] or
! 4232: ** [sqlite3_prepare16_v3()].
1.2 misho 4233: **
4234: ** See also: [sqlite3_bind_blob|sqlite3_bind()],
4235: ** [sqlite3_bind_parameter_count()], and
1.4 misho 4236: ** [sqlite3_bind_parameter_name()].
1.2 misho 4237: */
4238: SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
4239:
4240: /*
4241: ** CAPI3REF: Reset All Bindings On A Prepared Statement
1.4 misho 4242: ** METHOD: sqlite3_stmt
1.2 misho 4243: **
4244: ** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
4245: ** the [sqlite3_bind_blob | bindings] on a [prepared statement].
4246: ** ^Use this routine to reset all host parameters to NULL.
4247: */
4248: SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
4249:
4250: /*
4251: ** CAPI3REF: Number Of Columns In A Result Set
1.4 misho 4252: ** METHOD: sqlite3_stmt
1.2 misho 4253: **
4254: ** ^Return the number of columns in the result set returned by the
1.4.2.1 misho 4255: ** [prepared statement]. ^If this routine returns 0, that means the
4256: ** [prepared statement] returns no data (for example an [UPDATE]).
4257: ** ^However, just because this routine returns a positive number does not
4258: ** mean that one or more rows of data will be returned. ^A SELECT statement
4259: ** will always have a positive sqlite3_column_count() but depending on the
4260: ** WHERE clause constraints and the table content, it might return no rows.
1.2 misho 4261: **
4262: ** See also: [sqlite3_data_count()]
4263: */
4264: SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
4265:
4266: /*
4267: ** CAPI3REF: Column Names In A Result Set
1.4 misho 4268: ** METHOD: sqlite3_stmt
1.2 misho 4269: **
4270: ** ^These routines return the name assigned to a particular column
4271: ** in the result set of a [SELECT] statement. ^The sqlite3_column_name()
4272: ** interface returns a pointer to a zero-terminated UTF-8 string
4273: ** and sqlite3_column_name16() returns a pointer to a zero-terminated
4274: ** UTF-16 string. ^The first parameter is the [prepared statement]
4275: ** that implements the [SELECT] statement. ^The second parameter is the
4276: ** column number. ^The leftmost column is number 0.
4277: **
4278: ** ^The returned string pointer is valid until either the [prepared statement]
4279: ** is destroyed by [sqlite3_finalize()] or until the statement is automatically
4280: ** reprepared by the first call to [sqlite3_step()] for a particular run
4281: ** or until the next call to
4282: ** sqlite3_column_name() or sqlite3_column_name16() on the same column.
4283: **
4284: ** ^If sqlite3_malloc() fails during the processing of either routine
4285: ** (for example during a conversion from UTF-8 to UTF-16) then a
4286: ** NULL pointer is returned.
4287: **
4288: ** ^The name of a result column is the value of the "AS" clause for
4289: ** that column, if there is an AS clause. If there is no AS clause
4290: ** then the name of the column is unspecified and may change from
4291: ** one release of SQLite to the next.
4292: */
4293: SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N);
4294: SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);
4295:
4296: /*
4297: ** CAPI3REF: Source Of Data In A Query Result
1.4 misho 4298: ** METHOD: sqlite3_stmt
1.2 misho 4299: **
4300: ** ^These routines provide a means to determine the database, table, and
4301: ** table column that is the origin of a particular result column in
4302: ** [SELECT] statement.
4303: ** ^The name of the database or table or column can be returned as
4304: ** either a UTF-8 or UTF-16 string. ^The _database_ routines return
4305: ** the database name, the _table_ routines return the table name, and
4306: ** the origin_ routines return the column name.
4307: ** ^The returned string is valid until the [prepared statement] is destroyed
4308: ** using [sqlite3_finalize()] or until the statement is automatically
4309: ** reprepared by the first call to [sqlite3_step()] for a particular run
4310: ** or until the same information is requested
4311: ** again in a different encoding.
4312: **
4313: ** ^The names returned are the original un-aliased names of the
4314: ** database, table, and column.
4315: **
4316: ** ^The first argument to these interfaces is a [prepared statement].
4317: ** ^These functions return information about the Nth result column returned by
4318: ** the statement, where N is the second function argument.
4319: ** ^The left-most column is column 0 for these routines.
4320: **
4321: ** ^If the Nth column returned by the statement is an expression or
4322: ** subquery and is not a column value, then all of these functions return
4323: ** NULL. ^These routine might also return NULL if a memory allocation error
4324: ** occurs. ^Otherwise, they return the name of the attached database, table,
4325: ** or column that query result column was extracted from.
4326: **
4327: ** ^As with all other SQLite APIs, those whose names end with "16" return
4328: ** UTF-16 encoded strings and the other functions return UTF-8.
4329: **
4330: ** ^These APIs are only available if the library was compiled with the
4331: ** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
4332: **
4333: ** If two or more threads call one or more of these routines against the same
4334: ** prepared statement and column at the same time then the results are
4335: ** undefined.
4336: **
4337: ** If two or more threads call one or more
4338: ** [sqlite3_column_database_name | column metadata interfaces]
4339: ** for the same [prepared statement] and result column
4340: ** at the same time then the results are undefined.
4341: */
4342: SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int);
4343: SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
4344: SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int);
4345: SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
4346: SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
4347: SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
4348:
4349: /*
4350: ** CAPI3REF: Declared Datatype Of A Query Result
1.4 misho 4351: ** METHOD: sqlite3_stmt
1.2 misho 4352: **
4353: ** ^(The first parameter is a [prepared statement].
4354: ** If this statement is a [SELECT] statement and the Nth column of the
4355: ** returned result set of that [SELECT] is a table column (not an
4356: ** expression or subquery) then the declared type of the table
4357: ** column is returned.)^ ^If the Nth column of the result set is an
4358: ** expression or subquery, then a NULL pointer is returned.
4359: ** ^The returned string is always UTF-8 encoded.
4360: **
4361: ** ^(For example, given the database schema:
4362: **
4363: ** CREATE TABLE t1(c1 VARIANT);
4364: **
4365: ** and the following statement to be compiled:
4366: **
4367: ** SELECT c1 + 1, c1 FROM t1;
4368: **
4369: ** this routine would return the string "VARIANT" for the second result
4370: ** column (i==1), and a NULL pointer for the first result column (i==0).)^
4371: **
4372: ** ^SQLite uses dynamic run-time typing. ^So just because a column
4373: ** is declared to contain a particular type does not mean that the
4374: ** data stored in that column is of the declared type. SQLite is
4375: ** strongly typed, but the typing is dynamic not static. ^Type
4376: ** is associated with individual values, not with the containers
4377: ** used to hold those values.
4378: */
4379: SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);
4380: SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
4381:
4382: /*
4383: ** CAPI3REF: Evaluate An SQL Statement
1.4 misho 4384: ** METHOD: sqlite3_stmt
1.2 misho 4385: **
1.4.2.2 ! misho 4386: ** After a [prepared statement] has been prepared using any of
! 4387: ** [sqlite3_prepare_v2()], [sqlite3_prepare_v3()], [sqlite3_prepare16_v2()],
! 4388: ** or [sqlite3_prepare16_v3()] or one of the legacy
1.2 misho 4389: ** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
4390: ** must be called one or more times to evaluate the statement.
4391: **
4392: ** The details of the behavior of the sqlite3_step() interface depend
1.4.2.2 ! misho 4393: ** on whether the statement was prepared using the newer "vX" interfaces
! 4394: ** [sqlite3_prepare_v3()], [sqlite3_prepare_v2()], [sqlite3_prepare16_v3()],
! 4395: ** [sqlite3_prepare16_v2()] or the older legacy
! 4396: ** interfaces [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the
! 4397: ** new "vX" interface is recommended for new applications but the legacy
1.2 misho 4398: ** interface will continue to be supported.
4399: **
4400: ** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
4401: ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
4402: ** ^With the "v2" interface, any of the other [result codes] or
4403: ** [extended result codes] might be returned as well.
4404: **
4405: ** ^[SQLITE_BUSY] means that the database engine was unable to acquire the
4406: ** database locks it needs to do its job. ^If the statement is a [COMMIT]
4407: ** or occurs outside of an explicit transaction, then you can retry the
4408: ** statement. If the statement is not a [COMMIT] and occurs within an
4409: ** explicit transaction then you should rollback the transaction before
4410: ** continuing.
4411: **
4412: ** ^[SQLITE_DONE] means that the statement has finished executing
4413: ** successfully. sqlite3_step() should not be called again on this virtual
4414: ** machine without first calling [sqlite3_reset()] to reset the virtual
4415: ** machine back to its initial state.
4416: **
4417: ** ^If the SQL statement being executed returns any data, then [SQLITE_ROW]
4418: ** is returned each time a new row of data is ready for processing by the
4419: ** caller. The values may be accessed using the [column access functions].
4420: ** sqlite3_step() is called again to retrieve the next row of data.
4421: **
4422: ** ^[SQLITE_ERROR] means that a run-time error (such as a constraint
4423: ** violation) has occurred. sqlite3_step() should not be called again on
4424: ** the VM. More information may be found by calling [sqlite3_errmsg()].
4425: ** ^With the legacy interface, a more specific error code (for example,
4426: ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
4427: ** can be obtained by calling [sqlite3_reset()] on the
4428: ** [prepared statement]. ^In the "v2" interface,
4429: ** the more specific error code is returned directly by sqlite3_step().
4430: **
4431: ** [SQLITE_MISUSE] means that the this routine was called inappropriately.
4432: ** Perhaps it was called on a [prepared statement] that has
4433: ** already been [sqlite3_finalize | finalized] or on one that had
4434: ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could
4435: ** be the case that the same database connection is being used by two or
4436: ** more threads at the same moment in time.
4437: **
4438: ** For all versions of SQLite up to and including 3.6.23.1, a call to
4439: ** [sqlite3_reset()] was required after sqlite3_step() returned anything
4440: ** other than [SQLITE_ROW] before any subsequent invocation of
4441: ** sqlite3_step(). Failure to reset the prepared statement using
4442: ** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from
1.4.2.1 misho 4443: ** sqlite3_step(). But after [version 3.6.23.1] ([dateof:3.6.23.1],
4444: ** sqlite3_step() began
1.2 misho 4445: ** calling [sqlite3_reset()] automatically in this circumstance rather
4446: ** than returning [SQLITE_MISUSE]. This is not considered a compatibility
4447: ** break because any application that ever receives an SQLITE_MISUSE error
4448: ** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option
4449: ** can be used to restore the legacy behavior.
4450: **
4451: ** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
4452: ** API always returns a generic error code, [SQLITE_ERROR], following any
4453: ** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call
4454: ** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
4455: ** specific [error codes] that better describes the error.
4456: ** We admit that this is a goofy design. The problem has been fixed
4457: ** with the "v2" interface. If you prepare all of your SQL statements
1.4.2.2 ! misho 4458: ** using [sqlite3_prepare_v3()] or [sqlite3_prepare_v2()]
! 4459: ** or [sqlite3_prepare16_v2()] or [sqlite3_prepare16_v3()] instead
1.2 misho 4460: ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
4461: ** then the more specific [error codes] are returned directly
1.4.2.2 ! misho 4462: ** by sqlite3_step(). The use of the "vX" interfaces is recommended.
1.2 misho 4463: */
4464: SQLITE_API int sqlite3_step(sqlite3_stmt*);
4465:
4466: /*
4467: ** CAPI3REF: Number of columns in a result set
1.4 misho 4468: ** METHOD: sqlite3_stmt
1.2 misho 4469: **
4470: ** ^The sqlite3_data_count(P) interface returns the number of columns in the
4471: ** current row of the result set of [prepared statement] P.
4472: ** ^If prepared statement P does not have results ready to return
4473: ** (via calls to the [sqlite3_column_int | sqlite3_column_*()] of
4474: ** interfaces) then sqlite3_data_count(P) returns 0.
4475: ** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
4476: ** ^The sqlite3_data_count(P) routine returns 0 if the previous call to
4477: ** [sqlite3_step](P) returned [SQLITE_DONE]. ^The sqlite3_data_count(P)
4478: ** will return non-zero if previous call to [sqlite3_step](P) returned
4479: ** [SQLITE_ROW], except in the case of the [PRAGMA incremental_vacuum]
4480: ** where it always returns zero since each step of that multi-step
4481: ** pragma returns 0 columns of data.
4482: **
4483: ** See also: [sqlite3_column_count()]
4484: */
4485: SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
4486:
4487: /*
4488: ** CAPI3REF: Fundamental Datatypes
4489: ** KEYWORDS: SQLITE_TEXT
4490: **
4491: ** ^(Every value in SQLite has one of five fundamental datatypes:
4492: **
4493: ** <ul>
4494: ** <li> 64-bit signed integer
4495: ** <li> 64-bit IEEE floating point number
4496: ** <li> string
4497: ** <li> BLOB
4498: ** <li> NULL
4499: ** </ul>)^
4500: **
4501: ** These constants are codes for each of those types.
4502: **
4503: ** Note that the SQLITE_TEXT constant was also used in SQLite version 2
4504: ** for a completely different meaning. Software that links against both
4505: ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
4506: ** SQLITE_TEXT.
4507: */
4508: #define SQLITE_INTEGER 1
4509: #define SQLITE_FLOAT 2
4510: #define SQLITE_BLOB 4
4511: #define SQLITE_NULL 5
4512: #ifdef SQLITE_TEXT
4513: # undef SQLITE_TEXT
4514: #else
4515: # define SQLITE_TEXT 3
4516: #endif
4517: #define SQLITE3_TEXT 3
4518:
4519: /*
4520: ** CAPI3REF: Result Values From A Query
4521: ** KEYWORDS: {column access functions}
1.4 misho 4522: ** METHOD: sqlite3_stmt
1.2 misho 4523: **
1.4.2.2 ! misho 4524: ** <b>Summary:</b>
! 4525: ** <blockquote><table border=0 cellpadding=0 cellspacing=0>
! 4526: ** <tr><td><b>sqlite3_column_blob</b><td>→<td>BLOB result
! 4527: ** <tr><td><b>sqlite3_column_double</b><td>→<td>REAL result
! 4528: ** <tr><td><b>sqlite3_column_int</b><td>→<td>32-bit INTEGER result
! 4529: ** <tr><td><b>sqlite3_column_int64</b><td>→<td>64-bit INTEGER result
! 4530: ** <tr><td><b>sqlite3_column_text</b><td>→<td>UTF-8 TEXT result
! 4531: ** <tr><td><b>sqlite3_column_text16</b><td>→<td>UTF-16 TEXT result
! 4532: ** <tr><td><b>sqlite3_column_value</b><td>→<td>The result as an
! 4533: ** [sqlite3_value|unprotected sqlite3_value] object.
! 4534: ** <tr><td> <td> <td>
! 4535: ** <tr><td><b>sqlite3_column_bytes</b><td>→<td>Size of a BLOB
! 4536: ** or a UTF-8 TEXT result in bytes
! 4537: ** <tr><td><b>sqlite3_column_bytes16 </b>
! 4538: ** <td>→ <td>Size of UTF-16
! 4539: ** TEXT in bytes
! 4540: ** <tr><td><b>sqlite3_column_type</b><td>→<td>Default
! 4541: ** datatype of the result
! 4542: ** </table></blockquote>
! 4543: **
! 4544: ** <b>Details:</b>
! 4545: **
1.2 misho 4546: ** ^These routines return information about a single column of the current
4547: ** result row of a query. ^In every case the first argument is a pointer
4548: ** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
4549: ** that was returned from [sqlite3_prepare_v2()] or one of its variants)
4550: ** and the second argument is the index of the column for which information
4551: ** should be returned. ^The leftmost column of the result set has the index 0.
4552: ** ^The number of columns in the result can be determined using
4553: ** [sqlite3_column_count()].
4554: **
4555: ** If the SQL statement does not currently point to a valid row, or if the
4556: ** column index is out of range, the result is undefined.
4557: ** These routines may only be called when the most recent call to
4558: ** [sqlite3_step()] has returned [SQLITE_ROW] and neither
4559: ** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently.
4560: ** If any of these routines are called after [sqlite3_reset()] or
4561: ** [sqlite3_finalize()] or after [sqlite3_step()] has returned
4562: ** something other than [SQLITE_ROW], the results are undefined.
4563: ** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
4564: ** are called from a different thread while any of these routines
4565: ** are pending, then the results are undefined.
4566: **
1.4.2.2 ! misho 4567: ** The first six interfaces (_blob, _double, _int, _int64, _text, and _text16)
! 4568: ** each return the value of a result column in a specific data format. If
! 4569: ** the result column is not initially in the requested format (for example,
! 4570: ** if the query returns an integer but the sqlite3_column_text() interface
! 4571: ** is used to extract the value) then an automatic type conversion is performed.
! 4572: **
1.2 misho 4573: ** ^The sqlite3_column_type() routine returns the
4574: ** [SQLITE_INTEGER | datatype code] for the initial data type
4575: ** of the result column. ^The returned value is one of [SQLITE_INTEGER],
1.4.2.2 ! misho 4576: ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].
! 4577: ** The return value of sqlite3_column_type() can be used to decide which
! 4578: ** of the first six interface should be used to extract the column value.
! 4579: ** The value returned by sqlite3_column_type() is only meaningful if no
! 4580: ** automatic type conversions have occurred for the value in question.
! 4581: ** After a type conversion, the result of calling sqlite3_column_type()
! 4582: ** is undefined, though harmless. Future
1.2 misho 4583: ** versions of SQLite may change the behavior of sqlite3_column_type()
4584: ** following a type conversion.
4585: **
1.4.2.2 ! misho 4586: ** If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes()
! 4587: ** or sqlite3_column_bytes16() interfaces can be used to determine the size
! 4588: ** of that BLOB or string.
! 4589: **
1.2 misho 4590: ** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
4591: ** routine returns the number of bytes in that BLOB or string.
4592: ** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
4593: ** the string to UTF-8 and then returns the number of bytes.
4594: ** ^If the result is a numeric value then sqlite3_column_bytes() uses
4595: ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
4596: ** the number of bytes in that string.
4597: ** ^If the result is NULL, then sqlite3_column_bytes() returns zero.
4598: **
4599: ** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
4600: ** routine returns the number of bytes in that BLOB or string.
4601: ** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
4602: ** the string to UTF-16 and then returns the number of bytes.
4603: ** ^If the result is a numeric value then sqlite3_column_bytes16() uses
4604: ** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns
4605: ** the number of bytes in that string.
4606: ** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.
4607: **
4608: ** ^The values returned by [sqlite3_column_bytes()] and
4609: ** [sqlite3_column_bytes16()] do not include the zero terminators at the end
4610: ** of the string. ^For clarity: the values returned by
4611: ** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of
4612: ** bytes in the string, not the number of characters.
4613: **
4614: ** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
4615: ** even empty strings, are always zero-terminated. ^The return
4616: ** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
4617: **
1.4 misho 4618: ** <b>Warning:</b> ^The object returned by [sqlite3_column_value()] is an
4619: ** [unprotected sqlite3_value] object. In a multithreaded environment,
4620: ** an unprotected sqlite3_value object may only be used safely with
4621: ** [sqlite3_bind_value()] and [sqlite3_result_value()].
1.2 misho 4622: ** If the [unprotected sqlite3_value] object returned by
4623: ** [sqlite3_column_value()] is used in any other way, including calls
4624: ** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
1.4 misho 4625: ** or [sqlite3_value_bytes()], the behavior is not threadsafe.
1.4.2.2 ! misho 4626: ** Hence, the sqlite3_column_value() interface
! 4627: ** is normally only useful within the implementation of
! 4628: ** [application-defined SQL functions] or [virtual tables], not within
! 4629: ** top-level application code.
1.2 misho 4630: **
1.4.2.2 ! misho 4631: ** The these routines may attempt to convert the datatype of the result.
! 4632: ** ^For example, if the internal representation is FLOAT and a text result
1.2 misho 4633: ** is requested, [sqlite3_snprintf()] is used internally to perform the
4634: ** conversion automatically. ^(The following table details the conversions
4635: ** that are applied:
4636: **
4637: ** <blockquote>
4638: ** <table border="1">
4639: ** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion
4640: **
4641: ** <tr><td> NULL <td> INTEGER <td> Result is 0
4642: ** <tr><td> NULL <td> FLOAT <td> Result is 0.0
1.4 misho 4643: ** <tr><td> NULL <td> TEXT <td> Result is a NULL pointer
4644: ** <tr><td> NULL <td> BLOB <td> Result is a NULL pointer
1.2 misho 4645: ** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float
4646: ** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer
4647: ** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT
1.4 misho 4648: ** <tr><td> FLOAT <td> INTEGER <td> [CAST] to INTEGER
1.2 misho 4649: ** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float
1.4 misho 4650: ** <tr><td> FLOAT <td> BLOB <td> [CAST] to BLOB
4651: ** <tr><td> TEXT <td> INTEGER <td> [CAST] to INTEGER
4652: ** <tr><td> TEXT <td> FLOAT <td> [CAST] to REAL
1.2 misho 4653: ** <tr><td> TEXT <td> BLOB <td> No change
1.4 misho 4654: ** <tr><td> BLOB <td> INTEGER <td> [CAST] to INTEGER
4655: ** <tr><td> BLOB <td> FLOAT <td> [CAST] to REAL
1.2 misho 4656: ** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed
4657: ** </table>
4658: ** </blockquote>)^
4659: **
4660: ** Note that when type conversions occur, pointers returned by prior
4661: ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
4662: ** sqlite3_column_text16() may be invalidated.
4663: ** Type conversions and pointer invalidations might occur
4664: ** in the following cases:
4665: **
4666: ** <ul>
4667: ** <li> The initial content is a BLOB and sqlite3_column_text() or
4668: ** sqlite3_column_text16() is called. A zero-terminator might
4669: ** need to be added to the string.</li>
4670: ** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
4671: ** sqlite3_column_text16() is called. The content must be converted
4672: ** to UTF-16.</li>
4673: ** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
4674: ** sqlite3_column_text() is called. The content must be converted
4675: ** to UTF-8.</li>
4676: ** </ul>
4677: **
4678: ** ^Conversions between UTF-16be and UTF-16le are always done in place and do
4679: ** not invalidate a prior pointer, though of course the content of the buffer
4680: ** that the prior pointer references will have been modified. Other kinds
4681: ** of conversion are done in place when it is possible, but sometimes they
4682: ** are not possible and in those cases prior pointers are invalidated.
4683: **
1.4 misho 4684: ** The safest policy is to invoke these routines
1.2 misho 4685: ** in one of the following ways:
4686: **
4687: ** <ul>
4688: ** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
4689: ** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
4690: ** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
4691: ** </ul>
4692: **
4693: ** In other words, you should call sqlite3_column_text(),
4694: ** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
4695: ** into the desired format, then invoke sqlite3_column_bytes() or
4696: ** sqlite3_column_bytes16() to find the size of the result. Do not mix calls
4697: ** to sqlite3_column_text() or sqlite3_column_blob() with calls to
4698: ** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
4699: ** with calls to sqlite3_column_bytes().
4700: **
4701: ** ^The pointers returned are valid until a type conversion occurs as
4702: ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
4703: ** [sqlite3_finalize()] is called. ^The memory space used to hold strings
1.4.2.2 ! misho 4704: ** and BLOBs is freed automatically. Do not pass the pointers returned
1.4 misho 4705: ** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
1.2 misho 4706: ** [sqlite3_free()].
4707: **
1.4.2.2 ! misho 4708: ** As long as the input parameters are correct, these routines will only
! 4709: ** fail if an out-of-memory error occurs during a format conversion.
! 4710: ** Only the following subset of interfaces are subject to out-of-memory
! 4711: ** errors:
! 4712: **
! 4713: ** <ul>
! 4714: ** <li> sqlite3_column_blob()
! 4715: ** <li> sqlite3_column_text()
! 4716: ** <li> sqlite3_column_text16()
! 4717: ** <li> sqlite3_column_bytes()
! 4718: ** <li> sqlite3_column_bytes16()
! 4719: ** </ul>
! 4720: **
! 4721: ** If an out-of-memory error occurs, then the return value from these
! 4722: ** routines is the same as if the column had contained an SQL NULL value.
! 4723: ** Valid SQL NULL returns can be distinguished from out-of-memory errors
! 4724: ** by invoking the [sqlite3_errcode()] immediately after the suspect
! 4725: ** return value is obtained and before any
! 4726: ** other SQLite interface is called on the same [database connection].
1.2 misho 4727: */
4728: SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
4729: SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);
4730: SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol);
4731: SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
4732: SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
4733: SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
4734: SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
1.4.2.2 ! misho 4735: SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
! 4736: SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
! 4737: SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
1.2 misho 4738:
4739: /*
4740: ** CAPI3REF: Destroy A Prepared Statement Object
1.4 misho 4741: ** DESTRUCTOR: sqlite3_stmt
1.2 misho 4742: **
4743: ** ^The sqlite3_finalize() function is called to delete a [prepared statement].
4744: ** ^If the most recent evaluation of the statement encountered no errors
4745: ** or if the statement is never been evaluated, then sqlite3_finalize() returns
4746: ** SQLITE_OK. ^If the most recent evaluation of statement S failed, then
4747: ** sqlite3_finalize(S) returns the appropriate [error code] or
4748: ** [extended error code].
4749: **
4750: ** ^The sqlite3_finalize(S) routine can be called at any point during
4751: ** the life cycle of [prepared statement] S:
4752: ** before statement S is ever evaluated, after
4753: ** one or more calls to [sqlite3_reset()], or after any call
4754: ** to [sqlite3_step()] regardless of whether or not the statement has
4755: ** completed execution.
4756: **
4757: ** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
4758: **
4759: ** The application must finalize every [prepared statement] in order to avoid
4760: ** resource leaks. It is a grievous error for the application to try to use
4761: ** a prepared statement after it has been finalized. Any use of a prepared
4762: ** statement after it has been finalized can result in undefined and
4763: ** undesirable behavior such as segfaults and heap corruption.
4764: */
4765: SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
4766:
4767: /*
4768: ** CAPI3REF: Reset A Prepared Statement Object
1.4 misho 4769: ** METHOD: sqlite3_stmt
1.2 misho 4770: **
4771: ** The sqlite3_reset() function is called to reset a [prepared statement]
4772: ** object back to its initial state, ready to be re-executed.
4773: ** ^Any SQL statement variables that had values bound to them using
4774: ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
4775: ** Use [sqlite3_clear_bindings()] to reset the bindings.
4776: **
4777: ** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S
4778: ** back to the beginning of its program.
4779: **
4780: ** ^If the most recent call to [sqlite3_step(S)] for the
4781: ** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
4782: ** or if [sqlite3_step(S)] has never before been called on S,
4783: ** then [sqlite3_reset(S)] returns [SQLITE_OK].
4784: **
4785: ** ^If the most recent call to [sqlite3_step(S)] for the
4786: ** [prepared statement] S indicated an error, then
4787: ** [sqlite3_reset(S)] returns an appropriate [error code].
4788: **
4789: ** ^The [sqlite3_reset(S)] interface does not change the values
4790: ** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
4791: */
4792: SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
4793:
4794: /*
4795: ** CAPI3REF: Create Or Redefine SQL Functions
4796: ** KEYWORDS: {function creation routines}
4797: ** KEYWORDS: {application-defined SQL function}
4798: ** KEYWORDS: {application-defined SQL functions}
1.4 misho 4799: ** METHOD: sqlite3
1.2 misho 4800: **
4801: ** ^These functions (collectively known as "function creation routines")
4802: ** are used to add SQL functions or aggregates or to redefine the behavior
1.4.2.2 ! misho 4803: ** of existing SQL functions or aggregates. The only differences between
! 4804: ** the three "sqlite3_create_function*" routines are the text encoding
! 4805: ** expected for the second parameter (the name of the function being
! 4806: ** created) and the presence or absence of a destructor callback for
! 4807: ** the application data pointer. Function sqlite3_create_window_function()
! 4808: ** is similar, but allows the user to supply the extra callback functions
! 4809: ** needed by [aggregate window functions].
1.2 misho 4810: **
4811: ** ^The first parameter is the [database connection] to which the SQL
4812: ** function is to be added. ^If an application uses more than one database
4813: ** connection then application-defined SQL functions must be added
4814: ** to each database connection separately.
4815: **
4816: ** ^The second parameter is the name of the SQL function to be created or
4817: ** redefined. ^The length of the name is limited to 255 bytes in a UTF-8
4818: ** representation, exclusive of the zero-terminator. ^Note that the name
4819: ** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.
4820: ** ^Any attempt to create a function with a longer name
4821: ** will result in [SQLITE_MISUSE] being returned.
4822: **
4823: ** ^The third parameter (nArg)
4824: ** is the number of arguments that the SQL function or
4825: ** aggregate takes. ^If this parameter is -1, then the SQL function or
4826: ** aggregate may take any number of arguments between 0 and the limit
4827: ** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]). If the third
4828: ** parameter is less than -1 or greater than 127 then the behavior is
4829: ** undefined.
4830: **
4831: ** ^The fourth parameter, eTextRep, specifies what
4832: ** [SQLITE_UTF8 | text encoding] this SQL function prefers for
1.4 misho 4833: ** its parameters. The application should set this parameter to
4834: ** [SQLITE_UTF16LE] if the function implementation invokes
4835: ** [sqlite3_value_text16le()] on an input, or [SQLITE_UTF16BE] if the
4836: ** implementation invokes [sqlite3_value_text16be()] on an input, or
4837: ** [SQLITE_UTF16] if [sqlite3_value_text16()] is used, or [SQLITE_UTF8]
4838: ** otherwise. ^The same SQL function may be registered multiple times using
4839: ** different preferred text encodings, with different implementations for
4840: ** each encoding.
1.2 misho 4841: ** ^When multiple implementations of the same function are available, SQLite
4842: ** will pick the one that involves the least amount of data conversion.
1.4 misho 4843: **
4844: ** ^The fourth parameter may optionally be ORed with [SQLITE_DETERMINISTIC]
4845: ** to signal that the function will always return the same result given
4846: ** the same inputs within a single SQL statement. Most SQL functions are
4847: ** deterministic. The built-in [random()] SQL function is an example of a
4848: ** function that is not deterministic. The SQLite query planner is able to
4849: ** perform additional optimizations on deterministic functions, so use
4850: ** of the [SQLITE_DETERMINISTIC] flag is recommended where possible.
1.2 misho 4851: **
4852: ** ^(The fifth parameter is an arbitrary pointer. The implementation of the
4853: ** function can gain access to this pointer using [sqlite3_user_data()].)^
4854: **
1.4.2.2 ! misho 4855: ** ^The sixth, seventh and eighth parameters passed to the three
! 4856: ** "sqlite3_create_function*" functions, xFunc, xStep and xFinal, are
1.2 misho 4857: ** pointers to C-language functions that implement the SQL function or
4858: ** aggregate. ^A scalar SQL function requires an implementation of the xFunc
4859: ** callback only; NULL pointers must be passed as the xStep and xFinal
4860: ** parameters. ^An aggregate SQL function requires an implementation of xStep
4861: ** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing
4862: ** SQL function or aggregate, pass NULL pointers for all three function
4863: ** callbacks.
4864: **
1.4.2.2 ! misho 4865: ** ^The sixth, seventh, eighth and ninth parameters (xStep, xFinal, xValue
! 4866: ** and xInverse) passed to sqlite3_create_window_function are pointers to
! 4867: ** C-language callbacks that implement the new function. xStep and xFinal
! 4868: ** must both be non-NULL. xValue and xInverse may either both be NULL, in
! 4869: ** which case a regular aggregate function is created, or must both be
! 4870: ** non-NULL, in which case the new function may be used as either an aggregate
! 4871: ** or aggregate window function. More details regarding the implementation
! 4872: ** of aggregate window functions are
! 4873: ** [user-defined window functions|available here].
! 4874: **
! 4875: ** ^(If the final parameter to sqlite3_create_function_v2() or
! 4876: ** sqlite3_create_window_function() is not NULL, then it is destructor for
! 4877: ** the application data pointer. The destructor is invoked when the function
! 4878: ** is deleted, either by being overloaded or when the database connection
! 4879: ** closes.)^ ^The destructor is also invoked if the call to
! 4880: ** sqlite3_create_function_v2() fails. ^When the destructor callback is
! 4881: ** invoked, it is passed a single argument which is a copy of the application
! 4882: ** data pointer which was the fifth parameter to sqlite3_create_function_v2().
1.2 misho 4883: **
4884: ** ^It is permitted to register multiple implementations of the same
4885: ** functions with the same name but with either differing numbers of
4886: ** arguments or differing preferred text encodings. ^SQLite will use
4887: ** the implementation that most closely matches the way in which the
4888: ** SQL function is used. ^A function implementation with a non-negative
4889: ** nArg parameter is a better match than a function implementation with
4890: ** a negative nArg. ^A function where the preferred text encoding
4891: ** matches the database encoding is a better
4892: ** match than a function where the encoding is different.
4893: ** ^A function where the encoding difference is between UTF16le and UTF16be
4894: ** is a closer match than a function where the encoding difference is
4895: ** between UTF8 and UTF16.
4896: **
4897: ** ^Built-in functions may be overloaded by new application-defined functions.
4898: **
4899: ** ^An application-defined function is permitted to call other
4900: ** SQLite interfaces. However, such calls must not
4901: ** close the database connection nor finalize or reset the prepared
4902: ** statement in which the function is running.
4903: */
4904: SQLITE_API int sqlite3_create_function(
4905: sqlite3 *db,
4906: const char *zFunctionName,
4907: int nArg,
4908: int eTextRep,
4909: void *pApp,
4910: void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
4911: void (*xStep)(sqlite3_context*,int,sqlite3_value**),
4912: void (*xFinal)(sqlite3_context*)
4913: );
4914: SQLITE_API int sqlite3_create_function16(
4915: sqlite3 *db,
4916: const void *zFunctionName,
4917: int nArg,
4918: int eTextRep,
4919: void *pApp,
4920: void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
4921: void (*xStep)(sqlite3_context*,int,sqlite3_value**),
4922: void (*xFinal)(sqlite3_context*)
4923: );
4924: SQLITE_API int sqlite3_create_function_v2(
4925: sqlite3 *db,
4926: const char *zFunctionName,
4927: int nArg,
4928: int eTextRep,
4929: void *pApp,
4930: void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
4931: void (*xStep)(sqlite3_context*,int,sqlite3_value**),
4932: void (*xFinal)(sqlite3_context*),
4933: void(*xDestroy)(void*)
4934: );
1.4.2.2 ! misho 4935: SQLITE_API int sqlite3_create_window_function(
! 4936: sqlite3 *db,
! 4937: const char *zFunctionName,
! 4938: int nArg,
! 4939: int eTextRep,
! 4940: void *pApp,
! 4941: void (*xStep)(sqlite3_context*,int,sqlite3_value**),
! 4942: void (*xFinal)(sqlite3_context*),
! 4943: void (*xValue)(sqlite3_context*),
! 4944: void (*xInverse)(sqlite3_context*,int,sqlite3_value**),
! 4945: void(*xDestroy)(void*)
! 4946: );
1.2 misho 4947:
4948: /*
4949: ** CAPI3REF: Text Encodings
4950: **
4951: ** These constant define integer codes that represent the various
4952: ** text encodings supported by SQLite.
4953: */
1.4 misho 4954: #define SQLITE_UTF8 1 /* IMP: R-37514-35566 */
4955: #define SQLITE_UTF16LE 2 /* IMP: R-03371-37637 */
4956: #define SQLITE_UTF16BE 3 /* IMP: R-51971-34154 */
1.2 misho 4957: #define SQLITE_UTF16 4 /* Use native byte order */
1.4 misho 4958: #define SQLITE_ANY 5 /* Deprecated */
1.2 misho 4959: #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
4960:
4961: /*
1.4 misho 4962: ** CAPI3REF: Function Flags
4963: **
4964: ** These constants may be ORed together with the
4965: ** [SQLITE_UTF8 | preferred text encoding] as the fourth argument
4966: ** to [sqlite3_create_function()], [sqlite3_create_function16()], or
4967: ** [sqlite3_create_function_v2()].
4968: */
4969: #define SQLITE_DETERMINISTIC 0x800
4970:
4971: /*
1.2 misho 4972: ** CAPI3REF: Deprecated Functions
4973: ** DEPRECATED
4974: **
4975: ** These functions are [deprecated]. In order to maintain
4976: ** backwards compatibility with older code, these functions continue
4977: ** to be supported. However, new applications should avoid
1.4 misho 4978: ** the use of these functions. To encourage programmers to avoid
4979: ** these functions, we will not explain what they do.
1.2 misho 4980: */
4981: #ifndef SQLITE_OMIT_DEPRECATED
4982: SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
4983: SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
4984: SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
4985: SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void);
4986: SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void);
1.4 misho 4987: SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),
4988: void*,sqlite3_int64);
1.2 misho 4989: #endif
4990:
4991: /*
1.4 misho 4992: ** CAPI3REF: Obtaining SQL Values
4993: ** METHOD: sqlite3_value
1.2 misho 4994: **
1.4.2.2 ! misho 4995: ** <b>Summary:</b>
! 4996: ** <blockquote><table border=0 cellpadding=0 cellspacing=0>
! 4997: ** <tr><td><b>sqlite3_value_blob</b><td>→<td>BLOB value
! 4998: ** <tr><td><b>sqlite3_value_double</b><td>→<td>REAL value
! 4999: ** <tr><td><b>sqlite3_value_int</b><td>→<td>32-bit INTEGER value
! 5000: ** <tr><td><b>sqlite3_value_int64</b><td>→<td>64-bit INTEGER value
! 5001: ** <tr><td><b>sqlite3_value_pointer</b><td>→<td>Pointer value
! 5002: ** <tr><td><b>sqlite3_value_text</b><td>→<td>UTF-8 TEXT value
! 5003: ** <tr><td><b>sqlite3_value_text16</b><td>→<td>UTF-16 TEXT value in
! 5004: ** the native byteorder
! 5005: ** <tr><td><b>sqlite3_value_text16be</b><td>→<td>UTF-16be TEXT value
! 5006: ** <tr><td><b>sqlite3_value_text16le</b><td>→<td>UTF-16le TEXT value
! 5007: ** <tr><td> <td> <td>
! 5008: ** <tr><td><b>sqlite3_value_bytes</b><td>→<td>Size of a BLOB
! 5009: ** or a UTF-8 TEXT in bytes
! 5010: ** <tr><td><b>sqlite3_value_bytes16 </b>
! 5011: ** <td>→ <td>Size of UTF-16
! 5012: ** TEXT in bytes
! 5013: ** <tr><td><b>sqlite3_value_type</b><td>→<td>Default
! 5014: ** datatype of the value
! 5015: ** <tr><td><b>sqlite3_value_numeric_type </b>
! 5016: ** <td>→ <td>Best numeric datatype of the value
! 5017: ** <tr><td><b>sqlite3_value_nochange </b>
! 5018: ** <td>→ <td>True if the column is unchanged in an UPDATE
! 5019: ** against a virtual table.
! 5020: ** <tr><td><b>sqlite3_value_frombind </b>
! 5021: ** <td>→ <td>True if value originated from a [bound parameter]
! 5022: ** </table></blockquote>
! 5023: **
! 5024: ** <b>Details:</b>
! 5025: **
! 5026: ** These routines extract type, size, and content information from
! 5027: ** [protected sqlite3_value] objects. Protected sqlite3_value objects
! 5028: ** are used to pass parameter information into implementation of
! 5029: ** [application-defined SQL functions] and [virtual tables].
1.2 misho 5030: **
5031: ** These routines work only with [protected sqlite3_value] objects.
5032: ** Any attempt to use these routines on an [unprotected sqlite3_value]
1.4.2.2 ! misho 5033: ** is not threadsafe.
1.2 misho 5034: **
5035: ** ^These routines work just like the corresponding [column access functions]
1.4 misho 5036: ** except that these routines take a single [protected sqlite3_value] object
1.2 misho 5037: ** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
5038: **
5039: ** ^The sqlite3_value_text16() interface extracts a UTF-16 string
5040: ** in the native byte-order of the host machine. ^The
5041: ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
5042: ** extract UTF-16 strings as big-endian and little-endian respectively.
5043: **
1.4.2.2 ! misho 5044: ** ^If [sqlite3_value] object V was initialized
! 5045: ** using [sqlite3_bind_pointer(S,I,P,X,D)] or [sqlite3_result_pointer(C,P,X,D)]
! 5046: ** and if X and Y are strings that compare equal according to strcmp(X,Y),
! 5047: ** then sqlite3_value_pointer(V,Y) will return the pointer P. ^Otherwise,
! 5048: ** sqlite3_value_pointer(V,Y) returns a NULL. The sqlite3_bind_pointer()
! 5049: ** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
! 5050: **
! 5051: ** ^(The sqlite3_value_type(V) interface returns the
! 5052: ** [SQLITE_INTEGER | datatype code] for the initial datatype of the
! 5053: ** [sqlite3_value] object V. The returned value is one of [SQLITE_INTEGER],
! 5054: ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].)^
! 5055: ** Other interfaces might change the datatype for an sqlite3_value object.
! 5056: ** For example, if the datatype is initially SQLITE_INTEGER and
! 5057: ** sqlite3_value_text(V) is called to extract a text value for that
! 5058: ** integer, then subsequent calls to sqlite3_value_type(V) might return
! 5059: ** SQLITE_TEXT. Whether or not a persistent internal datatype conversion
! 5060: ** occurs is undefined and may change from one release of SQLite to the next.
! 5061: **
1.2 misho 5062: ** ^(The sqlite3_value_numeric_type() interface attempts to apply
5063: ** numeric affinity to the value. This means that an attempt is
5064: ** made to convert the value to an integer or floating point. If
5065: ** such a conversion is possible without loss of information (in other
5066: ** words, if the value is a string that looks like a number)
5067: ** then the conversion is performed. Otherwise no conversion occurs.
5068: ** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
5069: **
1.4.2.2 ! misho 5070: ** ^Within the [xUpdate] method of a [virtual table], the
! 5071: ** sqlite3_value_nochange(X) interface returns true if and only if
! 5072: ** the column corresponding to X is unchanged by the UPDATE operation
! 5073: ** that the xUpdate method call was invoked to implement and if
! 5074: ** and the prior [xColumn] method call that was invoked to extracted
! 5075: ** the value for that column returned without setting a result (probably
! 5076: ** because it queried [sqlite3_vtab_nochange()] and found that the column
! 5077: ** was unchanging). ^Within an [xUpdate] method, any value for which
! 5078: ** sqlite3_value_nochange(X) is true will in all other respects appear
! 5079: ** to be a NULL value. If sqlite3_value_nochange(X) is invoked anywhere other
! 5080: ** than within an [xUpdate] method call for an UPDATE statement, then
! 5081: ** the return value is arbitrary and meaningless.
! 5082: **
! 5083: ** ^The sqlite3_value_frombind(X) interface returns non-zero if the
! 5084: ** value X originated from one of the [sqlite3_bind_int|sqlite3_bind()]
! 5085: ** interfaces. ^If X comes from an SQL literal value, or a table column,
! 5086: ** and expression, then sqlite3_value_frombind(X) returns zero.
! 5087: **
1.2 misho 5088: ** Please pay particular attention to the fact that the pointer returned
5089: ** from [sqlite3_value_blob()], [sqlite3_value_text()], or
5090: ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
5091: ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
5092: ** or [sqlite3_value_text16()].
5093: **
5094: ** These routines must be called from the same thread as
5095: ** the SQL function that supplied the [sqlite3_value*] parameters.
1.4.2.2 ! misho 5096: **
! 5097: ** As long as the input parameter is correct, these routines can only
! 5098: ** fail if an out-of-memory error occurs during a format conversion.
! 5099: ** Only the following subset of interfaces are subject to out-of-memory
! 5100: ** errors:
! 5101: **
! 5102: ** <ul>
! 5103: ** <li> sqlite3_value_blob()
! 5104: ** <li> sqlite3_value_text()
! 5105: ** <li> sqlite3_value_text16()
! 5106: ** <li> sqlite3_value_text16le()
! 5107: ** <li> sqlite3_value_text16be()
! 5108: ** <li> sqlite3_value_bytes()
! 5109: ** <li> sqlite3_value_bytes16()
! 5110: ** </ul>
! 5111: **
! 5112: ** If an out-of-memory error occurs, then the return value from these
! 5113: ** routines is the same as if the column had contained an SQL NULL value.
! 5114: ** Valid SQL NULL returns can be distinguished from out-of-memory errors
! 5115: ** by invoking the [sqlite3_errcode()] immediately after the suspect
! 5116: ** return value is obtained and before any
! 5117: ** other SQLite interface is called on the same [database connection].
1.2 misho 5118: */
5119: SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);
5120: SQLITE_API double sqlite3_value_double(sqlite3_value*);
5121: SQLITE_API int sqlite3_value_int(sqlite3_value*);
5122: SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
1.4.2.2 ! misho 5123: SQLITE_API void *sqlite3_value_pointer(sqlite3_value*, const char*);
1.2 misho 5124: SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*);
5125: SQLITE_API const void *sqlite3_value_text16(sqlite3_value*);
5126: SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);
5127: SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);
1.4.2.2 ! misho 5128: SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
! 5129: SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
1.2 misho 5130: SQLITE_API int sqlite3_value_type(sqlite3_value*);
5131: SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
1.4.2.2 ! misho 5132: SQLITE_API int sqlite3_value_nochange(sqlite3_value*);
! 5133: SQLITE_API int sqlite3_value_frombind(sqlite3_value*);
1.2 misho 5134:
5135: /*
1.4 misho 5136: ** CAPI3REF: Finding The Subtype Of SQL Values
5137: ** METHOD: sqlite3_value
5138: **
5139: ** The sqlite3_value_subtype(V) function returns the subtype for
5140: ** an [application-defined SQL function] argument V. The subtype
5141: ** information can be used to pass a limited amount of context from
5142: ** one SQL function to another. Use the [sqlite3_result_subtype()]
5143: ** routine to set the subtype for the return value of an SQL function.
5144: */
5145: SQLITE_API unsigned int sqlite3_value_subtype(sqlite3_value*);
5146:
5147: /*
5148: ** CAPI3REF: Copy And Free SQL Values
5149: ** METHOD: sqlite3_value
5150: **
5151: ** ^The sqlite3_value_dup(V) interface makes a copy of the [sqlite3_value]
5152: ** object D and returns a pointer to that copy. ^The [sqlite3_value] returned
5153: ** is a [protected sqlite3_value] object even if the input is not.
5154: ** ^The sqlite3_value_dup(V) interface returns NULL if V is NULL or if a
5155: ** memory allocation fails.
5156: **
5157: ** ^The sqlite3_value_free(V) interface frees an [sqlite3_value] object
5158: ** previously obtained from [sqlite3_value_dup()]. ^If V is a NULL pointer
5159: ** then sqlite3_value_free(V) is a harmless no-op.
5160: */
5161: SQLITE_API sqlite3_value *sqlite3_value_dup(const sqlite3_value*);
5162: SQLITE_API void sqlite3_value_free(sqlite3_value*);
5163:
5164: /*
1.2 misho 5165: ** CAPI3REF: Obtain Aggregate Function Context
1.4 misho 5166: ** METHOD: sqlite3_context
1.2 misho 5167: **
5168: ** Implementations of aggregate SQL functions use this
5169: ** routine to allocate memory for storing their state.
5170: **
5171: ** ^The first time the sqlite3_aggregate_context(C,N) routine is called
5172: ** for a particular aggregate function, SQLite
5173: ** allocates N of memory, zeroes out that memory, and returns a pointer
5174: ** to the new memory. ^On second and subsequent calls to
5175: ** sqlite3_aggregate_context() for the same aggregate function instance,
5176: ** the same buffer is returned. Sqlite3_aggregate_context() is normally
5177: ** called once for each invocation of the xStep callback and then one
5178: ** last time when the xFinal callback is invoked. ^(When no rows match
5179: ** an aggregate query, the xStep() callback of the aggregate function
5180: ** implementation is never called and xFinal() is called exactly once.
5181: ** In those cases, sqlite3_aggregate_context() might be called for the
5182: ** first time from within xFinal().)^
5183: **
1.4 misho 5184: ** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer
5185: ** when first called if N is less than or equal to zero or if a memory
5186: ** allocate error occurs.
1.2 misho 5187: **
5188: ** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is
5189: ** determined by the N parameter on first successful call. Changing the
5190: ** value of N in subsequent call to sqlite3_aggregate_context() within
5191: ** the same aggregate function instance will not resize the memory
1.4 misho 5192: ** allocation.)^ Within the xFinal callback, it is customary to set
5193: ** N=0 in calls to sqlite3_aggregate_context(C,N) so that no
5194: ** pointless memory allocations occur.
1.2 misho 5195: **
5196: ** ^SQLite automatically frees the memory allocated by
5197: ** sqlite3_aggregate_context() when the aggregate query concludes.
5198: **
5199: ** The first parameter must be a copy of the
5200: ** [sqlite3_context | SQL function context] that is the first parameter
5201: ** to the xStep or xFinal callback routine that implements the aggregate
5202: ** function.
5203: **
5204: ** This routine must be called from the same thread in which
5205: ** the aggregate SQL function is running.
5206: */
5207: SQLITE_API void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
5208:
5209: /*
5210: ** CAPI3REF: User Data For Functions
1.4 misho 5211: ** METHOD: sqlite3_context
1.2 misho 5212: **
5213: ** ^The sqlite3_user_data() interface returns a copy of
5214: ** the pointer that was the pUserData parameter (the 5th parameter)
5215: ** of the [sqlite3_create_function()]
5216: ** and [sqlite3_create_function16()] routines that originally
5217: ** registered the application defined function.
5218: **
5219: ** This routine must be called from the same thread in which
5220: ** the application-defined function is running.
5221: */
5222: SQLITE_API void *sqlite3_user_data(sqlite3_context*);
5223:
5224: /*
5225: ** CAPI3REF: Database Connection For Functions
1.4 misho 5226: ** METHOD: sqlite3_context
1.2 misho 5227: **
5228: ** ^The sqlite3_context_db_handle() interface returns a copy of
5229: ** the pointer to the [database connection] (the 1st parameter)
5230: ** of the [sqlite3_create_function()]
5231: ** and [sqlite3_create_function16()] routines that originally
5232: ** registered the application defined function.
5233: */
5234: SQLITE_API sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
5235:
5236: /*
5237: ** CAPI3REF: Function Auxiliary Data
1.4 misho 5238: ** METHOD: sqlite3_context
1.2 misho 5239: **
1.4 misho 5240: ** These functions may be used by (non-aggregate) SQL functions to
1.2 misho 5241: ** associate metadata with argument values. If the same value is passed to
5242: ** multiple invocations of the same SQL function during query execution, under
1.4 misho 5243: ** some circumstances the associated metadata may be preserved. An example
5244: ** of where this might be useful is in a regular-expression matching
5245: ** function. The compiled version of the regular expression can be stored as
5246: ** metadata associated with the pattern string.
5247: ** Then as long as the pattern string remains the same,
5248: ** the compiled regular expression can be reused on multiple
5249: ** invocations of the same function.
1.2 misho 5250: **
1.4.2.1 misho 5251: ** ^The sqlite3_get_auxdata(C,N) interface returns a pointer to the metadata
5252: ** associated by the sqlite3_set_auxdata(C,N,P,X) function with the Nth argument
5253: ** value to the application-defined function. ^N is zero for the left-most
5254: ** function argument. ^If there is no metadata
5255: ** associated with the function argument, the sqlite3_get_auxdata(C,N) interface
1.4 misho 5256: ** returns a NULL pointer.
5257: **
5258: ** ^The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for the N-th
5259: ** argument of the application-defined function. ^Subsequent
5260: ** calls to sqlite3_get_auxdata(C,N) return P from the most recent
5261: ** sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid or
5262: ** NULL if the metadata has been discarded.
5263: ** ^After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,
5264: ** SQLite will invoke the destructor function X with parameter P exactly
5265: ** once, when the metadata is discarded.
5266: ** SQLite is free to discard the metadata at any time, including: <ul>
5267: ** <li> ^(when the corresponding function parameter changes)^, or
5268: ** <li> ^(when [sqlite3_reset()] or [sqlite3_finalize()] is called for the
5269: ** SQL statement)^, or
5270: ** <li> ^(when sqlite3_set_auxdata() is invoked again on the same
5271: ** parameter)^, or
5272: ** <li> ^(during the original sqlite3_set_auxdata() call when a memory
5273: ** allocation error occurs.)^ </ul>
5274: **
5275: ** Note the last bullet in particular. The destructor X in
5276: ** sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the
5277: ** sqlite3_set_auxdata() interface even returns. Hence sqlite3_set_auxdata()
5278: ** should be called near the end of the function implementation and the
5279: ** function implementation should not make any use of P after
5280: ** sqlite3_set_auxdata() has been called.
1.2 misho 5281: **
5282: ** ^(In practice, metadata is preserved between function calls for
1.4 misho 5283: ** function parameters that are compile-time constants, including literal
5284: ** values and [parameters] and expressions composed from the same.)^
1.2 misho 5285: **
1.4.2.1 misho 5286: ** The value of the N parameter to these interfaces should be non-negative.
5287: ** Future enhancements may make use of negative N values to define new
5288: ** kinds of function caching behavior.
5289: **
1.2 misho 5290: ** These routines must be called from the same thread in which
5291: ** the SQL function is running.
5292: */
5293: SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);
5294: SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
5295:
5296:
5297: /*
5298: ** CAPI3REF: Constants Defining Special Destructor Behavior
5299: **
5300: ** These are special values for the destructor that is passed in as the
5301: ** final argument to routines like [sqlite3_result_blob()]. ^If the destructor
5302: ** argument is SQLITE_STATIC, it means that the content pointer is constant
5303: ** and will never change. It does not need to be destroyed. ^The
5304: ** SQLITE_TRANSIENT value means that the content will likely change in
5305: ** the near future and that SQLite should make its own private copy of
5306: ** the content before returning.
5307: **
5308: ** The typedef is necessary to work around problems in certain
1.4 misho 5309: ** C++ compilers.
1.2 misho 5310: */
5311: typedef void (*sqlite3_destructor_type)(void*);
5312: #define SQLITE_STATIC ((sqlite3_destructor_type)0)
5313: #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1)
5314:
5315: /*
5316: ** CAPI3REF: Setting The Result Of An SQL Function
1.4 misho 5317: ** METHOD: sqlite3_context
1.2 misho 5318: **
5319: ** These routines are used by the xFunc or xFinal callbacks that
5320: ** implement SQL functions and aggregates. See
5321: ** [sqlite3_create_function()] and [sqlite3_create_function16()]
5322: ** for additional information.
5323: **
5324: ** These functions work very much like the [parameter binding] family of
5325: ** functions used to bind values to host parameters in prepared statements.
5326: ** Refer to the [SQL parameter] documentation for additional information.
5327: **
5328: ** ^The sqlite3_result_blob() interface sets the result from
5329: ** an application-defined function to be the BLOB whose content is pointed
5330: ** to by the second parameter and which is N bytes long where N is the
5331: ** third parameter.
5332: **
1.4 misho 5333: ** ^The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N)
5334: ** interfaces set the result of the application-defined function to be
5335: ** a BLOB containing all zero bytes and N bytes in size.
1.2 misho 5336: **
5337: ** ^The sqlite3_result_double() interface sets the result from
5338: ** an application-defined function to be a floating point value specified
5339: ** by its 2nd argument.
5340: **
5341: ** ^The sqlite3_result_error() and sqlite3_result_error16() functions
5342: ** cause the implemented SQL function to throw an exception.
5343: ** ^SQLite uses the string pointed to by the
5344: ** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
5345: ** as the text of an error message. ^SQLite interprets the error
5346: ** message string from sqlite3_result_error() as UTF-8. ^SQLite
5347: ** interprets the string from sqlite3_result_error16() as UTF-16 in native
5348: ** byte order. ^If the third parameter to sqlite3_result_error()
5349: ** or sqlite3_result_error16() is negative then SQLite takes as the error
5350: ** message all text up through the first zero character.
5351: ** ^If the third parameter to sqlite3_result_error() or
5352: ** sqlite3_result_error16() is non-negative then SQLite takes that many
5353: ** bytes (not characters) from the 2nd parameter as the error message.
5354: ** ^The sqlite3_result_error() and sqlite3_result_error16()
5355: ** routines make a private copy of the error message text before
5356: ** they return. Hence, the calling function can deallocate or
5357: ** modify the text after they return without harm.
5358: ** ^The sqlite3_result_error_code() function changes the error code
5359: ** returned by SQLite as a result of an error in a function. ^By default,
5360: ** the error code is SQLITE_ERROR. ^A subsequent call to sqlite3_result_error()
5361: ** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.
5362: **
1.3 misho 5363: ** ^The sqlite3_result_error_toobig() interface causes SQLite to throw an
5364: ** error indicating that a string or BLOB is too long to represent.
1.2 misho 5365: **
1.3 misho 5366: ** ^The sqlite3_result_error_nomem() interface causes SQLite to throw an
5367: ** error indicating that a memory allocation failed.
1.2 misho 5368: **
5369: ** ^The sqlite3_result_int() interface sets the return value
5370: ** of the application-defined function to be the 32-bit signed integer
5371: ** value given in the 2nd argument.
5372: ** ^The sqlite3_result_int64() interface sets the return value
5373: ** of the application-defined function to be the 64-bit signed integer
5374: ** value given in the 2nd argument.
5375: **
5376: ** ^The sqlite3_result_null() interface sets the return value
5377: ** of the application-defined function to be NULL.
5378: **
5379: ** ^The sqlite3_result_text(), sqlite3_result_text16(),
5380: ** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
5381: ** set the return value of the application-defined function to be
5382: ** a text string which is represented as UTF-8, UTF-16 native byte order,
5383: ** UTF-16 little endian, or UTF-16 big endian, respectively.
1.4 misho 5384: ** ^The sqlite3_result_text64() interface sets the return value of an
5385: ** application-defined function to be a text string in an encoding
5386: ** specified by the fifth (and last) parameter, which must be one
5387: ** of [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE].
1.2 misho 5388: ** ^SQLite takes the text result from the application from
5389: ** the 2nd parameter of the sqlite3_result_text* interfaces.
5390: ** ^If the 3rd parameter to the sqlite3_result_text* interfaces
5391: ** is negative, then SQLite takes result text from the 2nd parameter
5392: ** through the first zero character.
5393: ** ^If the 3rd parameter to the sqlite3_result_text* interfaces
5394: ** is non-negative, then as many bytes (not characters) of the text
5395: ** pointed to by the 2nd parameter are taken as the application-defined
5396: ** function result. If the 3rd parameter is non-negative, then it
5397: ** must be the byte offset into the string where the NUL terminator would
5398: ** appear if the string where NUL terminated. If any NUL characters occur
5399: ** in the string at a byte offset that is less than the value of the 3rd
5400: ** parameter, then the resulting string will contain embedded NULs and the
5401: ** result of expressions operating on strings with embedded NULs is undefined.
5402: ** ^If the 4th parameter to the sqlite3_result_text* interfaces
5403: ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
5404: ** function as the destructor on the text or BLOB result when it has
5405: ** finished using that result.
5406: ** ^If the 4th parameter to the sqlite3_result_text* interfaces or to
5407: ** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
5408: ** assumes that the text or BLOB result is in constant space and does not
5409: ** copy the content of the parameter nor call a destructor on the content
5410: ** when it has finished using that result.
5411: ** ^If the 4th parameter to the sqlite3_result_text* interfaces
5412: ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
1.4.2.2 ! misho 5413: ** then SQLite makes a copy of the result into space obtained
1.2 misho 5414: ** from [sqlite3_malloc()] before it returns.
5415: **
5416: ** ^The sqlite3_result_value() interface sets the result of
1.4 misho 5417: ** the application-defined function to be a copy of the
1.2 misho 5418: ** [unprotected sqlite3_value] object specified by the 2nd parameter. ^The
5419: ** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
5420: ** so that the [sqlite3_value] specified in the parameter may change or
5421: ** be deallocated after sqlite3_result_value() returns without harm.
5422: ** ^A [protected sqlite3_value] object may always be used where an
5423: ** [unprotected sqlite3_value] object is required, so either
5424: ** kind of [sqlite3_value] object can be used with this interface.
5425: **
1.4.2.2 ! misho 5426: ** ^The sqlite3_result_pointer(C,P,T,D) interface sets the result to an
! 5427: ** SQL NULL value, just like [sqlite3_result_null(C)], except that it
! 5428: ** also associates the host-language pointer P or type T with that
! 5429: ** NULL value such that the pointer can be retrieved within an
! 5430: ** [application-defined SQL function] using [sqlite3_value_pointer()].
! 5431: ** ^If the D parameter is not NULL, then it is a pointer to a destructor
! 5432: ** for the P parameter. ^SQLite invokes D with P as its only argument
! 5433: ** when SQLite is finished with P. The T parameter should be a static
! 5434: ** string and preferably a string literal. The sqlite3_result_pointer()
! 5435: ** routine is part of the [pointer passing interface] added for SQLite 3.20.0.
! 5436: **
1.2 misho 5437: ** If these routines are called from within the different thread
5438: ** than the one containing the application-defined function that received
5439: ** the [sqlite3_context] pointer, the results are undefined.
5440: */
5441: SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
1.4 misho 5442: SQLITE_API void sqlite3_result_blob64(sqlite3_context*,const void*,
5443: sqlite3_uint64,void(*)(void*));
1.2 misho 5444: SQLITE_API void sqlite3_result_double(sqlite3_context*, double);
5445: SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int);
5446: SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int);
5447: SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*);
5448: SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*);
5449: SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int);
5450: SQLITE_API void sqlite3_result_int(sqlite3_context*, int);
5451: SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
5452: SQLITE_API void sqlite3_result_null(sqlite3_context*);
5453: SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
1.4 misho 5454: SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64,
5455: void(*)(void*), unsigned char encoding);
1.2 misho 5456: SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
5457: SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
5458: SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
5459: SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
1.4.2.2 ! misho 5460: SQLITE_API void sqlite3_result_pointer(sqlite3_context*, void*,const char*,void(*)(void*));
1.2 misho 5461: SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
1.4 misho 5462: SQLITE_API int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);
5463:
5464:
5465: /*
5466: ** CAPI3REF: Setting The Subtype Of An SQL Function
5467: ** METHOD: sqlite3_context
5468: **
5469: ** The sqlite3_result_subtype(C,T) function causes the subtype of
5470: ** the result from the [application-defined SQL function] with
5471: ** [sqlite3_context] C to be the value T. Only the lower 8 bits
5472: ** of the subtype T are preserved in current versions of SQLite;
5473: ** higher order bits are discarded.
5474: ** The number of subtype bytes preserved by SQLite might increase
5475: ** in future releases of SQLite.
5476: */
5477: SQLITE_API void sqlite3_result_subtype(sqlite3_context*,unsigned int);
1.2 misho 5478:
5479: /*
5480: ** CAPI3REF: Define New Collating Sequences
1.4 misho 5481: ** METHOD: sqlite3
1.2 misho 5482: **
5483: ** ^These functions add, remove, or modify a [collation] associated
5484: ** with the [database connection] specified as the first argument.
5485: **
5486: ** ^The name of the collation is a UTF-8 string
5487: ** for sqlite3_create_collation() and sqlite3_create_collation_v2()
5488: ** and a UTF-16 string in native byte order for sqlite3_create_collation16().
5489: ** ^Collation names that compare equal according to [sqlite3_strnicmp()] are
5490: ** considered to be the same name.
5491: **
5492: ** ^(The third argument (eTextRep) must be one of the constants:
5493: ** <ul>
5494: ** <li> [SQLITE_UTF8],
5495: ** <li> [SQLITE_UTF16LE],
5496: ** <li> [SQLITE_UTF16BE],
5497: ** <li> [SQLITE_UTF16], or
5498: ** <li> [SQLITE_UTF16_ALIGNED].
5499: ** </ul>)^
5500: ** ^The eTextRep argument determines the encoding of strings passed
5501: ** to the collating function callback, xCallback.
5502: ** ^The [SQLITE_UTF16] and [SQLITE_UTF16_ALIGNED] values for eTextRep
5503: ** force strings to be UTF16 with native byte order.
5504: ** ^The [SQLITE_UTF16_ALIGNED] value for eTextRep forces strings to begin
5505: ** on an even byte address.
5506: **
5507: ** ^The fourth argument, pArg, is an application data pointer that is passed
5508: ** through as the first argument to the collating function callback.
5509: **
5510: ** ^The fifth argument, xCallback, is a pointer to the collating function.
5511: ** ^Multiple collating functions can be registered using the same name but
5512: ** with different eTextRep parameters and SQLite will use whichever
5513: ** function requires the least amount of data transformation.
5514: ** ^If the xCallback argument is NULL then the collating function is
5515: ** deleted. ^When all collating functions having the same name are deleted,
5516: ** that collation is no longer usable.
5517: **
5518: ** ^The collating function callback is invoked with a copy of the pArg
5519: ** application data pointer and with two strings in the encoding specified
5520: ** by the eTextRep argument. The collating function must return an
5521: ** integer that is negative, zero, or positive
5522: ** if the first string is less than, equal to, or greater than the second,
5523: ** respectively. A collating function must always return the same answer
5524: ** given the same inputs. If two or more collating functions are registered
5525: ** to the same collation name (using different eTextRep values) then all
5526: ** must give an equivalent answer when invoked with equivalent strings.
5527: ** The collating function must obey the following properties for all
5528: ** strings A, B, and C:
5529: **
5530: ** <ol>
5531: ** <li> If A==B then B==A.
5532: ** <li> If A==B and B==C then A==C.
5533: ** <li> If A<B THEN B>A.
5534: ** <li> If A<B and B<C then A<C.
5535: ** </ol>
5536: **
5537: ** If a collating function fails any of the above constraints and that
5538: ** collating function is registered and used, then the behavior of SQLite
5539: ** is undefined.
5540: **
5541: ** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation()
5542: ** with the addition that the xDestroy callback is invoked on pArg when
5543: ** the collating function is deleted.
5544: ** ^Collating functions are deleted when they are overridden by later
5545: ** calls to the collation creation functions or when the
5546: ** [database connection] is closed using [sqlite3_close()].
5547: **
5548: ** ^The xDestroy callback is <u>not</u> called if the
5549: ** sqlite3_create_collation_v2() function fails. Applications that invoke
5550: ** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should
5551: ** check the return code and dispose of the application data pointer
5552: ** themselves rather than expecting SQLite to deal with it for them.
5553: ** This is different from every other SQLite interface. The inconsistency
5554: ** is unfortunate but cannot be changed without breaking backwards
5555: ** compatibility.
5556: **
5557: ** See also: [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].
5558: */
5559: SQLITE_API int sqlite3_create_collation(
5560: sqlite3*,
5561: const char *zName,
5562: int eTextRep,
5563: void *pArg,
5564: int(*xCompare)(void*,int,const void*,int,const void*)
5565: );
5566: SQLITE_API int sqlite3_create_collation_v2(
5567: sqlite3*,
5568: const char *zName,
5569: int eTextRep,
5570: void *pArg,
5571: int(*xCompare)(void*,int,const void*,int,const void*),
5572: void(*xDestroy)(void*)
5573: );
5574: SQLITE_API int sqlite3_create_collation16(
5575: sqlite3*,
5576: const void *zName,
5577: int eTextRep,
5578: void *pArg,
5579: int(*xCompare)(void*,int,const void*,int,const void*)
5580: );
5581:
5582: /*
5583: ** CAPI3REF: Collation Needed Callbacks
1.4 misho 5584: ** METHOD: sqlite3
1.2 misho 5585: **
5586: ** ^To avoid having to register all collation sequences before a database
5587: ** can be used, a single callback function may be registered with the
5588: ** [database connection] to be invoked whenever an undefined collation
5589: ** sequence is required.
5590: **
5591: ** ^If the function is registered using the sqlite3_collation_needed() API,
5592: ** then it is passed the names of undefined collation sequences as strings
5593: ** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,
5594: ** the names are passed as UTF-16 in machine native byte order.
5595: ** ^A call to either function replaces the existing collation-needed callback.
5596: **
5597: ** ^(When the callback is invoked, the first argument passed is a copy
5598: ** of the second argument to sqlite3_collation_needed() or
5599: ** sqlite3_collation_needed16(). The second argument is the database
5600: ** connection. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],
5601: ** or [SQLITE_UTF16LE], indicating the most desirable form of the collation
5602: ** sequence function required. The fourth parameter is the name of the
5603: ** required collation sequence.)^
5604: **
5605: ** The callback function should register the desired collation using
5606: ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
5607: ** [sqlite3_create_collation_v2()].
5608: */
5609: SQLITE_API int sqlite3_collation_needed(
5610: sqlite3*,
5611: void*,
5612: void(*)(void*,sqlite3*,int eTextRep,const char*)
5613: );
5614: SQLITE_API int sqlite3_collation_needed16(
5615: sqlite3*,
5616: void*,
5617: void(*)(void*,sqlite3*,int eTextRep,const void*)
5618: );
5619:
5620: #ifdef SQLITE_HAS_CODEC
5621: /*
5622: ** Specify the key for an encrypted database. This routine should be
5623: ** called right after sqlite3_open().
5624: **
5625: ** The code to implement this API is not available in the public release
5626: ** of SQLite.
5627: */
5628: SQLITE_API int sqlite3_key(
5629: sqlite3 *db, /* Database to be rekeyed */
5630: const void *pKey, int nKey /* The key */
5631: );
1.4 misho 5632: SQLITE_API int sqlite3_key_v2(
5633: sqlite3 *db, /* Database to be rekeyed */
5634: const char *zDbName, /* Name of the database */
5635: const void *pKey, int nKey /* The key */
5636: );
1.2 misho 5637:
5638: /*
5639: ** Change the key on an open database. If the current database is not
5640: ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the
5641: ** database is decrypted.
5642: **
5643: ** The code to implement this API is not available in the public release
5644: ** of SQLite.
5645: */
5646: SQLITE_API int sqlite3_rekey(
5647: sqlite3 *db, /* Database to be rekeyed */
5648: const void *pKey, int nKey /* The new key */
5649: );
1.4 misho 5650: SQLITE_API int sqlite3_rekey_v2(
5651: sqlite3 *db, /* Database to be rekeyed */
5652: const char *zDbName, /* Name of the database */
5653: const void *pKey, int nKey /* The new key */
5654: );
1.2 misho 5655:
5656: /*
5657: ** Specify the activation key for a SEE database. Unless
5658: ** activated, none of the SEE routines will work.
5659: */
5660: SQLITE_API void sqlite3_activate_see(
5661: const char *zPassPhrase /* Activation phrase */
5662: );
5663: #endif
5664:
5665: #ifdef SQLITE_ENABLE_CEROD
5666: /*
5667: ** Specify the activation key for a CEROD database. Unless
5668: ** activated, none of the CEROD routines will work.
5669: */
5670: SQLITE_API void sqlite3_activate_cerod(
5671: const char *zPassPhrase /* Activation phrase */
5672: );
5673: #endif
5674:
5675: /*
5676: ** CAPI3REF: Suspend Execution For A Short Time
5677: **
5678: ** The sqlite3_sleep() function causes the current thread to suspend execution
5679: ** for at least a number of milliseconds specified in its parameter.
5680: **
5681: ** If the operating system does not support sleep requests with
5682: ** millisecond time resolution, then the time will be rounded up to
5683: ** the nearest second. The number of milliseconds of sleep actually
5684: ** requested from the operating system is returned.
5685: **
5686: ** ^SQLite implements this interface by calling the xSleep()
5687: ** method of the default [sqlite3_vfs] object. If the xSleep() method
5688: ** of the default VFS is not implemented correctly, or not implemented at
5689: ** all, then the behavior of sqlite3_sleep() may deviate from the description
5690: ** in the previous paragraphs.
5691: */
5692: SQLITE_API int sqlite3_sleep(int);
5693:
5694: /*
5695: ** CAPI3REF: Name Of The Folder Holding Temporary Files
5696: **
5697: ** ^(If this global variable is made to point to a string which is
5698: ** the name of a folder (a.k.a. directory), then all temporary files
5699: ** created by SQLite when using a built-in [sqlite3_vfs | VFS]
5700: ** will be placed in that directory.)^ ^If this variable
5701: ** is a NULL pointer, then SQLite performs a search for an appropriate
5702: ** temporary file directory.
5703: **
1.4 misho 5704: ** Applications are strongly discouraged from using this global variable.
5705: ** It is required to set a temporary folder on Windows Runtime (WinRT).
5706: ** But for all other platforms, it is highly recommended that applications
5707: ** neither read nor write this variable. This global variable is a relic
5708: ** that exists for backwards compatibility of legacy applications and should
5709: ** be avoided in new projects.
5710: **
1.2 misho 5711: ** It is not safe to read or modify this variable in more than one
5712: ** thread at a time. It is not safe to read or modify this variable
5713: ** if a [database connection] is being used at the same time in a separate
5714: ** thread.
5715: ** It is intended that this variable be set once
5716: ** as part of process initialization and before any SQLite interface
5717: ** routines have been called and that this variable remain unchanged
5718: ** thereafter.
5719: **
5720: ** ^The [temp_store_directory pragma] may modify this variable and cause
5721: ** it to point to memory obtained from [sqlite3_malloc]. ^Furthermore,
5722: ** the [temp_store_directory pragma] always assumes that any string
5723: ** that this variable points to is held in memory obtained from
5724: ** [sqlite3_malloc] and the pragma may attempt to free that memory
5725: ** using [sqlite3_free].
5726: ** Hence, if this variable is modified directly, either it should be
5727: ** made NULL or made to point to memory obtained from [sqlite3_malloc]
5728: ** or else the use of the [temp_store_directory pragma] should be avoided.
1.4 misho 5729: ** Except when requested by the [temp_store_directory pragma], SQLite
5730: ** does not free the memory that sqlite3_temp_directory points to. If
5731: ** the application wants that memory to be freed, it must do
5732: ** so itself, taking care to only do so after all [database connection]
5733: ** objects have been destroyed.
1.3 misho 5734: **
5735: ** <b>Note to Windows Runtime users:</b> The temporary directory must be set
5736: ** prior to calling [sqlite3_open] or [sqlite3_open_v2]. Otherwise, various
5737: ** features that require the use of temporary files may fail. Here is an
5738: ** example of how to do this using C++ with the Windows Runtime:
5739: **
5740: ** <blockquote><pre>
5741: ** LPCWSTR zPath = Windows::Storage::ApplicationData::Current->
5742: ** TemporaryFolder->Path->Data();
5743: ** char zPathBuf[MAX_PATH + 1];
5744: ** memset(zPathBuf, 0, sizeof(zPathBuf));
5745: ** WideCharToMultiByte(CP_UTF8, 0, zPath, -1, zPathBuf, sizeof(zPathBuf),
5746: ** NULL, NULL);
5747: ** sqlite3_temp_directory = sqlite3_mprintf("%s", zPathBuf);
5748: ** </pre></blockquote>
1.2 misho 5749: */
5750: SQLITE_API SQLITE_EXTERN char *sqlite3_temp_directory;
5751:
5752: /*
1.3 misho 5753: ** CAPI3REF: Name Of The Folder Holding Database Files
5754: **
5755: ** ^(If this global variable is made to point to a string which is
5756: ** the name of a folder (a.k.a. directory), then all database files
5757: ** specified with a relative pathname and created or accessed by
5758: ** SQLite when using a built-in windows [sqlite3_vfs | VFS] will be assumed
5759: ** to be relative to that directory.)^ ^If this variable is a NULL
5760: ** pointer, then SQLite assumes that all database files specified
5761: ** with a relative pathname are relative to the current directory
5762: ** for the process. Only the windows VFS makes use of this global
5763: ** variable; it is ignored by the unix VFS.
5764: **
5765: ** Changing the value of this variable while a database connection is
5766: ** open can result in a corrupt database.
5767: **
5768: ** It is not safe to read or modify this variable in more than one
5769: ** thread at a time. It is not safe to read or modify this variable
5770: ** if a [database connection] is being used at the same time in a separate
5771: ** thread.
5772: ** It is intended that this variable be set once
5773: ** as part of process initialization and before any SQLite interface
5774: ** routines have been called and that this variable remain unchanged
5775: ** thereafter.
5776: **
5777: ** ^The [data_store_directory pragma] may modify this variable and cause
5778: ** it to point to memory obtained from [sqlite3_malloc]. ^Furthermore,
5779: ** the [data_store_directory pragma] always assumes that any string
5780: ** that this variable points to is held in memory obtained from
5781: ** [sqlite3_malloc] and the pragma may attempt to free that memory
5782: ** using [sqlite3_free].
5783: ** Hence, if this variable is modified directly, either it should be
5784: ** made NULL or made to point to memory obtained from [sqlite3_malloc]
5785: ** or else the use of the [data_store_directory pragma] should be avoided.
5786: */
5787: SQLITE_API SQLITE_EXTERN char *sqlite3_data_directory;
5788:
5789: /*
1.4.2.2 ! misho 5790: ** CAPI3REF: Win32 Specific Interface
! 5791: **
! 5792: ** These interfaces are available only on Windows. The
! 5793: ** [sqlite3_win32_set_directory] interface is used to set the value associated
! 5794: ** with the [sqlite3_temp_directory] or [sqlite3_data_directory] variable, to
! 5795: ** zValue, depending on the value of the type parameter. The zValue parameter
! 5796: ** should be NULL to cause the previous value to be freed via [sqlite3_free];
! 5797: ** a non-NULL value will be copied into memory obtained from [sqlite3_malloc]
! 5798: ** prior to being used. The [sqlite3_win32_set_directory] interface returns
! 5799: ** [SQLITE_OK] to indicate success, [SQLITE_ERROR] if the type is unsupported,
! 5800: ** or [SQLITE_NOMEM] if memory could not be allocated. The value of the
! 5801: ** [sqlite3_data_directory] variable is intended to act as a replacement for
! 5802: ** the current directory on the sub-platforms of Win32 where that concept is
! 5803: ** not present, e.g. WinRT and UWP. The [sqlite3_win32_set_directory8] and
! 5804: ** [sqlite3_win32_set_directory16] interfaces behave exactly the same as the
! 5805: ** sqlite3_win32_set_directory interface except the string parameter must be
! 5806: ** UTF-8 or UTF-16, respectively.
! 5807: */
! 5808: SQLITE_API int sqlite3_win32_set_directory(
! 5809: unsigned long type, /* Identifier for directory being set or reset */
! 5810: void *zValue /* New value for directory being set or reset */
! 5811: );
! 5812: SQLITE_API int sqlite3_win32_set_directory8(unsigned long type, const char *zValue);
! 5813: SQLITE_API int sqlite3_win32_set_directory16(unsigned long type, const void *zValue);
! 5814:
! 5815: /*
! 5816: ** CAPI3REF: Win32 Directory Types
! 5817: **
! 5818: ** These macros are only available on Windows. They define the allowed values
! 5819: ** for the type argument to the [sqlite3_win32_set_directory] interface.
! 5820: */
! 5821: #define SQLITE_WIN32_DATA_DIRECTORY_TYPE 1
! 5822: #define SQLITE_WIN32_TEMP_DIRECTORY_TYPE 2
! 5823:
! 5824: /*
1.2 misho 5825: ** CAPI3REF: Test For Auto-Commit Mode
5826: ** KEYWORDS: {autocommit mode}
1.4 misho 5827: ** METHOD: sqlite3
1.2 misho 5828: **
5829: ** ^The sqlite3_get_autocommit() interface returns non-zero or
5830: ** zero if the given database connection is or is not in autocommit mode,
5831: ** respectively. ^Autocommit mode is on by default.
5832: ** ^Autocommit mode is disabled by a [BEGIN] statement.
5833: ** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
5834: **
5835: ** If certain kinds of errors occur on a statement within a multi-statement
5836: ** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR],
5837: ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
5838: ** transaction might be rolled back automatically. The only way to
5839: ** find out whether SQLite automatically rolled back the transaction after
5840: ** an error is to use this function.
5841: **
5842: ** If another thread changes the autocommit status of the database
5843: ** connection while this routine is running, then the return value
5844: ** is undefined.
5845: */
5846: SQLITE_API int sqlite3_get_autocommit(sqlite3*);
5847:
5848: /*
5849: ** CAPI3REF: Find The Database Handle Of A Prepared Statement
1.4 misho 5850: ** METHOD: sqlite3_stmt
1.2 misho 5851: **
5852: ** ^The sqlite3_db_handle interface returns the [database connection] handle
5853: ** to which a [prepared statement] belongs. ^The [database connection]
5854: ** returned by sqlite3_db_handle is the same [database connection]
5855: ** that was the first argument
5856: ** to the [sqlite3_prepare_v2()] call (or its variants) that was used to
5857: ** create the statement in the first place.
5858: */
5859: SQLITE_API sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
5860:
5861: /*
5862: ** CAPI3REF: Return The Filename For A Database Connection
1.4 misho 5863: ** METHOD: sqlite3
1.2 misho 5864: **
5865: ** ^The sqlite3_db_filename(D,N) interface returns a pointer to a filename
5866: ** associated with database N of connection D. ^The main database file
5867: ** has the name "main". If there is no attached database N on the database
5868: ** connection D, or if database N is a temporary or in-memory database, then
1.4.2.2 ! misho 5869: ** this function will return either a NULL pointer or an empty string.
1.2 misho 5870: **
5871: ** ^The filename returned by this function is the output of the
5872: ** xFullPathname method of the [VFS]. ^In other words, the filename
5873: ** will be an absolute pathname, even if the filename used
5874: ** to open the database originally was a URI or relative pathname.
5875: */
5876: SQLITE_API const char *sqlite3_db_filename(sqlite3 *db, const char *zDbName);
5877:
5878: /*
1.3 misho 5879: ** CAPI3REF: Determine if a database is read-only
1.4 misho 5880: ** METHOD: sqlite3
1.3 misho 5881: **
5882: ** ^The sqlite3_db_readonly(D,N) interface returns 1 if the database N
5883: ** of connection D is read-only, 0 if it is read/write, or -1 if N is not
5884: ** the name of a database on connection D.
5885: */
5886: SQLITE_API int sqlite3_db_readonly(sqlite3 *db, const char *zDbName);
5887:
5888: /*
1.2 misho 5889: ** CAPI3REF: Find the next prepared statement
1.4 misho 5890: ** METHOD: sqlite3
1.2 misho 5891: **
5892: ** ^This interface returns a pointer to the next [prepared statement] after
5893: ** pStmt associated with the [database connection] pDb. ^If pStmt is NULL
5894: ** then this interface returns a pointer to the first prepared statement
5895: ** associated with the database connection pDb. ^If no prepared statement
5896: ** satisfies the conditions of this routine, it returns NULL.
5897: **
5898: ** The [database connection] pointer D in a call to
5899: ** [sqlite3_next_stmt(D,S)] must refer to an open database
5900: ** connection and in particular must not be a NULL pointer.
5901: */
5902: SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
5903:
5904: /*
5905: ** CAPI3REF: Commit And Rollback Notification Callbacks
1.4 misho 5906: ** METHOD: sqlite3
1.2 misho 5907: **
5908: ** ^The sqlite3_commit_hook() interface registers a callback
5909: ** function to be invoked whenever a transaction is [COMMIT | committed].
5910: ** ^Any callback set by a previous call to sqlite3_commit_hook()
5911: ** for the same database connection is overridden.
5912: ** ^The sqlite3_rollback_hook() interface registers a callback
5913: ** function to be invoked whenever a transaction is [ROLLBACK | rolled back].
5914: ** ^Any callback set by a previous call to sqlite3_rollback_hook()
5915: ** for the same database connection is overridden.
5916: ** ^The pArg argument is passed through to the callback.
5917: ** ^If the callback on a commit hook function returns non-zero,
5918: ** then the commit is converted into a rollback.
5919: **
5920: ** ^The sqlite3_commit_hook(D,C,P) and sqlite3_rollback_hook(D,C,P) functions
5921: ** return the P argument from the previous call of the same function
5922: ** on the same [database connection] D, or NULL for
5923: ** the first call for each function on D.
5924: **
5925: ** The commit and rollback hook callbacks are not reentrant.
5926: ** The callback implementation must not do anything that will modify
5927: ** the database connection that invoked the callback. Any actions
5928: ** to modify the database connection must be deferred until after the
5929: ** completion of the [sqlite3_step()] call that triggered the commit
5930: ** or rollback hook in the first place.
5931: ** Note that running any other SQL statements, including SELECT statements,
5932: ** or merely calling [sqlite3_prepare_v2()] and [sqlite3_step()] will modify
5933: ** the database connections for the meaning of "modify" in this paragraph.
5934: **
5935: ** ^Registering a NULL function disables the callback.
5936: **
5937: ** ^When the commit hook callback routine returns zero, the [COMMIT]
5938: ** operation is allowed to continue normally. ^If the commit hook
5939: ** returns non-zero, then the [COMMIT] is converted into a [ROLLBACK].
5940: ** ^The rollback hook is invoked on a rollback that results from a commit
5941: ** hook returning non-zero, just as it would be with any other rollback.
5942: **
5943: ** ^For the purposes of this API, a transaction is said to have been
5944: ** rolled back if an explicit "ROLLBACK" statement is executed, or
5945: ** an error or constraint causes an implicit rollback to occur.
5946: ** ^The rollback callback is not invoked if a transaction is
5947: ** automatically rolled back because the database connection is closed.
5948: **
5949: ** See also the [sqlite3_update_hook()] interface.
5950: */
5951: SQLITE_API void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
5952: SQLITE_API void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
5953:
5954: /*
5955: ** CAPI3REF: Data Change Notification Callbacks
1.4 misho 5956: ** METHOD: sqlite3
1.2 misho 5957: **
5958: ** ^The sqlite3_update_hook() interface registers a callback function
5959: ** with the [database connection] identified by the first argument
1.4 misho 5960: ** to be invoked whenever a row is updated, inserted or deleted in
5961: ** a [rowid table].
1.2 misho 5962: ** ^Any callback set by a previous call to this function
5963: ** for the same database connection is overridden.
5964: **
5965: ** ^The second argument is a pointer to the function to invoke when a
1.4 misho 5966: ** row is updated, inserted or deleted in a rowid table.
1.2 misho 5967: ** ^The first argument to the callback is a copy of the third argument
5968: ** to sqlite3_update_hook().
5969: ** ^The second callback argument is one of [SQLITE_INSERT], [SQLITE_DELETE],
5970: ** or [SQLITE_UPDATE], depending on the operation that caused the callback
5971: ** to be invoked.
5972: ** ^The third and fourth arguments to the callback contain pointers to the
5973: ** database and table name containing the affected row.
5974: ** ^The final callback parameter is the [rowid] of the row.
5975: ** ^In the case of an update, this is the [rowid] after the update takes place.
5976: **
5977: ** ^(The update hook is not invoked when internal system tables are
5978: ** modified (i.e. sqlite_master and sqlite_sequence).)^
1.4 misho 5979: ** ^The update hook is not invoked when [WITHOUT ROWID] tables are modified.
1.2 misho 5980: **
5981: ** ^In the current implementation, the update hook
1.4.2.1 misho 5982: ** is not invoked when conflicting rows are deleted because of an
1.2 misho 5983: ** [ON CONFLICT | ON CONFLICT REPLACE] clause. ^Nor is the update hook
5984: ** invoked when rows are deleted using the [truncate optimization].
5985: ** The exceptions defined in this paragraph might change in a future
5986: ** release of SQLite.
5987: **
5988: ** The update hook implementation must not do anything that will modify
5989: ** the database connection that invoked the update hook. Any actions
5990: ** to modify the database connection must be deferred until after the
5991: ** completion of the [sqlite3_step()] call that triggered the update hook.
5992: ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
5993: ** database connections for the meaning of "modify" in this paragraph.
5994: **
5995: ** ^The sqlite3_update_hook(D,C,P) function
5996: ** returns the P argument from the previous call
5997: ** on the same [database connection] D, or NULL for
5998: ** the first call on D.
5999: **
1.4 misho 6000: ** See also the [sqlite3_commit_hook()], [sqlite3_rollback_hook()],
6001: ** and [sqlite3_preupdate_hook()] interfaces.
1.2 misho 6002: */
6003: SQLITE_API void *sqlite3_update_hook(
6004: sqlite3*,
6005: void(*)(void *,int ,char const *,char const *,sqlite3_int64),
6006: void*
6007: );
6008:
6009: /*
6010: ** CAPI3REF: Enable Or Disable Shared Pager Cache
6011: **
6012: ** ^(This routine enables or disables the sharing of the database cache
6013: ** and schema data structures between [database connection | connections]
6014: ** to the same database. Sharing is enabled if the argument is true
6015: ** and disabled if the argument is false.)^
6016: **
6017: ** ^Cache sharing is enabled and disabled for an entire process.
1.4.2.1 misho 6018: ** This is a change as of SQLite [version 3.5.0] ([dateof:3.5.0]).
6019: ** In prior versions of SQLite,
1.2 misho 6020: ** sharing was enabled or disabled for each thread separately.
6021: **
6022: ** ^(The cache sharing mode set by this interface effects all subsequent
6023: ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
6024: ** Existing database connections continue use the sharing mode
6025: ** that was in effect at the time they were opened.)^
6026: **
6027: ** ^(This routine returns [SQLITE_OK] if shared cache was enabled or disabled
6028: ** successfully. An [error code] is returned otherwise.)^
6029: **
6030: ** ^Shared cache is disabled by default. But this might change in
6031: ** future releases of SQLite. Applications that care about shared
6032: ** cache setting should set it explicitly.
6033: **
1.4 misho 6034: ** Note: This method is disabled on MacOS X 10.7 and iOS version 5.0
6035: ** and will always return SQLITE_MISUSE. On those systems,
6036: ** shared cache mode should be enabled per-database connection via
6037: ** [sqlite3_open_v2()] with [SQLITE_OPEN_SHAREDCACHE].
6038: **
1.3 misho 6039: ** This interface is threadsafe on processors where writing a
6040: ** 32-bit integer is atomic.
6041: **
1.2 misho 6042: ** See Also: [SQLite Shared-Cache Mode]
6043: */
6044: SQLITE_API int sqlite3_enable_shared_cache(int);
6045:
6046: /*
6047: ** CAPI3REF: Attempt To Free Heap Memory
6048: **
6049: ** ^The sqlite3_release_memory() interface attempts to free N bytes
6050: ** of heap memory by deallocating non-essential memory allocations
6051: ** held by the database library. Memory used to cache database
6052: ** pages to improve performance is an example of non-essential memory.
6053: ** ^sqlite3_release_memory() returns the number of bytes actually freed,
6054: ** which might be more or less than the amount requested.
6055: ** ^The sqlite3_release_memory() routine is a no-op returning zero
6056: ** if SQLite is not compiled with [SQLITE_ENABLE_MEMORY_MANAGEMENT].
6057: **
6058: ** See also: [sqlite3_db_release_memory()]
6059: */
6060: SQLITE_API int sqlite3_release_memory(int);
6061:
6062: /*
6063: ** CAPI3REF: Free Memory Used By A Database Connection
1.4 misho 6064: ** METHOD: sqlite3
1.2 misho 6065: **
6066: ** ^The sqlite3_db_release_memory(D) interface attempts to free as much heap
6067: ** memory as possible from database connection D. Unlike the
1.4 misho 6068: ** [sqlite3_release_memory()] interface, this interface is in effect even
6069: ** when the [SQLITE_ENABLE_MEMORY_MANAGEMENT] compile-time option is
1.2 misho 6070: ** omitted.
6071: **
6072: ** See also: [sqlite3_release_memory()]
6073: */
6074: SQLITE_API int sqlite3_db_release_memory(sqlite3*);
6075:
6076: /*
6077: ** CAPI3REF: Impose A Limit On Heap Size
6078: **
6079: ** ^The sqlite3_soft_heap_limit64() interface sets and/or queries the
6080: ** soft limit on the amount of heap memory that may be allocated by SQLite.
6081: ** ^SQLite strives to keep heap memory utilization below the soft heap
6082: ** limit by reducing the number of pages held in the page cache
6083: ** as heap memory usages approaches the limit.
6084: ** ^The soft heap limit is "soft" because even though SQLite strives to stay
6085: ** below the limit, it will exceed the limit rather than generate
6086: ** an [SQLITE_NOMEM] error. In other words, the soft heap limit
6087: ** is advisory only.
6088: **
6089: ** ^The return value from sqlite3_soft_heap_limit64() is the size of
6090: ** the soft heap limit prior to the call, or negative in the case of an
6091: ** error. ^If the argument N is negative
6092: ** then no change is made to the soft heap limit. Hence, the current
6093: ** size of the soft heap limit can be determined by invoking
6094: ** sqlite3_soft_heap_limit64() with a negative argument.
6095: **
6096: ** ^If the argument N is zero then the soft heap limit is disabled.
6097: **
6098: ** ^(The soft heap limit is not enforced in the current implementation
6099: ** if one or more of following conditions are true:
6100: **
6101: ** <ul>
6102: ** <li> The soft heap limit is set to zero.
6103: ** <li> Memory accounting is disabled using a combination of the
6104: ** [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],...) start-time option and
6105: ** the [SQLITE_DEFAULT_MEMSTATUS] compile-time option.
6106: ** <li> An alternative page cache implementation is specified using
6107: ** [sqlite3_config]([SQLITE_CONFIG_PCACHE2],...).
6108: ** <li> The page cache allocates from its own memory pool supplied
6109: ** by [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],...) rather than
6110: ** from the heap.
6111: ** </ul>)^
6112: **
1.4.2.1 misho 6113: ** Beginning with SQLite [version 3.7.3] ([dateof:3.7.3]),
6114: ** the soft heap limit is enforced
1.2 misho 6115: ** regardless of whether or not the [SQLITE_ENABLE_MEMORY_MANAGEMENT]
6116: ** compile-time option is invoked. With [SQLITE_ENABLE_MEMORY_MANAGEMENT],
6117: ** the soft heap limit is enforced on every memory allocation. Without
6118: ** [SQLITE_ENABLE_MEMORY_MANAGEMENT], the soft heap limit is only enforced
6119: ** when memory is allocated by the page cache. Testing suggests that because
6120: ** the page cache is the predominate memory user in SQLite, most
6121: ** applications will achieve adequate soft heap limit enforcement without
6122: ** the use of [SQLITE_ENABLE_MEMORY_MANAGEMENT].
6123: **
6124: ** The circumstances under which SQLite will enforce the soft heap limit may
6125: ** changes in future releases of SQLite.
6126: */
6127: SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);
6128:
6129: /*
6130: ** CAPI3REF: Deprecated Soft Heap Limit Interface
6131: ** DEPRECATED
6132: **
6133: ** This is a deprecated version of the [sqlite3_soft_heap_limit64()]
6134: ** interface. This routine is provided for historical compatibility
6135: ** only. All new applications should use the
6136: ** [sqlite3_soft_heap_limit64()] interface rather than this one.
6137: */
6138: SQLITE_API SQLITE_DEPRECATED void sqlite3_soft_heap_limit(int N);
6139:
6140:
6141: /*
6142: ** CAPI3REF: Extract Metadata About A Column Of A Table
1.4 misho 6143: ** METHOD: sqlite3
1.2 misho 6144: **
1.4 misho 6145: ** ^(The sqlite3_table_column_metadata(X,D,T,C,....) routine returns
6146: ** information about column C of table T in database D
6147: ** on [database connection] X.)^ ^The sqlite3_table_column_metadata()
6148: ** interface returns SQLITE_OK and fills in the non-NULL pointers in
6149: ** the final five arguments with appropriate values if the specified
6150: ** column exists. ^The sqlite3_table_column_metadata() interface returns
6151: ** SQLITE_ERROR and if the specified column does not exist.
6152: ** ^If the column-name parameter to sqlite3_table_column_metadata() is a
6153: ** NULL pointer, then this routine simply checks for the existence of the
6154: ** table and returns SQLITE_OK if the table exists and SQLITE_ERROR if it
1.4.2.2 ! misho 6155: ** does not. If the table name parameter T in a call to
! 6156: ** sqlite3_table_column_metadata(X,D,T,C,...) is NULL then the result is
! 6157: ** undefined behavior.
1.2 misho 6158: **
6159: ** ^The column is identified by the second, third and fourth parameters to
1.4 misho 6160: ** this function. ^(The second parameter is either the name of the database
1.2 misho 6161: ** (i.e. "main", "temp", or an attached database) containing the specified
1.4 misho 6162: ** table or NULL.)^ ^If it is NULL, then all attached databases are searched
1.2 misho 6163: ** for the table using the same algorithm used by the database engine to
6164: ** resolve unqualified table references.
6165: **
6166: ** ^The third and fourth parameters to this function are the table and column
1.4 misho 6167: ** name of the desired column, respectively.
1.2 misho 6168: **
6169: ** ^Metadata is returned by writing to the memory locations passed as the 5th
6170: ** and subsequent parameters to this function. ^Any of these arguments may be
6171: ** NULL, in which case the corresponding element of metadata is omitted.
6172: **
6173: ** ^(<blockquote>
6174: ** <table border="1">
6175: ** <tr><th> Parameter <th> Output<br>Type <th> Description
6176: **
6177: ** <tr><td> 5th <td> const char* <td> Data type
6178: ** <tr><td> 6th <td> const char* <td> Name of default collation sequence
6179: ** <tr><td> 7th <td> int <td> True if column has a NOT NULL constraint
6180: ** <tr><td> 8th <td> int <td> True if column is part of the PRIMARY KEY
6181: ** <tr><td> 9th <td> int <td> True if column is [AUTOINCREMENT]
6182: ** </table>
6183: ** </blockquote>)^
6184: **
6185: ** ^The memory pointed to by the character pointers returned for the
1.4 misho 6186: ** declaration type and collation sequence is valid until the next
1.2 misho 6187: ** call to any SQLite API function.
6188: **
6189: ** ^If the specified table is actually a view, an [error code] is returned.
6190: **
1.4 misho 6191: ** ^If the specified column is "rowid", "oid" or "_rowid_" and the table
6192: ** is not a [WITHOUT ROWID] table and an
1.2 misho 6193: ** [INTEGER PRIMARY KEY] column has been explicitly declared, then the output
6194: ** parameters are set for the explicitly declared column. ^(If there is no
1.4 misho 6195: ** [INTEGER PRIMARY KEY] column, then the outputs
6196: ** for the [rowid] are set as follows:
1.2 misho 6197: **
6198: ** <pre>
6199: ** data type: "INTEGER"
6200: ** collation sequence: "BINARY"
6201: ** not null: 0
6202: ** primary key: 1
6203: ** auto increment: 0
6204: ** </pre>)^
6205: **
1.4 misho 6206: ** ^This function causes all database schemas to be read from disk and
6207: ** parsed, if that has not already been done, and returns an error if
6208: ** any errors are encountered while loading the schema.
1.2 misho 6209: */
6210: SQLITE_API int sqlite3_table_column_metadata(
6211: sqlite3 *db, /* Connection handle */
6212: const char *zDbName, /* Database name or NULL */
6213: const char *zTableName, /* Table name */
6214: const char *zColumnName, /* Column name */
6215: char const **pzDataType, /* OUTPUT: Declared data type */
6216: char const **pzCollSeq, /* OUTPUT: Collation sequence name */
6217: int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */
6218: int *pPrimaryKey, /* OUTPUT: True if column part of PK */
6219: int *pAutoinc /* OUTPUT: True if column is auto-increment */
6220: );
6221:
6222: /*
6223: ** CAPI3REF: Load An Extension
1.4 misho 6224: ** METHOD: sqlite3
1.2 misho 6225: **
6226: ** ^This interface loads an SQLite extension library from the named file.
6227: **
6228: ** ^The sqlite3_load_extension() interface attempts to load an
1.4 misho 6229: ** [SQLite extension] library contained in the file zFile. If
6230: ** the file cannot be loaded directly, attempts are made to load
6231: ** with various operating-system specific extensions added.
6232: ** So for example, if "samplelib" cannot be loaded, then names like
6233: ** "samplelib.so" or "samplelib.dylib" or "samplelib.dll" might
6234: ** be tried also.
1.2 misho 6235: **
6236: ** ^The entry point is zProc.
1.4 misho 6237: ** ^(zProc may be 0, in which case SQLite will try to come up with an
6238: ** entry point name on its own. It first tries "sqlite3_extension_init".
6239: ** If that does not work, it constructs a name "sqlite3_X_init" where the
6240: ** X is consists of the lower-case equivalent of all ASCII alphabetic
6241: ** characters in the filename from the last "/" to the first following
6242: ** "." and omitting any initial "lib".)^
1.2 misho 6243: ** ^The sqlite3_load_extension() interface returns
6244: ** [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
6245: ** ^If an error occurs and pzErrMsg is not 0, then the
6246: ** [sqlite3_load_extension()] interface shall attempt to
6247: ** fill *pzErrMsg with error message text stored in memory
6248: ** obtained from [sqlite3_malloc()]. The calling function
6249: ** should free this memory by calling [sqlite3_free()].
6250: **
6251: ** ^Extension loading must be enabled using
1.4 misho 6252: ** [sqlite3_enable_load_extension()] or
6253: ** [sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],1,NULL)
6254: ** prior to calling this API,
1.2 misho 6255: ** otherwise an error will be returned.
6256: **
1.4 misho 6257: ** <b>Security warning:</b> It is recommended that the
6258: ** [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method be used to enable only this
6259: ** interface. The use of the [sqlite3_enable_load_extension()] interface
6260: ** should be avoided. This will keep the SQL function [load_extension()]
6261: ** disabled and prevent SQL injections from giving attackers
6262: ** access to extension loading capabilities.
6263: **
1.2 misho 6264: ** See also the [load_extension() SQL function].
6265: */
6266: SQLITE_API int sqlite3_load_extension(
6267: sqlite3 *db, /* Load the extension into this database connection */
6268: const char *zFile, /* Name of the shared library containing extension */
6269: const char *zProc, /* Entry point. Derived from zFile if 0 */
6270: char **pzErrMsg /* Put error message here if not 0 */
6271: );
6272:
6273: /*
6274: ** CAPI3REF: Enable Or Disable Extension Loading
1.4 misho 6275: ** METHOD: sqlite3
1.2 misho 6276: **
6277: ** ^So as not to open security holes in older applications that are
1.4 misho 6278: ** unprepared to deal with [extension loading], and as a means of disabling
6279: ** [extension loading] while evaluating user-entered SQL, the following API
1.2 misho 6280: ** is provided to turn the [sqlite3_load_extension()] mechanism on and off.
6281: **
1.4 misho 6282: ** ^Extension loading is off by default.
1.2 misho 6283: ** ^Call the sqlite3_enable_load_extension() routine with onoff==1
6284: ** to turn extension loading on and call it with onoff==0 to turn
6285: ** it back off again.
1.4 misho 6286: **
6287: ** ^This interface enables or disables both the C-API
6288: ** [sqlite3_load_extension()] and the SQL function [load_extension()].
6289: ** ^(Use [sqlite3_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],..)
6290: ** to enable or disable only the C-API.)^
6291: **
6292: ** <b>Security warning:</b> It is recommended that extension loading
6293: ** be disabled using the [SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION] method
6294: ** rather than this interface, so the [load_extension()] SQL function
6295: ** remains disabled. This will prevent SQL injections from giving attackers
6296: ** access to extension loading capabilities.
1.2 misho 6297: */
6298: SQLITE_API int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
6299:
6300: /*
6301: ** CAPI3REF: Automatically Load Statically Linked Extensions
6302: **
6303: ** ^This interface causes the xEntryPoint() function to be invoked for
6304: ** each new [database connection] that is created. The idea here is that
1.4 misho 6305: ** xEntryPoint() is the entry point for a statically linked [SQLite extension]
1.2 misho 6306: ** that is to be automatically loaded into all new database connections.
6307: **
6308: ** ^(Even though the function prototype shows that xEntryPoint() takes
6309: ** no arguments and returns void, SQLite invokes xEntryPoint() with three
1.4 misho 6310: ** arguments and expects an integer result as if the signature of the
1.2 misho 6311: ** entry point where as follows:
6312: **
6313: ** <blockquote><pre>
6314: ** int xEntryPoint(
6315: ** sqlite3 *db,
6316: ** const char **pzErrMsg,
6317: ** const struct sqlite3_api_routines *pThunk
6318: ** );
6319: ** </pre></blockquote>)^
6320: **
6321: ** If the xEntryPoint routine encounters an error, it should make *pzErrMsg
6322: ** point to an appropriate error message (obtained from [sqlite3_mprintf()])
6323: ** and return an appropriate [error code]. ^SQLite ensures that *pzErrMsg
6324: ** is NULL before calling the xEntryPoint(). ^SQLite will invoke
6325: ** [sqlite3_free()] on *pzErrMsg after xEntryPoint() returns. ^If any
6326: ** xEntryPoint() returns an error, the [sqlite3_open()], [sqlite3_open16()],
6327: ** or [sqlite3_open_v2()] call that provoked the xEntryPoint() will fail.
6328: **
6329: ** ^Calling sqlite3_auto_extension(X) with an entry point X that is already
6330: ** on the list of automatic extensions is a harmless no-op. ^No entry point
6331: ** will be called more than once for each database connection that is opened.
6332: **
1.4 misho 6333: ** See also: [sqlite3_reset_auto_extension()]
6334: ** and [sqlite3_cancel_auto_extension()]
1.2 misho 6335: */
1.4 misho 6336: SQLITE_API int sqlite3_auto_extension(void(*xEntryPoint)(void));
6337:
6338: /*
6339: ** CAPI3REF: Cancel Automatic Extension Loading
6340: **
6341: ** ^The [sqlite3_cancel_auto_extension(X)] interface unregisters the
6342: ** initialization routine X that was registered using a prior call to
6343: ** [sqlite3_auto_extension(X)]. ^The [sqlite3_cancel_auto_extension(X)]
6344: ** routine returns 1 if initialization routine X was successfully
6345: ** unregistered and it returns 0 if X was not on the list of initialization
6346: ** routines.
6347: */
6348: SQLITE_API int sqlite3_cancel_auto_extension(void(*xEntryPoint)(void));
1.2 misho 6349:
6350: /*
6351: ** CAPI3REF: Reset Automatic Extension Loading
6352: **
6353: ** ^This interface disables all automatic extensions previously
6354: ** registered using [sqlite3_auto_extension()].
6355: */
6356: SQLITE_API void sqlite3_reset_auto_extension(void);
6357:
6358: /*
6359: ** The interface to the virtual-table mechanism is currently considered
6360: ** to be experimental. The interface might change in incompatible ways.
6361: ** If this is a problem for you, do not use the interface at this time.
6362: **
6363: ** When the virtual-table mechanism stabilizes, we will declare the
6364: ** interface fixed, support it indefinitely, and remove this comment.
6365: */
6366:
6367: /*
6368: ** Structures used by the virtual table interface
6369: */
6370: typedef struct sqlite3_vtab sqlite3_vtab;
6371: typedef struct sqlite3_index_info sqlite3_index_info;
6372: typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
6373: typedef struct sqlite3_module sqlite3_module;
6374:
6375: /*
6376: ** CAPI3REF: Virtual Table Object
6377: ** KEYWORDS: sqlite3_module {virtual table module}
6378: **
6379: ** This structure, sometimes called a "virtual table module",
6380: ** defines the implementation of a [virtual tables].
6381: ** This structure consists mostly of methods for the module.
6382: **
6383: ** ^A virtual table module is created by filling in a persistent
6384: ** instance of this structure and passing a pointer to that instance
6385: ** to [sqlite3_create_module()] or [sqlite3_create_module_v2()].
6386: ** ^The registration remains valid until it is replaced by a different
6387: ** module or until the [database connection] closes. The content
6388: ** of this structure must not change while it is registered with
6389: ** any database connection.
6390: */
6391: struct sqlite3_module {
6392: int iVersion;
6393: int (*xCreate)(sqlite3*, void *pAux,
6394: int argc, const char *const*argv,
6395: sqlite3_vtab **ppVTab, char**);
6396: int (*xConnect)(sqlite3*, void *pAux,
6397: int argc, const char *const*argv,
6398: sqlite3_vtab **ppVTab, char**);
6399: int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
6400: int (*xDisconnect)(sqlite3_vtab *pVTab);
6401: int (*xDestroy)(sqlite3_vtab *pVTab);
6402: int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
6403: int (*xClose)(sqlite3_vtab_cursor*);
6404: int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
6405: int argc, sqlite3_value **argv);
6406: int (*xNext)(sqlite3_vtab_cursor*);
6407: int (*xEof)(sqlite3_vtab_cursor*);
6408: int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
6409: int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
6410: int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
6411: int (*xBegin)(sqlite3_vtab *pVTab);
6412: int (*xSync)(sqlite3_vtab *pVTab);
6413: int (*xCommit)(sqlite3_vtab *pVTab);
6414: int (*xRollback)(sqlite3_vtab *pVTab);
6415: int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
6416: void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
6417: void **ppArg);
6418: int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
6419: /* The methods above are in version 1 of the sqlite_module object. Those
6420: ** below are for version 2 and greater. */
6421: int (*xSavepoint)(sqlite3_vtab *pVTab, int);
6422: int (*xRelease)(sqlite3_vtab *pVTab, int);
6423: int (*xRollbackTo)(sqlite3_vtab *pVTab, int);
1.4.2.2 ! misho 6424: /* The methods above are in versions 1 and 2 of the sqlite_module object.
! 6425: ** Those below are for version 3 and greater. */
! 6426: int (*xShadowName)(const char*);
1.2 misho 6427: };
6428:
6429: /*
6430: ** CAPI3REF: Virtual Table Indexing Information
6431: ** KEYWORDS: sqlite3_index_info
6432: **
6433: ** The sqlite3_index_info structure and its substructures is used as part
6434: ** of the [virtual table] interface to
6435: ** pass information into and receive the reply from the [xBestIndex]
6436: ** method of a [virtual table module]. The fields under **Inputs** are the
6437: ** inputs to xBestIndex and are read-only. xBestIndex inserts its
6438: ** results into the **Outputs** fields.
6439: **
6440: ** ^(The aConstraint[] array records WHERE clause constraints of the form:
6441: **
6442: ** <blockquote>column OP expr</blockquote>
6443: **
6444: ** where OP is =, <, <=, >, or >=.)^ ^(The particular operator is
6445: ** stored in aConstraint[].op using one of the
6446: ** [SQLITE_INDEX_CONSTRAINT_EQ | SQLITE_INDEX_CONSTRAINT_ values].)^
6447: ** ^(The index of the column is stored in
6448: ** aConstraint[].iColumn.)^ ^(aConstraint[].usable is TRUE if the
6449: ** expr on the right-hand side can be evaluated (and thus the constraint
6450: ** is usable) and false if it cannot.)^
6451: **
6452: ** ^The optimizer automatically inverts terms of the form "expr OP column"
6453: ** and makes other simplifications to the WHERE clause in an attempt to
6454: ** get as many WHERE clause terms into the form shown above as possible.
6455: ** ^The aConstraint[] array only reports WHERE clause terms that are
6456: ** relevant to the particular virtual table being queried.
6457: **
6458: ** ^Information about the ORDER BY clause is stored in aOrderBy[].
6459: ** ^Each term of aOrderBy records a column of the ORDER BY clause.
6460: **
1.4 misho 6461: ** The colUsed field indicates which columns of the virtual table may be
6462: ** required by the current scan. Virtual table columns are numbered from
6463: ** zero in the order in which they appear within the CREATE TABLE statement
6464: ** passed to sqlite3_declare_vtab(). For the first 63 columns (columns 0-62),
6465: ** the corresponding bit is set within the colUsed mask if the column may be
6466: ** required by SQLite. If the table has at least 64 columns and any column
6467: ** to the right of the first 63 is required, then bit 63 of colUsed is also
6468: ** set. In other words, column iCol may be required if the expression
6469: ** (colUsed & ((sqlite3_uint64)1 << (iCol>=63 ? 63 : iCol))) evaluates to
6470: ** non-zero.
6471: **
1.2 misho 6472: ** The [xBestIndex] method must fill aConstraintUsage[] with information
6473: ** about what parameters to pass to xFilter. ^If argvIndex>0 then
6474: ** the right-hand side of the corresponding aConstraint[] is evaluated
6475: ** and becomes the argvIndex-th entry in argv. ^(If aConstraintUsage[].omit
6476: ** is true, then the constraint is assumed to be fully handled by the
6477: ** virtual table and is not checked again by SQLite.)^
6478: **
6479: ** ^The idxNum and idxPtr values are recorded and passed into the
6480: ** [xFilter] method.
6481: ** ^[sqlite3_free()] is used to free idxPtr if and only if
6482: ** needToFreeIdxPtr is true.
6483: **
6484: ** ^The orderByConsumed means that output from [xFilter]/[xNext] will occur in
6485: ** the correct order to satisfy the ORDER BY clause so that no separate
6486: ** sorting step is required.
6487: **
1.4 misho 6488: ** ^The estimatedCost value is an estimate of the cost of a particular
6489: ** strategy. A cost of N indicates that the cost of the strategy is similar
6490: ** to a linear scan of an SQLite table with N rows. A cost of log(N)
6491: ** indicates that the expense of the operation is similar to that of a
6492: ** binary search on a unique indexed field of an SQLite table with N rows.
6493: **
6494: ** ^The estimatedRows value is an estimate of the number of rows that
6495: ** will be returned by the strategy.
6496: **
6497: ** The xBestIndex method may optionally populate the idxFlags field with a
6498: ** mask of SQLITE_INDEX_SCAN_* flags. Currently there is only one such flag -
6499: ** SQLITE_INDEX_SCAN_UNIQUE. If the xBestIndex method sets this flag, SQLite
6500: ** assumes that the strategy may visit at most one row.
6501: **
6502: ** Additionally, if xBestIndex sets the SQLITE_INDEX_SCAN_UNIQUE flag, then
6503: ** SQLite also assumes that if a call to the xUpdate() method is made as
6504: ** part of the same statement to delete or update a virtual table row and the
6505: ** implementation returns SQLITE_CONSTRAINT, then there is no need to rollback
6506: ** any database changes. In other words, if the xUpdate() returns
6507: ** SQLITE_CONSTRAINT, the database contents must be exactly as they were
6508: ** before xUpdate was called. By contrast, if SQLITE_INDEX_SCAN_UNIQUE is not
6509: ** set and xUpdate returns SQLITE_CONSTRAINT, any database changes made by
6510: ** the xUpdate method are automatically rolled back by SQLite.
6511: **
6512: ** IMPORTANT: The estimatedRows field was added to the sqlite3_index_info
1.4.2.1 misho 6513: ** structure for SQLite [version 3.8.2] ([dateof:3.8.2]).
6514: ** If a virtual table extension is
1.4 misho 6515: ** used with an SQLite version earlier than 3.8.2, the results of attempting
6516: ** to read or write the estimatedRows field are undefined (but are likely
6517: ** to included crashing the application). The estimatedRows field should
6518: ** therefore only be used if [sqlite3_libversion_number()] returns a
6519: ** value greater than or equal to 3008002. Similarly, the idxFlags field
1.4.2.1 misho 6520: ** was added for [version 3.9.0] ([dateof:3.9.0]).
6521: ** It may therefore only be used if
1.4 misho 6522: ** sqlite3_libversion_number() returns a value greater than or equal to
6523: ** 3009000.
1.2 misho 6524: */
6525: struct sqlite3_index_info {
6526: /* Inputs */
6527: int nConstraint; /* Number of entries in aConstraint */
6528: struct sqlite3_index_constraint {
1.4 misho 6529: int iColumn; /* Column constrained. -1 for ROWID */
1.2 misho 6530: unsigned char op; /* Constraint operator */
6531: unsigned char usable; /* True if this constraint is usable */
6532: int iTermOffset; /* Used internally - xBestIndex should ignore */
6533: } *aConstraint; /* Table of WHERE clause constraints */
6534: int nOrderBy; /* Number of terms in the ORDER BY clause */
6535: struct sqlite3_index_orderby {
6536: int iColumn; /* Column number */
6537: unsigned char desc; /* True for DESC. False for ASC. */
6538: } *aOrderBy; /* The ORDER BY clause */
6539: /* Outputs */
6540: struct sqlite3_index_constraint_usage {
6541: int argvIndex; /* if >0, constraint is part of argv to xFilter */
6542: unsigned char omit; /* Do not code a test for this constraint */
6543: } *aConstraintUsage;
6544: int idxNum; /* Number used to identify the index */
6545: char *idxStr; /* String, possibly obtained from sqlite3_malloc */
6546: int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
6547: int orderByConsumed; /* True if output is already ordered */
1.4 misho 6548: double estimatedCost; /* Estimated cost of using this index */
6549: /* Fields below are only available in SQLite 3.8.2 and later */
6550: sqlite3_int64 estimatedRows; /* Estimated number of rows returned */
6551: /* Fields below are only available in SQLite 3.9.0 and later */
6552: int idxFlags; /* Mask of SQLITE_INDEX_SCAN_* flags */
6553: /* Fields below are only available in SQLite 3.10.0 and later */
6554: sqlite3_uint64 colUsed; /* Input: Mask of columns used by statement */
1.2 misho 6555: };
6556:
6557: /*
1.4 misho 6558: ** CAPI3REF: Virtual Table Scan Flags
1.4.2.2 ! misho 6559: **
! 6560: ** Virtual table implementations are allowed to set the
! 6561: ** [sqlite3_index_info].idxFlags field to some combination of
! 6562: ** these bits.
1.4 misho 6563: */
6564: #define SQLITE_INDEX_SCAN_UNIQUE 1 /* Scan visits at most 1 row */
6565:
6566: /*
1.2 misho 6567: ** CAPI3REF: Virtual Table Constraint Operator Codes
6568: **
6569: ** These macros defined the allowed values for the
6570: ** [sqlite3_index_info].aConstraint[].op field. Each value represents
6571: ** an operator that is part of a constraint term in the wHERE clause of
6572: ** a query that uses a [virtual table].
6573: */
1.4.2.2 ! misho 6574: #define SQLITE_INDEX_CONSTRAINT_EQ 2
! 6575: #define SQLITE_INDEX_CONSTRAINT_GT 4
! 6576: #define SQLITE_INDEX_CONSTRAINT_LE 8
! 6577: #define SQLITE_INDEX_CONSTRAINT_LT 16
! 6578: #define SQLITE_INDEX_CONSTRAINT_GE 32
! 6579: #define SQLITE_INDEX_CONSTRAINT_MATCH 64
! 6580: #define SQLITE_INDEX_CONSTRAINT_LIKE 65
! 6581: #define SQLITE_INDEX_CONSTRAINT_GLOB 66
! 6582: #define SQLITE_INDEX_CONSTRAINT_REGEXP 67
! 6583: #define SQLITE_INDEX_CONSTRAINT_NE 68
! 6584: #define SQLITE_INDEX_CONSTRAINT_ISNOT 69
! 6585: #define SQLITE_INDEX_CONSTRAINT_ISNOTNULL 70
! 6586: #define SQLITE_INDEX_CONSTRAINT_ISNULL 71
! 6587: #define SQLITE_INDEX_CONSTRAINT_IS 72
! 6588: #define SQLITE_INDEX_CONSTRAINT_FUNCTION 150
1.2 misho 6589:
6590: /*
6591: ** CAPI3REF: Register A Virtual Table Implementation
1.4 misho 6592: ** METHOD: sqlite3
1.2 misho 6593: **
6594: ** ^These routines are used to register a new [virtual table module] name.
6595: ** ^Module names must be registered before
6596: ** creating a new [virtual table] using the module and before using a
6597: ** preexisting [virtual table] for the module.
6598: **
6599: ** ^The module name is registered on the [database connection] specified
6600: ** by the first parameter. ^The name of the module is given by the
6601: ** second parameter. ^The third parameter is a pointer to
6602: ** the implementation of the [virtual table module]. ^The fourth
6603: ** parameter is an arbitrary client data pointer that is passed through
6604: ** into the [xCreate] and [xConnect] methods of the virtual table module
6605: ** when a new virtual table is be being created or reinitialized.
6606: **
6607: ** ^The sqlite3_create_module_v2() interface has a fifth parameter which
6608: ** is a pointer to a destructor for the pClientData. ^SQLite will
6609: ** invoke the destructor function (if it is not NULL) when SQLite
6610: ** no longer needs the pClientData pointer. ^The destructor will also
6611: ** be invoked if the call to sqlite3_create_module_v2() fails.
6612: ** ^The sqlite3_create_module()
6613: ** interface is equivalent to sqlite3_create_module_v2() with a NULL
6614: ** destructor.
6615: */
6616: SQLITE_API int sqlite3_create_module(
6617: sqlite3 *db, /* SQLite connection to register module with */
6618: const char *zName, /* Name of the module */
6619: const sqlite3_module *p, /* Methods for the module */
6620: void *pClientData /* Client data for xCreate/xConnect */
6621: );
6622: SQLITE_API int sqlite3_create_module_v2(
6623: sqlite3 *db, /* SQLite connection to register module with */
6624: const char *zName, /* Name of the module */
6625: const sqlite3_module *p, /* Methods for the module */
6626: void *pClientData, /* Client data for xCreate/xConnect */
6627: void(*xDestroy)(void*) /* Module destructor function */
6628: );
6629:
6630: /*
6631: ** CAPI3REF: Virtual Table Instance Object
6632: ** KEYWORDS: sqlite3_vtab
6633: **
6634: ** Every [virtual table module] implementation uses a subclass
6635: ** of this object to describe a particular instance
6636: ** of the [virtual table]. Each subclass will
6637: ** be tailored to the specific needs of the module implementation.
6638: ** The purpose of this superclass is to define certain fields that are
6639: ** common to all module implementations.
6640: **
6641: ** ^Virtual tables methods can set an error message by assigning a
6642: ** string obtained from [sqlite3_mprintf()] to zErrMsg. The method should
6643: ** take care that any prior string is freed by a call to [sqlite3_free()]
6644: ** prior to assigning a new string to zErrMsg. ^After the error message
6645: ** is delivered up to the client application, the string will be automatically
6646: ** freed by sqlite3_free() and the zErrMsg field will be zeroed.
6647: */
6648: struct sqlite3_vtab {
6649: const sqlite3_module *pModule; /* The module for this virtual table */
1.4 misho 6650: int nRef; /* Number of open cursors */
1.2 misho 6651: char *zErrMsg; /* Error message from sqlite3_mprintf() */
6652: /* Virtual table implementations will typically add additional fields */
6653: };
6654:
6655: /*
6656: ** CAPI3REF: Virtual Table Cursor Object
6657: ** KEYWORDS: sqlite3_vtab_cursor {virtual table cursor}
6658: **
6659: ** Every [virtual table module] implementation uses a subclass of the
6660: ** following structure to describe cursors that point into the
6661: ** [virtual table] and are used
6662: ** to loop through the virtual table. Cursors are created using the
6663: ** [sqlite3_module.xOpen | xOpen] method of the module and are destroyed
6664: ** by the [sqlite3_module.xClose | xClose] method. Cursors are used
6665: ** by the [xFilter], [xNext], [xEof], [xColumn], and [xRowid] methods
6666: ** of the module. Each module implementation will define
6667: ** the content of a cursor structure to suit its own needs.
6668: **
6669: ** This superclass exists in order to define fields of the cursor that
6670: ** are common to all implementations.
6671: */
6672: struct sqlite3_vtab_cursor {
6673: sqlite3_vtab *pVtab; /* Virtual table of this cursor */
6674: /* Virtual table implementations will typically add additional fields */
6675: };
6676:
6677: /*
6678: ** CAPI3REF: Declare The Schema Of A Virtual Table
6679: **
6680: ** ^The [xCreate] and [xConnect] methods of a
6681: ** [virtual table module] call this interface
6682: ** to declare the format (the names and datatypes of the columns) of
6683: ** the virtual tables they implement.
6684: */
6685: SQLITE_API int sqlite3_declare_vtab(sqlite3*, const char *zSQL);
6686:
6687: /*
6688: ** CAPI3REF: Overload A Function For A Virtual Table
1.4 misho 6689: ** METHOD: sqlite3
1.2 misho 6690: **
6691: ** ^(Virtual tables can provide alternative implementations of functions
6692: ** using the [xFindFunction] method of the [virtual table module].
6693: ** But global versions of those functions
6694: ** must exist in order to be overloaded.)^
6695: **
6696: ** ^(This API makes sure a global version of a function with a particular
6697: ** name and number of parameters exists. If no such function exists
6698: ** before this API is called, a new function is created.)^ ^The implementation
6699: ** of the new function always causes an exception to be thrown. So
6700: ** the new function is not good for anything by itself. Its only
6701: ** purpose is to be a placeholder function that can be overloaded
6702: ** by a [virtual table].
6703: */
6704: SQLITE_API int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
6705:
6706: /*
6707: ** The interface to the virtual-table mechanism defined above (back up
6708: ** to a comment remarkably similar to this one) is currently considered
6709: ** to be experimental. The interface might change in incompatible ways.
6710: ** If this is a problem for you, do not use the interface at this time.
6711: **
6712: ** When the virtual-table mechanism stabilizes, we will declare the
6713: ** interface fixed, support it indefinitely, and remove this comment.
6714: */
6715:
6716: /*
6717: ** CAPI3REF: A Handle To An Open BLOB
6718: ** KEYWORDS: {BLOB handle} {BLOB handles}
6719: **
6720: ** An instance of this object represents an open BLOB on which
6721: ** [sqlite3_blob_open | incremental BLOB I/O] can be performed.
6722: ** ^Objects of this type are created by [sqlite3_blob_open()]
6723: ** and destroyed by [sqlite3_blob_close()].
6724: ** ^The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
6725: ** can be used to read or write small subsections of the BLOB.
6726: ** ^The [sqlite3_blob_bytes()] interface returns the size of the BLOB in bytes.
6727: */
6728: typedef struct sqlite3_blob sqlite3_blob;
6729:
6730: /*
6731: ** CAPI3REF: Open A BLOB For Incremental I/O
1.4 misho 6732: ** METHOD: sqlite3
6733: ** CONSTRUCTOR: sqlite3_blob
1.2 misho 6734: **
6735: ** ^(This interfaces opens a [BLOB handle | handle] to the BLOB located
6736: ** in row iRow, column zColumn, table zTable in database zDb;
6737: ** in other words, the same BLOB that would be selected by:
6738: **
6739: ** <pre>
6740: ** SELECT zColumn FROM zDb.zTable WHERE [rowid] = iRow;
6741: ** </pre>)^
6742: **
1.4 misho 6743: ** ^(Parameter zDb is not the filename that contains the database, but
6744: ** rather the symbolic name of the database. For attached databases, this is
6745: ** the name that appears after the AS keyword in the [ATTACH] statement.
6746: ** For the main database file, the database name is "main". For TEMP
6747: ** tables, the database name is "temp".)^
6748: **
1.2 misho 6749: ** ^If the flags parameter is non-zero, then the BLOB is opened for read
1.4 misho 6750: ** and write access. ^If the flags parameter is zero, the BLOB is opened for
6751: ** read-only access.
6752: **
6753: ** ^(On success, [SQLITE_OK] is returned and the new [BLOB handle] is stored
6754: ** in *ppBlob. Otherwise an [error code] is returned and, unless the error
6755: ** code is SQLITE_MISUSE, *ppBlob is set to NULL.)^ ^This means that, provided
6756: ** the API is not misused, it is always safe to call [sqlite3_blob_close()]
6757: ** on *ppBlob after this function it returns.
6758: **
6759: ** This function fails with SQLITE_ERROR if any of the following are true:
6760: ** <ul>
6761: ** <li> ^(Database zDb does not exist)^,
6762: ** <li> ^(Table zTable does not exist within database zDb)^,
6763: ** <li> ^(Table zTable is a WITHOUT ROWID table)^,
6764: ** <li> ^(Column zColumn does not exist)^,
6765: ** <li> ^(Row iRow is not present in the table)^,
6766: ** <li> ^(The specified column of row iRow contains a value that is not
6767: ** a TEXT or BLOB value)^,
6768: ** <li> ^(Column zColumn is part of an index, PRIMARY KEY or UNIQUE
6769: ** constraint and the blob is being opened for read/write access)^,
6770: ** <li> ^([foreign key constraints | Foreign key constraints] are enabled,
6771: ** column zColumn is part of a [child key] definition and the blob is
6772: ** being opened for read/write access)^.
6773: ** </ul>
6774: **
6775: ** ^Unless it returns SQLITE_MISUSE, this function sets the
6776: ** [database connection] error code and message accessible via
6777: ** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions.
6778: **
1.4.2.1 misho 6779: ** A BLOB referenced by sqlite3_blob_open() may be read using the
6780: ** [sqlite3_blob_read()] interface and modified by using
6781: ** [sqlite3_blob_write()]. The [BLOB handle] can be moved to a
6782: ** different row of the same table using the [sqlite3_blob_reopen()]
6783: ** interface. However, the column, table, or database of a [BLOB handle]
6784: ** cannot be changed after the [BLOB handle] is opened.
1.2 misho 6785: **
6786: ** ^(If the row that a BLOB handle points to is modified by an
6787: ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects
6788: ** then the BLOB handle is marked as "expired".
6789: ** This is true if any column of the row is changed, even a column
6790: ** other than the one the BLOB handle is open on.)^
6791: ** ^Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for
6792: ** an expired BLOB handle fail with a return code of [SQLITE_ABORT].
6793: ** ^(Changes written into a BLOB prior to the BLOB expiring are not
6794: ** rolled back by the expiration of the BLOB. Such changes will eventually
6795: ** commit if the transaction continues to completion.)^
6796: **
6797: ** ^Use the [sqlite3_blob_bytes()] interface to determine the size of
6798: ** the opened blob. ^The size of a blob may not be changed by this
6799: ** interface. Use the [UPDATE] SQL command to change the size of a
6800: ** blob.
6801: **
6802: ** ^The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
1.4 misho 6803: ** and the built-in [zeroblob] SQL function may be used to create a
6804: ** zero-filled blob to read or write using the incremental-blob interface.
1.2 misho 6805: **
6806: ** To avoid a resource leak, every open [BLOB handle] should eventually
6807: ** be released by a call to [sqlite3_blob_close()].
1.4.2.1 misho 6808: **
6809: ** See also: [sqlite3_blob_close()],
6810: ** [sqlite3_blob_reopen()], [sqlite3_blob_read()],
6811: ** [sqlite3_blob_bytes()], [sqlite3_blob_write()].
1.2 misho 6812: */
6813: SQLITE_API int sqlite3_blob_open(
6814: sqlite3*,
6815: const char *zDb,
6816: const char *zTable,
6817: const char *zColumn,
6818: sqlite3_int64 iRow,
6819: int flags,
6820: sqlite3_blob **ppBlob
6821: );
6822:
6823: /*
6824: ** CAPI3REF: Move a BLOB Handle to a New Row
1.4 misho 6825: ** METHOD: sqlite3_blob
1.2 misho 6826: **
1.4.2.1 misho 6827: ** ^This function is used to move an existing [BLOB handle] so that it points
1.2 misho 6828: ** to a different row of the same database table. ^The new row is identified
6829: ** by the rowid value passed as the second argument. Only the row can be
6830: ** changed. ^The database, table and column on which the blob handle is open
1.4.2.1 misho 6831: ** remain the same. Moving an existing [BLOB handle] to a new row is
1.2 misho 6832: ** faster than closing the existing handle and opening a new one.
6833: **
6834: ** ^(The new row must meet the same criteria as for [sqlite3_blob_open()] -
6835: ** it must exist and there must be either a blob or text value stored in
6836: ** the nominated column.)^ ^If the new row is not present in the table, or if
6837: ** it does not contain a blob or text value, or if another error occurs, an
6838: ** SQLite error code is returned and the blob handle is considered aborted.
6839: ** ^All subsequent calls to [sqlite3_blob_read()], [sqlite3_blob_write()] or
6840: ** [sqlite3_blob_reopen()] on an aborted blob handle immediately return
6841: ** SQLITE_ABORT. ^Calling [sqlite3_blob_bytes()] on an aborted blob handle
6842: ** always returns zero.
6843: **
6844: ** ^This function sets the database handle error code and message.
6845: */
1.4 misho 6846: SQLITE_API int sqlite3_blob_reopen(sqlite3_blob *, sqlite3_int64);
1.2 misho 6847:
6848: /*
6849: ** CAPI3REF: Close A BLOB Handle
1.4 misho 6850: ** DESTRUCTOR: sqlite3_blob
1.2 misho 6851: **
1.4 misho 6852: ** ^This function closes an open [BLOB handle]. ^(The BLOB handle is closed
6853: ** unconditionally. Even if this routine returns an error code, the
6854: ** handle is still closed.)^
6855: **
6856: ** ^If the blob handle being closed was opened for read-write access, and if
6857: ** the database is in auto-commit mode and there are no other open read-write
6858: ** blob handles or active write statements, the current transaction is
6859: ** committed. ^If an error occurs while committing the transaction, an error
6860: ** code is returned and the transaction rolled back.
6861: **
6862: ** Calling this function with an argument that is not a NULL pointer or an
6863: ** open blob handle results in undefined behaviour. ^Calling this routine
6864: ** with a null pointer (such as would be returned by a failed call to
6865: ** [sqlite3_blob_open()]) is a harmless no-op. ^Otherwise, if this function
6866: ** is passed a valid open blob handle, the values returned by the
6867: ** sqlite3_errcode() and sqlite3_errmsg() functions are set before returning.
1.2 misho 6868: */
6869: SQLITE_API int sqlite3_blob_close(sqlite3_blob *);
6870:
6871: /*
6872: ** CAPI3REF: Return The Size Of An Open BLOB
1.4 misho 6873: ** METHOD: sqlite3_blob
1.2 misho 6874: **
6875: ** ^Returns the size in bytes of the BLOB accessible via the
6876: ** successfully opened [BLOB handle] in its only argument. ^The
6877: ** incremental blob I/O routines can only read or overwriting existing
6878: ** blob content; they cannot change the size of a blob.
6879: **
6880: ** This routine only works on a [BLOB handle] which has been created
6881: ** by a prior successful call to [sqlite3_blob_open()] and which has not
6882: ** been closed by [sqlite3_blob_close()]. Passing any other pointer in
6883: ** to this routine results in undefined and probably undesirable behavior.
6884: */
6885: SQLITE_API int sqlite3_blob_bytes(sqlite3_blob *);
6886:
6887: /*
6888: ** CAPI3REF: Read Data From A BLOB Incrementally
1.4 misho 6889: ** METHOD: sqlite3_blob
1.2 misho 6890: **
6891: ** ^(This function is used to read data from an open [BLOB handle] into a
6892: ** caller-supplied buffer. N bytes of data are copied into buffer Z
6893: ** from the open BLOB, starting at offset iOffset.)^
6894: **
6895: ** ^If offset iOffset is less than N bytes from the end of the BLOB,
6896: ** [SQLITE_ERROR] is returned and no data is read. ^If N or iOffset is
6897: ** less than zero, [SQLITE_ERROR] is returned and no data is read.
6898: ** ^The size of the blob (and hence the maximum value of N+iOffset)
6899: ** can be determined using the [sqlite3_blob_bytes()] interface.
6900: **
6901: ** ^An attempt to read from an expired [BLOB handle] fails with an
6902: ** error code of [SQLITE_ABORT].
6903: **
6904: ** ^(On success, sqlite3_blob_read() returns SQLITE_OK.
6905: ** Otherwise, an [error code] or an [extended error code] is returned.)^
6906: **
6907: ** This routine only works on a [BLOB handle] which has been created
6908: ** by a prior successful call to [sqlite3_blob_open()] and which has not
6909: ** been closed by [sqlite3_blob_close()]. Passing any other pointer in
6910: ** to this routine results in undefined and probably undesirable behavior.
6911: **
6912: ** See also: [sqlite3_blob_write()].
6913: */
6914: SQLITE_API int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
6915:
6916: /*
6917: ** CAPI3REF: Write Data Into A BLOB Incrementally
1.4 misho 6918: ** METHOD: sqlite3_blob
1.2 misho 6919: **
1.4 misho 6920: ** ^(This function is used to write data into an open [BLOB handle] from a
6921: ** caller-supplied buffer. N bytes of data are copied from the buffer Z
6922: ** into the open BLOB, starting at offset iOffset.)^
6923: **
6924: ** ^(On success, sqlite3_blob_write() returns SQLITE_OK.
6925: ** Otherwise, an [error code] or an [extended error code] is returned.)^
6926: ** ^Unless SQLITE_MISUSE is returned, this function sets the
6927: ** [database connection] error code and message accessible via
6928: ** [sqlite3_errcode()] and [sqlite3_errmsg()] and related functions.
1.2 misho 6929: **
6930: ** ^If the [BLOB handle] passed as the first argument was not opened for
6931: ** writing (the flags parameter to [sqlite3_blob_open()] was zero),
6932: ** this function returns [SQLITE_READONLY].
6933: **
1.4 misho 6934: ** This function may only modify the contents of the BLOB; it is
1.2 misho 6935: ** not possible to increase the size of a BLOB using this API.
6936: ** ^If offset iOffset is less than N bytes from the end of the BLOB,
1.4 misho 6937: ** [SQLITE_ERROR] is returned and no data is written. The size of the
6938: ** BLOB (and hence the maximum value of N+iOffset) can be determined
6939: ** using the [sqlite3_blob_bytes()] interface. ^If N or iOffset are less
6940: ** than zero [SQLITE_ERROR] is returned and no data is written.
1.2 misho 6941: **
6942: ** ^An attempt to write to an expired [BLOB handle] fails with an
6943: ** error code of [SQLITE_ABORT]. ^Writes to the BLOB that occurred
6944: ** before the [BLOB handle] expired are not rolled back by the
6945: ** expiration of the handle, though of course those changes might
6946: ** have been overwritten by the statement that expired the BLOB handle
6947: ** or by other independent statements.
6948: **
6949: ** This routine only works on a [BLOB handle] which has been created
6950: ** by a prior successful call to [sqlite3_blob_open()] and which has not
6951: ** been closed by [sqlite3_blob_close()]. Passing any other pointer in
6952: ** to this routine results in undefined and probably undesirable behavior.
6953: **
6954: ** See also: [sqlite3_blob_read()].
6955: */
6956: SQLITE_API int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
6957:
6958: /*
6959: ** CAPI3REF: Virtual File System Objects
6960: **
6961: ** A virtual filesystem (VFS) is an [sqlite3_vfs] object
6962: ** that SQLite uses to interact
6963: ** with the underlying operating system. Most SQLite builds come with a
6964: ** single default VFS that is appropriate for the host computer.
6965: ** New VFSes can be registered and existing VFSes can be unregistered.
6966: ** The following interfaces are provided.
6967: **
6968: ** ^The sqlite3_vfs_find() interface returns a pointer to a VFS given its name.
6969: ** ^Names are case sensitive.
6970: ** ^Names are zero-terminated UTF-8 strings.
6971: ** ^If there is no match, a NULL pointer is returned.
6972: ** ^If zVfsName is NULL then the default VFS is returned.
6973: **
6974: ** ^New VFSes are registered with sqlite3_vfs_register().
6975: ** ^Each new VFS becomes the default VFS if the makeDflt flag is set.
6976: ** ^The same VFS can be registered multiple times without injury.
6977: ** ^To make an existing VFS into the default VFS, register it again
6978: ** with the makeDflt flag set. If two different VFSes with the
6979: ** same name are registered, the behavior is undefined. If a
6980: ** VFS is registered with a name that is NULL or an empty string,
6981: ** then the behavior is undefined.
6982: **
6983: ** ^Unregister a VFS with the sqlite3_vfs_unregister() interface.
6984: ** ^(If the default VFS is unregistered, another VFS is chosen as
6985: ** the default. The choice for the new VFS is arbitrary.)^
6986: */
6987: SQLITE_API sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
6988: SQLITE_API int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
6989: SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
6990:
6991: /*
6992: ** CAPI3REF: Mutexes
6993: **
6994: ** The SQLite core uses these routines for thread
6995: ** synchronization. Though they are intended for internal
6996: ** use by SQLite, code that links against SQLite is
6997: ** permitted to use any of these routines.
6998: **
6999: ** The SQLite source code contains multiple implementations
7000: ** of these mutex routines. An appropriate implementation
1.4 misho 7001: ** is selected automatically at compile-time. The following
1.2 misho 7002: ** implementations are available in the SQLite core:
7003: **
7004: ** <ul>
7005: ** <li> SQLITE_MUTEX_PTHREADS
7006: ** <li> SQLITE_MUTEX_W32
7007: ** <li> SQLITE_MUTEX_NOOP
1.4 misho 7008: ** </ul>
1.2 misho 7009: **
1.4 misho 7010: ** The SQLITE_MUTEX_NOOP implementation is a set of routines
1.2 misho 7011: ** that does no real locking and is appropriate for use in
1.4 misho 7012: ** a single-threaded application. The SQLITE_MUTEX_PTHREADS and
1.3 misho 7013: ** SQLITE_MUTEX_W32 implementations are appropriate for use on Unix
7014: ** and Windows.
1.2 misho 7015: **
1.4 misho 7016: ** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
1.2 misho 7017: ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
7018: ** implementation is included with the library. In this case the
7019: ** application must supply a custom mutex implementation using the
7020: ** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function
7021: ** before calling sqlite3_initialize() or any other public sqlite3_
1.4 misho 7022: ** function that calls sqlite3_initialize().
1.2 misho 7023: **
7024: ** ^The sqlite3_mutex_alloc() routine allocates a new
1.4 misho 7025: ** mutex and returns a pointer to it. ^The sqlite3_mutex_alloc()
7026: ** routine returns NULL if it is unable to allocate the requested
7027: ** mutex. The argument to sqlite3_mutex_alloc() must one of these
7028: ** integer constants:
1.2 misho 7029: **
7030: ** <ul>
7031: ** <li> SQLITE_MUTEX_FAST
7032: ** <li> SQLITE_MUTEX_RECURSIVE
7033: ** <li> SQLITE_MUTEX_STATIC_MASTER
7034: ** <li> SQLITE_MUTEX_STATIC_MEM
1.4 misho 7035: ** <li> SQLITE_MUTEX_STATIC_OPEN
1.2 misho 7036: ** <li> SQLITE_MUTEX_STATIC_PRNG
7037: ** <li> SQLITE_MUTEX_STATIC_LRU
1.4 misho 7038: ** <li> SQLITE_MUTEX_STATIC_PMEM
7039: ** <li> SQLITE_MUTEX_STATIC_APP1
7040: ** <li> SQLITE_MUTEX_STATIC_APP2
7041: ** <li> SQLITE_MUTEX_STATIC_APP3
7042: ** <li> SQLITE_MUTEX_STATIC_VFS1
7043: ** <li> SQLITE_MUTEX_STATIC_VFS2
7044: ** <li> SQLITE_MUTEX_STATIC_VFS3
7045: ** </ul>
1.2 misho 7046: **
7047: ** ^The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)
7048: ** cause sqlite3_mutex_alloc() to create
7049: ** a new mutex. ^The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
7050: ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
7051: ** The mutex implementation does not need to make a distinction
7052: ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
1.4 misho 7053: ** not want to. SQLite will only request a recursive mutex in
7054: ** cases where it really needs one. If a faster non-recursive mutex
1.2 misho 7055: ** implementation is available on the host platform, the mutex subsystem
7056: ** might return such a mutex in response to SQLITE_MUTEX_FAST.
7057: **
7058: ** ^The other allowed parameters to sqlite3_mutex_alloc() (anything other
7059: ** than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return
1.4 misho 7060: ** a pointer to a static preexisting mutex. ^Nine static mutexes are
1.2 misho 7061: ** used by the current version of SQLite. Future versions of SQLite
7062: ** may add additional static mutexes. Static mutexes are for internal
7063: ** use by SQLite only. Applications that use SQLite mutexes should
7064: ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
7065: ** SQLITE_MUTEX_RECURSIVE.
7066: **
7067: ** ^Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
7068: ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
1.4 misho 7069: ** returns a different mutex on every call. ^For the static
1.2 misho 7070: ** mutex types, the same mutex is returned on every call that has
7071: ** the same type number.
7072: **
7073: ** ^The sqlite3_mutex_free() routine deallocates a previously
1.4 misho 7074: ** allocated dynamic mutex. Attempting to deallocate a static
7075: ** mutex results in undefined behavior.
1.2 misho 7076: **
7077: ** ^The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
7078: ** to enter a mutex. ^If another thread is already within the mutex,
7079: ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
7080: ** SQLITE_BUSY. ^The sqlite3_mutex_try() interface returns [SQLITE_OK]
7081: ** upon successful entry. ^(Mutexes created using
7082: ** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
1.4 misho 7083: ** In such cases, the
1.2 misho 7084: ** mutex must be exited an equal number of times before another thread
1.4 misho 7085: ** can enter.)^ If the same thread tries to enter any mutex other
7086: ** than an SQLITE_MUTEX_RECURSIVE more than once, the behavior is undefined.
1.2 misho 7087: **
7088: ** ^(Some systems (for example, Windows 95) do not support the operation
7089: ** implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try()
1.4 misho 7090: ** will always return SQLITE_BUSY. The SQLite core only ever uses
7091: ** sqlite3_mutex_try() as an optimization so this is acceptable
7092: ** behavior.)^
1.2 misho 7093: **
7094: ** ^The sqlite3_mutex_leave() routine exits a mutex that was
1.4 misho 7095: ** previously entered by the same thread. The behavior
1.2 misho 7096: ** is undefined if the mutex is not currently entered by the
1.4 misho 7097: ** calling thread or is not currently allocated.
1.2 misho 7098: **
7099: ** ^If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or
7100: ** sqlite3_mutex_leave() is a NULL pointer, then all three routines
7101: ** behave as no-ops.
7102: **
7103: ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
7104: */
7105: SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int);
7106: SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*);
7107: SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*);
7108: SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*);
7109: SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*);
7110:
7111: /*
7112: ** CAPI3REF: Mutex Methods Object
7113: **
7114: ** An instance of this structure defines the low-level routines
7115: ** used to allocate and use mutexes.
7116: **
7117: ** Usually, the default mutex implementations provided by SQLite are
1.4 misho 7118: ** sufficient, however the application has the option of substituting a custom
1.2 misho 7119: ** implementation for specialized deployments or systems for which SQLite
1.4 misho 7120: ** does not provide a suitable implementation. In this case, the application
1.2 misho 7121: ** creates and populates an instance of this structure to pass
7122: ** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option.
7123: ** Additionally, an instance of this structure can be used as an
7124: ** output variable when querying the system for the current mutex
7125: ** implementation, using the [SQLITE_CONFIG_GETMUTEX] option.
7126: **
7127: ** ^The xMutexInit method defined by this structure is invoked as
7128: ** part of system initialization by the sqlite3_initialize() function.
7129: ** ^The xMutexInit routine is called by SQLite exactly once for each
7130: ** effective call to [sqlite3_initialize()].
7131: **
7132: ** ^The xMutexEnd method defined by this structure is invoked as
7133: ** part of system shutdown by the sqlite3_shutdown() function. The
7134: ** implementation of this method is expected to release all outstanding
7135: ** resources obtained by the mutex methods implementation, especially
7136: ** those obtained by the xMutexInit method. ^The xMutexEnd()
7137: ** interface is invoked exactly once for each call to [sqlite3_shutdown()].
7138: **
7139: ** ^(The remaining seven methods defined by this structure (xMutexAlloc,
7140: ** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and
7141: ** xMutexNotheld) implement the following interfaces (respectively):
7142: **
7143: ** <ul>
7144: ** <li> [sqlite3_mutex_alloc()] </li>
7145: ** <li> [sqlite3_mutex_free()] </li>
7146: ** <li> [sqlite3_mutex_enter()] </li>
7147: ** <li> [sqlite3_mutex_try()] </li>
7148: ** <li> [sqlite3_mutex_leave()] </li>
7149: ** <li> [sqlite3_mutex_held()] </li>
7150: ** <li> [sqlite3_mutex_notheld()] </li>
7151: ** </ul>)^
7152: **
7153: ** The only difference is that the public sqlite3_XXX functions enumerated
7154: ** above silently ignore any invocations that pass a NULL pointer instead
7155: ** of a valid mutex handle. The implementations of the methods defined
7156: ** by this structure are not required to handle this case, the results
7157: ** of passing a NULL pointer instead of a valid mutex handle are undefined
7158: ** (i.e. it is acceptable to provide an implementation that segfaults if
7159: ** it is passed a NULL pointer).
7160: **
1.4 misho 7161: ** The xMutexInit() method must be threadsafe. It must be harmless to
1.2 misho 7162: ** invoke xMutexInit() multiple times within the same process and without
7163: ** intervening calls to xMutexEnd(). Second and subsequent calls to
7164: ** xMutexInit() must be no-ops.
7165: **
1.4 misho 7166: ** xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()]
7167: ** and its associates). Similarly, xMutexAlloc() must not use SQLite memory
1.2 misho 7168: ** allocation for a static mutex. ^However xMutexAlloc() may use SQLite
7169: ** memory allocation for a fast or recursive mutex.
7170: **
7171: ** ^SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is
7172: ** called, but only if the prior call to xMutexInit returned SQLITE_OK.
7173: ** If xMutexInit fails in any way, it is expected to clean up after itself
7174: ** prior to returning.
7175: */
7176: typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
7177: struct sqlite3_mutex_methods {
7178: int (*xMutexInit)(void);
7179: int (*xMutexEnd)(void);
7180: sqlite3_mutex *(*xMutexAlloc)(int);
7181: void (*xMutexFree)(sqlite3_mutex *);
7182: void (*xMutexEnter)(sqlite3_mutex *);
7183: int (*xMutexTry)(sqlite3_mutex *);
7184: void (*xMutexLeave)(sqlite3_mutex *);
7185: int (*xMutexHeld)(sqlite3_mutex *);
7186: int (*xMutexNotheld)(sqlite3_mutex *);
7187: };
7188:
7189: /*
7190: ** CAPI3REF: Mutex Verification Routines
7191: **
7192: ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
1.4 misho 7193: ** are intended for use inside assert() statements. The SQLite core
1.2 misho 7194: ** never uses these routines except inside an assert() and applications
1.4 misho 7195: ** are advised to follow the lead of the core. The SQLite core only
1.2 misho 7196: ** provides implementations for these routines when it is compiled
1.4 misho 7197: ** with the SQLITE_DEBUG flag. External mutex implementations
1.2 misho 7198: ** are only required to provide these routines if SQLITE_DEBUG is
7199: ** defined and if NDEBUG is not defined.
7200: **
1.4 misho 7201: ** These routines should return true if the mutex in their argument
1.2 misho 7202: ** is held or not held, respectively, by the calling thread.
7203: **
1.4 misho 7204: ** The implementation is not required to provide versions of these
1.2 misho 7205: ** routines that actually work. If the implementation does not provide working
7206: ** versions of these routines, it should at least provide stubs that always
7207: ** return true so that one does not get spurious assertion failures.
7208: **
1.4 misho 7209: ** If the argument to sqlite3_mutex_held() is a NULL pointer then
1.2 misho 7210: ** the routine should return 1. This seems counter-intuitive since
7211: ** clearly the mutex cannot be held if it does not exist. But
7212: ** the reason the mutex does not exist is because the build is not
7213: ** using mutexes. And we do not want the assert() containing the
7214: ** call to sqlite3_mutex_held() to fail, so a non-zero return is
1.4 misho 7215: ** the appropriate thing to do. The sqlite3_mutex_notheld()
1.2 misho 7216: ** interface should also return 1 when given a NULL pointer.
7217: */
7218: #ifndef NDEBUG
7219: SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*);
7220: SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*);
7221: #endif
7222:
7223: /*
7224: ** CAPI3REF: Mutex Types
7225: **
7226: ** The [sqlite3_mutex_alloc()] interface takes a single argument
7227: ** which is one of these integer constants.
7228: **
7229: ** The set of static mutexes may change from one SQLite release to the
7230: ** next. Applications that override the built-in mutex logic must be
7231: ** prepared to accommodate additional static mutexes.
7232: */
7233: #define SQLITE_MUTEX_FAST 0
7234: #define SQLITE_MUTEX_RECURSIVE 1
7235: #define SQLITE_MUTEX_STATIC_MASTER 2
7236: #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */
7237: #define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */
7238: #define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */
1.4.2.1 misho 7239: #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_randomness() */
1.2 misho 7240: #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
7241: #define SQLITE_MUTEX_STATIC_LRU2 7 /* NOT USED */
7242: #define SQLITE_MUTEX_STATIC_PMEM 7 /* sqlite3PageMalloc() */
1.4 misho 7243: #define SQLITE_MUTEX_STATIC_APP1 8 /* For use by application */
7244: #define SQLITE_MUTEX_STATIC_APP2 9 /* For use by application */
7245: #define SQLITE_MUTEX_STATIC_APP3 10 /* For use by application */
7246: #define SQLITE_MUTEX_STATIC_VFS1 11 /* For use by built-in VFS */
7247: #define SQLITE_MUTEX_STATIC_VFS2 12 /* For use by extension VFS */
7248: #define SQLITE_MUTEX_STATIC_VFS3 13 /* For use by application VFS */
1.2 misho 7249:
7250: /*
7251: ** CAPI3REF: Retrieve the mutex for a database connection
1.4 misho 7252: ** METHOD: sqlite3
1.2 misho 7253: **
7254: ** ^This interface returns a pointer the [sqlite3_mutex] object that
7255: ** serializes access to the [database connection] given in the argument
7256: ** when the [threading mode] is Serialized.
7257: ** ^If the [threading mode] is Single-thread or Multi-thread then this
7258: ** routine returns a NULL pointer.
7259: */
7260: SQLITE_API sqlite3_mutex *sqlite3_db_mutex(sqlite3*);
7261:
7262: /*
7263: ** CAPI3REF: Low-Level Control Of Database Files
1.4 misho 7264: ** METHOD: sqlite3
1.4.2.2 ! misho 7265: ** KEYWORDS: {file control}
1.2 misho 7266: **
7267: ** ^The [sqlite3_file_control()] interface makes a direct call to the
7268: ** xFileControl method for the [sqlite3_io_methods] object associated
7269: ** with a particular database identified by the second argument. ^The
7270: ** name of the database is "main" for the main database or "temp" for the
7271: ** TEMP database, or the name that appears after the AS keyword for
7272: ** databases that are added using the [ATTACH] SQL command.
7273: ** ^A NULL pointer can be used in place of "main" to refer to the
7274: ** main database file.
7275: ** ^The third and fourth parameters to this routine
7276: ** are passed directly through to the second and third parameters of
7277: ** the xFileControl method. ^The return value of the xFileControl
7278: ** method becomes the return value of this routine.
7279: **
1.4.2.2 ! misho 7280: ** A few opcodes for [sqlite3_file_control()] are handled directly
! 7281: ** by the SQLite core and never invoke the
! 7282: ** sqlite3_io_methods.xFileControl method.
! 7283: ** ^The [SQLITE_FCNTL_FILE_POINTER] value for the op parameter causes
1.2 misho 7284: ** a pointer to the underlying [sqlite3_file] object to be written into
1.4.2.2 ! misho 7285: ** the space pointed to by the 4th parameter. The
! 7286: ** [SQLITE_FCNTL_JOURNAL_POINTER] works similarly except that it returns
! 7287: ** the [sqlite3_file] object associated with the journal file instead of
! 7288: ** the main database. The [SQLITE_FCNTL_VFS_POINTER] opcode returns
! 7289: ** a pointer to the underlying [sqlite3_vfs] object for the file.
! 7290: ** The [SQLITE_FCNTL_DATA_VERSION] returns the data version counter
! 7291: ** from the pager.
1.2 misho 7292: **
7293: ** ^If the second parameter (zDbName) does not match the name of any
7294: ** open database file, then SQLITE_ERROR is returned. ^This error
7295: ** code is not remembered and will not be recalled by [sqlite3_errcode()]
7296: ** or [sqlite3_errmsg()]. The underlying xFileControl method might
7297: ** also return SQLITE_ERROR. There is no way to distinguish between
7298: ** an incorrect zDbName and an SQLITE_ERROR return from the underlying
7299: ** xFileControl method.
7300: **
1.4.2.2 ! misho 7301: ** See also: [file control opcodes]
1.2 misho 7302: */
7303: SQLITE_API int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
7304:
7305: /*
7306: ** CAPI3REF: Testing Interface
7307: **
7308: ** ^The sqlite3_test_control() interface is used to read out internal
7309: ** state of SQLite and to inject faults into SQLite for testing
7310: ** purposes. ^The first parameter is an operation code that determines
7311: ** the number, meaning, and operation of all subsequent parameters.
7312: **
7313: ** This interface is not for use by applications. It exists solely
7314: ** for verifying the correct operation of the SQLite library. Depending
7315: ** on how the SQLite library is compiled, this interface might not exist.
7316: **
7317: ** The details of the operation codes, their meanings, the parameters
7318: ** they take, and what they do are all subject to change without notice.
7319: ** Unlike most of the SQLite API, this function is not guaranteed to
7320: ** operate consistently from one release to the next.
7321: */
7322: SQLITE_API int sqlite3_test_control(int op, ...);
7323:
7324: /*
7325: ** CAPI3REF: Testing Interface Operation Codes
7326: **
7327: ** These constants are the valid operation code parameters used
7328: ** as the first argument to [sqlite3_test_control()].
7329: **
7330: ** These parameters and their meanings are subject to change
7331: ** without notice. These values are for testing purposes only.
7332: ** Applications should not use any of these parameters or the
7333: ** [sqlite3_test_control()] interface.
7334: */
7335: #define SQLITE_TESTCTRL_FIRST 5
7336: #define SQLITE_TESTCTRL_PRNG_SAVE 5
7337: #define SQLITE_TESTCTRL_PRNG_RESTORE 6
7338: #define SQLITE_TESTCTRL_PRNG_RESET 7
7339: #define SQLITE_TESTCTRL_BITVEC_TEST 8
7340: #define SQLITE_TESTCTRL_FAULT_INSTALL 9
7341: #define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10
7342: #define SQLITE_TESTCTRL_PENDING_BYTE 11
7343: #define SQLITE_TESTCTRL_ASSERT 12
7344: #define SQLITE_TESTCTRL_ALWAYS 13
7345: #define SQLITE_TESTCTRL_RESERVE 14
7346: #define SQLITE_TESTCTRL_OPTIMIZATIONS 15
1.4.2.2 ! misho 7347: #define SQLITE_TESTCTRL_ISKEYWORD 16 /* NOT USED */
! 7348: #define SQLITE_TESTCTRL_SCRATCHMALLOC 17 /* NOT USED */
! 7349: #define SQLITE_TESTCTRL_INTERNAL_FUNCTIONS 17
1.2 misho 7350: #define SQLITE_TESTCTRL_LOCALTIME_FAULT 18
1.4 misho 7351: #define SQLITE_TESTCTRL_EXPLAIN_STMT 19 /* NOT USED */
1.4.2.1 misho 7352: #define SQLITE_TESTCTRL_ONCE_RESET_THRESHOLD 19
1.4 misho 7353: #define SQLITE_TESTCTRL_NEVER_CORRUPT 20
7354: #define SQLITE_TESTCTRL_VDBE_COVERAGE 21
7355: #define SQLITE_TESTCTRL_BYTEORDER 22
7356: #define SQLITE_TESTCTRL_ISINIT 23
7357: #define SQLITE_TESTCTRL_SORTER_MMAP 24
7358: #define SQLITE_TESTCTRL_IMPOSTER 25
1.4.2.2 ! misho 7359: #define SQLITE_TESTCTRL_PARSER_COVERAGE 26
! 7360: #define SQLITE_TESTCTRL_RESULT_INTREAL 27
! 7361: #define SQLITE_TESTCTRL_LAST 27 /* Largest TESTCTRL */
! 7362:
! 7363: /*
! 7364: ** CAPI3REF: SQL Keyword Checking
! 7365: **
! 7366: ** These routines provide access to the set of SQL language keywords
! 7367: ** recognized by SQLite. Applications can uses these routines to determine
! 7368: ** whether or not a specific identifier needs to be escaped (for example,
! 7369: ** by enclosing in double-quotes) so as not to confuse the parser.
! 7370: **
! 7371: ** The sqlite3_keyword_count() interface returns the number of distinct
! 7372: ** keywords understood by SQLite.
! 7373: **
! 7374: ** The sqlite3_keyword_name(N,Z,L) interface finds the N-th keyword and
! 7375: ** makes *Z point to that keyword expressed as UTF8 and writes the number
! 7376: ** of bytes in the keyword into *L. The string that *Z points to is not
! 7377: ** zero-terminated. The sqlite3_keyword_name(N,Z,L) routine returns
! 7378: ** SQLITE_OK if N is within bounds and SQLITE_ERROR if not. If either Z
! 7379: ** or L are NULL or invalid pointers then calls to
! 7380: ** sqlite3_keyword_name(N,Z,L) result in undefined behavior.
! 7381: **
! 7382: ** The sqlite3_keyword_check(Z,L) interface checks to see whether or not
! 7383: ** the L-byte UTF8 identifier that Z points to is a keyword, returning non-zero
! 7384: ** if it is and zero if not.
! 7385: **
! 7386: ** The parser used by SQLite is forgiving. It is often possible to use
! 7387: ** a keyword as an identifier as long as such use does not result in a
! 7388: ** parsing ambiguity. For example, the statement
! 7389: ** "CREATE TABLE BEGIN(REPLACE,PRAGMA,END);" is accepted by SQLite, and
! 7390: ** creates a new table named "BEGIN" with three columns named
! 7391: ** "REPLACE", "PRAGMA", and "END". Nevertheless, best practice is to avoid
! 7392: ** using keywords as identifiers. Common techniques used to avoid keyword
! 7393: ** name collisions include:
! 7394: ** <ul>
! 7395: ** <li> Put all identifier names inside double-quotes. This is the official
! 7396: ** SQL way to escape identifier names.
! 7397: ** <li> Put identifier names inside [...]. This is not standard SQL,
! 7398: ** but it is what SQL Server does and so lots of programmers use this
! 7399: ** technique.
! 7400: ** <li> Begin every identifier with the letter "Z" as no SQL keywords start
! 7401: ** with "Z".
! 7402: ** <li> Include a digit somewhere in every identifier name.
! 7403: ** </ul>
! 7404: **
! 7405: ** Note that the number of keywords understood by SQLite can depend on
! 7406: ** compile-time options. For example, "VACUUM" is not a keyword if
! 7407: ** SQLite is compiled with the [-DSQLITE_OMIT_VACUUM] option. Also,
! 7408: ** new keywords may be added to future releases of SQLite.
! 7409: */
! 7410: SQLITE_API int sqlite3_keyword_count(void);
! 7411: SQLITE_API int sqlite3_keyword_name(int,const char**,int*);
! 7412: SQLITE_API int sqlite3_keyword_check(const char*,int);
! 7413:
! 7414: /*
! 7415: ** CAPI3REF: Dynamic String Object
! 7416: ** KEYWORDS: {dynamic string}
! 7417: **
! 7418: ** An instance of the sqlite3_str object contains a dynamically-sized
! 7419: ** string under construction.
! 7420: **
! 7421: ** The lifecycle of an sqlite3_str object is as follows:
! 7422: ** <ol>
! 7423: ** <li> ^The sqlite3_str object is created using [sqlite3_str_new()].
! 7424: ** <li> ^Text is appended to the sqlite3_str object using various
! 7425: ** methods, such as [sqlite3_str_appendf()].
! 7426: ** <li> ^The sqlite3_str object is destroyed and the string it created
! 7427: ** is returned using the [sqlite3_str_finish()] interface.
! 7428: ** </ol>
! 7429: */
! 7430: typedef struct sqlite3_str sqlite3_str;
! 7431:
! 7432: /*
! 7433: ** CAPI3REF: Create A New Dynamic String Object
! 7434: ** CONSTRUCTOR: sqlite3_str
! 7435: **
! 7436: ** ^The [sqlite3_str_new(D)] interface allocates and initializes
! 7437: ** a new [sqlite3_str] object. To avoid memory leaks, the object returned by
! 7438: ** [sqlite3_str_new()] must be freed by a subsequent call to
! 7439: ** [sqlite3_str_finish(X)].
! 7440: **
! 7441: ** ^The [sqlite3_str_new(D)] interface always returns a pointer to a
! 7442: ** valid [sqlite3_str] object, though in the event of an out-of-memory
! 7443: ** error the returned object might be a special singleton that will
! 7444: ** silently reject new text, always return SQLITE_NOMEM from
! 7445: ** [sqlite3_str_errcode()], always return 0 for
! 7446: ** [sqlite3_str_length()], and always return NULL from
! 7447: ** [sqlite3_str_finish(X)]. It is always safe to use the value
! 7448: ** returned by [sqlite3_str_new(D)] as the sqlite3_str parameter
! 7449: ** to any of the other [sqlite3_str] methods.
! 7450: **
! 7451: ** The D parameter to [sqlite3_str_new(D)] may be NULL. If the
! 7452: ** D parameter in [sqlite3_str_new(D)] is not NULL, then the maximum
! 7453: ** length of the string contained in the [sqlite3_str] object will be
! 7454: ** the value set for [sqlite3_limit](D,[SQLITE_LIMIT_LENGTH]) instead
! 7455: ** of [SQLITE_MAX_LENGTH].
! 7456: */
! 7457: SQLITE_API sqlite3_str *sqlite3_str_new(sqlite3*);
! 7458:
! 7459: /*
! 7460: ** CAPI3REF: Finalize A Dynamic String
! 7461: ** DESTRUCTOR: sqlite3_str
! 7462: **
! 7463: ** ^The [sqlite3_str_finish(X)] interface destroys the sqlite3_str object X
! 7464: ** and returns a pointer to a memory buffer obtained from [sqlite3_malloc64()]
! 7465: ** that contains the constructed string. The calling application should
! 7466: ** pass the returned value to [sqlite3_free()] to avoid a memory leak.
! 7467: ** ^The [sqlite3_str_finish(X)] interface may return a NULL pointer if any
! 7468: ** errors were encountered during construction of the string. ^The
! 7469: ** [sqlite3_str_finish(X)] interface will also return a NULL pointer if the
! 7470: ** string in [sqlite3_str] object X is zero bytes long.
! 7471: */
! 7472: SQLITE_API char *sqlite3_str_finish(sqlite3_str*);
! 7473:
! 7474: /*
! 7475: ** CAPI3REF: Add Content To A Dynamic String
! 7476: ** METHOD: sqlite3_str
! 7477: **
! 7478: ** These interfaces add content to an sqlite3_str object previously obtained
! 7479: ** from [sqlite3_str_new()].
! 7480: **
! 7481: ** ^The [sqlite3_str_appendf(X,F,...)] and
! 7482: ** [sqlite3_str_vappendf(X,F,V)] interfaces uses the [built-in printf]
! 7483: ** functionality of SQLite to append formatted text onto the end of
! 7484: ** [sqlite3_str] object X.
! 7485: **
! 7486: ** ^The [sqlite3_str_append(X,S,N)] method appends exactly N bytes from string S
! 7487: ** onto the end of the [sqlite3_str] object X. N must be non-negative.
! 7488: ** S must contain at least N non-zero bytes of content. To append a
! 7489: ** zero-terminated string in its entirety, use the [sqlite3_str_appendall()]
! 7490: ** method instead.
! 7491: **
! 7492: ** ^The [sqlite3_str_appendall(X,S)] method appends the complete content of
! 7493: ** zero-terminated string S onto the end of [sqlite3_str] object X.
! 7494: **
! 7495: ** ^The [sqlite3_str_appendchar(X,N,C)] method appends N copies of the
! 7496: ** single-byte character C onto the end of [sqlite3_str] object X.
! 7497: ** ^This method can be used, for example, to add whitespace indentation.
! 7498: **
! 7499: ** ^The [sqlite3_str_reset(X)] method resets the string under construction
! 7500: ** inside [sqlite3_str] object X back to zero bytes in length.
! 7501: **
! 7502: ** These methods do not return a result code. ^If an error occurs, that fact
! 7503: ** is recorded in the [sqlite3_str] object and can be recovered by a
! 7504: ** subsequent call to [sqlite3_str_errcode(X)].
! 7505: */
! 7506: SQLITE_API void sqlite3_str_appendf(sqlite3_str*, const char *zFormat, ...);
! 7507: SQLITE_API void sqlite3_str_vappendf(sqlite3_str*, const char *zFormat, va_list);
! 7508: SQLITE_API void sqlite3_str_append(sqlite3_str*, const char *zIn, int N);
! 7509: SQLITE_API void sqlite3_str_appendall(sqlite3_str*, const char *zIn);
! 7510: SQLITE_API void sqlite3_str_appendchar(sqlite3_str*, int N, char C);
! 7511: SQLITE_API void sqlite3_str_reset(sqlite3_str*);
! 7512:
! 7513: /*
! 7514: ** CAPI3REF: Status Of A Dynamic String
! 7515: ** METHOD: sqlite3_str
! 7516: **
! 7517: ** These interfaces return the current status of an [sqlite3_str] object.
! 7518: **
! 7519: ** ^If any prior errors have occurred while constructing the dynamic string
! 7520: ** in sqlite3_str X, then the [sqlite3_str_errcode(X)] method will return
! 7521: ** an appropriate error code. ^The [sqlite3_str_errcode(X)] method returns
! 7522: ** [SQLITE_NOMEM] following any out-of-memory error, or
! 7523: ** [SQLITE_TOOBIG] if the size of the dynamic string exceeds
! 7524: ** [SQLITE_MAX_LENGTH], or [SQLITE_OK] if there have been no errors.
! 7525: **
! 7526: ** ^The [sqlite3_str_length(X)] method returns the current length, in bytes,
! 7527: ** of the dynamic string under construction in [sqlite3_str] object X.
! 7528: ** ^The length returned by [sqlite3_str_length(X)] does not include the
! 7529: ** zero-termination byte.
! 7530: **
! 7531: ** ^The [sqlite3_str_value(X)] method returns a pointer to the current
! 7532: ** content of the dynamic string under construction in X. The value
! 7533: ** returned by [sqlite3_str_value(X)] is managed by the sqlite3_str object X
! 7534: ** and might be freed or altered by any subsequent method on the same
! 7535: ** [sqlite3_str] object. Applications must not used the pointer returned
! 7536: ** [sqlite3_str_value(X)] after any subsequent method call on the same
! 7537: ** object. ^Applications may change the content of the string returned
! 7538: ** by [sqlite3_str_value(X)] as long as they do not write into any bytes
! 7539: ** outside the range of 0 to [sqlite3_str_length(X)] and do not read or
! 7540: ** write any byte after any subsequent sqlite3_str method call.
! 7541: */
! 7542: SQLITE_API int sqlite3_str_errcode(sqlite3_str*);
! 7543: SQLITE_API int sqlite3_str_length(sqlite3_str*);
! 7544: SQLITE_API char *sqlite3_str_value(sqlite3_str*);
1.2 misho 7545:
7546: /*
7547: ** CAPI3REF: SQLite Runtime Status
7548: **
1.4 misho 7549: ** ^These interfaces are used to retrieve runtime status information
1.2 misho 7550: ** about the performance of SQLite, and optionally to reset various
7551: ** highwater marks. ^The first argument is an integer code for
7552: ** the specific parameter to measure. ^(Recognized integer codes
7553: ** are of the form [status parameters | SQLITE_STATUS_...].)^
7554: ** ^The current value of the parameter is returned into *pCurrent.
7555: ** ^The highest recorded value is returned in *pHighwater. ^If the
7556: ** resetFlag is true, then the highest record value is reset after
7557: ** *pHighwater is written. ^(Some parameters do not record the highest
7558: ** value. For those parameters
7559: ** nothing is written into *pHighwater and the resetFlag is ignored.)^
7560: ** ^(Other parameters record only the highwater mark and not the current
7561: ** value. For these latter parameters nothing is written into *pCurrent.)^
7562: **
1.4 misho 7563: ** ^The sqlite3_status() and sqlite3_status64() routines return
7564: ** SQLITE_OK on success and a non-zero [error code] on failure.
1.2 misho 7565: **
1.4 misho 7566: ** If either the current value or the highwater mark is too large to
7567: ** be represented by a 32-bit integer, then the values returned by
7568: ** sqlite3_status() are undefined.
1.2 misho 7569: **
7570: ** See also: [sqlite3_db_status()]
7571: */
7572: SQLITE_API int sqlite3_status(int op, int *pCurrent, int *pHighwater, int resetFlag);
1.4 misho 7573: SQLITE_API int sqlite3_status64(
7574: int op,
7575: sqlite3_int64 *pCurrent,
7576: sqlite3_int64 *pHighwater,
7577: int resetFlag
7578: );
1.2 misho 7579:
7580:
7581: /*
7582: ** CAPI3REF: Status Parameters
7583: ** KEYWORDS: {status parameters}
7584: **
7585: ** These integer constants designate various run-time status parameters
7586: ** that can be returned by [sqlite3_status()].
7587: **
7588: ** <dl>
7589: ** [[SQLITE_STATUS_MEMORY_USED]] ^(<dt>SQLITE_STATUS_MEMORY_USED</dt>
7590: ** <dd>This parameter is the current amount of memory checked out
7591: ** using [sqlite3_malloc()], either directly or indirectly. The
7592: ** figure includes calls made to [sqlite3_malloc()] by the application
1.4.2.2 ! misho 7593: ** and internal memory usage by the SQLite library. Auxiliary page-cache
1.2 misho 7594: ** memory controlled by [SQLITE_CONFIG_PAGECACHE] is not included in
7595: ** this parameter. The amount returned is the sum of the allocation
7596: ** sizes as reported by the xSize method in [sqlite3_mem_methods].</dd>)^
7597: **
7598: ** [[SQLITE_STATUS_MALLOC_SIZE]] ^(<dt>SQLITE_STATUS_MALLOC_SIZE</dt>
7599: ** <dd>This parameter records the largest memory allocation request
7600: ** handed to [sqlite3_malloc()] or [sqlite3_realloc()] (or their
7601: ** internal equivalents). Only the value returned in the
7602: ** *pHighwater parameter to [sqlite3_status()] is of interest.
7603: ** The value written into the *pCurrent parameter is undefined.</dd>)^
7604: **
7605: ** [[SQLITE_STATUS_MALLOC_COUNT]] ^(<dt>SQLITE_STATUS_MALLOC_COUNT</dt>
7606: ** <dd>This parameter records the number of separate memory allocations
7607: ** currently checked out.</dd>)^
7608: **
7609: ** [[SQLITE_STATUS_PAGECACHE_USED]] ^(<dt>SQLITE_STATUS_PAGECACHE_USED</dt>
7610: ** <dd>This parameter returns the number of pages used out of the
7611: ** [pagecache memory allocator] that was configured using
7612: ** [SQLITE_CONFIG_PAGECACHE]. The
7613: ** value returned is in pages, not in bytes.</dd>)^
7614: **
7615: ** [[SQLITE_STATUS_PAGECACHE_OVERFLOW]]
7616: ** ^(<dt>SQLITE_STATUS_PAGECACHE_OVERFLOW</dt>
7617: ** <dd>This parameter returns the number of bytes of page cache
7618: ** allocation which could not be satisfied by the [SQLITE_CONFIG_PAGECACHE]
7619: ** buffer and where forced to overflow to [sqlite3_malloc()]. The
7620: ** returned value includes allocations that overflowed because they
7621: ** where too large (they were larger than the "sz" parameter to
7622: ** [SQLITE_CONFIG_PAGECACHE]) and allocations that overflowed because
7623: ** no space was left in the page cache.</dd>)^
7624: **
7625: ** [[SQLITE_STATUS_PAGECACHE_SIZE]] ^(<dt>SQLITE_STATUS_PAGECACHE_SIZE</dt>
7626: ** <dd>This parameter records the largest memory allocation request
7627: ** handed to [pagecache memory allocator]. Only the value returned in the
7628: ** *pHighwater parameter to [sqlite3_status()] is of interest.
7629: ** The value written into the *pCurrent parameter is undefined.</dd>)^
7630: **
1.4.2.2 ! misho 7631: ** [[SQLITE_STATUS_SCRATCH_USED]] <dt>SQLITE_STATUS_SCRATCH_USED</dt>
! 7632: ** <dd>No longer used.</dd>
1.2 misho 7633: **
7634: ** [[SQLITE_STATUS_SCRATCH_OVERFLOW]] ^(<dt>SQLITE_STATUS_SCRATCH_OVERFLOW</dt>
1.4.2.2 ! misho 7635: ** <dd>No longer used.</dd>
1.2 misho 7636: **
1.4.2.2 ! misho 7637: ** [[SQLITE_STATUS_SCRATCH_SIZE]] <dt>SQLITE_STATUS_SCRATCH_SIZE</dt>
! 7638: ** <dd>No longer used.</dd>
1.2 misho 7639: **
7640: ** [[SQLITE_STATUS_PARSER_STACK]] ^(<dt>SQLITE_STATUS_PARSER_STACK</dt>
1.4 misho 7641: ** <dd>The *pHighwater parameter records the deepest parser stack.
7642: ** The *pCurrent value is undefined. The *pHighwater value is only
1.2 misho 7643: ** meaningful if SQLite is compiled with [YYTRACKMAXSTACKDEPTH].</dd>)^
7644: ** </dl>
7645: **
7646: ** New status parameters may be added from time to time.
7647: */
7648: #define SQLITE_STATUS_MEMORY_USED 0
7649: #define SQLITE_STATUS_PAGECACHE_USED 1
7650: #define SQLITE_STATUS_PAGECACHE_OVERFLOW 2
1.4.2.2 ! misho 7651: #define SQLITE_STATUS_SCRATCH_USED 3 /* NOT USED */
! 7652: #define SQLITE_STATUS_SCRATCH_OVERFLOW 4 /* NOT USED */
1.2 misho 7653: #define SQLITE_STATUS_MALLOC_SIZE 5
7654: #define SQLITE_STATUS_PARSER_STACK 6
7655: #define SQLITE_STATUS_PAGECACHE_SIZE 7
1.4.2.2 ! misho 7656: #define SQLITE_STATUS_SCRATCH_SIZE 8 /* NOT USED */
1.2 misho 7657: #define SQLITE_STATUS_MALLOC_COUNT 9
7658:
7659: /*
7660: ** CAPI3REF: Database Connection Status
1.4 misho 7661: ** METHOD: sqlite3
1.2 misho 7662: **
7663: ** ^This interface is used to retrieve runtime status information
7664: ** about a single [database connection]. ^The first argument is the
7665: ** database connection object to be interrogated. ^The second argument
7666: ** is an integer constant, taken from the set of
7667: ** [SQLITE_DBSTATUS options], that
7668: ** determines the parameter to interrogate. The set of
7669: ** [SQLITE_DBSTATUS options] is likely
7670: ** to grow in future releases of SQLite.
7671: **
7672: ** ^The current value of the requested parameter is written into *pCur
7673: ** and the highest instantaneous value is written into *pHiwtr. ^If
7674: ** the resetFlg is true, then the highest instantaneous value is
7675: ** reset back down to the current value.
7676: **
7677: ** ^The sqlite3_db_status() routine returns SQLITE_OK on success and a
7678: ** non-zero [error code] on failure.
7679: **
7680: ** See also: [sqlite3_status()] and [sqlite3_stmt_status()].
7681: */
7682: SQLITE_API int sqlite3_db_status(sqlite3*, int op, int *pCur, int *pHiwtr, int resetFlg);
7683:
7684: /*
7685: ** CAPI3REF: Status Parameters for database connections
7686: ** KEYWORDS: {SQLITE_DBSTATUS options}
7687: **
7688: ** These constants are the available integer "verbs" that can be passed as
7689: ** the second argument to the [sqlite3_db_status()] interface.
7690: **
7691: ** New verbs may be added in future releases of SQLite. Existing verbs
7692: ** might be discontinued. Applications should check the return code from
7693: ** [sqlite3_db_status()] to make sure that the call worked.
7694: ** The [sqlite3_db_status()] interface will return a non-zero error code
7695: ** if a discontinued or unsupported verb is invoked.
7696: **
7697: ** <dl>
7698: ** [[SQLITE_DBSTATUS_LOOKASIDE_USED]] ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>
7699: ** <dd>This parameter returns the number of lookaside memory slots currently
7700: ** checked out.</dd>)^
7701: **
7702: ** [[SQLITE_DBSTATUS_LOOKASIDE_HIT]] ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_HIT</dt>
7703: ** <dd>This parameter returns the number malloc attempts that were
7704: ** satisfied using lookaside memory. Only the high-water value is meaningful;
7705: ** the current value is always zero.)^
7706: **
7707: ** [[SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE]]
7708: ** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE</dt>
7709: ** <dd>This parameter returns the number malloc attempts that might have
7710: ** been satisfied using lookaside memory but failed due to the amount of
7711: ** memory requested being larger than the lookaside slot size.
7712: ** Only the high-water value is meaningful;
7713: ** the current value is always zero.)^
7714: **
7715: ** [[SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL]]
7716: ** ^(<dt>SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL</dt>
7717: ** <dd>This parameter returns the number malloc attempts that might have
7718: ** been satisfied using lookaside memory but failed due to all lookaside
7719: ** memory already being in use.
7720: ** Only the high-water value is meaningful;
7721: ** the current value is always zero.)^
7722: **
7723: ** [[SQLITE_DBSTATUS_CACHE_USED]] ^(<dt>SQLITE_DBSTATUS_CACHE_USED</dt>
1.4 misho 7724: ** <dd>This parameter returns the approximate number of bytes of heap
1.2 misho 7725: ** memory used by all pager caches associated with the database connection.)^
7726: ** ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_USED is always 0.
7727: **
1.4 misho 7728: ** [[SQLITE_DBSTATUS_CACHE_USED_SHARED]]
7729: ** ^(<dt>SQLITE_DBSTATUS_CACHE_USED_SHARED</dt>
7730: ** <dd>This parameter is similar to DBSTATUS_CACHE_USED, except that if a
7731: ** pager cache is shared between two or more connections the bytes of heap
7732: ** memory used by that pager cache is divided evenly between the attached
7733: ** connections.)^ In other words, if none of the pager caches associated
7734: ** with the database connection are shared, this request returns the same
7735: ** value as DBSTATUS_CACHE_USED. Or, if one or more or the pager caches are
7736: ** shared, the value returned by this call will be smaller than that returned
7737: ** by DBSTATUS_CACHE_USED. ^The highwater mark associated with
7738: ** SQLITE_DBSTATUS_CACHE_USED_SHARED is always 0.
7739: **
1.2 misho 7740: ** [[SQLITE_DBSTATUS_SCHEMA_USED]] ^(<dt>SQLITE_DBSTATUS_SCHEMA_USED</dt>
1.4 misho 7741: ** <dd>This parameter returns the approximate number of bytes of heap
1.2 misho 7742: ** memory used to store the schema for all databases associated
7743: ** with the connection - main, temp, and any [ATTACH]-ed databases.)^
7744: ** ^The full amount of memory used by the schemas is reported, even if the
7745: ** schema memory is shared with other database connections due to
7746: ** [shared cache mode] being enabled.
7747: ** ^The highwater mark associated with SQLITE_DBSTATUS_SCHEMA_USED is always 0.
7748: **
7749: ** [[SQLITE_DBSTATUS_STMT_USED]] ^(<dt>SQLITE_DBSTATUS_STMT_USED</dt>
1.4 misho 7750: ** <dd>This parameter returns the approximate number of bytes of heap
1.2 misho 7751: ** and lookaside memory used by all prepared statements associated with
7752: ** the database connection.)^
7753: ** ^The highwater mark associated with SQLITE_DBSTATUS_STMT_USED is always 0.
7754: ** </dd>
7755: **
7756: ** [[SQLITE_DBSTATUS_CACHE_HIT]] ^(<dt>SQLITE_DBSTATUS_CACHE_HIT</dt>
7757: ** <dd>This parameter returns the number of pager cache hits that have
7758: ** occurred.)^ ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_HIT
7759: ** is always 0.
7760: ** </dd>
7761: **
7762: ** [[SQLITE_DBSTATUS_CACHE_MISS]] ^(<dt>SQLITE_DBSTATUS_CACHE_MISS</dt>
7763: ** <dd>This parameter returns the number of pager cache misses that have
7764: ** occurred.)^ ^The highwater mark associated with SQLITE_DBSTATUS_CACHE_MISS
7765: ** is always 0.
7766: ** </dd>
1.3 misho 7767: **
7768: ** [[SQLITE_DBSTATUS_CACHE_WRITE]] ^(<dt>SQLITE_DBSTATUS_CACHE_WRITE</dt>
7769: ** <dd>This parameter returns the number of dirty cache entries that have
7770: ** been written to disk. Specifically, the number of pages written to the
7771: ** wal file in wal mode databases, or the number of pages written to the
7772: ** database file in rollback mode databases. Any pages written as part of
7773: ** transaction rollback or database recovery operations are not included.
7774: ** If an IO or other error occurs while writing a page to disk, the effect
7775: ** on subsequent SQLITE_DBSTATUS_CACHE_WRITE requests is undefined.)^ ^The
7776: ** highwater mark associated with SQLITE_DBSTATUS_CACHE_WRITE is always 0.
7777: ** </dd>
1.4 misho 7778: **
1.4.2.2 ! misho 7779: ** [[SQLITE_DBSTATUS_CACHE_SPILL]] ^(<dt>SQLITE_DBSTATUS_CACHE_SPILL</dt>
! 7780: ** <dd>This parameter returns the number of dirty cache entries that have
! 7781: ** been written to disk in the middle of a transaction due to the page
! 7782: ** cache overflowing. Transactions are more efficient if they are written
! 7783: ** to disk all at once. When pages spill mid-transaction, that introduces
! 7784: ** additional overhead. This parameter can be used help identify
! 7785: ** inefficiencies that can be resolve by increasing the cache size.
! 7786: ** </dd>
! 7787: **
1.4 misho 7788: ** [[SQLITE_DBSTATUS_DEFERRED_FKS]] ^(<dt>SQLITE_DBSTATUS_DEFERRED_FKS</dt>
7789: ** <dd>This parameter returns zero for the current value if and only if
7790: ** all foreign key constraints (deferred or immediate) have been
7791: ** resolved.)^ ^The highwater mark is always 0.
7792: ** </dd>
1.2 misho 7793: ** </dl>
7794: */
7795: #define SQLITE_DBSTATUS_LOOKASIDE_USED 0
7796: #define SQLITE_DBSTATUS_CACHE_USED 1
7797: #define SQLITE_DBSTATUS_SCHEMA_USED 2
7798: #define SQLITE_DBSTATUS_STMT_USED 3
7799: #define SQLITE_DBSTATUS_LOOKASIDE_HIT 4
7800: #define SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE 5
7801: #define SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL 6
7802: #define SQLITE_DBSTATUS_CACHE_HIT 7
7803: #define SQLITE_DBSTATUS_CACHE_MISS 8
1.3 misho 7804: #define SQLITE_DBSTATUS_CACHE_WRITE 9
1.4 misho 7805: #define SQLITE_DBSTATUS_DEFERRED_FKS 10
7806: #define SQLITE_DBSTATUS_CACHE_USED_SHARED 11
1.4.2.2 ! misho 7807: #define SQLITE_DBSTATUS_CACHE_SPILL 12
! 7808: #define SQLITE_DBSTATUS_MAX 12 /* Largest defined DBSTATUS */
1.2 misho 7809:
7810:
7811: /*
7812: ** CAPI3REF: Prepared Statement Status
1.4 misho 7813: ** METHOD: sqlite3_stmt
1.2 misho 7814: **
7815: ** ^(Each prepared statement maintains various
7816: ** [SQLITE_STMTSTATUS counters] that measure the number
7817: ** of times it has performed specific operations.)^ These counters can
7818: ** be used to monitor the performance characteristics of the prepared
7819: ** statements. For example, if the number of table steps greatly exceeds
7820: ** the number of table searches or result rows, that would tend to indicate
7821: ** that the prepared statement is using a full table scan rather than
7822: ** an index.
7823: **
7824: ** ^(This interface is used to retrieve and reset counter values from
7825: ** a [prepared statement]. The first argument is the prepared statement
7826: ** object to be interrogated. The second argument
7827: ** is an integer code for a specific [SQLITE_STMTSTATUS counter]
7828: ** to be interrogated.)^
7829: ** ^The current value of the requested counter is returned.
7830: ** ^If the resetFlg is true, then the counter is reset to zero after this
7831: ** interface call returns.
7832: **
7833: ** See also: [sqlite3_status()] and [sqlite3_db_status()].
7834: */
7835: SQLITE_API int sqlite3_stmt_status(sqlite3_stmt*, int op,int resetFlg);
7836:
7837: /*
7838: ** CAPI3REF: Status Parameters for prepared statements
7839: ** KEYWORDS: {SQLITE_STMTSTATUS counter} {SQLITE_STMTSTATUS counters}
7840: **
7841: ** These preprocessor macros define integer codes that name counter
7842: ** values associated with the [sqlite3_stmt_status()] interface.
7843: ** The meanings of the various counters are as follows:
7844: **
7845: ** <dl>
7846: ** [[SQLITE_STMTSTATUS_FULLSCAN_STEP]] <dt>SQLITE_STMTSTATUS_FULLSCAN_STEP</dt>
7847: ** <dd>^This is the number of times that SQLite has stepped forward in
7848: ** a table as part of a full table scan. Large numbers for this counter
7849: ** may indicate opportunities for performance improvement through
7850: ** careful use of indices.</dd>
7851: **
7852: ** [[SQLITE_STMTSTATUS_SORT]] <dt>SQLITE_STMTSTATUS_SORT</dt>
7853: ** <dd>^This is the number of sort operations that have occurred.
7854: ** A non-zero value in this counter may indicate an opportunity to
7855: ** improvement performance through careful use of indices.</dd>
7856: **
7857: ** [[SQLITE_STMTSTATUS_AUTOINDEX]] <dt>SQLITE_STMTSTATUS_AUTOINDEX</dt>
7858: ** <dd>^This is the number of rows inserted into transient indices that
7859: ** were created automatically in order to help joins run faster.
7860: ** A non-zero value in this counter may indicate an opportunity to
7861: ** improvement performance by adding permanent indices that do not
7862: ** need to be reinitialized each time the statement is run.</dd>
1.4 misho 7863: **
7864: ** [[SQLITE_STMTSTATUS_VM_STEP]] <dt>SQLITE_STMTSTATUS_VM_STEP</dt>
7865: ** <dd>^This is the number of virtual machine operations executed
7866: ** by the prepared statement if that number is less than or equal
7867: ** to 2147483647. The number of virtual machine operations can be
7868: ** used as a proxy for the total work done by the prepared statement.
7869: ** If the number of virtual machine operations exceeds 2147483647
7870: ** then the value returned by this statement status code is undefined.
1.4.2.2 ! misho 7871: **
! 7872: ** [[SQLITE_STMTSTATUS_REPREPARE]] <dt>SQLITE_STMTSTATUS_REPREPARE</dt>
! 7873: ** <dd>^This is the number of times that the prepare statement has been
! 7874: ** automatically regenerated due to schema changes or change to
! 7875: ** [bound parameters] that might affect the query plan.
! 7876: **
! 7877: ** [[SQLITE_STMTSTATUS_RUN]] <dt>SQLITE_STMTSTATUS_RUN</dt>
! 7878: ** <dd>^This is the number of times that the prepared statement has
! 7879: ** been run. A single "run" for the purposes of this counter is one
! 7880: ** or more calls to [sqlite3_step()] followed by a call to [sqlite3_reset()].
! 7881: ** The counter is incremented on the first [sqlite3_step()] call of each
! 7882: ** cycle.
! 7883: **
! 7884: ** [[SQLITE_STMTSTATUS_MEMUSED]] <dt>SQLITE_STMTSTATUS_MEMUSED</dt>
! 7885: ** <dd>^This is the approximate number of bytes of heap memory
! 7886: ** used to store the prepared statement. ^This value is not actually
! 7887: ** a counter, and so the resetFlg parameter to sqlite3_stmt_status()
! 7888: ** is ignored when the opcode is SQLITE_STMTSTATUS_MEMUSED.
1.4 misho 7889: ** </dd>
1.2 misho 7890: ** </dl>
7891: */
7892: #define SQLITE_STMTSTATUS_FULLSCAN_STEP 1
7893: #define SQLITE_STMTSTATUS_SORT 2
7894: #define SQLITE_STMTSTATUS_AUTOINDEX 3
1.4 misho 7895: #define SQLITE_STMTSTATUS_VM_STEP 4
1.4.2.2 ! misho 7896: #define SQLITE_STMTSTATUS_REPREPARE 5
! 7897: #define SQLITE_STMTSTATUS_RUN 6
! 7898: #define SQLITE_STMTSTATUS_MEMUSED 99
1.2 misho 7899:
7900: /*
7901: ** CAPI3REF: Custom Page Cache Object
7902: **
7903: ** The sqlite3_pcache type is opaque. It is implemented by
7904: ** the pluggable module. The SQLite core has no knowledge of
7905: ** its size or internal structure and never deals with the
7906: ** sqlite3_pcache object except by holding and passing pointers
7907: ** to the object.
7908: **
7909: ** See [sqlite3_pcache_methods2] for additional information.
7910: */
7911: typedef struct sqlite3_pcache sqlite3_pcache;
7912:
7913: /*
7914: ** CAPI3REF: Custom Page Cache Object
7915: **
7916: ** The sqlite3_pcache_page object represents a single page in the
7917: ** page cache. The page cache will allocate instances of this
7918: ** object. Various methods of the page cache use pointers to instances
7919: ** of this object as parameters or as their return value.
7920: **
7921: ** See [sqlite3_pcache_methods2] for additional information.
7922: */
7923: typedef struct sqlite3_pcache_page sqlite3_pcache_page;
7924: struct sqlite3_pcache_page {
7925: void *pBuf; /* The content of the page */
7926: void *pExtra; /* Extra information associated with the page */
7927: };
7928:
7929: /*
7930: ** CAPI3REF: Application Defined Page Cache.
7931: ** KEYWORDS: {page cache}
7932: **
7933: ** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE2], ...) interface can
7934: ** register an alternative page cache implementation by passing in an
7935: ** instance of the sqlite3_pcache_methods2 structure.)^
7936: ** In many applications, most of the heap memory allocated by
7937: ** SQLite is used for the page cache.
7938: ** By implementing a
7939: ** custom page cache using this API, an application can better control
7940: ** the amount of memory consumed by SQLite, the way in which
7941: ** that memory is allocated and released, and the policies used to
7942: ** determine exactly which parts of a database file are cached and for
7943: ** how long.
7944: **
7945: ** The alternative page cache mechanism is an
7946: ** extreme measure that is only needed by the most demanding applications.
7947: ** The built-in page cache is recommended for most uses.
7948: **
7949: ** ^(The contents of the sqlite3_pcache_methods2 structure are copied to an
7950: ** internal buffer by SQLite within the call to [sqlite3_config]. Hence
7951: ** the application may discard the parameter after the call to
7952: ** [sqlite3_config()] returns.)^
7953: **
7954: ** [[the xInit() page cache method]]
7955: ** ^(The xInit() method is called once for each effective
7956: ** call to [sqlite3_initialize()])^
7957: ** (usually only once during the lifetime of the process). ^(The xInit()
7958: ** method is passed a copy of the sqlite3_pcache_methods2.pArg value.)^
7959: ** The intent of the xInit() method is to set up global data structures
7960: ** required by the custom page cache implementation.
7961: ** ^(If the xInit() method is NULL, then the
7962: ** built-in default page cache is used instead of the application defined
7963: ** page cache.)^
7964: **
7965: ** [[the xShutdown() page cache method]]
7966: ** ^The xShutdown() method is called by [sqlite3_shutdown()].
7967: ** It can be used to clean up
7968: ** any outstanding resources before process shutdown, if required.
7969: ** ^The xShutdown() method may be NULL.
7970: **
7971: ** ^SQLite automatically serializes calls to the xInit method,
7972: ** so the xInit method need not be threadsafe. ^The
7973: ** xShutdown method is only called from [sqlite3_shutdown()] so it does
7974: ** not need to be threadsafe either. All other methods must be threadsafe
7975: ** in multithreaded applications.
7976: **
7977: ** ^SQLite will never invoke xInit() more than once without an intervening
7978: ** call to xShutdown().
7979: **
7980: ** [[the xCreate() page cache methods]]
7981: ** ^SQLite invokes the xCreate() method to construct a new cache instance.
7982: ** SQLite will typically create one cache instance for each open database file,
7983: ** though this is not guaranteed. ^The
7984: ** first parameter, szPage, is the size in bytes of the pages that must
7985: ** be allocated by the cache. ^szPage will always a power of two. ^The
7986: ** second parameter szExtra is a number of bytes of extra storage
7987: ** associated with each page cache entry. ^The szExtra parameter will
7988: ** a number less than 250. SQLite will use the
7989: ** extra szExtra bytes on each page to store metadata about the underlying
7990: ** database page on disk. The value passed into szExtra depends
7991: ** on the SQLite version, the target platform, and how SQLite was compiled.
7992: ** ^The third argument to xCreate(), bPurgeable, is true if the cache being
7993: ** created will be used to cache database pages of a file stored on disk, or
7994: ** false if it is used for an in-memory database. The cache implementation
7995: ** does not have to do anything special based with the value of bPurgeable;
7996: ** it is purely advisory. ^On a cache where bPurgeable is false, SQLite will
7997: ** never invoke xUnpin() except to deliberately delete a page.
7998: ** ^In other words, calls to xUnpin() on a cache with bPurgeable set to
7999: ** false will always have the "discard" flag set to true.
8000: ** ^Hence, a cache created with bPurgeable false will
8001: ** never contain any unpinned pages.
8002: **
8003: ** [[the xCachesize() page cache method]]
8004: ** ^(The xCachesize() method may be called at any time by SQLite to set the
8005: ** suggested maximum cache-size (number of pages stored by) the cache
8006: ** instance passed as the first argument. This is the value configured using
8007: ** the SQLite "[PRAGMA cache_size]" command.)^ As with the bPurgeable
8008: ** parameter, the implementation is not required to do anything with this
8009: ** value; it is advisory only.
8010: **
8011: ** [[the xPagecount() page cache methods]]
8012: ** The xPagecount() method must return the number of pages currently
8013: ** stored in the cache, both pinned and unpinned.
8014: **
8015: ** [[the xFetch() page cache methods]]
8016: ** The xFetch() method locates a page in the cache and returns a pointer to
8017: ** an sqlite3_pcache_page object associated with that page, or a NULL pointer.
8018: ** The pBuf element of the returned sqlite3_pcache_page object will be a
8019: ** pointer to a buffer of szPage bytes used to store the content of a
8020: ** single database page. The pExtra element of sqlite3_pcache_page will be
8021: ** a pointer to the szExtra bytes of extra storage that SQLite has requested
8022: ** for each entry in the page cache.
8023: **
8024: ** The page to be fetched is determined by the key. ^The minimum key value
8025: ** is 1. After it has been retrieved using xFetch, the page is considered
8026: ** to be "pinned".
8027: **
8028: ** If the requested page is already in the page cache, then the page cache
8029: ** implementation must return a pointer to the page buffer with its content
8030: ** intact. If the requested page is not already in the cache, then the
8031: ** cache implementation should use the value of the createFlag
8032: ** parameter to help it determined what action to take:
8033: **
8034: ** <table border=1 width=85% align=center>
1.4 misho 8035: ** <tr><th> createFlag <th> Behavior when page is not already in cache
1.2 misho 8036: ** <tr><td> 0 <td> Do not allocate a new page. Return NULL.
8037: ** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
8038: ** Otherwise return NULL.
8039: ** <tr><td> 2 <td> Make every effort to allocate a new page. Only return
8040: ** NULL if allocating a new page is effectively impossible.
8041: ** </table>
8042: **
8043: ** ^(SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite
8044: ** will only use a createFlag of 2 after a prior call with a createFlag of 1
8045: ** failed.)^ In between the to xFetch() calls, SQLite may
8046: ** attempt to unpin one or more cache pages by spilling the content of
8047: ** pinned pages to disk and synching the operating system disk cache.
8048: **
8049: ** [[the xUnpin() page cache method]]
8050: ** ^xUnpin() is called by SQLite with a pointer to a currently pinned page
8051: ** as its second argument. If the third parameter, discard, is non-zero,
8052: ** then the page must be evicted from the cache.
8053: ** ^If the discard parameter is
8054: ** zero, then the page may be discarded or retained at the discretion of
8055: ** page cache implementation. ^The page cache implementation
8056: ** may choose to evict unpinned pages at any time.
8057: **
8058: ** The cache must not perform any reference counting. A single
8059: ** call to xUnpin() unpins the page regardless of the number of prior calls
8060: ** to xFetch().
8061: **
8062: ** [[the xRekey() page cache methods]]
8063: ** The xRekey() method is used to change the key value associated with the
8064: ** page passed as the second argument. If the cache
8065: ** previously contains an entry associated with newKey, it must be
8066: ** discarded. ^Any prior cache entry associated with newKey is guaranteed not
8067: ** to be pinned.
8068: **
8069: ** When SQLite calls the xTruncate() method, the cache must discard all
8070: ** existing cache entries with page numbers (keys) greater than or equal
8071: ** to the value of the iLimit parameter passed to xTruncate(). If any
8072: ** of these pages are pinned, they are implicitly unpinned, meaning that
8073: ** they can be safely discarded.
8074: **
8075: ** [[the xDestroy() page cache method]]
8076: ** ^The xDestroy() method is used to delete a cache allocated by xCreate().
8077: ** All resources associated with the specified cache should be freed. ^After
8078: ** calling the xDestroy() method, SQLite considers the [sqlite3_pcache*]
8079: ** handle invalid, and will not use it with any other sqlite3_pcache_methods2
8080: ** functions.
8081: **
8082: ** [[the xShrink() page cache method]]
8083: ** ^SQLite invokes the xShrink() method when it wants the page cache to
8084: ** free up as much of heap memory as possible. The page cache implementation
8085: ** is not obligated to free any memory, but well-behaved implementations should
8086: ** do their best.
8087: */
8088: typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2;
8089: struct sqlite3_pcache_methods2 {
8090: int iVersion;
8091: void *pArg;
8092: int (*xInit)(void*);
8093: void (*xShutdown)(void*);
8094: sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable);
8095: void (*xCachesize)(sqlite3_pcache*, int nCachesize);
8096: int (*xPagecount)(sqlite3_pcache*);
8097: sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
8098: void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard);
8099: void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*,
8100: unsigned oldKey, unsigned newKey);
8101: void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
8102: void (*xDestroy)(sqlite3_pcache*);
8103: void (*xShrink)(sqlite3_pcache*);
8104: };
8105:
8106: /*
8107: ** This is the obsolete pcache_methods object that has now been replaced
8108: ** by sqlite3_pcache_methods2. This object is not used by SQLite. It is
8109: ** retained in the header file for backwards compatibility only.
8110: */
8111: typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;
8112: struct sqlite3_pcache_methods {
8113: void *pArg;
8114: int (*xInit)(void*);
8115: void (*xShutdown)(void*);
8116: sqlite3_pcache *(*xCreate)(int szPage, int bPurgeable);
8117: void (*xCachesize)(sqlite3_pcache*, int nCachesize);
8118: int (*xPagecount)(sqlite3_pcache*);
8119: void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
8120: void (*xUnpin)(sqlite3_pcache*, void*, int discard);
8121: void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);
8122: void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
8123: void (*xDestroy)(sqlite3_pcache*);
8124: };
8125:
8126:
8127: /*
8128: ** CAPI3REF: Online Backup Object
8129: **
8130: ** The sqlite3_backup object records state information about an ongoing
8131: ** online backup operation. ^The sqlite3_backup object is created by
8132: ** a call to [sqlite3_backup_init()] and is destroyed by a call to
8133: ** [sqlite3_backup_finish()].
8134: **
8135: ** See Also: [Using the SQLite Online Backup API]
8136: */
8137: typedef struct sqlite3_backup sqlite3_backup;
8138:
8139: /*
8140: ** CAPI3REF: Online Backup API.
8141: **
8142: ** The backup API copies the content of one database into another.
8143: ** It is useful either for creating backups of databases or
8144: ** for copying in-memory databases to or from persistent files.
8145: **
8146: ** See Also: [Using the SQLite Online Backup API]
8147: **
8148: ** ^SQLite holds a write transaction open on the destination database file
8149: ** for the duration of the backup operation.
8150: ** ^The source database is read-locked only while it is being read;
8151: ** it is not locked continuously for the entire backup operation.
8152: ** ^Thus, the backup may be performed on a live source database without
8153: ** preventing other database connections from
8154: ** reading or writing to the source database while the backup is underway.
8155: **
8156: ** ^(To perform a backup operation:
8157: ** <ol>
8158: ** <li><b>sqlite3_backup_init()</b> is called once to initialize the
8159: ** backup,
8160: ** <li><b>sqlite3_backup_step()</b> is called one or more times to transfer
8161: ** the data between the two databases, and finally
8162: ** <li><b>sqlite3_backup_finish()</b> is called to release all resources
8163: ** associated with the backup operation.
8164: ** </ol>)^
8165: ** There should be exactly one call to sqlite3_backup_finish() for each
8166: ** successful call to sqlite3_backup_init().
8167: **
8168: ** [[sqlite3_backup_init()]] <b>sqlite3_backup_init()</b>
8169: **
8170: ** ^The D and N arguments to sqlite3_backup_init(D,N,S,M) are the
8171: ** [database connection] associated with the destination database
8172: ** and the database name, respectively.
8173: ** ^The database name is "main" for the main database, "temp" for the
8174: ** temporary database, or the name specified after the AS keyword in
8175: ** an [ATTACH] statement for an attached database.
8176: ** ^The S and M arguments passed to
8177: ** sqlite3_backup_init(D,N,S,M) identify the [database connection]
8178: ** and database name of the source database, respectively.
8179: ** ^The source and destination [database connections] (parameters S and D)
8180: ** must be different or else sqlite3_backup_init(D,N,S,M) will fail with
8181: ** an error.
8182: **
1.4 misho 8183: ** ^A call to sqlite3_backup_init() will fail, returning NULL, if
8184: ** there is already a read or read-write transaction open on the
8185: ** destination database.
8186: **
1.2 misho 8187: ** ^If an error occurs within sqlite3_backup_init(D,N,S,M), then NULL is
8188: ** returned and an error code and error message are stored in the
8189: ** destination [database connection] D.
8190: ** ^The error code and message for the failed call to sqlite3_backup_init()
8191: ** can be retrieved using the [sqlite3_errcode()], [sqlite3_errmsg()], and/or
8192: ** [sqlite3_errmsg16()] functions.
8193: ** ^A successful call to sqlite3_backup_init() returns a pointer to an
8194: ** [sqlite3_backup] object.
8195: ** ^The [sqlite3_backup] object may be used with the sqlite3_backup_step() and
8196: ** sqlite3_backup_finish() functions to perform the specified backup
8197: ** operation.
8198: **
8199: ** [[sqlite3_backup_step()]] <b>sqlite3_backup_step()</b>
8200: **
8201: ** ^Function sqlite3_backup_step(B,N) will copy up to N pages between
8202: ** the source and destination databases specified by [sqlite3_backup] object B.
8203: ** ^If N is negative, all remaining source pages are copied.
8204: ** ^If sqlite3_backup_step(B,N) successfully copies N pages and there
8205: ** are still more pages to be copied, then the function returns [SQLITE_OK].
8206: ** ^If sqlite3_backup_step(B,N) successfully finishes copying all pages
8207: ** from source to destination, then it returns [SQLITE_DONE].
8208: ** ^If an error occurs while running sqlite3_backup_step(B,N),
8209: ** then an [error code] is returned. ^As well as [SQLITE_OK] and
8210: ** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
8211: ** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an
8212: ** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.
8213: **
8214: ** ^(The sqlite3_backup_step() might return [SQLITE_READONLY] if
8215: ** <ol>
8216: ** <li> the destination database was opened read-only, or
8217: ** <li> the destination database is using write-ahead-log journaling
8218: ** and the destination and source page sizes differ, or
8219: ** <li> the destination database is an in-memory database and the
8220: ** destination and source page sizes differ.
8221: ** </ol>)^
8222: **
8223: ** ^If sqlite3_backup_step() cannot obtain a required file-system lock, then
8224: ** the [sqlite3_busy_handler | busy-handler function]
8225: ** is invoked (if one is specified). ^If the
8226: ** busy-handler returns non-zero before the lock is available, then
8227: ** [SQLITE_BUSY] is returned to the caller. ^In this case the call to
8228: ** sqlite3_backup_step() can be retried later. ^If the source
8229: ** [database connection]
8230: ** is being used to write to the source database when sqlite3_backup_step()
8231: ** is called, then [SQLITE_LOCKED] is returned immediately. ^Again, in this
8232: ** case the call to sqlite3_backup_step() can be retried later on. ^(If
8233: ** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or
8234: ** [SQLITE_READONLY] is returned, then
8235: ** there is no point in retrying the call to sqlite3_backup_step(). These
8236: ** errors are considered fatal.)^ The application must accept
8237: ** that the backup operation has failed and pass the backup operation handle
8238: ** to the sqlite3_backup_finish() to release associated resources.
8239: **
8240: ** ^The first call to sqlite3_backup_step() obtains an exclusive lock
8241: ** on the destination file. ^The exclusive lock is not released until either
8242: ** sqlite3_backup_finish() is called or the backup operation is complete
8243: ** and sqlite3_backup_step() returns [SQLITE_DONE]. ^Every call to
8244: ** sqlite3_backup_step() obtains a [shared lock] on the source database that
8245: ** lasts for the duration of the sqlite3_backup_step() call.
8246: ** ^Because the source database is not locked between calls to
8247: ** sqlite3_backup_step(), the source database may be modified mid-way
8248: ** through the backup process. ^If the source database is modified by an
8249: ** external process or via a database connection other than the one being
8250: ** used by the backup operation, then the backup will be automatically
8251: ** restarted by the next call to sqlite3_backup_step(). ^If the source
8252: ** database is modified by the using the same database connection as is used
8253: ** by the backup operation, then the backup database is automatically
8254: ** updated at the same time.
8255: **
8256: ** [[sqlite3_backup_finish()]] <b>sqlite3_backup_finish()</b>
8257: **
8258: ** When sqlite3_backup_step() has returned [SQLITE_DONE], or when the
8259: ** application wishes to abandon the backup operation, the application
8260: ** should destroy the [sqlite3_backup] by passing it to sqlite3_backup_finish().
8261: ** ^The sqlite3_backup_finish() interfaces releases all
8262: ** resources associated with the [sqlite3_backup] object.
8263: ** ^If sqlite3_backup_step() has not yet returned [SQLITE_DONE], then any
8264: ** active write-transaction on the destination database is rolled back.
8265: ** The [sqlite3_backup] object is invalid
8266: ** and may not be used following a call to sqlite3_backup_finish().
8267: **
8268: ** ^The value returned by sqlite3_backup_finish is [SQLITE_OK] if no
8269: ** sqlite3_backup_step() errors occurred, regardless or whether or not
8270: ** sqlite3_backup_step() completed.
8271: ** ^If an out-of-memory condition or IO error occurred during any prior
8272: ** sqlite3_backup_step() call on the same [sqlite3_backup] object, then
8273: ** sqlite3_backup_finish() returns the corresponding [error code].
8274: **
8275: ** ^A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step()
8276: ** is not a permanent error and does not affect the return value of
8277: ** sqlite3_backup_finish().
8278: **
1.4 misho 8279: ** [[sqlite3_backup_remaining()]] [[sqlite3_backup_pagecount()]]
1.2 misho 8280: ** <b>sqlite3_backup_remaining() and sqlite3_backup_pagecount()</b>
8281: **
1.4 misho 8282: ** ^The sqlite3_backup_remaining() routine returns the number of pages still
8283: ** to be backed up at the conclusion of the most recent sqlite3_backup_step().
8284: ** ^The sqlite3_backup_pagecount() routine returns the total number of pages
8285: ** in the source database at the conclusion of the most recent
8286: ** sqlite3_backup_step().
8287: ** ^(The values returned by these functions are only updated by
8288: ** sqlite3_backup_step(). If the source database is modified in a way that
8289: ** changes the size of the source database or the number of pages remaining,
8290: ** those changes are not reflected in the output of sqlite3_backup_pagecount()
8291: ** and sqlite3_backup_remaining() until after the next
8292: ** sqlite3_backup_step().)^
1.2 misho 8293: **
8294: ** <b>Concurrent Usage of Database Handles</b>
8295: **
8296: ** ^The source [database connection] may be used by the application for other
8297: ** purposes while a backup operation is underway or being initialized.
8298: ** ^If SQLite is compiled and configured to support threadsafe database
8299: ** connections, then the source database connection may be used concurrently
8300: ** from within other threads.
8301: **
8302: ** However, the application must guarantee that the destination
8303: ** [database connection] is not passed to any other API (by any thread) after
8304: ** sqlite3_backup_init() is called and before the corresponding call to
8305: ** sqlite3_backup_finish(). SQLite does not currently check to see
8306: ** if the application incorrectly accesses the destination [database connection]
8307: ** and so no error code is reported, but the operations may malfunction
8308: ** nevertheless. Use of the destination database connection while a
8309: ** backup is in progress might also also cause a mutex deadlock.
8310: **
8311: ** If running in [shared cache mode], the application must
8312: ** guarantee that the shared cache used by the destination database
8313: ** is not accessed while the backup is running. In practice this means
8314: ** that the application must guarantee that the disk file being
8315: ** backed up to is not accessed by any connection within the process,
8316: ** not just the specific connection that was passed to sqlite3_backup_init().
8317: **
8318: ** The [sqlite3_backup] object itself is partially threadsafe. Multiple
8319: ** threads may safely make multiple concurrent calls to sqlite3_backup_step().
8320: ** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
8321: ** APIs are not strictly speaking threadsafe. If they are invoked at the
8322: ** same time as another thread is invoking sqlite3_backup_step() it is
8323: ** possible that they return invalid values.
8324: */
8325: SQLITE_API sqlite3_backup *sqlite3_backup_init(
8326: sqlite3 *pDest, /* Destination database handle */
8327: const char *zDestName, /* Destination database name */
8328: sqlite3 *pSource, /* Source database handle */
8329: const char *zSourceName /* Source database name */
8330: );
8331: SQLITE_API int sqlite3_backup_step(sqlite3_backup *p, int nPage);
8332: SQLITE_API int sqlite3_backup_finish(sqlite3_backup *p);
8333: SQLITE_API int sqlite3_backup_remaining(sqlite3_backup *p);
8334: SQLITE_API int sqlite3_backup_pagecount(sqlite3_backup *p);
8335:
8336: /*
8337: ** CAPI3REF: Unlock Notification
1.4 misho 8338: ** METHOD: sqlite3
1.2 misho 8339: **
8340: ** ^When running in shared-cache mode, a database operation may fail with
8341: ** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
8342: ** individual tables within the shared-cache cannot be obtained. See
8343: ** [SQLite Shared-Cache Mode] for a description of shared-cache locking.
8344: ** ^This API may be used to register a callback that SQLite will invoke
8345: ** when the connection currently holding the required lock relinquishes it.
8346: ** ^This API is only available if the library was compiled with the
8347: ** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.
8348: **
8349: ** See Also: [Using the SQLite Unlock Notification Feature].
8350: **
8351: ** ^Shared-cache locks are released when a database connection concludes
8352: ** its current transaction, either by committing it or rolling it back.
8353: **
8354: ** ^When a connection (known as the blocked connection) fails to obtain a
8355: ** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
8356: ** identity of the database connection (the blocking connection) that
8357: ** has locked the required resource is stored internally. ^After an
8358: ** application receives an SQLITE_LOCKED error, it may call the
8359: ** sqlite3_unlock_notify() method with the blocked connection handle as
8360: ** the first argument to register for a callback that will be invoked
8361: ** when the blocking connections current transaction is concluded. ^The
8362: ** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
8363: ** call that concludes the blocking connections transaction.
8364: **
8365: ** ^(If sqlite3_unlock_notify() is called in a multi-threaded application,
8366: ** there is a chance that the blocking connection will have already
8367: ** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
8368: ** If this happens, then the specified callback is invoked immediately,
8369: ** from within the call to sqlite3_unlock_notify().)^
8370: **
8371: ** ^If the blocked connection is attempting to obtain a write-lock on a
8372: ** shared-cache table, and more than one other connection currently holds
8373: ** a read-lock on the same table, then SQLite arbitrarily selects one of
8374: ** the other connections to use as the blocking connection.
8375: **
8376: ** ^(There may be at most one unlock-notify callback registered by a
8377: ** blocked connection. If sqlite3_unlock_notify() is called when the
8378: ** blocked connection already has a registered unlock-notify callback,
8379: ** then the new callback replaces the old.)^ ^If sqlite3_unlock_notify() is
8380: ** called with a NULL pointer as its second argument, then any existing
8381: ** unlock-notify callback is canceled. ^The blocked connections
8382: ** unlock-notify callback may also be canceled by closing the blocked
8383: ** connection using [sqlite3_close()].
8384: **
8385: ** The unlock-notify callback is not reentrant. If an application invokes
8386: ** any sqlite3_xxx API functions from within an unlock-notify callback, a
8387: ** crash or deadlock may be the result.
8388: **
8389: ** ^Unless deadlock is detected (see below), sqlite3_unlock_notify() always
8390: ** returns SQLITE_OK.
8391: **
8392: ** <b>Callback Invocation Details</b>
8393: **
8394: ** When an unlock-notify callback is registered, the application provides a
8395: ** single void* pointer that is passed to the callback when it is invoked.
8396: ** However, the signature of the callback function allows SQLite to pass
8397: ** it an array of void* context pointers. The first argument passed to
8398: ** an unlock-notify callback is a pointer to an array of void* pointers,
8399: ** and the second is the number of entries in the array.
8400: **
8401: ** When a blocking connections transaction is concluded, there may be
8402: ** more than one blocked connection that has registered for an unlock-notify
8403: ** callback. ^If two or more such blocked connections have specified the
8404: ** same callback function, then instead of invoking the callback function
8405: ** multiple times, it is invoked once with the set of void* context pointers
8406: ** specified by the blocked connections bundled together into an array.
8407: ** This gives the application an opportunity to prioritize any actions
8408: ** related to the set of unblocked database connections.
8409: **
8410: ** <b>Deadlock Detection</b>
8411: **
8412: ** Assuming that after registering for an unlock-notify callback a
8413: ** database waits for the callback to be issued before taking any further
8414: ** action (a reasonable assumption), then using this API may cause the
8415: ** application to deadlock. For example, if connection X is waiting for
8416: ** connection Y's transaction to be concluded, and similarly connection
8417: ** Y is waiting on connection X's transaction, then neither connection
8418: ** will proceed and the system may remain deadlocked indefinitely.
8419: **
8420: ** To avoid this scenario, the sqlite3_unlock_notify() performs deadlock
8421: ** detection. ^If a given call to sqlite3_unlock_notify() would put the
8422: ** system in a deadlocked state, then SQLITE_LOCKED is returned and no
8423: ** unlock-notify callback is registered. The system is said to be in
8424: ** a deadlocked state if connection A has registered for an unlock-notify
8425: ** callback on the conclusion of connection B's transaction, and connection
8426: ** B has itself registered for an unlock-notify callback when connection
8427: ** A's transaction is concluded. ^Indirect deadlock is also detected, so
8428: ** the system is also considered to be deadlocked if connection B has
8429: ** registered for an unlock-notify callback on the conclusion of connection
8430: ** C's transaction, where connection C is waiting on connection A. ^Any
8431: ** number of levels of indirection are allowed.
8432: **
8433: ** <b>The "DROP TABLE" Exception</b>
8434: **
8435: ** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost
8436: ** always appropriate to call sqlite3_unlock_notify(). There is however,
8437: ** one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,
8438: ** SQLite checks if there are any currently executing SELECT statements
8439: ** that belong to the same connection. If there are, SQLITE_LOCKED is
8440: ** returned. In this case there is no "blocking connection", so invoking
8441: ** sqlite3_unlock_notify() results in the unlock-notify callback being
8442: ** invoked immediately. If the application then re-attempts the "DROP TABLE"
8443: ** or "DROP INDEX" query, an infinite loop might be the result.
8444: **
8445: ** One way around this problem is to check the extended error code returned
8446: ** by an sqlite3_step() call. ^(If there is a blocking connection, then the
8447: ** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
8448: ** the special "DROP TABLE/INDEX" case, the extended error code is just
8449: ** SQLITE_LOCKED.)^
8450: */
8451: SQLITE_API int sqlite3_unlock_notify(
8452: sqlite3 *pBlocked, /* Waiting connection */
8453: void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */
8454: void *pNotifyArg /* Argument to pass to xNotify */
8455: );
8456:
8457:
8458: /*
8459: ** CAPI3REF: String Comparison
8460: **
1.3 misho 8461: ** ^The [sqlite3_stricmp()] and [sqlite3_strnicmp()] APIs allow applications
8462: ** and extensions to compare the contents of two buffers containing UTF-8
8463: ** strings in a case-independent fashion, using the same definition of "case
8464: ** independence" that SQLite uses internally when comparing identifiers.
1.2 misho 8465: */
1.3 misho 8466: SQLITE_API int sqlite3_stricmp(const char *, const char *);
1.2 misho 8467: SQLITE_API int sqlite3_strnicmp(const char *, const char *, int);
8468:
8469: /*
1.4 misho 8470: ** CAPI3REF: String Globbing
8471: *
8472: ** ^The [sqlite3_strglob(P,X)] interface returns zero if and only if
8473: ** string X matches the [GLOB] pattern P.
8474: ** ^The definition of [GLOB] pattern matching used in
8475: ** [sqlite3_strglob(P,X)] is the same as for the "X GLOB P" operator in the
8476: ** SQL dialect understood by SQLite. ^The [sqlite3_strglob(P,X)] function
8477: ** is case sensitive.
8478: **
8479: ** Note that this routine returns zero on a match and non-zero if the strings
8480: ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].
8481: **
8482: ** See also: [sqlite3_strlike()].
8483: */
8484: SQLITE_API int sqlite3_strglob(const char *zGlob, const char *zStr);
8485:
8486: /*
8487: ** CAPI3REF: String LIKE Matching
8488: *
8489: ** ^The [sqlite3_strlike(P,X,E)] interface returns zero if and only if
8490: ** string X matches the [LIKE] pattern P with escape character E.
8491: ** ^The definition of [LIKE] pattern matching used in
8492: ** [sqlite3_strlike(P,X,E)] is the same as for the "X LIKE P ESCAPE E"
8493: ** operator in the SQL dialect understood by SQLite. ^For "X LIKE P" without
8494: ** the ESCAPE clause, set the E parameter of [sqlite3_strlike(P,X,E)] to 0.
8495: ** ^As with the LIKE operator, the [sqlite3_strlike(P,X,E)] function is case
8496: ** insensitive - equivalent upper and lower case ASCII characters match
8497: ** one another.
8498: **
8499: ** ^The [sqlite3_strlike(P,X,E)] function matches Unicode characters, though
8500: ** only ASCII characters are case folded.
8501: **
8502: ** Note that this routine returns zero on a match and non-zero if the strings
8503: ** do not match, the same as [sqlite3_stricmp()] and [sqlite3_strnicmp()].
8504: **
8505: ** See also: [sqlite3_strglob()].
8506: */
8507: SQLITE_API int sqlite3_strlike(const char *zGlob, const char *zStr, unsigned int cEsc);
8508:
8509: /*
1.2 misho 8510: ** CAPI3REF: Error Logging Interface
8511: **
1.4 misho 8512: ** ^The [sqlite3_log()] interface writes a message into the [error log]
1.2 misho 8513: ** established by the [SQLITE_CONFIG_LOG] option to [sqlite3_config()].
8514: ** ^If logging is enabled, the zFormat string and subsequent arguments are
8515: ** used with [sqlite3_snprintf()] to generate the final output string.
8516: **
8517: ** The sqlite3_log() interface is intended for use by extensions such as
8518: ** virtual tables, collating functions, and SQL functions. While there is
8519: ** nothing to prevent an application from calling sqlite3_log(), doing so
8520: ** is considered bad form.
8521: **
8522: ** The zFormat string must not be NULL.
8523: **
8524: ** To avoid deadlocks and other threading problems, the sqlite3_log() routine
8525: ** will not use dynamically allocated memory. The log message is stored in
8526: ** a fixed-length buffer on the stack. If the log message is longer than
8527: ** a few hundred characters, it will be truncated to the length of the
8528: ** buffer.
8529: */
8530: SQLITE_API void sqlite3_log(int iErrCode, const char *zFormat, ...);
8531:
8532: /*
8533: ** CAPI3REF: Write-Ahead Log Commit Hook
1.4 misho 8534: ** METHOD: sqlite3
1.2 misho 8535: **
8536: ** ^The [sqlite3_wal_hook()] function is used to register a callback that
1.4 misho 8537: ** is invoked each time data is committed to a database in wal mode.
1.2 misho 8538: **
1.4 misho 8539: ** ^(The callback is invoked by SQLite after the commit has taken place and
8540: ** the associated write-lock on the database released)^, so the implementation
1.2 misho 8541: ** may read, write or [checkpoint] the database as required.
8542: **
8543: ** ^The first parameter passed to the callback function when it is invoked
8544: ** is a copy of the third parameter passed to sqlite3_wal_hook() when
8545: ** registering the callback. ^The second is a copy of the database handle.
8546: ** ^The third parameter is the name of the database that was written to -
8547: ** either "main" or the name of an [ATTACH]-ed database. ^The fourth parameter
8548: ** is the number of pages currently in the write-ahead log file,
8549: ** including those that were just committed.
8550: **
8551: ** The callback function should normally return [SQLITE_OK]. ^If an error
8552: ** code is returned, that error will propagate back up through the
8553: ** SQLite code base to cause the statement that provoked the callback
8554: ** to report an error, though the commit will have still occurred. If the
8555: ** callback returns [SQLITE_ROW] or [SQLITE_DONE], or if it returns a value
8556: ** that does not correspond to any valid SQLite error code, the results
8557: ** are undefined.
8558: **
8559: ** A single database handle may have at most a single write-ahead log callback
8560: ** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any
8561: ** previously registered write-ahead log callback. ^Note that the
8562: ** [sqlite3_wal_autocheckpoint()] interface and the
8563: ** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will
1.4 misho 8564: ** overwrite any prior [sqlite3_wal_hook()] settings.
1.2 misho 8565: */
8566: SQLITE_API void *sqlite3_wal_hook(
8567: sqlite3*,
8568: int(*)(void *,sqlite3*,const char*,int),
8569: void*
8570: );
8571:
8572: /*
8573: ** CAPI3REF: Configure an auto-checkpoint
1.4 misho 8574: ** METHOD: sqlite3
1.2 misho 8575: **
8576: ** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around
8577: ** [sqlite3_wal_hook()] that causes any database on [database connection] D
8578: ** to automatically [checkpoint]
8579: ** after committing a transaction if there are N or
8580: ** more frames in the [write-ahead log] file. ^Passing zero or
8581: ** a negative value as the nFrame parameter disables automatic
8582: ** checkpoints entirely.
8583: **
8584: ** ^The callback registered by this function replaces any existing callback
8585: ** registered using [sqlite3_wal_hook()]. ^Likewise, registering a callback
8586: ** using [sqlite3_wal_hook()] disables the automatic checkpoint mechanism
8587: ** configured by this function.
8588: **
8589: ** ^The [wal_autocheckpoint pragma] can be used to invoke this interface
8590: ** from SQL.
8591: **
1.4 misho 8592: ** ^Checkpoints initiated by this mechanism are
8593: ** [sqlite3_wal_checkpoint_v2|PASSIVE].
8594: **
1.2 misho 8595: ** ^Every new [database connection] defaults to having the auto-checkpoint
8596: ** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT]
8597: ** pages. The use of this interface
8598: ** is only necessary if the default setting is found to be suboptimal
8599: ** for a particular application.
8600: */
8601: SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
8602:
8603: /*
8604: ** CAPI3REF: Checkpoint a database
1.4 misho 8605: ** METHOD: sqlite3
1.2 misho 8606: **
1.4 misho 8607: ** ^(The sqlite3_wal_checkpoint(D,X) is equivalent to
8608: ** [sqlite3_wal_checkpoint_v2](D,X,[SQLITE_CHECKPOINT_PASSIVE],0,0).)^
1.2 misho 8609: **
1.4 misho 8610: ** In brief, sqlite3_wal_checkpoint(D,X) causes the content in the
8611: ** [write-ahead log] for database X on [database connection] D to be
8612: ** transferred into the database file and for the write-ahead log to
8613: ** be reset. See the [checkpointing] documentation for addition
8614: ** information.
8615: **
8616: ** This interface used to be the only way to cause a checkpoint to
8617: ** occur. But then the newer and more powerful [sqlite3_wal_checkpoint_v2()]
8618: ** interface was added. This interface is retained for backwards
8619: ** compatibility and as a convenience for applications that need to manually
8620: ** start a callback but which do not need the full power (and corresponding
8621: ** complication) of [sqlite3_wal_checkpoint_v2()].
1.2 misho 8622: */
8623: SQLITE_API int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
8624:
8625: /*
8626: ** CAPI3REF: Checkpoint a database
1.4 misho 8627: ** METHOD: sqlite3
1.2 misho 8628: **
1.4 misho 8629: ** ^(The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint
8630: ** operation on database X of [database connection] D in mode M. Status
8631: ** information is written back into integers pointed to by L and C.)^
8632: ** ^(The M parameter must be a valid [checkpoint mode]:)^
1.2 misho 8633: **
8634: ** <dl>
8635: ** <dt>SQLITE_CHECKPOINT_PASSIVE<dd>
1.4 misho 8636: ** ^Checkpoint as many frames as possible without waiting for any database
8637: ** readers or writers to finish, then sync the database file if all frames
8638: ** in the log were checkpointed. ^The [busy-handler callback]
8639: ** is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode.
8640: ** ^On the other hand, passive mode might leave the checkpoint unfinished
8641: ** if there are concurrent readers or writers.
1.2 misho 8642: **
8643: ** <dt>SQLITE_CHECKPOINT_FULL<dd>
1.4 misho 8644: ** ^This mode blocks (it invokes the
8645: ** [sqlite3_busy_handler|busy-handler callback]) until there is no
1.2 misho 8646: ** database writer and all readers are reading from the most recent database
1.4 misho 8647: ** snapshot. ^It then checkpoints all frames in the log file and syncs the
8648: ** database file. ^This mode blocks new database writers while it is pending,
8649: ** but new database readers are allowed to continue unimpeded.
1.2 misho 8650: **
8651: ** <dt>SQLITE_CHECKPOINT_RESTART<dd>
1.4 misho 8652: ** ^This mode works the same way as SQLITE_CHECKPOINT_FULL with the addition
8653: ** that after checkpointing the log file it blocks (calls the
8654: ** [busy-handler callback])
8655: ** until all readers are reading from the database file only. ^This ensures
8656: ** that the next writer will restart the log file from the beginning.
8657: ** ^Like SQLITE_CHECKPOINT_FULL, this mode blocks new
8658: ** database writer attempts while it is pending, but does not impede readers.
8659: **
8660: ** <dt>SQLITE_CHECKPOINT_TRUNCATE<dd>
8661: ** ^This mode works the same way as SQLITE_CHECKPOINT_RESTART with the
8662: ** addition that it also truncates the log file to zero bytes just prior
8663: ** to a successful return.
1.2 misho 8664: ** </dl>
8665: **
1.4 misho 8666: ** ^If pnLog is not NULL, then *pnLog is set to the total number of frames in
8667: ** the log file or to -1 if the checkpoint could not run because
8668: ** of an error or because the database is not in [WAL mode]. ^If pnCkpt is not
8669: ** NULL,then *pnCkpt is set to the total number of checkpointed frames in the
8670: ** log file (including any that were already checkpointed before the function
8671: ** was called) or to -1 if the checkpoint could not run due to an error or
8672: ** because the database is not in WAL mode. ^Note that upon successful
8673: ** completion of an SQLITE_CHECKPOINT_TRUNCATE, the log file will have been
8674: ** truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero.
1.2 misho 8675: **
1.4 misho 8676: ** ^All calls obtain an exclusive "checkpoint" lock on the database file. ^If
1.2 misho 8677: ** any other process is running a checkpoint operation at the same time, the
1.4 misho 8678: ** lock cannot be obtained and SQLITE_BUSY is returned. ^Even if there is a
1.2 misho 8679: ** busy-handler configured, it will not be invoked in this case.
8680: **
1.4 misho 8681: ** ^The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the
8682: ** exclusive "writer" lock on the database file. ^If the writer lock cannot be
8683: ** obtained immediately, and a busy-handler is configured, it is invoked and
8684: ** the writer lock retried until either the busy-handler returns 0 or the lock
8685: ** is successfully obtained. ^The busy-handler is also invoked while waiting for
8686: ** database readers as described above. ^If the busy-handler returns 0 before
1.2 misho 8687: ** the writer lock is obtained or while waiting for database readers, the
8688: ** checkpoint operation proceeds from that point in the same way as
8689: ** SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible
1.4 misho 8690: ** without blocking any further. ^SQLITE_BUSY is returned in this case.
1.2 misho 8691: **
1.4 misho 8692: ** ^If parameter zDb is NULL or points to a zero length string, then the
8693: ** specified operation is attempted on all WAL databases [attached] to
8694: ** [database connection] db. In this case the
8695: ** values written to output parameters *pnLog and *pnCkpt are undefined. ^If
1.2 misho 8696: ** an SQLITE_BUSY error is encountered when processing one or more of the
8697: ** attached WAL databases, the operation is still attempted on any remaining
1.4 misho 8698: ** attached databases and SQLITE_BUSY is returned at the end. ^If any other
1.2 misho 8699: ** error occurs while processing an attached database, processing is abandoned
1.4 misho 8700: ** and the error code is returned to the caller immediately. ^If no error
1.2 misho 8701: ** (SQLITE_BUSY or otherwise) is encountered while processing the attached
8702: ** databases, SQLITE_OK is returned.
8703: **
1.4 misho 8704: ** ^If database zDb is the name of an attached database that is not in WAL
8705: ** mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. ^If
1.2 misho 8706: ** zDb is not NULL (or a zero length string) and is not the name of any
8707: ** attached database, SQLITE_ERROR is returned to the caller.
1.4 misho 8708: **
8709: ** ^Unless it returns SQLITE_MISUSE,
8710: ** the sqlite3_wal_checkpoint_v2() interface
8711: ** sets the error information that is queried by
8712: ** [sqlite3_errcode()] and [sqlite3_errmsg()].
8713: **
8714: ** ^The [PRAGMA wal_checkpoint] command can be used to invoke this interface
8715: ** from SQL.
1.2 misho 8716: */
8717: SQLITE_API int sqlite3_wal_checkpoint_v2(
8718: sqlite3 *db, /* Database handle */
8719: const char *zDb, /* Name of attached database (or NULL) */
8720: int eMode, /* SQLITE_CHECKPOINT_* value */
8721: int *pnLog, /* OUT: Size of WAL log in frames */
8722: int *pnCkpt /* OUT: Total number of frames checkpointed */
8723: );
8724:
8725: /*
1.4 misho 8726: ** CAPI3REF: Checkpoint Mode Values
8727: ** KEYWORDS: {checkpoint mode}
1.2 misho 8728: **
1.4 misho 8729: ** These constants define all valid values for the "checkpoint mode" passed
8730: ** as the third parameter to the [sqlite3_wal_checkpoint_v2()] interface.
8731: ** See the [sqlite3_wal_checkpoint_v2()] documentation for details on the
8732: ** meaning of each of these checkpoint modes.
8733: */
8734: #define SQLITE_CHECKPOINT_PASSIVE 0 /* Do as much as possible w/o blocking */
8735: #define SQLITE_CHECKPOINT_FULL 1 /* Wait for writers, then checkpoint */
8736: #define SQLITE_CHECKPOINT_RESTART 2 /* Like FULL but wait for for readers */
8737: #define SQLITE_CHECKPOINT_TRUNCATE 3 /* Like RESTART but also truncate WAL */
1.2 misho 8738:
8739: /*
8740: ** CAPI3REF: Virtual Table Interface Configuration
8741: **
8742: ** This function may be called by either the [xConnect] or [xCreate] method
8743: ** of a [virtual table] implementation to configure
8744: ** various facets of the virtual table interface.
8745: **
8746: ** If this interface is invoked outside the context of an xConnect or
8747: ** xCreate virtual table method then the behavior is undefined.
8748: **
8749: ** At present, there is only one option that may be configured using
8750: ** this function. (See [SQLITE_VTAB_CONSTRAINT_SUPPORT].) Further options
8751: ** may be added in the future.
8752: */
8753: SQLITE_API int sqlite3_vtab_config(sqlite3*, int op, ...);
8754:
8755: /*
8756: ** CAPI3REF: Virtual Table Configuration Options
8757: **
8758: ** These macros define the various options to the
8759: ** [sqlite3_vtab_config()] interface that [virtual table] implementations
8760: ** can use to customize and optimize their behavior.
8761: **
8762: ** <dl>
1.4.2.2 ! misho 8763: ** [[SQLITE_VTAB_CONSTRAINT_SUPPORT]]
1.2 misho 8764: ** <dt>SQLITE_VTAB_CONSTRAINT_SUPPORT
8765: ** <dd>Calls of the form
8766: ** [sqlite3_vtab_config](db,SQLITE_VTAB_CONSTRAINT_SUPPORT,X) are supported,
8767: ** where X is an integer. If X is zero, then the [virtual table] whose
8768: ** [xCreate] or [xConnect] method invoked [sqlite3_vtab_config()] does not
8769: ** support constraints. In this configuration (which is the default) if
8770: ** a call to the [xUpdate] method returns [SQLITE_CONSTRAINT], then the entire
8771: ** statement is rolled back as if [ON CONFLICT | OR ABORT] had been
8772: ** specified as part of the users SQL statement, regardless of the actual
8773: ** ON CONFLICT mode specified.
8774: **
8775: ** If X is non-zero, then the virtual table implementation guarantees
8776: ** that if [xUpdate] returns [SQLITE_CONSTRAINT], it will do so before
8777: ** any modifications to internal or persistent data structures have been made.
8778: ** If the [ON CONFLICT] mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite
8779: ** is able to roll back a statement or database transaction, and abandon
8780: ** or continue processing the current SQL statement as appropriate.
8781: ** If the ON CONFLICT mode is REPLACE and the [xUpdate] method returns
8782: ** [SQLITE_CONSTRAINT], SQLite handles this as if the ON CONFLICT mode
8783: ** had been ABORT.
8784: **
8785: ** Virtual table implementations that are required to handle OR REPLACE
8786: ** must do so within the [xUpdate] method. If a call to the
8787: ** [sqlite3_vtab_on_conflict()] function indicates that the current ON
8788: ** CONFLICT policy is REPLACE, the virtual table implementation should
8789: ** silently replace the appropriate rows within the xUpdate callback and
8790: ** return SQLITE_OK. Or, if this is not possible, it may return
8791: ** SQLITE_CONSTRAINT, in which case SQLite falls back to OR ABORT
8792: ** constraint handling.
8793: ** </dl>
8794: */
8795: #define SQLITE_VTAB_CONSTRAINT_SUPPORT 1
8796:
8797: /*
8798: ** CAPI3REF: Determine The Virtual Table Conflict Policy
8799: **
8800: ** This function may only be called from within a call to the [xUpdate] method
8801: ** of a [virtual table] implementation for an INSERT or UPDATE operation. ^The
8802: ** value returned is one of [SQLITE_ROLLBACK], [SQLITE_IGNORE], [SQLITE_FAIL],
8803: ** [SQLITE_ABORT], or [SQLITE_REPLACE], according to the [ON CONFLICT] mode
8804: ** of the SQL statement that triggered the call to the [xUpdate] method of the
8805: ** [virtual table].
8806: */
8807: SQLITE_API int sqlite3_vtab_on_conflict(sqlite3 *);
8808:
8809: /*
1.4.2.2 ! misho 8810: ** CAPI3REF: Determine If Virtual Table Column Access Is For UPDATE
! 8811: **
! 8812: ** If the sqlite3_vtab_nochange(X) routine is called within the [xColumn]
! 8813: ** method of a [virtual table], then it returns true if and only if the
! 8814: ** column is being fetched as part of an UPDATE operation during which the
! 8815: ** column value will not change. Applications might use this to substitute
! 8816: ** a return value that is less expensive to compute and that the corresponding
! 8817: ** [xUpdate] method understands as a "no-change" value.
! 8818: **
! 8819: ** If the [xColumn] method calls sqlite3_vtab_nochange() and finds that
! 8820: ** the column is not changed by the UPDATE statement, then the xColumn
! 8821: ** method can optionally return without setting a result, without calling
! 8822: ** any of the [sqlite3_result_int|sqlite3_result_xxxxx() interfaces].
! 8823: ** In that case, [sqlite3_value_nochange(X)] will return true for the
! 8824: ** same column in the [xUpdate] method.
! 8825: */
! 8826: SQLITE_API int sqlite3_vtab_nochange(sqlite3_context*);
! 8827:
! 8828: /*
! 8829: ** CAPI3REF: Determine The Collation For a Virtual Table Constraint
! 8830: **
! 8831: ** This function may only be called from within a call to the [xBestIndex]
! 8832: ** method of a [virtual table].
! 8833: **
! 8834: ** The first argument must be the sqlite3_index_info object that is the
! 8835: ** first parameter to the xBestIndex() method. The second argument must be
! 8836: ** an index into the aConstraint[] array belonging to the sqlite3_index_info
! 8837: ** structure passed to xBestIndex. This function returns a pointer to a buffer
! 8838: ** containing the name of the collation sequence for the corresponding
! 8839: ** constraint.
! 8840: */
! 8841: SQLITE_API SQLITE_EXPERIMENTAL const char *sqlite3_vtab_collation(sqlite3_index_info*,int);
! 8842:
! 8843: /*
1.2 misho 8844: ** CAPI3REF: Conflict resolution modes
1.4 misho 8845: ** KEYWORDS: {conflict resolution mode}
1.2 misho 8846: **
8847: ** These constants are returned by [sqlite3_vtab_on_conflict()] to
8848: ** inform a [virtual table] implementation what the [ON CONFLICT] mode
8849: ** is for the SQL statement being evaluated.
8850: **
8851: ** Note that the [SQLITE_IGNORE] constant is also used as a potential
8852: ** return value from the [sqlite3_set_authorizer()] callback and that
8853: ** [SQLITE_ABORT] is also a [result code].
8854: */
8855: #define SQLITE_ROLLBACK 1
8856: /* #define SQLITE_IGNORE 2 // Also used by sqlite3_authorizer() callback */
8857: #define SQLITE_FAIL 3
8858: /* #define SQLITE_ABORT 4 // Also an error code */
8859: #define SQLITE_REPLACE 5
8860:
1.4 misho 8861: /*
8862: ** CAPI3REF: Prepared Statement Scan Status Opcodes
8863: ** KEYWORDS: {scanstatus options}
8864: **
8865: ** The following constants can be used for the T parameter to the
8866: ** [sqlite3_stmt_scanstatus(S,X,T,V)] interface. Each constant designates a
8867: ** different metric for sqlite3_stmt_scanstatus() to return.
8868: **
8869: ** When the value returned to V is a string, space to hold that string is
8870: ** managed by the prepared statement S and will be automatically freed when
8871: ** S is finalized.
8872: **
8873: ** <dl>
8874: ** [[SQLITE_SCANSTAT_NLOOP]] <dt>SQLITE_SCANSTAT_NLOOP</dt>
8875: ** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be
8876: ** set to the total number of times that the X-th loop has run.</dd>
8877: **
8878: ** [[SQLITE_SCANSTAT_NVISIT]] <dt>SQLITE_SCANSTAT_NVISIT</dt>
8879: ** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be set
8880: ** to the total number of rows examined by all iterations of the X-th loop.</dd>
8881: **
8882: ** [[SQLITE_SCANSTAT_EST]] <dt>SQLITE_SCANSTAT_EST</dt>
8883: ** <dd>^The "double" variable pointed to by the T parameter will be set to the
8884: ** query planner's estimate for the average number of rows output from each
8885: ** iteration of the X-th loop. If the query planner's estimates was accurate,
8886: ** then this value will approximate the quotient NVISIT/NLOOP and the
8887: ** product of this value for all prior loops with the same SELECTID will
8888: ** be the NLOOP value for the current loop.
8889: **
8890: ** [[SQLITE_SCANSTAT_NAME]] <dt>SQLITE_SCANSTAT_NAME</dt>
8891: ** <dd>^The "const char *" variable pointed to by the T parameter will be set
8892: ** to a zero-terminated UTF-8 string containing the name of the index or table
8893: ** used for the X-th loop.
8894: **
8895: ** [[SQLITE_SCANSTAT_EXPLAIN]] <dt>SQLITE_SCANSTAT_EXPLAIN</dt>
8896: ** <dd>^The "const char *" variable pointed to by the T parameter will be set
8897: ** to a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN]
8898: ** description for the X-th loop.
8899: **
8900: ** [[SQLITE_SCANSTAT_SELECTID]] <dt>SQLITE_SCANSTAT_SELECT</dt>
8901: ** <dd>^The "int" variable pointed to by the T parameter will be set to the
8902: ** "select-id" for the X-th loop. The select-id identifies which query or
8903: ** subquery the loop is part of. The main query has a select-id of zero.
8904: ** The select-id is the same value as is output in the first column
8905: ** of an [EXPLAIN QUERY PLAN] query.
8906: ** </dl>
8907: */
8908: #define SQLITE_SCANSTAT_NLOOP 0
8909: #define SQLITE_SCANSTAT_NVISIT 1
8910: #define SQLITE_SCANSTAT_EST 2
8911: #define SQLITE_SCANSTAT_NAME 3
8912: #define SQLITE_SCANSTAT_EXPLAIN 4
8913: #define SQLITE_SCANSTAT_SELECTID 5
8914:
8915: /*
8916: ** CAPI3REF: Prepared Statement Scan Status
8917: ** METHOD: sqlite3_stmt
8918: **
8919: ** This interface returns information about the predicted and measured
8920: ** performance for pStmt. Advanced applications can use this
8921: ** interface to compare the predicted and the measured performance and
8922: ** issue warnings and/or rerun [ANALYZE] if discrepancies are found.
8923: **
8924: ** Since this interface is expected to be rarely used, it is only
8925: ** available if SQLite is compiled using the [SQLITE_ENABLE_STMT_SCANSTATUS]
8926: ** compile-time option.
8927: **
8928: ** The "iScanStatusOp" parameter determines which status information to return.
8929: ** The "iScanStatusOp" must be one of the [scanstatus options] or the behavior
8930: ** of this interface is undefined.
8931: ** ^The requested measurement is written into a variable pointed to by
8932: ** the "pOut" parameter.
8933: ** Parameter "idx" identifies the specific loop to retrieve statistics for.
8934: ** Loops are numbered starting from zero. ^If idx is out of range - less than
8935: ** zero or greater than or equal to the total number of loops used to implement
8936: ** the statement - a non-zero value is returned and the variable that pOut
8937: ** points to is unchanged.
8938: **
8939: ** ^Statistics might not be available for all loops in all statements. ^In cases
8940: ** where there exist loops with no available statistics, this function behaves
8941: ** as if the loop did not exist - it returns non-zero and leave the variable
8942: ** that pOut points to unchanged.
8943: **
8944: ** See also: [sqlite3_stmt_scanstatus_reset()]
8945: */
8946: SQLITE_API int sqlite3_stmt_scanstatus(
8947: sqlite3_stmt *pStmt, /* Prepared statement for which info desired */
8948: int idx, /* Index of loop to report on */
8949: int iScanStatusOp, /* Information desired. SQLITE_SCANSTAT_* */
8950: void *pOut /* Result written here */
8951: );
8952:
8953: /*
8954: ** CAPI3REF: Zero Scan-Status Counters
8955: ** METHOD: sqlite3_stmt
8956: **
8957: ** ^Zero all [sqlite3_stmt_scanstatus()] related event counters.
8958: **
8959: ** This API is only available if the library is built with pre-processor
8960: ** symbol [SQLITE_ENABLE_STMT_SCANSTATUS] defined.
8961: */
8962: SQLITE_API void sqlite3_stmt_scanstatus_reset(sqlite3_stmt*);
8963:
8964: /*
8965: ** CAPI3REF: Flush caches to disk mid-transaction
8966: **
8967: ** ^If a write-transaction is open on [database connection] D when the
8968: ** [sqlite3_db_cacheflush(D)] interface invoked, any dirty
8969: ** pages in the pager-cache that are not currently in use are written out
8970: ** to disk. A dirty page may be in use if a database cursor created by an
8971: ** active SQL statement is reading from it, or if it is page 1 of a database
8972: ** file (page 1 is always "in use"). ^The [sqlite3_db_cacheflush(D)]
8973: ** interface flushes caches for all schemas - "main", "temp", and
8974: ** any [attached] databases.
8975: **
8976: ** ^If this function needs to obtain extra database locks before dirty pages
8977: ** can be flushed to disk, it does so. ^If those locks cannot be obtained
8978: ** immediately and there is a busy-handler callback configured, it is invoked
8979: ** in the usual manner. ^If the required lock still cannot be obtained, then
8980: ** the database is skipped and an attempt made to flush any dirty pages
8981: ** belonging to the next (if any) database. ^If any databases are skipped
8982: ** because locks cannot be obtained, but no other error occurs, this
8983: ** function returns SQLITE_BUSY.
8984: **
8985: ** ^If any other error occurs while flushing dirty pages to disk (for
8986: ** example an IO error or out-of-memory condition), then processing is
8987: ** abandoned and an SQLite [error code] is returned to the caller immediately.
8988: **
8989: ** ^Otherwise, if no error occurs, [sqlite3_db_cacheflush()] returns SQLITE_OK.
8990: **
8991: ** ^This function does not set the database handle error code or message
8992: ** returned by the [sqlite3_errcode()] and [sqlite3_errmsg()] functions.
8993: */
8994: SQLITE_API int sqlite3_db_cacheflush(sqlite3*);
8995:
8996: /*
8997: ** CAPI3REF: The pre-update hook.
8998: **
8999: ** ^These interfaces are only available if SQLite is compiled using the
9000: ** [SQLITE_ENABLE_PREUPDATE_HOOK] compile-time option.
9001: **
9002: ** ^The [sqlite3_preupdate_hook()] interface registers a callback function
9003: ** that is invoked prior to each [INSERT], [UPDATE], and [DELETE] operation
1.4.2.1 misho 9004: ** on a database table.
1.4 misho 9005: ** ^At most one preupdate hook may be registered at a time on a single
9006: ** [database connection]; each call to [sqlite3_preupdate_hook()] overrides
9007: ** the previous setting.
9008: ** ^The preupdate hook is disabled by invoking [sqlite3_preupdate_hook()]
9009: ** with a NULL pointer as the second parameter.
9010: ** ^The third parameter to [sqlite3_preupdate_hook()] is passed through as
9011: ** the first parameter to callbacks.
9012: **
1.4.2.1 misho 9013: ** ^The preupdate hook only fires for changes to real database tables; the
9014: ** preupdate hook is not invoked for changes to [virtual tables] or to
9015: ** system tables like sqlite_master or sqlite_stat1.
1.4 misho 9016: **
9017: ** ^The second parameter to the preupdate callback is a pointer to
9018: ** the [database connection] that registered the preupdate hook.
9019: ** ^The third parameter to the preupdate callback is one of the constants
9020: ** [SQLITE_INSERT], [SQLITE_DELETE], or [SQLITE_UPDATE] to identify the
9021: ** kind of update operation that is about to occur.
9022: ** ^(The fourth parameter to the preupdate callback is the name of the
9023: ** database within the database connection that is being modified. This
9024: ** will be "main" for the main database or "temp" for TEMP tables or
9025: ** the name given after the AS keyword in the [ATTACH] statement for attached
9026: ** databases.)^
9027: ** ^The fifth parameter to the preupdate callback is the name of the
9028: ** table that is being modified.
1.4.2.1 misho 9029: **
9030: ** For an UPDATE or DELETE operation on a [rowid table], the sixth
9031: ** parameter passed to the preupdate callback is the initial [rowid] of the
9032: ** row being modified or deleted. For an INSERT operation on a rowid table,
9033: ** or any operation on a WITHOUT ROWID table, the value of the sixth
9034: ** parameter is undefined. For an INSERT or UPDATE on a rowid table the
9035: ** seventh parameter is the final rowid value of the row being inserted
9036: ** or updated. The value of the seventh parameter passed to the callback
9037: ** function is not defined for operations on WITHOUT ROWID tables, or for
9038: ** INSERT operations on rowid tables.
1.4 misho 9039: **
9040: ** The [sqlite3_preupdate_old()], [sqlite3_preupdate_new()],
9041: ** [sqlite3_preupdate_count()], and [sqlite3_preupdate_depth()] interfaces
9042: ** provide additional information about a preupdate event. These routines
9043: ** may only be called from within a preupdate callback. Invoking any of
9044: ** these routines from outside of a preupdate callback or with a
9045: ** [database connection] pointer that is different from the one supplied
9046: ** to the preupdate callback results in undefined and probably undesirable
9047: ** behavior.
9048: **
9049: ** ^The [sqlite3_preupdate_count(D)] interface returns the number of columns
9050: ** in the row that is being inserted, updated, or deleted.
9051: **
9052: ** ^The [sqlite3_preupdate_old(D,N,P)] interface writes into P a pointer to
9053: ** a [protected sqlite3_value] that contains the value of the Nth column of
9054: ** the table row before it is updated. The N parameter must be between 0
9055: ** and one less than the number of columns or the behavior will be
9056: ** undefined. This must only be used within SQLITE_UPDATE and SQLITE_DELETE
9057: ** preupdate callbacks; if it is used by an SQLITE_INSERT callback then the
9058: ** behavior is undefined. The [sqlite3_value] that P points to
9059: ** will be destroyed when the preupdate callback returns.
9060: **
9061: ** ^The [sqlite3_preupdate_new(D,N,P)] interface writes into P a pointer to
9062: ** a [protected sqlite3_value] that contains the value of the Nth column of
9063: ** the table row after it is updated. The N parameter must be between 0
9064: ** and one less than the number of columns or the behavior will be
9065: ** undefined. This must only be used within SQLITE_INSERT and SQLITE_UPDATE
9066: ** preupdate callbacks; if it is used by an SQLITE_DELETE callback then the
9067: ** behavior is undefined. The [sqlite3_value] that P points to
9068: ** will be destroyed when the preupdate callback returns.
9069: **
9070: ** ^The [sqlite3_preupdate_depth(D)] interface returns 0 if the preupdate
9071: ** callback was invoked as a result of a direct insert, update, or delete
9072: ** operation; or 1 for inserts, updates, or deletes invoked by top-level
9073: ** triggers; or 2 for changes resulting from triggers called by top-level
9074: ** triggers; and so forth.
9075: **
9076: ** See also: [sqlite3_update_hook()]
9077: */
1.4.2.1 misho 9078: #if defined(SQLITE_ENABLE_PREUPDATE_HOOK)
9079: SQLITE_API void *sqlite3_preupdate_hook(
1.4 misho 9080: sqlite3 *db,
9081: void(*xPreUpdate)(
9082: void *pCtx, /* Copy of third arg to preupdate_hook() */
9083: sqlite3 *db, /* Database handle */
9084: int op, /* SQLITE_UPDATE, DELETE or INSERT */
9085: char const *zDb, /* Database name */
9086: char const *zName, /* Table name */
9087: sqlite3_int64 iKey1, /* Rowid of row about to be deleted/updated */
9088: sqlite3_int64 iKey2 /* New rowid value (for a rowid UPDATE) */
9089: ),
9090: void*
9091: );
1.4.2.1 misho 9092: SQLITE_API int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **);
9093: SQLITE_API int sqlite3_preupdate_count(sqlite3 *);
9094: SQLITE_API int sqlite3_preupdate_depth(sqlite3 *);
9095: SQLITE_API int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **);
9096: #endif
1.4 misho 9097:
9098: /*
9099: ** CAPI3REF: Low-level system error code
9100: **
9101: ** ^Attempt to return the underlying operating system error code or error
9102: ** number that caused the most recent I/O error or failure to open a file.
9103: ** The return value is OS-dependent. For example, on unix systems, after
9104: ** [sqlite3_open_v2()] returns [SQLITE_CANTOPEN], this interface could be
9105: ** called to get back the underlying "errno" that caused the problem, such
9106: ** as ENOSPC, EAUTH, EISDIR, and so forth.
9107: */
9108: SQLITE_API int sqlite3_system_errno(sqlite3*);
9109:
9110: /*
9111: ** CAPI3REF: Database Snapshot
1.4.2.1 misho 9112: ** KEYWORDS: {snapshot} {sqlite3_snapshot}
1.4 misho 9113: **
9114: ** An instance of the snapshot object records the state of a [WAL mode]
9115: ** database for some specific point in history.
9116: **
9117: ** In [WAL mode], multiple [database connections] that are open on the
9118: ** same database file can each be reading a different historical version
9119: ** of the database file. When a [database connection] begins a read
9120: ** transaction, that connection sees an unchanging copy of the database
9121: ** as it existed for the point in time when the transaction first started.
9122: ** Subsequent changes to the database from other connections are not seen
9123: ** by the reader until a new read transaction is started.
9124: **
9125: ** The sqlite3_snapshot object records state information about an historical
9126: ** version of the database file so that it is possible to later open a new read
9127: ** transaction that sees that historical version of the database rather than
9128: ** the most recent version.
9129: */
1.4.2.1 misho 9130: typedef struct sqlite3_snapshot {
9131: unsigned char hidden[48];
9132: } sqlite3_snapshot;
1.4 misho 9133:
9134: /*
9135: ** CAPI3REF: Record A Database Snapshot
1.4.2.2 ! misho 9136: ** CONSTRUCTOR: sqlite3_snapshot
1.4 misho 9137: **
9138: ** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a
9139: ** new [sqlite3_snapshot] object that records the current state of
9140: ** schema S in database connection D. ^On success, the
9141: ** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly
9142: ** created [sqlite3_snapshot] object into *P and returns SQLITE_OK.
1.4.2.1 misho 9143: ** If there is not already a read-transaction open on schema S when
9144: ** this function is called, one is opened automatically.
9145: **
9146: ** The following must be true for this function to succeed. If any of
9147: ** the following statements are false when sqlite3_snapshot_get() is
9148: ** called, SQLITE_ERROR is returned. The final value of *P is undefined
9149: ** in this case.
9150: **
9151: ** <ul>
1.4.2.2 ! misho 9152: ** <li> The database handle must not be in [autocommit mode].
1.4.2.1 misho 9153: **
9154: ** <li> Schema S of [database connection] D must be a [WAL mode] database.
9155: **
9156: ** <li> There must not be a write transaction open on schema S of database
9157: ** connection D.
9158: **
9159: ** <li> One or more transactions must have been written to the current wal
9160: ** file since it was created on disk (by any connection). This means
9161: ** that a snapshot cannot be taken on a wal mode database with no wal
9162: ** file immediately after it is first opened. At least one transaction
9163: ** must be written to it first.
9164: ** </ul>
9165: **
9166: ** This function may also return SQLITE_NOMEM. If it is called with the
9167: ** database handle in autocommit mode but fails for some other reason,
9168: ** whether or not a read transaction is opened on schema S is undefined.
1.4 misho 9169: **
9170: ** The [sqlite3_snapshot] object returned from a successful call to
9171: ** [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()]
9172: ** to avoid a memory leak.
9173: **
9174: ** The [sqlite3_snapshot_get()] interface is only available when the
1.4.2.2 ! misho 9175: ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
1.4 misho 9176: */
9177: SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_get(
9178: sqlite3 *db,
9179: const char *zSchema,
9180: sqlite3_snapshot **ppSnapshot
9181: );
9182:
9183: /*
9184: ** CAPI3REF: Start a read transaction on an historical snapshot
1.4.2.2 ! misho 9185: ** METHOD: sqlite3_snapshot
! 9186: **
! 9187: ** ^The [sqlite3_snapshot_open(D,S,P)] interface either starts a new read
! 9188: ** transaction or upgrades an existing one for schema S of
! 9189: ** [database connection] D such that the read transaction refers to
! 9190: ** historical [snapshot] P, rather than the most recent change to the
! 9191: ** database. ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK
! 9192: ** on success or an appropriate [error code] if it fails.
! 9193: **
! 9194: ** ^In order to succeed, the database connection must not be in
! 9195: ** [autocommit mode] when [sqlite3_snapshot_open(D,S,P)] is called. If there
! 9196: ** is already a read transaction open on schema S, then the database handle
! 9197: ** must have no active statements (SELECT statements that have been passed
! 9198: ** to sqlite3_step() but not sqlite3_reset() or sqlite3_finalize()).
! 9199: ** SQLITE_ERROR is returned if either of these conditions is violated, or
! 9200: ** if schema S does not exist, or if the snapshot object is invalid.
! 9201: **
! 9202: ** ^A call to sqlite3_snapshot_open() will fail to open if the specified
! 9203: ** snapshot has been overwritten by a [checkpoint]. In this case
! 9204: ** SQLITE_ERROR_SNAPSHOT is returned.
! 9205: **
! 9206: ** If there is already a read transaction open when this function is
! 9207: ** invoked, then the same read transaction remains open (on the same
! 9208: ** database snapshot) if SQLITE_ERROR, SQLITE_BUSY or SQLITE_ERROR_SNAPSHOT
! 9209: ** is returned. If another error code - for example SQLITE_PROTOCOL or an
! 9210: ** SQLITE_IOERR error code - is returned, then the final state of the
! 9211: ** read transaction is undefined. If SQLITE_OK is returned, then the
! 9212: ** read transaction is now open on database snapshot P.
1.4 misho 9213: **
9214: ** ^(A call to [sqlite3_snapshot_open(D,S,P)] will fail if the
9215: ** database connection D does not know that the database file for
9216: ** schema S is in [WAL mode]. A database connection might not know
9217: ** that the database file is in [WAL mode] if there has been no prior
9218: ** I/O on that database connection, or if the database entered [WAL mode]
9219: ** after the most recent I/O on the database connection.)^
9220: ** (Hint: Run "[PRAGMA application_id]" against a newly opened
9221: ** database connection in order to make it ready to use snapshots.)
9222: **
9223: ** The [sqlite3_snapshot_open()] interface is only available when the
1.4.2.2 ! misho 9224: ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
1.4 misho 9225: */
9226: SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_open(
9227: sqlite3 *db,
9228: const char *zSchema,
9229: sqlite3_snapshot *pSnapshot
9230: );
9231:
9232: /*
9233: ** CAPI3REF: Destroy a snapshot
1.4.2.2 ! misho 9234: ** DESTRUCTOR: sqlite3_snapshot
1.4 misho 9235: **
9236: ** ^The [sqlite3_snapshot_free(P)] interface destroys [sqlite3_snapshot] P.
9237: ** The application must eventually free every [sqlite3_snapshot] object
9238: ** using this routine to avoid a memory leak.
9239: **
9240: ** The [sqlite3_snapshot_free()] interface is only available when the
1.4.2.2 ! misho 9241: ** [SQLITE_ENABLE_SNAPSHOT] compile-time option is used.
1.4 misho 9242: */
9243: SQLITE_API SQLITE_EXPERIMENTAL void sqlite3_snapshot_free(sqlite3_snapshot*);
1.2 misho 9244:
1.4 misho 9245: /*
9246: ** CAPI3REF: Compare the ages of two snapshot handles.
1.4.2.2 ! misho 9247: ** METHOD: sqlite3_snapshot
1.4 misho 9248: **
9249: ** The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages
9250: ** of two valid snapshot handles.
9251: **
9252: ** If the two snapshot handles are not associated with the same database
9253: ** file, the result of the comparison is undefined.
9254: **
9255: ** Additionally, the result of the comparison is only valid if both of the
9256: ** snapshot handles were obtained by calling sqlite3_snapshot_get() since the
9257: ** last time the wal file was deleted. The wal file is deleted when the
9258: ** database is changed back to rollback mode or when the number of database
9259: ** clients drops to zero. If either snapshot handle was obtained before the
9260: ** wal file was last deleted, the value returned by this function
9261: ** is undefined.
9262: **
9263: ** Otherwise, this API returns a negative value if P1 refers to an older
9264: ** snapshot than P2, zero if the two handles refer to the same database
9265: ** snapshot, and a positive value if P1 is a newer snapshot than P2.
1.4.2.2 ! misho 9266: **
! 9267: ** This interface is only available if SQLite is compiled with the
! 9268: ** [SQLITE_ENABLE_SNAPSHOT] option.
1.4 misho 9269: */
9270: SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_cmp(
9271: sqlite3_snapshot *p1,
9272: sqlite3_snapshot *p2
9273: );
1.2 misho 9274:
9275: /*
1.4.2.1 misho 9276: ** CAPI3REF: Recover snapshots from a wal file
1.4.2.2 ! misho 9277: ** METHOD: sqlite3_snapshot
1.4.2.1 misho 9278: **
1.4.2.2 ! misho 9279: ** If a [WAL file] remains on disk after all database connections close
! 9280: ** (either through the use of the [SQLITE_FCNTL_PERSIST_WAL] [file control]
! 9281: ** or because the last process to have the database opened exited without
! 9282: ** calling [sqlite3_close()]) and a new connection is subsequently opened
! 9283: ** on that database and [WAL file], the [sqlite3_snapshot_open()] interface
! 9284: ** will only be able to open the last transaction added to the WAL file
! 9285: ** even though the WAL file contains other valid transactions.
1.4.2.1 misho 9286: **
1.4.2.2 ! misho 9287: ** This function attempts to scan the WAL file associated with database zDb
1.4.2.1 misho 9288: ** of database handle db and make all valid snapshots available to
9289: ** sqlite3_snapshot_open(). It is an error if there is already a read
1.4.2.2 ! misho 9290: ** transaction open on the database, or if the database is not a WAL mode
1.4.2.1 misho 9291: ** database.
9292: **
9293: ** SQLITE_OK is returned if successful, or an SQLite error code otherwise.
1.4.2.2 ! misho 9294: **
! 9295: ** This interface is only available if SQLite is compiled with the
! 9296: ** [SQLITE_ENABLE_SNAPSHOT] option.
1.4.2.1 misho 9297: */
9298: SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_recover(sqlite3 *db, const char *zDb);
9299:
9300: /*
1.4.2.2 ! misho 9301: ** CAPI3REF: Serialize a database
! 9302: **
! 9303: ** The sqlite3_serialize(D,S,P,F) interface returns a pointer to memory
! 9304: ** that is a serialization of the S database on [database connection] D.
! 9305: ** If P is not a NULL pointer, then the size of the database in bytes
! 9306: ** is written into *P.
! 9307: **
! 9308: ** For an ordinary on-disk database file, the serialization is just a
! 9309: ** copy of the disk file. For an in-memory database or a "TEMP" database,
! 9310: ** the serialization is the same sequence of bytes which would be written
! 9311: ** to disk if that database where backed up to disk.
! 9312: **
! 9313: ** The usual case is that sqlite3_serialize() copies the serialization of
! 9314: ** the database into memory obtained from [sqlite3_malloc64()] and returns
! 9315: ** a pointer to that memory. The caller is responsible for freeing the
! 9316: ** returned value to avoid a memory leak. However, if the F argument
! 9317: ** contains the SQLITE_SERIALIZE_NOCOPY bit, then no memory allocations
! 9318: ** are made, and the sqlite3_serialize() function will return a pointer
! 9319: ** to the contiguous memory representation of the database that SQLite
! 9320: ** is currently using for that database, or NULL if the no such contiguous
! 9321: ** memory representation of the database exists. A contiguous memory
! 9322: ** representation of the database will usually only exist if there has
! 9323: ** been a prior call to [sqlite3_deserialize(D,S,...)] with the same
! 9324: ** values of D and S.
! 9325: ** The size of the database is written into *P even if the
! 9326: ** SQLITE_SERIALIZE_NOCOPY bit is set but no contiguous copy
! 9327: ** of the database exists.
! 9328: **
! 9329: ** A call to sqlite3_serialize(D,S,P,F) might return NULL even if the
! 9330: ** SQLITE_SERIALIZE_NOCOPY bit is omitted from argument F if a memory
! 9331: ** allocation error occurs.
! 9332: **
! 9333: ** This interface is only available if SQLite is compiled with the
! 9334: ** [SQLITE_ENABLE_DESERIALIZE] option.
! 9335: */
! 9336: SQLITE_API unsigned char *sqlite3_serialize(
! 9337: sqlite3 *db, /* The database connection */
! 9338: const char *zSchema, /* Which DB to serialize. ex: "main", "temp", ... */
! 9339: sqlite3_int64 *piSize, /* Write size of the DB here, if not NULL */
! 9340: unsigned int mFlags /* Zero or more SQLITE_SERIALIZE_* flags */
! 9341: );
! 9342:
! 9343: /*
! 9344: ** CAPI3REF: Flags for sqlite3_serialize
! 9345: **
! 9346: ** Zero or more of the following constants can be OR-ed together for
! 9347: ** the F argument to [sqlite3_serialize(D,S,P,F)].
! 9348: **
! 9349: ** SQLITE_SERIALIZE_NOCOPY means that [sqlite3_serialize()] will return
! 9350: ** a pointer to contiguous in-memory database that it is currently using,
! 9351: ** without making a copy of the database. If SQLite is not currently using
! 9352: ** a contiguous in-memory database, then this option causes
! 9353: ** [sqlite3_serialize()] to return a NULL pointer. SQLite will only be
! 9354: ** using a contiguous in-memory database if it has been initialized by a
! 9355: ** prior call to [sqlite3_deserialize()].
! 9356: */
! 9357: #define SQLITE_SERIALIZE_NOCOPY 0x001 /* Do no memory allocations */
! 9358:
! 9359: /*
! 9360: ** CAPI3REF: Deserialize a database
! 9361: **
! 9362: ** The sqlite3_deserialize(D,S,P,N,M,F) interface causes the
! 9363: ** [database connection] D to disconnect from database S and then
! 9364: ** reopen S as an in-memory database based on the serialization contained
! 9365: ** in P. The serialized database P is N bytes in size. M is the size of
! 9366: ** the buffer P, which might be larger than N. If M is larger than N, and
! 9367: ** the SQLITE_DESERIALIZE_READONLY bit is not set in F, then SQLite is
! 9368: ** permitted to add content to the in-memory database as long as the total
! 9369: ** size does not exceed M bytes.
! 9370: **
! 9371: ** If the SQLITE_DESERIALIZE_FREEONCLOSE bit is set in F, then SQLite will
! 9372: ** invoke sqlite3_free() on the serialization buffer when the database
! 9373: ** connection closes. If the SQLITE_DESERIALIZE_RESIZEABLE bit is set, then
! 9374: ** SQLite will try to increase the buffer size using sqlite3_realloc64()
! 9375: ** if writes on the database cause it to grow larger than M bytes.
! 9376: **
! 9377: ** The sqlite3_deserialize() interface will fail with SQLITE_BUSY if the
! 9378: ** database is currently in a read transaction or is involved in a backup
! 9379: ** operation.
! 9380: **
! 9381: ** If sqlite3_deserialize(D,S,P,N,M,F) fails for any reason and if the
! 9382: ** SQLITE_DESERIALIZE_FREEONCLOSE bit is set in argument F, then
! 9383: ** [sqlite3_free()] is invoked on argument P prior to returning.
! 9384: **
! 9385: ** This interface is only available if SQLite is compiled with the
! 9386: ** [SQLITE_ENABLE_DESERIALIZE] option.
! 9387: */
! 9388: SQLITE_API int sqlite3_deserialize(
! 9389: sqlite3 *db, /* The database connection */
! 9390: const char *zSchema, /* Which DB to reopen with the deserialization */
! 9391: unsigned char *pData, /* The serialized database content */
! 9392: sqlite3_int64 szDb, /* Number bytes in the deserialization */
! 9393: sqlite3_int64 szBuf, /* Total size of buffer pData[] */
! 9394: unsigned mFlags /* Zero or more SQLITE_DESERIALIZE_* flags */
! 9395: );
! 9396:
! 9397: /*
! 9398: ** CAPI3REF: Flags for sqlite3_deserialize()
! 9399: **
! 9400: ** The following are allowed values for 6th argument (the F argument) to
! 9401: ** the [sqlite3_deserialize(D,S,P,N,M,F)] interface.
! 9402: **
! 9403: ** The SQLITE_DESERIALIZE_FREEONCLOSE means that the database serialization
! 9404: ** in the P argument is held in memory obtained from [sqlite3_malloc64()]
! 9405: ** and that SQLite should take ownership of this memory and automatically
! 9406: ** free it when it has finished using it. Without this flag, the caller
! 9407: ** is responsible for freeing any dynamically allocated memory.
! 9408: **
! 9409: ** The SQLITE_DESERIALIZE_RESIZEABLE flag means that SQLite is allowed to
! 9410: ** grow the size of the database using calls to [sqlite3_realloc64()]. This
! 9411: ** flag should only be used if SQLITE_DESERIALIZE_FREEONCLOSE is also used.
! 9412: ** Without this flag, the deserialized database cannot increase in size beyond
! 9413: ** the number of bytes specified by the M parameter.
! 9414: **
! 9415: ** The SQLITE_DESERIALIZE_READONLY flag means that the deserialized database
! 9416: ** should be treated as read-only.
! 9417: */
! 9418: #define SQLITE_DESERIALIZE_FREEONCLOSE 1 /* Call sqlite3_free() on close */
! 9419: #define SQLITE_DESERIALIZE_RESIZEABLE 2 /* Resize using sqlite3_realloc64() */
! 9420: #define SQLITE_DESERIALIZE_READONLY 4 /* Database is read-only */
! 9421:
! 9422: /*
1.2 misho 9423: ** Undo the hack that converts floating point types to integer for
9424: ** builds on processors without floating point support.
9425: */
9426: #ifdef SQLITE_OMIT_FLOATING_POINT
9427: # undef double
9428: #endif
9429:
9430: #ifdef __cplusplus
9431: } /* End of the 'extern "C"' block */
9432: #endif
1.4 misho 9433: #endif /* SQLITE3_H */
1.2 misho 9434:
1.4 misho 9435: /******** Begin file sqlite3rtree.h *********/
1.2 misho 9436: /*
9437: ** 2010 August 30
9438: **
9439: ** The author disclaims copyright to this source code. In place of
9440: ** a legal notice, here is a blessing:
9441: **
9442: ** May you do good and not evil.
9443: ** May you find forgiveness for yourself and forgive others.
9444: ** May you share freely, never taking more than you give.
9445: **
9446: *************************************************************************
9447: */
9448:
9449: #ifndef _SQLITE3RTREE_H_
9450: #define _SQLITE3RTREE_H_
9451:
9452:
9453: #ifdef __cplusplus
9454: extern "C" {
9455: #endif
9456:
9457: typedef struct sqlite3_rtree_geometry sqlite3_rtree_geometry;
1.4 misho 9458: typedef struct sqlite3_rtree_query_info sqlite3_rtree_query_info;
9459:
9460: /* The double-precision datatype used by RTree depends on the
9461: ** SQLITE_RTREE_INT_ONLY compile-time option.
9462: */
9463: #ifdef SQLITE_RTREE_INT_ONLY
9464: typedef sqlite3_int64 sqlite3_rtree_dbl;
9465: #else
9466: typedef double sqlite3_rtree_dbl;
9467: #endif
1.2 misho 9468:
9469: /*
9470: ** Register a geometry callback named zGeom that can be used as part of an
9471: ** R-Tree geometry query as follows:
9472: **
9473: ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zGeom(... params ...)
9474: */
9475: SQLITE_API int sqlite3_rtree_geometry_callback(
9476: sqlite3 *db,
9477: const char *zGeom,
1.4 misho 9478: int (*xGeom)(sqlite3_rtree_geometry*, int, sqlite3_rtree_dbl*,int*),
1.2 misho 9479: void *pContext
9480: );
9481:
9482:
9483: /*
9484: ** A pointer to a structure of the following type is passed as the first
9485: ** argument to callbacks registered using rtree_geometry_callback().
9486: */
9487: struct sqlite3_rtree_geometry {
9488: void *pContext; /* Copy of pContext passed to s_r_g_c() */
9489: int nParam; /* Size of array aParam[] */
1.4 misho 9490: sqlite3_rtree_dbl *aParam; /* Parameters passed to SQL geom function */
1.2 misho 9491: void *pUser; /* Callback implementation user data */
9492: void (*xDelUser)(void *); /* Called by SQLite to clean up pUser */
9493: };
9494:
1.4 misho 9495: /*
9496: ** Register a 2nd-generation geometry callback named zScore that can be
9497: ** used as part of an R-Tree geometry query as follows:
9498: **
9499: ** SELECT ... FROM <rtree> WHERE <rtree col> MATCH $zQueryFunc(... params ...)
9500: */
9501: SQLITE_API int sqlite3_rtree_query_callback(
9502: sqlite3 *db,
9503: const char *zQueryFunc,
9504: int (*xQueryFunc)(sqlite3_rtree_query_info*),
9505: void *pContext,
9506: void (*xDestructor)(void*)
9507: );
9508:
9509:
9510: /*
9511: ** A pointer to a structure of the following type is passed as the
9512: ** argument to scored geometry callback registered using
9513: ** sqlite3_rtree_query_callback().
9514: **
9515: ** Note that the first 5 fields of this structure are identical to
9516: ** sqlite3_rtree_geometry. This structure is a subclass of
9517: ** sqlite3_rtree_geometry.
9518: */
9519: struct sqlite3_rtree_query_info {
9520: void *pContext; /* pContext from when function registered */
9521: int nParam; /* Number of function parameters */
9522: sqlite3_rtree_dbl *aParam; /* value of function parameters */
9523: void *pUser; /* callback can use this, if desired */
9524: void (*xDelUser)(void*); /* function to free pUser */
9525: sqlite3_rtree_dbl *aCoord; /* Coordinates of node or entry to check */
9526: unsigned int *anQueue; /* Number of pending entries in the queue */
9527: int nCoord; /* Number of coordinates */
9528: int iLevel; /* Level of current node or entry */
9529: int mxLevel; /* The largest iLevel value in the tree */
9530: sqlite3_int64 iRowid; /* Rowid for current entry */
9531: sqlite3_rtree_dbl rParentScore; /* Score of parent node */
9532: int eParentWithin; /* Visibility of parent node */
1.4.2.2 ! misho 9533: int eWithin; /* OUT: Visibility */
1.4 misho 9534: sqlite3_rtree_dbl rScore; /* OUT: Write the score here */
9535: /* The following fields are only available in 3.8.11 and later */
9536: sqlite3_value **apSqlParam; /* Original SQL values of parameters */
9537: };
9538:
9539: /*
9540: ** Allowed values for sqlite3_rtree_query.eWithin and .eParentWithin.
9541: */
9542: #define NOT_WITHIN 0 /* Object completely outside of query region */
9543: #define PARTLY_WITHIN 1 /* Object partially overlaps query region */
9544: #define FULLY_WITHIN 2 /* Object fully contained within query region */
9545:
1.2 misho 9546:
9547: #ifdef __cplusplus
9548: } /* end of the 'extern "C"' block */
9549: #endif
9550:
9551: #endif /* ifndef _SQLITE3RTREE_H_ */
9552:
1.4 misho 9553: /******** End of sqlite3rtree.h *********/
9554: /******** Begin file sqlite3session.h *********/
9555:
9556: #if !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION)
9557: #define __SQLITESESSION_H_ 1
9558:
9559: /*
9560: ** Make sure we can call this stuff from C++.
9561: */
9562: #ifdef __cplusplus
9563: extern "C" {
9564: #endif
9565:
9566:
9567: /*
9568: ** CAPI3REF: Session Object Handle
1.4.2.2 ! misho 9569: **
! 9570: ** An instance of this object is a [session] that can be used to
! 9571: ** record changes to a database.
1.4 misho 9572: */
9573: typedef struct sqlite3_session sqlite3_session;
9574:
9575: /*
9576: ** CAPI3REF: Changeset Iterator Handle
1.4.2.2 ! misho 9577: **
! 9578: ** An instance of this object acts as a cursor for iterating
! 9579: ** over the elements of a [changeset] or [patchset].
1.4 misho 9580: */
9581: typedef struct sqlite3_changeset_iter sqlite3_changeset_iter;
9582:
9583: /*
9584: ** CAPI3REF: Create A New Session Object
1.4.2.2 ! misho 9585: ** CONSTRUCTOR: sqlite3_session
1.4 misho 9586: **
9587: ** Create a new session object attached to database handle db. If successful,
9588: ** a pointer to the new object is written to *ppSession and SQLITE_OK is
9589: ** returned. If an error occurs, *ppSession is set to NULL and an SQLite
9590: ** error code (e.g. SQLITE_NOMEM) is returned.
9591: **
9592: ** It is possible to create multiple session objects attached to a single
9593: ** database handle.
9594: **
9595: ** Session objects created using this function should be deleted using the
9596: ** [sqlite3session_delete()] function before the database handle that they
9597: ** are attached to is itself closed. If the database handle is closed before
9598: ** the session object is deleted, then the results of calling any session
9599: ** module function, including [sqlite3session_delete()] on the session object
9600: ** are undefined.
9601: **
9602: ** Because the session module uses the [sqlite3_preupdate_hook()] API, it
9603: ** is not possible for an application to register a pre-update hook on a
9604: ** database handle that has one or more session objects attached. Nor is
9605: ** it possible to create a session object attached to a database handle for
9606: ** which a pre-update hook is already defined. The results of attempting
9607: ** either of these things are undefined.
9608: **
9609: ** The session object will be used to create changesets for tables in
9610: ** database zDb, where zDb is either "main", or "temp", or the name of an
9611: ** attached database. It is not an error if database zDb is not attached
9612: ** to the database when the session object is created.
9613: */
1.4.2.1 misho 9614: SQLITE_API int sqlite3session_create(
1.4 misho 9615: sqlite3 *db, /* Database handle */
9616: const char *zDb, /* Name of db (e.g. "main") */
9617: sqlite3_session **ppSession /* OUT: New session object */
9618: );
9619:
9620: /*
9621: ** CAPI3REF: Delete A Session Object
1.4.2.2 ! misho 9622: ** DESTRUCTOR: sqlite3_session
1.4 misho 9623: **
9624: ** Delete a session object previously allocated using
9625: ** [sqlite3session_create()]. Once a session object has been deleted, the
9626: ** results of attempting to use pSession with any other session module
9627: ** function are undefined.
9628: **
9629: ** Session objects must be deleted before the database handle to which they
9630: ** are attached is closed. Refer to the documentation for
9631: ** [sqlite3session_create()] for details.
9632: */
1.4.2.1 misho 9633: SQLITE_API void sqlite3session_delete(sqlite3_session *pSession);
1.4 misho 9634:
9635:
9636: /*
9637: ** CAPI3REF: Enable Or Disable A Session Object
1.4.2.2 ! misho 9638: ** METHOD: sqlite3_session
1.4 misho 9639: **
9640: ** Enable or disable the recording of changes by a session object. When
9641: ** enabled, a session object records changes made to the database. When
9642: ** disabled - it does not. A newly created session object is enabled.
9643: ** Refer to the documentation for [sqlite3session_changeset()] for further
9644: ** details regarding how enabling and disabling a session object affects
9645: ** the eventual changesets.
9646: **
9647: ** Passing zero to this function disables the session. Passing a value
9648: ** greater than zero enables it. Passing a value less than zero is a
9649: ** no-op, and may be used to query the current state of the session.
9650: **
9651: ** The return value indicates the final state of the session object: 0 if
9652: ** the session is disabled, or 1 if it is enabled.
9653: */
1.4.2.1 misho 9654: SQLITE_API int sqlite3session_enable(sqlite3_session *pSession, int bEnable);
1.4 misho 9655:
9656: /*
9657: ** CAPI3REF: Set Or Clear the Indirect Change Flag
1.4.2.2 ! misho 9658: ** METHOD: sqlite3_session
1.4 misho 9659: **
9660: ** Each change recorded by a session object is marked as either direct or
9661: ** indirect. A change is marked as indirect if either:
9662: **
9663: ** <ul>
9664: ** <li> The session object "indirect" flag is set when the change is
9665: ** made, or
9666: ** <li> The change is made by an SQL trigger or foreign key action
9667: ** instead of directly as a result of a users SQL statement.
9668: ** </ul>
9669: **
9670: ** If a single row is affected by more than one operation within a session,
9671: ** then the change is considered indirect if all operations meet the criteria
9672: ** for an indirect change above, or direct otherwise.
9673: **
9674: ** This function is used to set, clear or query the session object indirect
9675: ** flag. If the second argument passed to this function is zero, then the
9676: ** indirect flag is cleared. If it is greater than zero, the indirect flag
9677: ** is set. Passing a value less than zero does not modify the current value
9678: ** of the indirect flag, and may be used to query the current state of the
9679: ** indirect flag for the specified session object.
9680: **
9681: ** The return value indicates the final state of the indirect flag: 0 if
9682: ** it is clear, or 1 if it is set.
9683: */
1.4.2.1 misho 9684: SQLITE_API int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect);
1.4 misho 9685:
9686: /*
9687: ** CAPI3REF: Attach A Table To A Session Object
1.4.2.2 ! misho 9688: ** METHOD: sqlite3_session
1.4 misho 9689: **
9690: ** If argument zTab is not NULL, then it is the name of a table to attach
9691: ** to the session object passed as the first argument. All subsequent changes
9692: ** made to the table while the session object is enabled will be recorded. See
9693: ** documentation for [sqlite3session_changeset()] for further details.
9694: **
9695: ** Or, if argument zTab is NULL, then changes are recorded for all tables
9696: ** in the database. If additional tables are added to the database (by
9697: ** executing "CREATE TABLE" statements) after this call is made, changes for
9698: ** the new tables are also recorded.
9699: **
9700: ** Changes can only be recorded for tables that have a PRIMARY KEY explicitly
9701: ** defined as part of their CREATE TABLE statement. It does not matter if the
9702: ** PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY
9703: ** KEY may consist of a single column, or may be a composite key.
9704: **
9705: ** It is not an error if the named table does not exist in the database. Nor
9706: ** is it an error if the named table does not have a PRIMARY KEY. However,
9707: ** no changes will be recorded in either of these scenarios.
9708: **
9709: ** Changes are not recorded for individual rows that have NULL values stored
9710: ** in one or more of their PRIMARY KEY columns.
9711: **
9712: ** SQLITE_OK is returned if the call completes without error. Or, if an error
9713: ** occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.
1.4.2.2 ! misho 9714: **
! 9715: ** <h3>Special sqlite_stat1 Handling</h3>
! 9716: **
! 9717: ** As of SQLite version 3.22.0, the "sqlite_stat1" table is an exception to
! 9718: ** some of the rules above. In SQLite, the schema of sqlite_stat1 is:
! 9719: ** <pre>
! 9720: ** CREATE TABLE sqlite_stat1(tbl,idx,stat)
! 9721: ** </pre>
! 9722: **
! 9723: ** Even though sqlite_stat1 does not have a PRIMARY KEY, changes are
! 9724: ** recorded for it as if the PRIMARY KEY is (tbl,idx). Additionally, changes
! 9725: ** are recorded for rows for which (idx IS NULL) is true. However, for such
! 9726: ** rows a zero-length blob (SQL value X'') is stored in the changeset or
! 9727: ** patchset instead of a NULL value. This allows such changesets to be
! 9728: ** manipulated by legacy implementations of sqlite3changeset_invert(),
! 9729: ** concat() and similar.
! 9730: **
! 9731: ** The sqlite3changeset_apply() function automatically converts the
! 9732: ** zero-length blob back to a NULL value when updating the sqlite_stat1
! 9733: ** table. However, if the application calls sqlite3changeset_new(),
! 9734: ** sqlite3changeset_old() or sqlite3changeset_conflict on a changeset
! 9735: ** iterator directly (including on a changeset iterator passed to a
! 9736: ** conflict-handler callback) then the X'' value is returned. The application
! 9737: ** must translate X'' to NULL itself if required.
! 9738: **
! 9739: ** Legacy (older than 3.22.0) versions of the sessions module cannot capture
! 9740: ** changes made to the sqlite_stat1 table. Legacy versions of the
! 9741: ** sqlite3changeset_apply() function silently ignore any modifications to the
! 9742: ** sqlite_stat1 table that are part of a changeset or patchset.
1.4 misho 9743: */
1.4.2.1 misho 9744: SQLITE_API int sqlite3session_attach(
1.4 misho 9745: sqlite3_session *pSession, /* Session object */
9746: const char *zTab /* Table name */
9747: );
9748:
9749: /*
9750: ** CAPI3REF: Set a table filter on a Session Object.
1.4.2.2 ! misho 9751: ** METHOD: sqlite3_session
1.4 misho 9752: **
9753: ** The second argument (xFilter) is the "filter callback". For changes to rows
1.4.2.1 misho 9754: ** in tables that are not attached to the Session object, the filter is called
1.4 misho 9755: ** to determine whether changes to the table's rows should be tracked or not.
9756: ** If xFilter returns 0, changes is not tracked. Note that once a table is
9757: ** attached, xFilter will not be called again.
9758: */
1.4.2.1 misho 9759: SQLITE_API void sqlite3session_table_filter(
1.4 misho 9760: sqlite3_session *pSession, /* Session object */
9761: int(*xFilter)(
9762: void *pCtx, /* Copy of third arg to _filter_table() */
9763: const char *zTab /* Table name */
9764: ),
9765: void *pCtx /* First argument passed to xFilter */
9766: );
9767:
9768: /*
9769: ** CAPI3REF: Generate A Changeset From A Session Object
1.4.2.2 ! misho 9770: ** METHOD: sqlite3_session
1.4 misho 9771: **
9772: ** Obtain a changeset containing changes to the tables attached to the
9773: ** session object passed as the first argument. If successful,
9774: ** set *ppChangeset to point to a buffer containing the changeset
9775: ** and *pnChangeset to the size of the changeset in bytes before returning
9776: ** SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to
9777: ** zero and return an SQLite error code.
9778: **
9779: ** A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes,
9780: ** each representing a change to a single row of an attached table. An INSERT
9781: ** change contains the values of each field of a new database row. A DELETE
9782: ** contains the original values of each field of a deleted database row. An
9783: ** UPDATE change contains the original values of each field of an updated
9784: ** database row along with the updated values for each updated non-primary-key
9785: ** column. It is not possible for an UPDATE change to represent a change that
9786: ** modifies the values of primary key columns. If such a change is made, it
9787: ** is represented in a changeset as a DELETE followed by an INSERT.
9788: **
9789: ** Changes are not recorded for rows that have NULL values stored in one or
9790: ** more of their PRIMARY KEY columns. If such a row is inserted or deleted,
9791: ** no corresponding change is present in the changesets returned by this
9792: ** function. If an existing row with one or more NULL values stored in
9793: ** PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL,
9794: ** only an INSERT is appears in the changeset. Similarly, if an existing row
9795: ** with non-NULL PRIMARY KEY values is updated so that one or more of its
9796: ** PRIMARY KEY columns are set to NULL, the resulting changeset contains a
9797: ** DELETE change only.
9798: **
9799: ** The contents of a changeset may be traversed using an iterator created
9800: ** using the [sqlite3changeset_start()] API. A changeset may be applied to
9801: ** a database with a compatible schema using the [sqlite3changeset_apply()]
9802: ** API.
9803: **
9804: ** Within a changeset generated by this function, all changes related to a
9805: ** single table are grouped together. In other words, when iterating through
9806: ** a changeset or when applying a changeset to a database, all changes related
9807: ** to a single table are processed before moving on to the next table. Tables
9808: ** are sorted in the same order in which they were attached (or auto-attached)
9809: ** to the sqlite3_session object. The order in which the changes related to
9810: ** a single table are stored is undefined.
9811: **
9812: ** Following a successful call to this function, it is the responsibility of
9813: ** the caller to eventually free the buffer that *ppChangeset points to using
9814: ** [sqlite3_free()].
9815: **
9816: ** <h3>Changeset Generation</h3>
9817: **
9818: ** Once a table has been attached to a session object, the session object
9819: ** records the primary key values of all new rows inserted into the table.
9820: ** It also records the original primary key and other column values of any
9821: ** deleted or updated rows. For each unique primary key value, data is only
9822: ** recorded once - the first time a row with said primary key is inserted,
9823: ** updated or deleted in the lifetime of the session.
9824: **
9825: ** There is one exception to the previous paragraph: when a row is inserted,
9826: ** updated or deleted, if one or more of its primary key columns contain a
9827: ** NULL value, no record of the change is made.
9828: **
9829: ** The session object therefore accumulates two types of records - those
9830: ** that consist of primary key values only (created when the user inserts
9831: ** a new record) and those that consist of the primary key values and the
9832: ** original values of other table columns (created when the users deletes
9833: ** or updates a record).
9834: **
9835: ** When this function is called, the requested changeset is created using
9836: ** both the accumulated records and the current contents of the database
9837: ** file. Specifically:
9838: **
9839: ** <ul>
9840: ** <li> For each record generated by an insert, the database is queried
9841: ** for a row with a matching primary key. If one is found, an INSERT
9842: ** change is added to the changeset. If no such row is found, no change
9843: ** is added to the changeset.
9844: **
9845: ** <li> For each record generated by an update or delete, the database is
9846: ** queried for a row with a matching primary key. If such a row is
9847: ** found and one or more of the non-primary key fields have been
9848: ** modified from their original values, an UPDATE change is added to
9849: ** the changeset. Or, if no such row is found in the table, a DELETE
9850: ** change is added to the changeset. If there is a row with a matching
9851: ** primary key in the database, but all fields contain their original
9852: ** values, no change is added to the changeset.
9853: ** </ul>
9854: **
9855: ** This means, amongst other things, that if a row is inserted and then later
9856: ** deleted while a session object is active, neither the insert nor the delete
9857: ** will be present in the changeset. Or if a row is deleted and then later a
9858: ** row with the same primary key values inserted while a session object is
9859: ** active, the resulting changeset will contain an UPDATE change instead of
9860: ** a DELETE and an INSERT.
9861: **
9862: ** When a session object is disabled (see the [sqlite3session_enable()] API),
9863: ** it does not accumulate records when rows are inserted, updated or deleted.
9864: ** This may appear to have some counter-intuitive effects if a single row
9865: ** is written to more than once during a session. For example, if a row
9866: ** is inserted while a session object is enabled, then later deleted while
9867: ** the same session object is disabled, no INSERT record will appear in the
9868: ** changeset, even though the delete took place while the session was disabled.
9869: ** Or, if one field of a row is updated while a session is disabled, and
9870: ** another field of the same row is updated while the session is enabled, the
9871: ** resulting changeset will contain an UPDATE change that updates both fields.
9872: */
1.4.2.1 misho 9873: SQLITE_API int sqlite3session_changeset(
1.4 misho 9874: sqlite3_session *pSession, /* Session object */
9875: int *pnChangeset, /* OUT: Size of buffer at *ppChangeset */
9876: void **ppChangeset /* OUT: Buffer containing changeset */
9877: );
9878:
9879: /*
1.4.2.2 ! misho 9880: ** CAPI3REF: Load The Difference Between Tables Into A Session
! 9881: ** METHOD: sqlite3_session
1.4 misho 9882: **
9883: ** If it is not already attached to the session object passed as the first
9884: ** argument, this function attaches table zTbl in the same manner as the
9885: ** [sqlite3session_attach()] function. If zTbl does not exist, or if it
9886: ** does not have a primary key, this function is a no-op (but does not return
9887: ** an error).
9888: **
9889: ** Argument zFromDb must be the name of a database ("main", "temp" etc.)
9890: ** attached to the same database handle as the session object that contains
9891: ** a table compatible with the table attached to the session by this function.
9892: ** A table is considered compatible if it:
9893: **
9894: ** <ul>
9895: ** <li> Has the same name,
9896: ** <li> Has the same set of columns declared in the same order, and
9897: ** <li> Has the same PRIMARY KEY definition.
9898: ** </ul>
9899: **
9900: ** If the tables are not compatible, SQLITE_SCHEMA is returned. If the tables
9901: ** are compatible but do not have any PRIMARY KEY columns, it is not an error
9902: ** but no changes are added to the session object. As with other session
9903: ** APIs, tables without PRIMARY KEYs are simply ignored.
9904: **
9905: ** This function adds a set of changes to the session object that could be
9906: ** used to update the table in database zFrom (call this the "from-table")
9907: ** so that its content is the same as the table attached to the session
9908: ** object (call this the "to-table"). Specifically:
9909: **
9910: ** <ul>
9911: ** <li> For each row (primary key) that exists in the to-table but not in
9912: ** the from-table, an INSERT record is added to the session object.
9913: **
9914: ** <li> For each row (primary key) that exists in the to-table but not in
9915: ** the from-table, a DELETE record is added to the session object.
9916: **
9917: ** <li> For each row (primary key) that exists in both tables, but features
1.4.2.1 misho 9918: ** different non-PK values in each, an UPDATE record is added to the
9919: ** session.
1.4 misho 9920: ** </ul>
9921: **
9922: ** To clarify, if this function is called and then a changeset constructed
9923: ** using [sqlite3session_changeset()], then after applying that changeset to
9924: ** database zFrom the contents of the two compatible tables would be
9925: ** identical.
9926: **
9927: ** It an error if database zFrom does not exist or does not contain the
9928: ** required compatible table.
9929: **
9930: ** If the operation successful, SQLITE_OK is returned. Otherwise, an SQLite
9931: ** error code. In this case, if argument pzErrMsg is not NULL, *pzErrMsg
9932: ** may be set to point to a buffer containing an English language error
9933: ** message. It is the responsibility of the caller to free this buffer using
9934: ** sqlite3_free().
9935: */
1.4.2.1 misho 9936: SQLITE_API int sqlite3session_diff(
1.4 misho 9937: sqlite3_session *pSession,
9938: const char *zFromDb,
9939: const char *zTbl,
9940: char **pzErrMsg
9941: );
9942:
9943:
9944: /*
9945: ** CAPI3REF: Generate A Patchset From A Session Object
1.4.2.2 ! misho 9946: ** METHOD: sqlite3_session
1.4 misho 9947: **
9948: ** The differences between a patchset and a changeset are that:
9949: **
9950: ** <ul>
9951: ** <li> DELETE records consist of the primary key fields only. The
9952: ** original values of other fields are omitted.
9953: ** <li> The original values of any modified fields are omitted from
9954: ** UPDATE records.
9955: ** </ul>
9956: **
9957: ** A patchset blob may be used with up to date versions of all
9958: ** sqlite3changeset_xxx API functions except for sqlite3changeset_invert(),
9959: ** which returns SQLITE_CORRUPT if it is passed a patchset. Similarly,
9960: ** attempting to use a patchset blob with old versions of the
9961: ** sqlite3changeset_xxx APIs also provokes an SQLITE_CORRUPT error.
9962: **
9963: ** Because the non-primary key "old.*" fields are omitted, no
9964: ** SQLITE_CHANGESET_DATA conflicts can be detected or reported if a patchset
9965: ** is passed to the sqlite3changeset_apply() API. Other conflict types work
9966: ** in the same way as for changesets.
9967: **
9968: ** Changes within a patchset are ordered in the same way as for changesets
9969: ** generated by the sqlite3session_changeset() function (i.e. all changes for
9970: ** a single table are grouped together, tables appear in the order in which
9971: ** they were attached to the session object).
9972: */
1.4.2.1 misho 9973: SQLITE_API int sqlite3session_patchset(
1.4 misho 9974: sqlite3_session *pSession, /* Session object */
1.4.2.2 ! misho 9975: int *pnPatchset, /* OUT: Size of buffer at *ppPatchset */
! 9976: void **ppPatchset /* OUT: Buffer containing patchset */
1.4 misho 9977: );
9978:
9979: /*
9980: ** CAPI3REF: Test if a changeset has recorded any changes.
9981: **
9982: ** Return non-zero if no changes to attached tables have been recorded by
9983: ** the session object passed as the first argument. Otherwise, if one or
9984: ** more changes have been recorded, return zero.
9985: **
9986: ** Even if this function returns zero, it is possible that calling
9987: ** [sqlite3session_changeset()] on the session handle may still return a
9988: ** changeset that contains no changes. This can happen when a row in
9989: ** an attached table is modified and then later on the original values
9990: ** are restored. However, if this function returns non-zero, then it is
9991: ** guaranteed that a call to sqlite3session_changeset() will return a
9992: ** changeset containing zero changes.
9993: */
1.4.2.1 misho 9994: SQLITE_API int sqlite3session_isempty(sqlite3_session *pSession);
1.4 misho 9995:
9996: /*
9997: ** CAPI3REF: Create An Iterator To Traverse A Changeset
1.4.2.2 ! misho 9998: ** CONSTRUCTOR: sqlite3_changeset_iter
1.4 misho 9999: **
10000: ** Create an iterator used to iterate through the contents of a changeset.
10001: ** If successful, *pp is set to point to the iterator handle and SQLITE_OK
10002: ** is returned. Otherwise, if an error occurs, *pp is set to zero and an
10003: ** SQLite error code is returned.
10004: **
10005: ** The following functions can be used to advance and query a changeset
10006: ** iterator created by this function:
10007: **
10008: ** <ul>
10009: ** <li> [sqlite3changeset_next()]
10010: ** <li> [sqlite3changeset_op()]
10011: ** <li> [sqlite3changeset_new()]
10012: ** <li> [sqlite3changeset_old()]
10013: ** </ul>
10014: **
10015: ** It is the responsibility of the caller to eventually destroy the iterator
10016: ** by passing it to [sqlite3changeset_finalize()]. The buffer containing the
10017: ** changeset (pChangeset) must remain valid until after the iterator is
10018: ** destroyed.
10019: **
10020: ** Assuming the changeset blob was created by one of the
10021: ** [sqlite3session_changeset()], [sqlite3changeset_concat()] or
10022: ** [sqlite3changeset_invert()] functions, all changes within the changeset
10023: ** that apply to a single table are grouped together. This means that when
10024: ** an application iterates through a changeset using an iterator created by
1.4.2.1 misho 10025: ** this function, all changes that relate to a single table are visited
1.4 misho 10026: ** consecutively. There is no chance that the iterator will visit a change
10027: ** the applies to table X, then one for table Y, and then later on visit
10028: ** another change for table X.
1.4.2.2 ! misho 10029: **
! 10030: ** The behavior of sqlite3changeset_start_v2() and its streaming equivalent
! 10031: ** may be modified by passing a combination of
! 10032: ** [SQLITE_CHANGESETSTART_INVERT | supported flags] as the 4th parameter.
! 10033: **
! 10034: ** Note that the sqlite3changeset_start_v2() API is still <b>experimental</b>
! 10035: ** and therefore subject to change.
1.4 misho 10036: */
1.4.2.1 misho 10037: SQLITE_API int sqlite3changeset_start(
1.4 misho 10038: sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */
10039: int nChangeset, /* Size of changeset blob in bytes */
10040: void *pChangeset /* Pointer to blob containing changeset */
10041: );
1.4.2.2 ! misho 10042: SQLITE_API int sqlite3changeset_start_v2(
! 10043: sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */
! 10044: int nChangeset, /* Size of changeset blob in bytes */
! 10045: void *pChangeset, /* Pointer to blob containing changeset */
! 10046: int flags /* SESSION_CHANGESETSTART_* flags */
! 10047: );
! 10048:
! 10049: /*
! 10050: ** CAPI3REF: Flags for sqlite3changeset_start_v2
! 10051: **
! 10052: ** The following flags may passed via the 4th parameter to
! 10053: ** [sqlite3changeset_start_v2] and [sqlite3changeset_start_v2_strm]:
! 10054: **
! 10055: ** <dt>SQLITE_CHANGESETAPPLY_INVERT <dd>
! 10056: ** Invert the changeset while iterating through it. This is equivalent to
! 10057: ** inverting a changeset using sqlite3changeset_invert() before applying it.
! 10058: ** It is an error to specify this flag with a patchset.
! 10059: */
! 10060: #define SQLITE_CHANGESETSTART_INVERT 0x0002
1.4 misho 10061:
10062:
10063: /*
10064: ** CAPI3REF: Advance A Changeset Iterator
1.4.2.2 ! misho 10065: ** METHOD: sqlite3_changeset_iter
1.4 misho 10066: **
10067: ** This function may only be used with iterators created by function
10068: ** [sqlite3changeset_start()]. If it is called on an iterator passed to
10069: ** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE
10070: ** is returned and the call has no effect.
10071: **
10072: ** Immediately after an iterator is created by sqlite3changeset_start(), it
10073: ** does not point to any change in the changeset. Assuming the changeset
10074: ** is not empty, the first call to this function advances the iterator to
10075: ** point to the first change in the changeset. Each subsequent call advances
10076: ** the iterator to point to the next change in the changeset (if any). If
10077: ** no error occurs and the iterator points to a valid change after a call
10078: ** to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned.
10079: ** Otherwise, if all changes in the changeset have already been visited,
10080: ** SQLITE_DONE is returned.
10081: **
10082: ** If an error occurs, an SQLite error code is returned. Possible error
10083: ** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or
10084: ** SQLITE_NOMEM.
10085: */
1.4.2.1 misho 10086: SQLITE_API int sqlite3changeset_next(sqlite3_changeset_iter *pIter);
1.4 misho 10087:
10088: /*
10089: ** CAPI3REF: Obtain The Current Operation From A Changeset Iterator
1.4.2.2 ! misho 10090: ** METHOD: sqlite3_changeset_iter
1.4 misho 10091: **
10092: ** The pIter argument passed to this function may either be an iterator
10093: ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
10094: ** created by [sqlite3changeset_start()]. In the latter case, the most recent
10095: ** call to [sqlite3changeset_next()] must have returned [SQLITE_ROW]. If this
10096: ** is not the case, this function returns [SQLITE_MISUSE].
10097: **
10098: ** If argument pzTab is not NULL, then *pzTab is set to point to a
10099: ** nul-terminated utf-8 encoded string containing the name of the table
10100: ** affected by the current change. The buffer remains valid until either
10101: ** sqlite3changeset_next() is called on the iterator or until the
10102: ** conflict-handler function returns. If pnCol is not NULL, then *pnCol is
10103: ** set to the number of columns in the table affected by the change. If
1.4.2.2 ! misho 10104: ** pbIndirect is not NULL, then *pbIndirect is set to true (1) if the change
1.4 misho 10105: ** is an indirect change, or false (0) otherwise. See the documentation for
10106: ** [sqlite3session_indirect()] for a description of direct and indirect
10107: ** changes. Finally, if pOp is not NULL, then *pOp is set to one of
10108: ** [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE], depending on the
10109: ** type of change that the iterator currently points to.
10110: **
10111: ** If no error occurs, SQLITE_OK is returned. If an error does occur, an
10112: ** SQLite error code is returned. The values of the output variables may not
10113: ** be trusted in this case.
10114: */
1.4.2.1 misho 10115: SQLITE_API int sqlite3changeset_op(
1.4 misho 10116: sqlite3_changeset_iter *pIter, /* Iterator object */
10117: const char **pzTab, /* OUT: Pointer to table name */
10118: int *pnCol, /* OUT: Number of columns in table */
10119: int *pOp, /* OUT: SQLITE_INSERT, DELETE or UPDATE */
10120: int *pbIndirect /* OUT: True for an 'indirect' change */
10121: );
10122:
10123: /*
10124: ** CAPI3REF: Obtain The Primary Key Definition Of A Table
1.4.2.2 ! misho 10125: ** METHOD: sqlite3_changeset_iter
1.4 misho 10126: **
10127: ** For each modified table, a changeset includes the following:
10128: **
10129: ** <ul>
10130: ** <li> The number of columns in the table, and
10131: ** <li> Which of those columns make up the tables PRIMARY KEY.
10132: ** </ul>
10133: **
10134: ** This function is used to find which columns comprise the PRIMARY KEY of
10135: ** the table modified by the change that iterator pIter currently points to.
10136: ** If successful, *pabPK is set to point to an array of nCol entries, where
10137: ** nCol is the number of columns in the table. Elements of *pabPK are set to
10138: ** 0x01 if the corresponding column is part of the tables primary key, or
10139: ** 0x00 if it is not.
10140: **
1.4.2.1 misho 10141: ** If argument pnCol is not NULL, then *pnCol is set to the number of columns
1.4 misho 10142: ** in the table.
10143: **
10144: ** If this function is called when the iterator does not point to a valid
10145: ** entry, SQLITE_MISUSE is returned and the output variables zeroed. Otherwise,
10146: ** SQLITE_OK is returned and the output variables populated as described
10147: ** above.
10148: */
1.4.2.1 misho 10149: SQLITE_API int sqlite3changeset_pk(
1.4 misho 10150: sqlite3_changeset_iter *pIter, /* Iterator object */
10151: unsigned char **pabPK, /* OUT: Array of boolean - true for PK cols */
10152: int *pnCol /* OUT: Number of entries in output array */
10153: );
10154:
10155: /*
10156: ** CAPI3REF: Obtain old.* Values From A Changeset Iterator
1.4.2.2 ! misho 10157: ** METHOD: sqlite3_changeset_iter
1.4 misho 10158: **
10159: ** The pIter argument passed to this function may either be an iterator
10160: ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
10161: ** created by [sqlite3changeset_start()]. In the latter case, the most recent
10162: ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.
10163: ** Furthermore, it may only be called if the type of change that the iterator
10164: ** currently points to is either [SQLITE_DELETE] or [SQLITE_UPDATE]. Otherwise,
10165: ** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.
10166: **
10167: ** Argument iVal must be greater than or equal to 0, and less than the number
10168: ** of columns in the table affected by the current change. Otherwise,
10169: ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
10170: **
10171: ** If successful, this function sets *ppValue to point to a protected
10172: ** sqlite3_value object containing the iVal'th value from the vector of
10173: ** original row values stored as part of the UPDATE or DELETE change and
10174: ** returns SQLITE_OK. The name of the function comes from the fact that this
10175: ** is similar to the "old.*" columns available to update or delete triggers.
10176: **
10177: ** If some other error occurs (e.g. an OOM condition), an SQLite error code
10178: ** is returned and *ppValue is set to NULL.
10179: */
1.4.2.1 misho 10180: SQLITE_API int sqlite3changeset_old(
1.4 misho 10181: sqlite3_changeset_iter *pIter, /* Changeset iterator */
10182: int iVal, /* Column number */
10183: sqlite3_value **ppValue /* OUT: Old value (or NULL pointer) */
10184: );
10185:
10186: /*
10187: ** CAPI3REF: Obtain new.* Values From A Changeset Iterator
1.4.2.2 ! misho 10188: ** METHOD: sqlite3_changeset_iter
1.4 misho 10189: **
10190: ** The pIter argument passed to this function may either be an iterator
10191: ** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator
10192: ** created by [sqlite3changeset_start()]. In the latter case, the most recent
10193: ** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.
10194: ** Furthermore, it may only be called if the type of change that the iterator
10195: ** currently points to is either [SQLITE_UPDATE] or [SQLITE_INSERT]. Otherwise,
10196: ** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.
10197: **
10198: ** Argument iVal must be greater than or equal to 0, and less than the number
10199: ** of columns in the table affected by the current change. Otherwise,
10200: ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
10201: **
10202: ** If successful, this function sets *ppValue to point to a protected
10203: ** sqlite3_value object containing the iVal'th value from the vector of
10204: ** new row values stored as part of the UPDATE or INSERT change and
10205: ** returns SQLITE_OK. If the change is an UPDATE and does not include
10206: ** a new value for the requested column, *ppValue is set to NULL and
10207: ** SQLITE_OK returned. The name of the function comes from the fact that
10208: ** this is similar to the "new.*" columns available to update or delete
10209: ** triggers.
10210: **
10211: ** If some other error occurs (e.g. an OOM condition), an SQLite error code
10212: ** is returned and *ppValue is set to NULL.
10213: */
1.4.2.1 misho 10214: SQLITE_API int sqlite3changeset_new(
1.4 misho 10215: sqlite3_changeset_iter *pIter, /* Changeset iterator */
10216: int iVal, /* Column number */
10217: sqlite3_value **ppValue /* OUT: New value (or NULL pointer) */
10218: );
10219:
10220: /*
10221: ** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator
1.4.2.2 ! misho 10222: ** METHOD: sqlite3_changeset_iter
1.4 misho 10223: **
10224: ** This function should only be used with iterator objects passed to a
10225: ** conflict-handler callback by [sqlite3changeset_apply()] with either
10226: ** [SQLITE_CHANGESET_DATA] or [SQLITE_CHANGESET_CONFLICT]. If this function
10227: ** is called on any other iterator, [SQLITE_MISUSE] is returned and *ppValue
10228: ** is set to NULL.
10229: **
10230: ** Argument iVal must be greater than or equal to 0, and less than the number
10231: ** of columns in the table affected by the current change. Otherwise,
10232: ** [SQLITE_RANGE] is returned and *ppValue is set to NULL.
10233: **
10234: ** If successful, this function sets *ppValue to point to a protected
10235: ** sqlite3_value object containing the iVal'th value from the
10236: ** "conflicting row" associated with the current conflict-handler callback
10237: ** and returns SQLITE_OK.
10238: **
10239: ** If some other error occurs (e.g. an OOM condition), an SQLite error code
10240: ** is returned and *ppValue is set to NULL.
10241: */
1.4.2.1 misho 10242: SQLITE_API int sqlite3changeset_conflict(
1.4 misho 10243: sqlite3_changeset_iter *pIter, /* Changeset iterator */
10244: int iVal, /* Column number */
10245: sqlite3_value **ppValue /* OUT: Value from conflicting row */
10246: );
10247:
10248: /*
10249: ** CAPI3REF: Determine The Number Of Foreign Key Constraint Violations
1.4.2.2 ! misho 10250: ** METHOD: sqlite3_changeset_iter
1.4 misho 10251: **
10252: ** This function may only be called with an iterator passed to an
10253: ** SQLITE_CHANGESET_FOREIGN_KEY conflict handler callback. In this case
10254: ** it sets the output variable to the total number of known foreign key
10255: ** violations in the destination database and returns SQLITE_OK.
10256: **
10257: ** In all other cases this function returns SQLITE_MISUSE.
10258: */
1.4.2.1 misho 10259: SQLITE_API int sqlite3changeset_fk_conflicts(
1.4 misho 10260: sqlite3_changeset_iter *pIter, /* Changeset iterator */
10261: int *pnOut /* OUT: Number of FK violations */
10262: );
10263:
10264:
10265: /*
10266: ** CAPI3REF: Finalize A Changeset Iterator
1.4.2.2 ! misho 10267: ** METHOD: sqlite3_changeset_iter
1.4 misho 10268: **
10269: ** This function is used to finalize an iterator allocated with
10270: ** [sqlite3changeset_start()].
10271: **
10272: ** This function should only be called on iterators created using the
10273: ** [sqlite3changeset_start()] function. If an application calls this
10274: ** function with an iterator passed to a conflict-handler by
10275: ** [sqlite3changeset_apply()], [SQLITE_MISUSE] is immediately returned and the
10276: ** call has no effect.
10277: **
10278: ** If an error was encountered within a call to an sqlite3changeset_xxx()
10279: ** function (for example an [SQLITE_CORRUPT] in [sqlite3changeset_next()] or an
10280: ** [SQLITE_NOMEM] in [sqlite3changeset_new()]) then an error code corresponding
10281: ** to that error is returned by this function. Otherwise, SQLITE_OK is
10282: ** returned. This is to allow the following pattern (pseudo-code):
10283: **
1.4.2.2 ! misho 10284: ** <pre>
1.4 misho 10285: ** sqlite3changeset_start();
10286: ** while( SQLITE_ROW==sqlite3changeset_next() ){
10287: ** // Do something with change.
10288: ** }
10289: ** rc = sqlite3changeset_finalize();
10290: ** if( rc!=SQLITE_OK ){
10291: ** // An error has occurred
10292: ** }
1.4.2.2 ! misho 10293: ** </pre>
1.4 misho 10294: */
1.4.2.1 misho 10295: SQLITE_API int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);
1.4 misho 10296:
10297: /*
10298: ** CAPI3REF: Invert A Changeset
10299: **
10300: ** This function is used to "invert" a changeset object. Applying an inverted
10301: ** changeset to a database reverses the effects of applying the uninverted
10302: ** changeset. Specifically:
10303: **
10304: ** <ul>
10305: ** <li> Each DELETE change is changed to an INSERT, and
10306: ** <li> Each INSERT change is changed to a DELETE, and
10307: ** <li> For each UPDATE change, the old.* and new.* values are exchanged.
10308: ** </ul>
10309: **
10310: ** This function does not change the order in which changes appear within
10311: ** the changeset. It merely reverses the sense of each individual change.
10312: **
10313: ** If successful, a pointer to a buffer containing the inverted changeset
10314: ** is stored in *ppOut, the size of the same buffer is stored in *pnOut, and
10315: ** SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are
10316: ** zeroed and an SQLite error code returned.
10317: **
10318: ** It is the responsibility of the caller to eventually call sqlite3_free()
10319: ** on the *ppOut pointer to free the buffer allocation following a successful
10320: ** call to this function.
10321: **
10322: ** WARNING/TODO: This function currently assumes that the input is a valid
10323: ** changeset. If it is not, the results are undefined.
10324: */
1.4.2.1 misho 10325: SQLITE_API int sqlite3changeset_invert(
1.4 misho 10326: int nIn, const void *pIn, /* Input changeset */
10327: int *pnOut, void **ppOut /* OUT: Inverse of input */
10328: );
10329:
10330: /*
10331: ** CAPI3REF: Concatenate Two Changeset Objects
10332: **
10333: ** This function is used to concatenate two changesets, A and B, into a
10334: ** single changeset. The result is a changeset equivalent to applying
10335: ** changeset A followed by changeset B.
10336: **
10337: ** This function combines the two input changesets using an
10338: ** sqlite3_changegroup object. Calling it produces similar results as the
10339: ** following code fragment:
10340: **
1.4.2.2 ! misho 10341: ** <pre>
1.4 misho 10342: ** sqlite3_changegroup *pGrp;
10343: ** rc = sqlite3_changegroup_new(&pGrp);
10344: ** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nA, pA);
10345: ** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nB, pB);
10346: ** if( rc==SQLITE_OK ){
10347: ** rc = sqlite3changegroup_output(pGrp, pnOut, ppOut);
10348: ** }else{
10349: ** *ppOut = 0;
10350: ** *pnOut = 0;
10351: ** }
1.4.2.2 ! misho 10352: ** </pre>
1.4 misho 10353: **
10354: ** Refer to the sqlite3_changegroup documentation below for details.
10355: */
1.4.2.1 misho 10356: SQLITE_API int sqlite3changeset_concat(
1.4 misho 10357: int nA, /* Number of bytes in buffer pA */
10358: void *pA, /* Pointer to buffer containing changeset A */
10359: int nB, /* Number of bytes in buffer pB */
10360: void *pB, /* Pointer to buffer containing changeset B */
10361: int *pnOut, /* OUT: Number of bytes in output changeset */
10362: void **ppOut /* OUT: Buffer containing output changeset */
10363: );
10364:
10365:
10366: /*
1.4.2.1 misho 10367: ** CAPI3REF: Changegroup Handle
1.4.2.2 ! misho 10368: **
! 10369: ** A changegroup is an object used to combine two or more
! 10370: ** [changesets] or [patchsets]
1.4 misho 10371: */
10372: typedef struct sqlite3_changegroup sqlite3_changegroup;
10373:
10374: /*
1.4.2.1 misho 10375: ** CAPI3REF: Create A New Changegroup Object
1.4.2.2 ! misho 10376: ** CONSTRUCTOR: sqlite3_changegroup
1.4 misho 10377: **
10378: ** An sqlite3_changegroup object is used to combine two or more changesets
10379: ** (or patchsets) into a single changeset (or patchset). A single changegroup
10380: ** object may combine changesets or patchsets, but not both. The output is
10381: ** always in the same format as the input.
10382: **
10383: ** If successful, this function returns SQLITE_OK and populates (*pp) with
10384: ** a pointer to a new sqlite3_changegroup object before returning. The caller
10385: ** should eventually free the returned object using a call to
10386: ** sqlite3changegroup_delete(). If an error occurs, an SQLite error code
10387: ** (i.e. SQLITE_NOMEM) is returned and *pp is set to NULL.
10388: **
10389: ** The usual usage pattern for an sqlite3_changegroup object is as follows:
10390: **
10391: ** <ul>
10392: ** <li> It is created using a call to sqlite3changegroup_new().
10393: **
10394: ** <li> Zero or more changesets (or patchsets) are added to the object
10395: ** by calling sqlite3changegroup_add().
10396: **
10397: ** <li> The result of combining all input changesets together is obtained
10398: ** by the application via a call to sqlite3changegroup_output().
10399: **
10400: ** <li> The object is deleted using a call to sqlite3changegroup_delete().
10401: ** </ul>
10402: **
10403: ** Any number of calls to add() and output() may be made between the calls to
10404: ** new() and delete(), and in any order.
10405: **
10406: ** As well as the regular sqlite3changegroup_add() and
10407: ** sqlite3changegroup_output() functions, also available are the streaming
10408: ** versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm().
10409: */
1.4.2.1 misho 10410: SQLITE_API int sqlite3changegroup_new(sqlite3_changegroup **pp);
1.4 misho 10411:
10412: /*
1.4.2.1 misho 10413: ** CAPI3REF: Add A Changeset To A Changegroup
1.4.2.2 ! misho 10414: ** METHOD: sqlite3_changegroup
1.4.2.1 misho 10415: **
1.4 misho 10416: ** Add all changes within the changeset (or patchset) in buffer pData (size
10417: ** nData bytes) to the changegroup.
10418: **
10419: ** If the buffer contains a patchset, then all prior calls to this function
10420: ** on the same changegroup object must also have specified patchsets. Or, if
10421: ** the buffer contains a changeset, so must have the earlier calls to this
10422: ** function. Otherwise, SQLITE_ERROR is returned and no changes are added
10423: ** to the changegroup.
10424: **
10425: ** Rows within the changeset and changegroup are identified by the values in
10426: ** their PRIMARY KEY columns. A change in the changeset is considered to
10427: ** apply to the same row as a change already present in the changegroup if
10428: ** the two rows have the same primary key.
10429: **
1.4.2.1 misho 10430: ** Changes to rows that do not already appear in the changegroup are
1.4 misho 10431: ** simply copied into it. Or, if both the new changeset and the changegroup
10432: ** contain changes that apply to a single row, the final contents of the
10433: ** changegroup depends on the type of each change, as follows:
10434: **
10435: ** <table border=1 style="margin-left:8ex;margin-right:8ex">
10436: ** <tr><th style="white-space:pre">Existing Change </th>
10437: ** <th style="white-space:pre">New Change </th>
10438: ** <th>Output Change
10439: ** <tr><td>INSERT <td>INSERT <td>
10440: ** The new change is ignored. This case does not occur if the new
10441: ** changeset was recorded immediately after the changesets already
10442: ** added to the changegroup.
10443: ** <tr><td>INSERT <td>UPDATE <td>
10444: ** The INSERT change remains in the changegroup. The values in the
10445: ** INSERT change are modified as if the row was inserted by the
10446: ** existing change and then updated according to the new change.
10447: ** <tr><td>INSERT <td>DELETE <td>
10448: ** The existing INSERT is removed from the changegroup. The DELETE is
10449: ** not added.
10450: ** <tr><td>UPDATE <td>INSERT <td>
10451: ** The new change is ignored. This case does not occur if the new
10452: ** changeset was recorded immediately after the changesets already
10453: ** added to the changegroup.
10454: ** <tr><td>UPDATE <td>UPDATE <td>
10455: ** The existing UPDATE remains within the changegroup. It is amended
10456: ** so that the accompanying values are as if the row was updated once
10457: ** by the existing change and then again by the new change.
10458: ** <tr><td>UPDATE <td>DELETE <td>
10459: ** The existing UPDATE is replaced by the new DELETE within the
10460: ** changegroup.
10461: ** <tr><td>DELETE <td>INSERT <td>
10462: ** If one or more of the column values in the row inserted by the
10463: ** new change differ from those in the row deleted by the existing
10464: ** change, the existing DELETE is replaced by an UPDATE within the
10465: ** changegroup. Otherwise, if the inserted row is exactly the same
10466: ** as the deleted row, the existing DELETE is simply discarded.
10467: ** <tr><td>DELETE <td>UPDATE <td>
10468: ** The new change is ignored. This case does not occur if the new
10469: ** changeset was recorded immediately after the changesets already
10470: ** added to the changegroup.
10471: ** <tr><td>DELETE <td>DELETE <td>
10472: ** The new change is ignored. This case does not occur if the new
10473: ** changeset was recorded immediately after the changesets already
10474: ** added to the changegroup.
10475: ** </table>
10476: **
10477: ** If the new changeset contains changes to a table that is already present
10478: ** in the changegroup, then the number of columns and the position of the
10479: ** primary key columns for the table must be consistent. If this is not the
10480: ** case, this function fails with SQLITE_SCHEMA. If the input changeset
10481: ** appears to be corrupt and the corruption is detected, SQLITE_CORRUPT is
10482: ** returned. Or, if an out-of-memory condition occurs during processing, this
10483: ** function returns SQLITE_NOMEM. In all cases, if an error occurs the
10484: ** final contents of the changegroup is undefined.
10485: **
10486: ** If no error occurs, SQLITE_OK is returned.
10487: */
1.4.2.1 misho 10488: SQLITE_API int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pData);
1.4 misho 10489:
10490: /*
1.4.2.1 misho 10491: ** CAPI3REF: Obtain A Composite Changeset From A Changegroup
1.4.2.2 ! misho 10492: ** METHOD: sqlite3_changegroup
1.4.2.1 misho 10493: **
1.4 misho 10494: ** Obtain a buffer containing a changeset (or patchset) representing the
10495: ** current contents of the changegroup. If the inputs to the changegroup
10496: ** were themselves changesets, the output is a changeset. Or, if the
10497: ** inputs were patchsets, the output is also a patchset.
10498: **
10499: ** As with the output of the sqlite3session_changeset() and
10500: ** sqlite3session_patchset() functions, all changes related to a single
10501: ** table are grouped together in the output of this function. Tables appear
10502: ** in the same order as for the very first changeset added to the changegroup.
10503: ** If the second or subsequent changesets added to the changegroup contain
10504: ** changes for tables that do not appear in the first changeset, they are
10505: ** appended onto the end of the output changeset, again in the order in
10506: ** which they are first encountered.
10507: **
10508: ** If an error occurs, an SQLite error code is returned and the output
10509: ** variables (*pnData) and (*ppData) are set to 0. Otherwise, SQLITE_OK
10510: ** is returned and the output variables are set to the size of and a
10511: ** pointer to the output buffer, respectively. In this case it is the
10512: ** responsibility of the caller to eventually free the buffer using a
10513: ** call to sqlite3_free().
10514: */
1.4.2.1 misho 10515: SQLITE_API int sqlite3changegroup_output(
1.4 misho 10516: sqlite3_changegroup*,
10517: int *pnData, /* OUT: Size of output buffer in bytes */
10518: void **ppData /* OUT: Pointer to output buffer */
10519: );
10520:
10521: /*
1.4.2.1 misho 10522: ** CAPI3REF: Delete A Changegroup Object
1.4.2.2 ! misho 10523: ** DESTRUCTOR: sqlite3_changegroup
1.4 misho 10524: */
1.4.2.1 misho 10525: SQLITE_API void sqlite3changegroup_delete(sqlite3_changegroup*);
1.4 misho 10526:
10527: /*
10528: ** CAPI3REF: Apply A Changeset To A Database
10529: **
1.4.2.2 ! misho 10530: ** Apply a changeset or patchset to a database. These functions attempt to
! 10531: ** update the "main" database attached to handle db with the changes found in
! 10532: ** the changeset passed via the second and third arguments.
1.4 misho 10533: **
1.4.2.2 ! misho 10534: ** The fourth argument (xFilter) passed to these functions is the "filter
1.4 misho 10535: ** callback". If it is not NULL, then for each table affected by at least one
10536: ** change in the changeset, the filter callback is invoked with
10537: ** the table name as the second argument, and a copy of the context pointer
1.4.2.2 ! misho 10538: ** passed as the sixth argument as the first. If the "filter callback"
! 10539: ** returns zero, then no attempt is made to apply any changes to the table.
! 10540: ** Otherwise, if the return value is non-zero or the xFilter argument to
! 10541: ** is NULL, all changes related to the table are attempted.
1.4 misho 10542: **
10543: ** For each table that is not excluded by the filter callback, this function
10544: ** tests that the target database contains a compatible table. A table is
10545: ** considered compatible if all of the following are true:
10546: **
10547: ** <ul>
10548: ** <li> The table has the same name as the name recorded in the
10549: ** changeset, and
1.4.2.1 misho 10550: ** <li> The table has at least as many columns as recorded in the
1.4 misho 10551: ** changeset, and
10552: ** <li> The table has primary key columns in the same position as
10553: ** recorded in the changeset.
10554: ** </ul>
10555: **
10556: ** If there is no compatible table, it is not an error, but none of the
10557: ** changes associated with the table are applied. A warning message is issued
10558: ** via the sqlite3_log() mechanism with the error code SQLITE_SCHEMA. At most
10559: ** one such warning is issued for each table in the changeset.
10560: **
10561: ** For each change for which there is a compatible table, an attempt is made
10562: ** to modify the table contents according to the UPDATE, INSERT or DELETE
10563: ** change. If a change cannot be applied cleanly, the conflict handler
10564: ** function passed as the fifth argument to sqlite3changeset_apply() may be
10565: ** invoked. A description of exactly when the conflict handler is invoked for
10566: ** each type of change is below.
10567: **
10568: ** Unlike the xFilter argument, xConflict may not be passed NULL. The results
10569: ** of passing anything other than a valid function pointer as the xConflict
10570: ** argument are undefined.
10571: **
10572: ** Each time the conflict handler function is invoked, it must return one
10573: ** of [SQLITE_CHANGESET_OMIT], [SQLITE_CHANGESET_ABORT] or
10574: ** [SQLITE_CHANGESET_REPLACE]. SQLITE_CHANGESET_REPLACE may only be returned
10575: ** if the second argument passed to the conflict handler is either
10576: ** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler
10577: ** returns an illegal value, any changes already made are rolled back and
10578: ** the call to sqlite3changeset_apply() returns SQLITE_MISUSE. Different
10579: ** actions are taken by sqlite3changeset_apply() depending on the value
10580: ** returned by each invocation of the conflict-handler function. Refer to
10581: ** the documentation for the three
10582: ** [SQLITE_CHANGESET_OMIT|available return values] for details.
10583: **
10584: ** <dl>
10585: ** <dt>DELETE Changes<dd>
1.4.2.2 ! misho 10586: ** For each DELETE change, the function checks if the target database
1.4 misho 10587: ** contains a row with the same primary key value (or values) as the
10588: ** original row values stored in the changeset. If it does, and the values
10589: ** stored in all non-primary key columns also match the values stored in
10590: ** the changeset the row is deleted from the target database.
10591: **
10592: ** If a row with matching primary key values is found, but one or more of
10593: ** the non-primary key fields contains a value different from the original
10594: ** row value stored in the changeset, the conflict-handler function is
1.4.2.1 misho 10595: ** invoked with [SQLITE_CHANGESET_DATA] as the second argument. If the
10596: ** database table has more columns than are recorded in the changeset,
10597: ** only the values of those non-primary key fields are compared against
10598: ** the current database contents - any trailing database table columns
10599: ** are ignored.
1.4 misho 10600: **
10601: ** If no row with matching primary key values is found in the database,
10602: ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
10603: ** passed as the second argument.
10604: **
10605: ** If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT
10606: ** (which can only happen if a foreign key constraint is violated), the
10607: ** conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT]
10608: ** passed as the second argument. This includes the case where the DELETE
10609: ** operation is attempted because an earlier call to the conflict handler
10610: ** function returned [SQLITE_CHANGESET_REPLACE].
10611: **
10612: ** <dt>INSERT Changes<dd>
10613: ** For each INSERT change, an attempt is made to insert the new row into
1.4.2.1 misho 10614: ** the database. If the changeset row contains fewer fields than the
10615: ** database table, the trailing fields are populated with their default
10616: ** values.
1.4 misho 10617: **
10618: ** If the attempt to insert the row fails because the database already
10619: ** contains a row with the same primary key values, the conflict handler
10620: ** function is invoked with the second argument set to
10621: ** [SQLITE_CHANGESET_CONFLICT].
10622: **
10623: ** If the attempt to insert the row fails because of some other constraint
10624: ** violation (e.g. NOT NULL or UNIQUE), the conflict handler function is
10625: ** invoked with the second argument set to [SQLITE_CHANGESET_CONSTRAINT].
10626: ** This includes the case where the INSERT operation is re-attempted because
10627: ** an earlier call to the conflict handler function returned
10628: ** [SQLITE_CHANGESET_REPLACE].
10629: **
10630: ** <dt>UPDATE Changes<dd>
1.4.2.2 ! misho 10631: ** For each UPDATE change, the function checks if the target database
1.4 misho 10632: ** contains a row with the same primary key value (or values) as the
10633: ** original row values stored in the changeset. If it does, and the values
1.4.2.1 misho 10634: ** stored in all modified non-primary key columns also match the values
10635: ** stored in the changeset the row is updated within the target database.
1.4 misho 10636: **
10637: ** If a row with matching primary key values is found, but one or more of
1.4.2.1 misho 10638: ** the modified non-primary key fields contains a value different from an
10639: ** original row value stored in the changeset, the conflict-handler function
10640: ** is invoked with [SQLITE_CHANGESET_DATA] as the second argument. Since
1.4 misho 10641: ** UPDATE changes only contain values for non-primary key fields that are
10642: ** to be modified, only those fields need to match the original values to
10643: ** avoid the SQLITE_CHANGESET_DATA conflict-handler callback.
10644: **
10645: ** If no row with matching primary key values is found in the database,
10646: ** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
10647: ** passed as the second argument.
10648: **
10649: ** If the UPDATE operation is attempted, but SQLite returns
10650: ** SQLITE_CONSTRAINT, the conflict-handler function is invoked with
10651: ** [SQLITE_CHANGESET_CONSTRAINT] passed as the second argument.
10652: ** This includes the case where the UPDATE operation is attempted after
10653: ** an earlier call to the conflict handler function returned
10654: ** [SQLITE_CHANGESET_REPLACE].
10655: ** </dl>
10656: **
10657: ** It is safe to execute SQL statements, including those that write to the
10658: ** table that the callback related to, from within the xConflict callback.
10659: ** This can be used to further customize the applications conflict
10660: ** resolution strategy.
10661: **
1.4.2.2 ! misho 10662: ** All changes made by these functions are enclosed in a savepoint transaction.
1.4 misho 10663: ** If any other error (aside from a constraint failure when attempting to
10664: ** write to the target database) occurs, then the savepoint transaction is
10665: ** rolled back, restoring the target database to its original state, and an
10666: ** SQLite error code returned.
1.4.2.2 ! misho 10667: **
! 10668: ** If the output parameters (ppRebase) and (pnRebase) are non-NULL and
! 10669: ** the input is a changeset (not a patchset), then sqlite3changeset_apply_v2()
! 10670: ** may set (*ppRebase) to point to a "rebase" that may be used with the
! 10671: ** sqlite3_rebaser APIs buffer before returning. In this case (*pnRebase)
! 10672: ** is set to the size of the buffer in bytes. It is the responsibility of the
! 10673: ** caller to eventually free any such buffer using sqlite3_free(). The buffer
! 10674: ** is only allocated and populated if one or more conflicts were encountered
! 10675: ** while applying the patchset. See comments surrounding the sqlite3_rebaser
! 10676: ** APIs for further details.
! 10677: **
! 10678: ** The behavior of sqlite3changeset_apply_v2() and its streaming equivalent
! 10679: ** may be modified by passing a combination of
! 10680: ** [SQLITE_CHANGESETAPPLY_NOSAVEPOINT | supported flags] as the 9th parameter.
! 10681: **
! 10682: ** Note that the sqlite3changeset_apply_v2() API is still <b>experimental</b>
! 10683: ** and therefore subject to change.
1.4 misho 10684: */
1.4.2.1 misho 10685: SQLITE_API int sqlite3changeset_apply(
1.4 misho 10686: sqlite3 *db, /* Apply change to "main" db of this handle */
10687: int nChangeset, /* Size of changeset in bytes */
10688: void *pChangeset, /* Changeset blob */
10689: int(*xFilter)(
10690: void *pCtx, /* Copy of sixth arg to _apply() */
10691: const char *zTab /* Table name */
10692: ),
10693: int(*xConflict)(
10694: void *pCtx, /* Copy of sixth arg to _apply() */
10695: int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
10696: sqlite3_changeset_iter *p /* Handle describing change and conflict */
10697: ),
10698: void *pCtx /* First argument passed to xConflict */
10699: );
1.4.2.2 ! misho 10700: SQLITE_API int sqlite3changeset_apply_v2(
! 10701: sqlite3 *db, /* Apply change to "main" db of this handle */
! 10702: int nChangeset, /* Size of changeset in bytes */
! 10703: void *pChangeset, /* Changeset blob */
! 10704: int(*xFilter)(
! 10705: void *pCtx, /* Copy of sixth arg to _apply() */
! 10706: const char *zTab /* Table name */
! 10707: ),
! 10708: int(*xConflict)(
! 10709: void *pCtx, /* Copy of sixth arg to _apply() */
! 10710: int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
! 10711: sqlite3_changeset_iter *p /* Handle describing change and conflict */
! 10712: ),
! 10713: void *pCtx, /* First argument passed to xConflict */
! 10714: void **ppRebase, int *pnRebase, /* OUT: Rebase data */
! 10715: int flags /* SESSION_CHANGESETAPPLY_* flags */
! 10716: );
! 10717:
! 10718: /*
! 10719: ** CAPI3REF: Flags for sqlite3changeset_apply_v2
! 10720: **
! 10721: ** The following flags may passed via the 9th parameter to
! 10722: ** [sqlite3changeset_apply_v2] and [sqlite3changeset_apply_v2_strm]:
! 10723: **
! 10724: ** <dl>
! 10725: ** <dt>SQLITE_CHANGESETAPPLY_NOSAVEPOINT <dd>
! 10726: ** Usually, the sessions module encloses all operations performed by
! 10727: ** a single call to apply_v2() or apply_v2_strm() in a [SAVEPOINT]. The
! 10728: ** SAVEPOINT is committed if the changeset or patchset is successfully
! 10729: ** applied, or rolled back if an error occurs. Specifying this flag
! 10730: ** causes the sessions module to omit this savepoint. In this case, if the
! 10731: ** caller has an open transaction or savepoint when apply_v2() is called,
! 10732: ** it may revert the partially applied changeset by rolling it back.
! 10733: **
! 10734: ** <dt>SQLITE_CHANGESETAPPLY_INVERT <dd>
! 10735: ** Invert the changeset before applying it. This is equivalent to inverting
! 10736: ** a changeset using sqlite3changeset_invert() before applying it. It is
! 10737: ** an error to specify this flag with a patchset.
! 10738: */
! 10739: #define SQLITE_CHANGESETAPPLY_NOSAVEPOINT 0x0001
! 10740: #define SQLITE_CHANGESETAPPLY_INVERT 0x0002
1.4 misho 10741:
10742: /*
10743: ** CAPI3REF: Constants Passed To The Conflict Handler
10744: **
10745: ** Values that may be passed as the second argument to a conflict-handler.
10746: **
10747: ** <dl>
10748: ** <dt>SQLITE_CHANGESET_DATA<dd>
10749: ** The conflict handler is invoked with CHANGESET_DATA as the second argument
10750: ** when processing a DELETE or UPDATE change if a row with the required
10751: ** PRIMARY KEY fields is present in the database, but one or more other
10752: ** (non primary-key) fields modified by the update do not contain the
10753: ** expected "before" values.
10754: **
10755: ** The conflicting row, in this case, is the database row with the matching
10756: ** primary key.
10757: **
10758: ** <dt>SQLITE_CHANGESET_NOTFOUND<dd>
10759: ** The conflict handler is invoked with CHANGESET_NOTFOUND as the second
10760: ** argument when processing a DELETE or UPDATE change if a row with the
10761: ** required PRIMARY KEY fields is not present in the database.
10762: **
10763: ** There is no conflicting row in this case. The results of invoking the
10764: ** sqlite3changeset_conflict() API are undefined.
10765: **
10766: ** <dt>SQLITE_CHANGESET_CONFLICT<dd>
10767: ** CHANGESET_CONFLICT is passed as the second argument to the conflict
10768: ** handler while processing an INSERT change if the operation would result
10769: ** in duplicate primary key values.
10770: **
10771: ** The conflicting row in this case is the database row with the matching
10772: ** primary key.
10773: **
10774: ** <dt>SQLITE_CHANGESET_FOREIGN_KEY<dd>
10775: ** If foreign key handling is enabled, and applying a changeset leaves the
10776: ** database in a state containing foreign key violations, the conflict
10777: ** handler is invoked with CHANGESET_FOREIGN_KEY as the second argument
10778: ** exactly once before the changeset is committed. If the conflict handler
10779: ** returns CHANGESET_OMIT, the changes, including those that caused the
10780: ** foreign key constraint violation, are committed. Or, if it returns
10781: ** CHANGESET_ABORT, the changeset is rolled back.
10782: **
10783: ** No current or conflicting row information is provided. The only function
10784: ** it is possible to call on the supplied sqlite3_changeset_iter handle
10785: ** is sqlite3changeset_fk_conflicts().
10786: **
10787: ** <dt>SQLITE_CHANGESET_CONSTRAINT<dd>
10788: ** If any other constraint violation occurs while applying a change (i.e.
10789: ** a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is
10790: ** invoked with CHANGESET_CONSTRAINT as the second argument.
10791: **
10792: ** There is no conflicting row in this case. The results of invoking the
10793: ** sqlite3changeset_conflict() API are undefined.
10794: **
10795: ** </dl>
10796: */
10797: #define SQLITE_CHANGESET_DATA 1
10798: #define SQLITE_CHANGESET_NOTFOUND 2
10799: #define SQLITE_CHANGESET_CONFLICT 3
10800: #define SQLITE_CHANGESET_CONSTRAINT 4
10801: #define SQLITE_CHANGESET_FOREIGN_KEY 5
10802:
10803: /*
10804: ** CAPI3REF: Constants Returned By The Conflict Handler
10805: **
10806: ** A conflict handler callback must return one of the following three values.
10807: **
10808: ** <dl>
10809: ** <dt>SQLITE_CHANGESET_OMIT<dd>
10810: ** If a conflict handler returns this value no special action is taken. The
10811: ** change that caused the conflict is not applied. The session module
10812: ** continues to the next change in the changeset.
10813: **
10814: ** <dt>SQLITE_CHANGESET_REPLACE<dd>
10815: ** This value may only be returned if the second argument to the conflict
10816: ** handler was SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this
10817: ** is not the case, any changes applied so far are rolled back and the
10818: ** call to sqlite3changeset_apply() returns SQLITE_MISUSE.
10819: **
10820: ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_DATA conflict
10821: ** handler, then the conflicting row is either updated or deleted, depending
10822: ** on the type of change.
10823: **
10824: ** If CHANGESET_REPLACE is returned by an SQLITE_CHANGESET_CONFLICT conflict
10825: ** handler, then the conflicting row is removed from the database and a
10826: ** second attempt to apply the change is made. If this second attempt fails,
10827: ** the original row is restored to the database before continuing.
10828: **
10829: ** <dt>SQLITE_CHANGESET_ABORT<dd>
10830: ** If this value is returned, any changes applied so far are rolled back
10831: ** and the call to sqlite3changeset_apply() returns SQLITE_ABORT.
10832: ** </dl>
10833: */
10834: #define SQLITE_CHANGESET_OMIT 0
10835: #define SQLITE_CHANGESET_REPLACE 1
10836: #define SQLITE_CHANGESET_ABORT 2
10837:
1.4.2.2 ! misho 10838: /*
! 10839: ** CAPI3REF: Rebasing changesets
! 10840: ** EXPERIMENTAL
! 10841: **
! 10842: ** Suppose there is a site hosting a database in state S0. And that
! 10843: ** modifications are made that move that database to state S1 and a
! 10844: ** changeset recorded (the "local" changeset). Then, a changeset based
! 10845: ** on S0 is received from another site (the "remote" changeset) and
! 10846: ** applied to the database. The database is then in state
! 10847: ** (S1+"remote"), where the exact state depends on any conflict
! 10848: ** resolution decisions (OMIT or REPLACE) made while applying "remote".
! 10849: ** Rebasing a changeset is to update it to take those conflict
! 10850: ** resolution decisions into account, so that the same conflicts
! 10851: ** do not have to be resolved elsewhere in the network.
! 10852: **
! 10853: ** For example, if both the local and remote changesets contain an
! 10854: ** INSERT of the same key on "CREATE TABLE t1(a PRIMARY KEY, b)":
! 10855: **
! 10856: ** local: INSERT INTO t1 VALUES(1, 'v1');
! 10857: ** remote: INSERT INTO t1 VALUES(1, 'v2');
! 10858: **
! 10859: ** and the conflict resolution is REPLACE, then the INSERT change is
! 10860: ** removed from the local changeset (it was overridden). Or, if the
! 10861: ** conflict resolution was "OMIT", then the local changeset is modified
! 10862: ** to instead contain:
! 10863: **
! 10864: ** UPDATE t1 SET b = 'v2' WHERE a=1;
! 10865: **
! 10866: ** Changes within the local changeset are rebased as follows:
! 10867: **
! 10868: ** <dl>
! 10869: ** <dt>Local INSERT<dd>
! 10870: ** This may only conflict with a remote INSERT. If the conflict
! 10871: ** resolution was OMIT, then add an UPDATE change to the rebased
! 10872: ** changeset. Or, if the conflict resolution was REPLACE, add
! 10873: ** nothing to the rebased changeset.
! 10874: **
! 10875: ** <dt>Local DELETE<dd>
! 10876: ** This may conflict with a remote UPDATE or DELETE. In both cases the
! 10877: ** only possible resolution is OMIT. If the remote operation was a
! 10878: ** DELETE, then add no change to the rebased changeset. If the remote
! 10879: ** operation was an UPDATE, then the old.* fields of change are updated
! 10880: ** to reflect the new.* values in the UPDATE.
! 10881: **
! 10882: ** <dt>Local UPDATE<dd>
! 10883: ** This may conflict with a remote UPDATE or DELETE. If it conflicts
! 10884: ** with a DELETE, and the conflict resolution was OMIT, then the update
! 10885: ** is changed into an INSERT. Any undefined values in the new.* record
! 10886: ** from the update change are filled in using the old.* values from
! 10887: ** the conflicting DELETE. Or, if the conflict resolution was REPLACE,
! 10888: ** the UPDATE change is simply omitted from the rebased changeset.
! 10889: **
! 10890: ** If conflict is with a remote UPDATE and the resolution is OMIT, then
! 10891: ** the old.* values are rebased using the new.* values in the remote
! 10892: ** change. Or, if the resolution is REPLACE, then the change is copied
! 10893: ** into the rebased changeset with updates to columns also updated by
! 10894: ** the conflicting remote UPDATE removed. If this means no columns would
! 10895: ** be updated, the change is omitted.
! 10896: ** </dl>
! 10897: **
! 10898: ** A local change may be rebased against multiple remote changes
! 10899: ** simultaneously. If a single key is modified by multiple remote
! 10900: ** changesets, they are combined as follows before the local changeset
! 10901: ** is rebased:
! 10902: **
! 10903: ** <ul>
! 10904: ** <li> If there has been one or more REPLACE resolutions on a
! 10905: ** key, it is rebased according to a REPLACE.
! 10906: **
! 10907: ** <li> If there have been no REPLACE resolutions on a key, then
! 10908: ** the local changeset is rebased according to the most recent
! 10909: ** of the OMIT resolutions.
! 10910: ** </ul>
! 10911: **
! 10912: ** Note that conflict resolutions from multiple remote changesets are
! 10913: ** combined on a per-field basis, not per-row. This means that in the
! 10914: ** case of multiple remote UPDATE operations, some fields of a single
! 10915: ** local change may be rebased for REPLACE while others are rebased for
! 10916: ** OMIT.
! 10917: **
! 10918: ** In order to rebase a local changeset, the remote changeset must first
! 10919: ** be applied to the local database using sqlite3changeset_apply_v2() and
! 10920: ** the buffer of rebase information captured. Then:
! 10921: **
! 10922: ** <ol>
! 10923: ** <li> An sqlite3_rebaser object is created by calling
! 10924: ** sqlite3rebaser_create().
! 10925: ** <li> The new object is configured with the rebase buffer obtained from
! 10926: ** sqlite3changeset_apply_v2() by calling sqlite3rebaser_configure().
! 10927: ** If the local changeset is to be rebased against multiple remote
! 10928: ** changesets, then sqlite3rebaser_configure() should be called
! 10929: ** multiple times, in the same order that the multiple
! 10930: ** sqlite3changeset_apply_v2() calls were made.
! 10931: ** <li> Each local changeset is rebased by calling sqlite3rebaser_rebase().
! 10932: ** <li> The sqlite3_rebaser object is deleted by calling
! 10933: ** sqlite3rebaser_delete().
! 10934: ** </ol>
! 10935: */
! 10936: typedef struct sqlite3_rebaser sqlite3_rebaser;
! 10937:
! 10938: /*
! 10939: ** CAPI3REF: Create a changeset rebaser object.
! 10940: ** EXPERIMENTAL
! 10941: **
! 10942: ** Allocate a new changeset rebaser object. If successful, set (*ppNew) to
! 10943: ** point to the new object and return SQLITE_OK. Otherwise, if an error
! 10944: ** occurs, return an SQLite error code (e.g. SQLITE_NOMEM) and set (*ppNew)
! 10945: ** to NULL.
! 10946: */
! 10947: SQLITE_API int sqlite3rebaser_create(sqlite3_rebaser **ppNew);
! 10948:
! 10949: /*
! 10950: ** CAPI3REF: Configure a changeset rebaser object.
! 10951: ** EXPERIMENTAL
! 10952: **
! 10953: ** Configure the changeset rebaser object to rebase changesets according
! 10954: ** to the conflict resolutions described by buffer pRebase (size nRebase
! 10955: ** bytes), which must have been obtained from a previous call to
! 10956: ** sqlite3changeset_apply_v2().
! 10957: */
! 10958: SQLITE_API int sqlite3rebaser_configure(
! 10959: sqlite3_rebaser*,
! 10960: int nRebase, const void *pRebase
! 10961: );
! 10962:
! 10963: /*
! 10964: ** CAPI3REF: Rebase a changeset
! 10965: ** EXPERIMENTAL
! 10966: **
! 10967: ** Argument pIn must point to a buffer containing a changeset nIn bytes
! 10968: ** in size. This function allocates and populates a buffer with a copy
! 10969: ** of the changeset rebased rebased according to the configuration of the
! 10970: ** rebaser object passed as the first argument. If successful, (*ppOut)
! 10971: ** is set to point to the new buffer containing the rebased changeset and
! 10972: ** (*pnOut) to its size in bytes and SQLITE_OK returned. It is the
! 10973: ** responsibility of the caller to eventually free the new buffer using
! 10974: ** sqlite3_free(). Otherwise, if an error occurs, (*ppOut) and (*pnOut)
! 10975: ** are set to zero and an SQLite error code returned.
! 10976: */
! 10977: SQLITE_API int sqlite3rebaser_rebase(
! 10978: sqlite3_rebaser*,
! 10979: int nIn, const void *pIn,
! 10980: int *pnOut, void **ppOut
! 10981: );
! 10982:
! 10983: /*
! 10984: ** CAPI3REF: Delete a changeset rebaser object.
! 10985: ** EXPERIMENTAL
! 10986: **
! 10987: ** Delete the changeset rebaser object and all associated resources. There
! 10988: ** should be one call to this function for each successful invocation
! 10989: ** of sqlite3rebaser_create().
! 10990: */
! 10991: SQLITE_API void sqlite3rebaser_delete(sqlite3_rebaser *p);
! 10992:
1.4 misho 10993: /*
10994: ** CAPI3REF: Streaming Versions of API functions.
10995: **
10996: ** The six streaming API xxx_strm() functions serve similar purposes to the
10997: ** corresponding non-streaming API functions:
10998: **
10999: ** <table border=1 style="margin-left:8ex;margin-right:8ex">
11000: ** <tr><th>Streaming function<th>Non-streaming equivalent</th>
1.4.2.2 ! misho 11001: ** <tr><td>sqlite3changeset_apply_strm<td>[sqlite3changeset_apply]
! 11002: ** <tr><td>sqlite3changeset_apply_strm_v2<td>[sqlite3changeset_apply_v2]
! 11003: ** <tr><td>sqlite3changeset_concat_strm<td>[sqlite3changeset_concat]
! 11004: ** <tr><td>sqlite3changeset_invert_strm<td>[sqlite3changeset_invert]
! 11005: ** <tr><td>sqlite3changeset_start_strm<td>[sqlite3changeset_start]
! 11006: ** <tr><td>sqlite3session_changeset_strm<td>[sqlite3session_changeset]
! 11007: ** <tr><td>sqlite3session_patchset_strm<td>[sqlite3session_patchset]
1.4 misho 11008: ** </table>
11009: **
11010: ** Non-streaming functions that accept changesets (or patchsets) as input
11011: ** require that the entire changeset be stored in a single buffer in memory.
11012: ** Similarly, those that return a changeset or patchset do so by returning
11013: ** a pointer to a single large buffer allocated using sqlite3_malloc().
11014: ** Normally this is convenient. However, if an application running in a
11015: ** low-memory environment is required to handle very large changesets, the
11016: ** large contiguous memory allocations required can become onerous.
11017: **
11018: ** In order to avoid this problem, instead of a single large buffer, input
11019: ** is passed to a streaming API functions by way of a callback function that
11020: ** the sessions module invokes to incrementally request input data as it is
11021: ** required. In all cases, a pair of API function parameters such as
11022: **
11023: ** <pre>
11024: ** int nChangeset,
11025: ** void *pChangeset,
11026: ** </pre>
11027: **
11028: ** Is replaced by:
11029: **
11030: ** <pre>
11031: ** int (*xInput)(void *pIn, void *pData, int *pnData),
11032: ** void *pIn,
11033: ** </pre>
11034: **
11035: ** Each time the xInput callback is invoked by the sessions module, the first
11036: ** argument passed is a copy of the supplied pIn context pointer. The second
11037: ** argument, pData, points to a buffer (*pnData) bytes in size. Assuming no
11038: ** error occurs the xInput method should copy up to (*pnData) bytes of data
11039: ** into the buffer and set (*pnData) to the actual number of bytes copied
11040: ** before returning SQLITE_OK. If the input is completely exhausted, (*pnData)
11041: ** should be set to zero to indicate this. Or, if an error occurs, an SQLite
11042: ** error code should be returned. In all cases, if an xInput callback returns
11043: ** an error, all processing is abandoned and the streaming API function
11044: ** returns a copy of the error code to the caller.
11045: **
11046: ** In the case of sqlite3changeset_start_strm(), the xInput callback may be
11047: ** invoked by the sessions module at any point during the lifetime of the
11048: ** iterator. If such an xInput callback returns an error, the iterator enters
11049: ** an error state, whereby all subsequent calls to iterator functions
11050: ** immediately fail with the same error code as returned by xInput.
11051: **
11052: ** Similarly, streaming API functions that return changesets (or patchsets)
11053: ** return them in chunks by way of a callback function instead of via a
11054: ** pointer to a single large buffer. In this case, a pair of parameters such
11055: ** as:
11056: **
11057: ** <pre>
11058: ** int *pnChangeset,
11059: ** void **ppChangeset,
11060: ** </pre>
11061: **
11062: ** Is replaced by:
11063: **
11064: ** <pre>
11065: ** int (*xOutput)(void *pOut, const void *pData, int nData),
11066: ** void *pOut
11067: ** </pre>
11068: **
11069: ** The xOutput callback is invoked zero or more times to return data to
11070: ** the application. The first parameter passed to each call is a copy of the
11071: ** pOut pointer supplied by the application. The second parameter, pData,
11072: ** points to a buffer nData bytes in size containing the chunk of output
11073: ** data being returned. If the xOutput callback successfully processes the
11074: ** supplied data, it should return SQLITE_OK to indicate success. Otherwise,
11075: ** it should return some other SQLite error code. In this case processing
11076: ** is immediately abandoned and the streaming API function returns a copy
11077: ** of the xOutput error code to the application.
11078: **
11079: ** The sessions module never invokes an xOutput callback with the third
11080: ** parameter set to a value less than or equal to zero. Other than this,
11081: ** no guarantees are made as to the size of the chunks of data returned.
11082: */
1.4.2.1 misho 11083: SQLITE_API int sqlite3changeset_apply_strm(
1.4 misho 11084: sqlite3 *db, /* Apply change to "main" db of this handle */
11085: int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
11086: void *pIn, /* First arg for xInput */
11087: int(*xFilter)(
11088: void *pCtx, /* Copy of sixth arg to _apply() */
11089: const char *zTab /* Table name */
11090: ),
11091: int(*xConflict)(
11092: void *pCtx, /* Copy of sixth arg to _apply() */
11093: int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
11094: sqlite3_changeset_iter *p /* Handle describing change and conflict */
11095: ),
11096: void *pCtx /* First argument passed to xConflict */
11097: );
1.4.2.2 ! misho 11098: SQLITE_API int sqlite3changeset_apply_v2_strm(
! 11099: sqlite3 *db, /* Apply change to "main" db of this handle */
! 11100: int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
! 11101: void *pIn, /* First arg for xInput */
! 11102: int(*xFilter)(
! 11103: void *pCtx, /* Copy of sixth arg to _apply() */
! 11104: const char *zTab /* Table name */
! 11105: ),
! 11106: int(*xConflict)(
! 11107: void *pCtx, /* Copy of sixth arg to _apply() */
! 11108: int eConflict, /* DATA, MISSING, CONFLICT, CONSTRAINT */
! 11109: sqlite3_changeset_iter *p /* Handle describing change and conflict */
! 11110: ),
! 11111: void *pCtx, /* First argument passed to xConflict */
! 11112: void **ppRebase, int *pnRebase,
! 11113: int flags
! 11114: );
1.4.2.1 misho 11115: SQLITE_API int sqlite3changeset_concat_strm(
1.4 misho 11116: int (*xInputA)(void *pIn, void *pData, int *pnData),
11117: void *pInA,
11118: int (*xInputB)(void *pIn, void *pData, int *pnData),
11119: void *pInB,
11120: int (*xOutput)(void *pOut, const void *pData, int nData),
11121: void *pOut
11122: );
1.4.2.1 misho 11123: SQLITE_API int sqlite3changeset_invert_strm(
1.4 misho 11124: int (*xInput)(void *pIn, void *pData, int *pnData),
11125: void *pIn,
11126: int (*xOutput)(void *pOut, const void *pData, int nData),
11127: void *pOut
11128: );
1.4.2.1 misho 11129: SQLITE_API int sqlite3changeset_start_strm(
1.4 misho 11130: sqlite3_changeset_iter **pp,
11131: int (*xInput)(void *pIn, void *pData, int *pnData),
11132: void *pIn
11133: );
1.4.2.2 ! misho 11134: SQLITE_API int sqlite3changeset_start_v2_strm(
! 11135: sqlite3_changeset_iter **pp,
! 11136: int (*xInput)(void *pIn, void *pData, int *pnData),
! 11137: void *pIn,
! 11138: int flags
! 11139: );
1.4.2.1 misho 11140: SQLITE_API int sqlite3session_changeset_strm(
1.4 misho 11141: sqlite3_session *pSession,
11142: int (*xOutput)(void *pOut, const void *pData, int nData),
11143: void *pOut
11144: );
1.4.2.1 misho 11145: SQLITE_API int sqlite3session_patchset_strm(
1.4 misho 11146: sqlite3_session *pSession,
11147: int (*xOutput)(void *pOut, const void *pData, int nData),
11148: void *pOut
11149: );
1.4.2.1 misho 11150: SQLITE_API int sqlite3changegroup_add_strm(sqlite3_changegroup*,
1.4 misho 11151: int (*xInput)(void *pIn, void *pData, int *pnData),
11152: void *pIn
11153: );
1.4.2.1 misho 11154: SQLITE_API int sqlite3changegroup_output_strm(sqlite3_changegroup*,
1.4 misho 11155: int (*xOutput)(void *pOut, const void *pData, int nData),
11156: void *pOut
11157: );
1.4.2.2 ! misho 11158: SQLITE_API int sqlite3rebaser_rebase_strm(
! 11159: sqlite3_rebaser *pRebaser,
! 11160: int (*xInput)(void *pIn, void *pData, int *pnData),
! 11161: void *pIn,
! 11162: int (*xOutput)(void *pOut, const void *pData, int nData),
! 11163: void *pOut
! 11164: );
! 11165:
! 11166: /*
! 11167: ** CAPI3REF: Configure global parameters
! 11168: **
! 11169: ** The sqlite3session_config() interface is used to make global configuration
! 11170: ** changes to the sessions module in order to tune it to the specific needs
! 11171: ** of the application.
! 11172: **
! 11173: ** The sqlite3session_config() interface is not threadsafe. If it is invoked
! 11174: ** while any other thread is inside any other sessions method then the
! 11175: ** results are undefined. Furthermore, if it is invoked after any sessions
! 11176: ** related objects have been created, the results are also undefined.
! 11177: **
! 11178: ** The first argument to the sqlite3session_config() function must be one
! 11179: ** of the SQLITE_SESSION_CONFIG_XXX constants defined below. The
! 11180: ** interpretation of the (void*) value passed as the second parameter and
! 11181: ** the effect of calling this function depends on the value of the first
! 11182: ** parameter.
! 11183: **
! 11184: ** <dl>
! 11185: ** <dt>SQLITE_SESSION_CONFIG_STRMSIZE<dd>
! 11186: ** By default, the sessions module streaming interfaces attempt to input
! 11187: ** and output data in approximately 1 KiB chunks. This operand may be used
! 11188: ** to set and query the value of this configuration setting. The pointer
! 11189: ** passed as the second argument must point to a value of type (int).
! 11190: ** If this value is greater than 0, it is used as the new streaming data
! 11191: ** chunk size for both input and output. Before returning, the (int) value
! 11192: ** pointed to by pArg is set to the final value of the streaming interface
! 11193: ** chunk size.
! 11194: ** </dl>
! 11195: **
! 11196: ** This function returns SQLITE_OK if successful, or an SQLite error code
! 11197: ** otherwise.
! 11198: */
! 11199: SQLITE_API int sqlite3session_config(int op, void *pArg);
1.4 misho 11200:
1.4.2.2 ! misho 11201: /*
! 11202: ** CAPI3REF: Values for sqlite3session_config().
! 11203: */
! 11204: #define SQLITE_SESSION_CONFIG_STRMSIZE 1
1.4 misho 11205:
11206: /*
11207: ** Make sure we can call this stuff from C++.
11208: */
11209: #ifdef __cplusplus
11210: }
11211: #endif
11212:
11213: #endif /* !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION) */
11214:
11215: /******** End of sqlite3session.h *********/
11216: /******** Begin file fts5.h *********/
11217: /*
11218: ** 2014 May 31
11219: **
11220: ** The author disclaims copyright to this source code. In place of
11221: ** a legal notice, here is a blessing:
11222: **
11223: ** May you do good and not evil.
11224: ** May you find forgiveness for yourself and forgive others.
11225: ** May you share freely, never taking more than you give.
11226: **
11227: ******************************************************************************
11228: **
11229: ** Interfaces to extend FTS5. Using the interfaces defined in this file,
11230: ** FTS5 may be extended with:
11231: **
11232: ** * custom tokenizers, and
11233: ** * custom auxiliary functions.
11234: */
11235:
11236:
11237: #ifndef _FTS5_H
11238: #define _FTS5_H
11239:
11240:
11241: #ifdef __cplusplus
11242: extern "C" {
11243: #endif
11244:
11245: /*************************************************************************
11246: ** CUSTOM AUXILIARY FUNCTIONS
11247: **
11248: ** Virtual table implementations may overload SQL functions by implementing
11249: ** the sqlite3_module.xFindFunction() method.
11250: */
11251:
11252: typedef struct Fts5ExtensionApi Fts5ExtensionApi;
11253: typedef struct Fts5Context Fts5Context;
11254: typedef struct Fts5PhraseIter Fts5PhraseIter;
11255:
11256: typedef void (*fts5_extension_function)(
11257: const Fts5ExtensionApi *pApi, /* API offered by current FTS version */
11258: Fts5Context *pFts, /* First arg to pass to pApi functions */
11259: sqlite3_context *pCtx, /* Context for returning result/error */
11260: int nVal, /* Number of values in apVal[] array */
11261: sqlite3_value **apVal /* Array of trailing arguments */
11262: );
11263:
11264: struct Fts5PhraseIter {
11265: const unsigned char *a;
11266: const unsigned char *b;
11267: };
11268:
11269: /*
11270: ** EXTENSION API FUNCTIONS
11271: **
11272: ** xUserData(pFts):
11273: ** Return a copy of the context pointer the extension function was
11274: ** registered with.
11275: **
11276: ** xColumnTotalSize(pFts, iCol, pnToken):
11277: ** If parameter iCol is less than zero, set output variable *pnToken
11278: ** to the total number of tokens in the FTS5 table. Or, if iCol is
11279: ** non-negative but less than the number of columns in the table, return
11280: ** the total number of tokens in column iCol, considering all rows in
11281: ** the FTS5 table.
11282: **
11283: ** If parameter iCol is greater than or equal to the number of columns
11284: ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.
11285: ** an OOM condition or IO error), an appropriate SQLite error code is
11286: ** returned.
11287: **
11288: ** xColumnCount(pFts):
11289: ** Return the number of columns in the table.
11290: **
11291: ** xColumnSize(pFts, iCol, pnToken):
11292: ** If parameter iCol is less than zero, set output variable *pnToken
11293: ** to the total number of tokens in the current row. Or, if iCol is
11294: ** non-negative but less than the number of columns in the table, set
11295: ** *pnToken to the number of tokens in column iCol of the current row.
11296: **
11297: ** If parameter iCol is greater than or equal to the number of columns
11298: ** in the table, SQLITE_RANGE is returned. Or, if an error occurs (e.g.
11299: ** an OOM condition or IO error), an appropriate SQLite error code is
11300: ** returned.
11301: **
11302: ** This function may be quite inefficient if used with an FTS5 table
11303: ** created with the "columnsize=0" option.
11304: **
11305: ** xColumnText:
11306: ** This function attempts to retrieve the text of column iCol of the
11307: ** current document. If successful, (*pz) is set to point to a buffer
11308: ** containing the text in utf-8 encoding, (*pn) is set to the size in bytes
11309: ** (not characters) of the buffer and SQLITE_OK is returned. Otherwise,
11310: ** if an error occurs, an SQLite error code is returned and the final values
11311: ** of (*pz) and (*pn) are undefined.
11312: **
11313: ** xPhraseCount:
11314: ** Returns the number of phrases in the current query expression.
11315: **
11316: ** xPhraseSize:
11317: ** Returns the number of tokens in phrase iPhrase of the query. Phrases
11318: ** are numbered starting from zero.
11319: **
11320: ** xInstCount:
11321: ** Set *pnInst to the total number of occurrences of all phrases within
11322: ** the query within the current row. Return SQLITE_OK if successful, or
11323: ** an error code (i.e. SQLITE_NOMEM) if an error occurs.
11324: **
11325: ** This API can be quite slow if used with an FTS5 table created with the
11326: ** "detail=none" or "detail=column" option. If the FTS5 table is created
11327: ** with either "detail=none" or "detail=column" and "content=" option
11328: ** (i.e. if it is a contentless table), then this API always returns 0.
11329: **
11330: ** xInst:
11331: ** Query for the details of phrase match iIdx within the current row.
11332: ** Phrase matches are numbered starting from zero, so the iIdx argument
11333: ** should be greater than or equal to zero and smaller than the value
11334: ** output by xInstCount().
11335: **
11336: ** Usually, output parameter *piPhrase is set to the phrase number, *piCol
11337: ** to the column in which it occurs and *piOff the token offset of the
1.4.2.2 ! misho 11338: ** first token of the phrase. Returns SQLITE_OK if successful, or an error
! 11339: ** code (i.e. SQLITE_NOMEM) if an error occurs.
1.4 misho 11340: **
11341: ** This API can be quite slow if used with an FTS5 table created with the
11342: ** "detail=none" or "detail=column" option.
11343: **
11344: ** xRowid:
11345: ** Returns the rowid of the current row.
11346: **
11347: ** xTokenize:
11348: ** Tokenize text using the tokenizer belonging to the FTS5 table.
11349: **
11350: ** xQueryPhrase(pFts5, iPhrase, pUserData, xCallback):
11351: ** This API function is used to query the FTS table for phrase iPhrase
11352: ** of the current query. Specifically, a query equivalent to:
11353: **
11354: ** ... FROM ftstable WHERE ftstable MATCH $p ORDER BY rowid
11355: **
11356: ** with $p set to a phrase equivalent to the phrase iPhrase of the
11357: ** current query is executed. Any column filter that applies to
11358: ** phrase iPhrase of the current query is included in $p. For each
11359: ** row visited, the callback function passed as the fourth argument
11360: ** is invoked. The context and API objects passed to the callback
11361: ** function may be used to access the properties of each matched row.
11362: ** Invoking Api.xUserData() returns a copy of the pointer passed as
11363: ** the third argument to pUserData.
11364: **
11365: ** If the callback function returns any value other than SQLITE_OK, the
11366: ** query is abandoned and the xQueryPhrase function returns immediately.
11367: ** If the returned value is SQLITE_DONE, xQueryPhrase returns SQLITE_OK.
11368: ** Otherwise, the error code is propagated upwards.
11369: **
11370: ** If the query runs to completion without incident, SQLITE_OK is returned.
11371: ** Or, if some error occurs before the query completes or is aborted by
11372: ** the callback, an SQLite error code is returned.
11373: **
11374: **
11375: ** xSetAuxdata(pFts5, pAux, xDelete)
11376: **
11377: ** Save the pointer passed as the second argument as the extension functions
11378: ** "auxiliary data". The pointer may then be retrieved by the current or any
11379: ** future invocation of the same fts5 extension function made as part of
1.4.2.2 ! misho 11380: ** the same MATCH query using the xGetAuxdata() API.
1.4 misho 11381: **
11382: ** Each extension function is allocated a single auxiliary data slot for
11383: ** each FTS query (MATCH expression). If the extension function is invoked
11384: ** more than once for a single FTS query, then all invocations share a
11385: ** single auxiliary data context.
11386: **
11387: ** If there is already an auxiliary data pointer when this function is
11388: ** invoked, then it is replaced by the new pointer. If an xDelete callback
11389: ** was specified along with the original pointer, it is invoked at this
11390: ** point.
11391: **
11392: ** The xDelete callback, if one is specified, is also invoked on the
11393: ** auxiliary data pointer after the FTS5 query has finished.
11394: **
1.4.2.2 ! misho 11395: ** If an error (e.g. an OOM condition) occurs within this function,
1.4 misho 11396: ** the auxiliary data is set to NULL and an error code returned. If the
11397: ** xDelete parameter was not NULL, it is invoked on the auxiliary data
11398: ** pointer before returning.
11399: **
11400: **
11401: ** xGetAuxdata(pFts5, bClear)
11402: **
11403: ** Returns the current auxiliary data pointer for the fts5 extension
11404: ** function. See the xSetAuxdata() method for details.
11405: **
11406: ** If the bClear argument is non-zero, then the auxiliary data is cleared
11407: ** (set to NULL) before this function returns. In this case the xDelete,
11408: ** if any, is not invoked.
11409: **
11410: **
11411: ** xRowCount(pFts5, pnRow)
11412: **
11413: ** This function is used to retrieve the total number of rows in the table.
11414: ** In other words, the same value that would be returned by:
11415: **
11416: ** SELECT count(*) FROM ftstable;
11417: **
11418: ** xPhraseFirst()
11419: ** This function is used, along with type Fts5PhraseIter and the xPhraseNext
11420: ** method, to iterate through all instances of a single query phrase within
11421: ** the current row. This is the same information as is accessible via the
11422: ** xInstCount/xInst APIs. While the xInstCount/xInst APIs are more convenient
11423: ** to use, this API may be faster under some circumstances. To iterate
11424: ** through instances of phrase iPhrase, use the following code:
11425: **
11426: ** Fts5PhraseIter iter;
11427: ** int iCol, iOff;
11428: ** for(pApi->xPhraseFirst(pFts, iPhrase, &iter, &iCol, &iOff);
11429: ** iCol>=0;
11430: ** pApi->xPhraseNext(pFts, &iter, &iCol, &iOff)
11431: ** ){
11432: ** // An instance of phrase iPhrase at offset iOff of column iCol
11433: ** }
11434: **
11435: ** The Fts5PhraseIter structure is defined above. Applications should not
11436: ** modify this structure directly - it should only be used as shown above
11437: ** with the xPhraseFirst() and xPhraseNext() API methods (and by
11438: ** xPhraseFirstColumn() and xPhraseNextColumn() as illustrated below).
11439: **
11440: ** This API can be quite slow if used with an FTS5 table created with the
11441: ** "detail=none" or "detail=column" option. If the FTS5 table is created
11442: ** with either "detail=none" or "detail=column" and "content=" option
11443: ** (i.e. if it is a contentless table), then this API always iterates
11444: ** through an empty set (all calls to xPhraseFirst() set iCol to -1).
11445: **
11446: ** xPhraseNext()
11447: ** See xPhraseFirst above.
11448: **
11449: ** xPhraseFirstColumn()
11450: ** This function and xPhraseNextColumn() are similar to the xPhraseFirst()
11451: ** and xPhraseNext() APIs described above. The difference is that instead
11452: ** of iterating through all instances of a phrase in the current row, these
11453: ** APIs are used to iterate through the set of columns in the current row
11454: ** that contain one or more instances of a specified phrase. For example:
11455: **
11456: ** Fts5PhraseIter iter;
11457: ** int iCol;
11458: ** for(pApi->xPhraseFirstColumn(pFts, iPhrase, &iter, &iCol);
11459: ** iCol>=0;
11460: ** pApi->xPhraseNextColumn(pFts, &iter, &iCol)
11461: ** ){
11462: ** // Column iCol contains at least one instance of phrase iPhrase
11463: ** }
11464: **
11465: ** This API can be quite slow if used with an FTS5 table created with the
11466: ** "detail=none" option. If the FTS5 table is created with either
11467: ** "detail=none" "content=" option (i.e. if it is a contentless table),
11468: ** then this API always iterates through an empty set (all calls to
11469: ** xPhraseFirstColumn() set iCol to -1).
11470: **
11471: ** The information accessed using this API and its companion
11472: ** xPhraseFirstColumn() may also be obtained using xPhraseFirst/xPhraseNext
11473: ** (or xInst/xInstCount). The chief advantage of this API is that it is
11474: ** significantly more efficient than those alternatives when used with
11475: ** "detail=column" tables.
11476: **
11477: ** xPhraseNextColumn()
11478: ** See xPhraseFirstColumn above.
11479: */
11480: struct Fts5ExtensionApi {
11481: int iVersion; /* Currently always set to 3 */
11482:
11483: void *(*xUserData)(Fts5Context*);
11484:
11485: int (*xColumnCount)(Fts5Context*);
11486: int (*xRowCount)(Fts5Context*, sqlite3_int64 *pnRow);
11487: int (*xColumnTotalSize)(Fts5Context*, int iCol, sqlite3_int64 *pnToken);
11488:
11489: int (*xTokenize)(Fts5Context*,
11490: const char *pText, int nText, /* Text to tokenize */
11491: void *pCtx, /* Context passed to xToken() */
11492: int (*xToken)(void*, int, const char*, int, int, int) /* Callback */
11493: );
11494:
11495: int (*xPhraseCount)(Fts5Context*);
11496: int (*xPhraseSize)(Fts5Context*, int iPhrase);
11497:
11498: int (*xInstCount)(Fts5Context*, int *pnInst);
11499: int (*xInst)(Fts5Context*, int iIdx, int *piPhrase, int *piCol, int *piOff);
11500:
11501: sqlite3_int64 (*xRowid)(Fts5Context*);
11502: int (*xColumnText)(Fts5Context*, int iCol, const char **pz, int *pn);
11503: int (*xColumnSize)(Fts5Context*, int iCol, int *pnToken);
11504:
11505: int (*xQueryPhrase)(Fts5Context*, int iPhrase, void *pUserData,
11506: int(*)(const Fts5ExtensionApi*,Fts5Context*,void*)
11507: );
11508: int (*xSetAuxdata)(Fts5Context*, void *pAux, void(*xDelete)(void*));
11509: void *(*xGetAuxdata)(Fts5Context*, int bClear);
11510:
11511: int (*xPhraseFirst)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*, int*);
11512: void (*xPhraseNext)(Fts5Context*, Fts5PhraseIter*, int *piCol, int *piOff);
11513:
11514: int (*xPhraseFirstColumn)(Fts5Context*, int iPhrase, Fts5PhraseIter*, int*);
11515: void (*xPhraseNextColumn)(Fts5Context*, Fts5PhraseIter*, int *piCol);
11516: };
11517:
11518: /*
11519: ** CUSTOM AUXILIARY FUNCTIONS
11520: *************************************************************************/
11521:
11522: /*************************************************************************
11523: ** CUSTOM TOKENIZERS
11524: **
11525: ** Applications may also register custom tokenizer types. A tokenizer
11526: ** is registered by providing fts5 with a populated instance of the
11527: ** following structure. All structure methods must be defined, setting
11528: ** any member of the fts5_tokenizer struct to NULL leads to undefined
11529: ** behaviour. The structure methods are expected to function as follows:
11530: **
11531: ** xCreate:
11532: ** This function is used to allocate and initialize a tokenizer instance.
11533: ** A tokenizer instance is required to actually tokenize text.
11534: **
11535: ** The first argument passed to this function is a copy of the (void*)
11536: ** pointer provided by the application when the fts5_tokenizer object
11537: ** was registered with FTS5 (the third argument to xCreateTokenizer()).
11538: ** The second and third arguments are an array of nul-terminated strings
11539: ** containing the tokenizer arguments, if any, specified following the
11540: ** tokenizer name as part of the CREATE VIRTUAL TABLE statement used
11541: ** to create the FTS5 table.
11542: **
11543: ** The final argument is an output variable. If successful, (*ppOut)
11544: ** should be set to point to the new tokenizer handle and SQLITE_OK
11545: ** returned. If an error occurs, some value other than SQLITE_OK should
11546: ** be returned. In this case, fts5 assumes that the final value of *ppOut
11547: ** is undefined.
11548: **
11549: ** xDelete:
11550: ** This function is invoked to delete a tokenizer handle previously
11551: ** allocated using xCreate(). Fts5 guarantees that this function will
11552: ** be invoked exactly once for each successful call to xCreate().
11553: **
11554: ** xTokenize:
11555: ** This function is expected to tokenize the nText byte string indicated
11556: ** by argument pText. pText may or may not be nul-terminated. The first
11557: ** argument passed to this function is a pointer to an Fts5Tokenizer object
11558: ** returned by an earlier call to xCreate().
11559: **
11560: ** The second argument indicates the reason that FTS5 is requesting
11561: ** tokenization of the supplied text. This is always one of the following
11562: ** four values:
11563: **
11564: ** <ul><li> <b>FTS5_TOKENIZE_DOCUMENT</b> - A document is being inserted into
11565: ** or removed from the FTS table. The tokenizer is being invoked to
11566: ** determine the set of tokens to add to (or delete from) the
11567: ** FTS index.
11568: **
11569: ** <li> <b>FTS5_TOKENIZE_QUERY</b> - A MATCH query is being executed
11570: ** against the FTS index. The tokenizer is being called to tokenize
11571: ** a bareword or quoted string specified as part of the query.
11572: **
11573: ** <li> <b>(FTS5_TOKENIZE_QUERY | FTS5_TOKENIZE_PREFIX)</b> - Same as
11574: ** FTS5_TOKENIZE_QUERY, except that the bareword or quoted string is
11575: ** followed by a "*" character, indicating that the last token
11576: ** returned by the tokenizer will be treated as a token prefix.
11577: **
11578: ** <li> <b>FTS5_TOKENIZE_AUX</b> - The tokenizer is being invoked to
11579: ** satisfy an fts5_api.xTokenize() request made by an auxiliary
11580: ** function. Or an fts5_api.xColumnSize() request made by the same
11581: ** on a columnsize=0 database.
11582: ** </ul>
11583: **
11584: ** For each token in the input string, the supplied callback xToken() must
11585: ** be invoked. The first argument to it should be a copy of the pointer
11586: ** passed as the second argument to xTokenize(). The third and fourth
11587: ** arguments are a pointer to a buffer containing the token text, and the
11588: ** size of the token in bytes. The 4th and 5th arguments are the byte offsets
11589: ** of the first byte of and first byte immediately following the text from
11590: ** which the token is derived within the input.
11591: **
11592: ** The second argument passed to the xToken() callback ("tflags") should
11593: ** normally be set to 0. The exception is if the tokenizer supports
11594: ** synonyms. In this case see the discussion below for details.
11595: **
11596: ** FTS5 assumes the xToken() callback is invoked for each token in the
11597: ** order that they occur within the input text.
11598: **
11599: ** If an xToken() callback returns any value other than SQLITE_OK, then
11600: ** the tokenization should be abandoned and the xTokenize() method should
11601: ** immediately return a copy of the xToken() return value. Or, if the
11602: ** input buffer is exhausted, xTokenize() should return SQLITE_OK. Finally,
11603: ** if an error occurs with the xTokenize() implementation itself, it
11604: ** may abandon the tokenization and return any error code other than
11605: ** SQLITE_OK or SQLITE_DONE.
11606: **
11607: ** SYNONYM SUPPORT
11608: **
11609: ** Custom tokenizers may also support synonyms. Consider a case in which a
11610: ** user wishes to query for a phrase such as "first place". Using the
11611: ** built-in tokenizers, the FTS5 query 'first + place' will match instances
11612: ** of "first place" within the document set, but not alternative forms
11613: ** such as "1st place". In some applications, it would be better to match
11614: ** all instances of "first place" or "1st place" regardless of which form
11615: ** the user specified in the MATCH query text.
11616: **
11617: ** There are several ways to approach this in FTS5:
11618: **
11619: ** <ol><li> By mapping all synonyms to a single token. In this case, the
11620: ** In the above example, this means that the tokenizer returns the
11621: ** same token for inputs "first" and "1st". Say that token is in
11622: ** fact "first", so that when the user inserts the document "I won
11623: ** 1st place" entries are added to the index for tokens "i", "won",
11624: ** "first" and "place". If the user then queries for '1st + place',
11625: ** the tokenizer substitutes "first" for "1st" and the query works
11626: ** as expected.
11627: **
1.4.2.2 ! misho 11628: ** <li> By querying the index for all synonyms of each query term
! 11629: ** separately. In this case, when tokenizing query text, the
! 11630: ** tokenizer may provide multiple synonyms for a single term
! 11631: ** within the document. FTS5 then queries the index for each
! 11632: ** synonym individually. For example, faced with the query:
1.4 misho 11633: **
11634: ** <codeblock>
11635: ** ... MATCH 'first place'</codeblock>
11636: **
11637: ** the tokenizer offers both "1st" and "first" as synonyms for the
11638: ** first token in the MATCH query and FTS5 effectively runs a query
11639: ** similar to:
11640: **
11641: ** <codeblock>
11642: ** ... MATCH '(first OR 1st) place'</codeblock>
11643: **
11644: ** except that, for the purposes of auxiliary functions, the query
11645: ** still appears to contain just two phrases - "(first OR 1st)"
11646: ** being treated as a single phrase.
11647: **
11648: ** <li> By adding multiple synonyms for a single term to the FTS index.
11649: ** Using this method, when tokenizing document text, the tokenizer
11650: ** provides multiple synonyms for each token. So that when a
11651: ** document such as "I won first place" is tokenized, entries are
11652: ** added to the FTS index for "i", "won", "first", "1st" and
11653: ** "place".
11654: **
11655: ** This way, even if the tokenizer does not provide synonyms
1.4.2.2 ! misho 11656: ** when tokenizing query text (it should not - to do so would be
1.4 misho 11657: ** inefficient), it doesn't matter if the user queries for
1.4.2.2 ! misho 11658: ** 'first + place' or '1st + place', as there are entries in the
1.4 misho 11659: ** FTS index corresponding to both forms of the first token.
11660: ** </ol>
11661: **
11662: ** Whether it is parsing document or query text, any call to xToken that
11663: ** specifies a <i>tflags</i> argument with the FTS5_TOKEN_COLOCATED bit
11664: ** is considered to supply a synonym for the previous token. For example,
11665: ** when parsing the document "I won first place", a tokenizer that supports
11666: ** synonyms would call xToken() 5 times, as follows:
11667: **
11668: ** <codeblock>
11669: ** xToken(pCtx, 0, "i", 1, 0, 1);
11670: ** xToken(pCtx, 0, "won", 3, 2, 5);
11671: ** xToken(pCtx, 0, "first", 5, 6, 11);
11672: ** xToken(pCtx, FTS5_TOKEN_COLOCATED, "1st", 3, 6, 11);
11673: ** xToken(pCtx, 0, "place", 5, 12, 17);
11674: **</codeblock>
11675: **
11676: ** It is an error to specify the FTS5_TOKEN_COLOCATED flag the first time
11677: ** xToken() is called. Multiple synonyms may be specified for a single token
11678: ** by making multiple calls to xToken(FTS5_TOKEN_COLOCATED) in sequence.
11679: ** There is no limit to the number of synonyms that may be provided for a
11680: ** single token.
11681: **
11682: ** In many cases, method (1) above is the best approach. It does not add
11683: ** extra data to the FTS index or require FTS5 to query for multiple terms,
11684: ** so it is efficient in terms of disk space and query speed. However, it
11685: ** does not support prefix queries very well. If, as suggested above, the
1.4.2.2 ! misho 11686: ** token "first" is substituted for "1st" by the tokenizer, then the query:
1.4 misho 11687: **
11688: ** <codeblock>
11689: ** ... MATCH '1s*'</codeblock>
11690: **
11691: ** will not match documents that contain the token "1st" (as the tokenizer
11692: ** will probably not map "1s" to any prefix of "first").
11693: **
11694: ** For full prefix support, method (3) may be preferred. In this case,
11695: ** because the index contains entries for both "first" and "1st", prefix
11696: ** queries such as 'fi*' or '1s*' will match correctly. However, because
11697: ** extra entries are added to the FTS index, this method uses more space
11698: ** within the database.
11699: **
11700: ** Method (2) offers a midpoint between (1) and (3). Using this method,
11701: ** a query such as '1s*' will match documents that contain the literal
11702: ** token "1st", but not "first" (assuming the tokenizer is not able to
11703: ** provide synonyms for prefixes). However, a non-prefix query like '1st'
11704: ** will match against "1st" and "first". This method does not require
11705: ** extra disk space, as no extra entries are added to the FTS index.
11706: ** On the other hand, it may require more CPU cycles to run MATCH queries,
11707: ** as separate queries of the FTS index are required for each synonym.
11708: **
11709: ** When using methods (2) or (3), it is important that the tokenizer only
11710: ** provide synonyms when tokenizing document text (method (2)) or query
11711: ** text (method (3)), not both. Doing so will not cause any errors, but is
11712: ** inefficient.
11713: */
11714: typedef struct Fts5Tokenizer Fts5Tokenizer;
11715: typedef struct fts5_tokenizer fts5_tokenizer;
11716: struct fts5_tokenizer {
11717: int (*xCreate)(void*, const char **azArg, int nArg, Fts5Tokenizer **ppOut);
11718: void (*xDelete)(Fts5Tokenizer*);
11719: int (*xTokenize)(Fts5Tokenizer*,
11720: void *pCtx,
11721: int flags, /* Mask of FTS5_TOKENIZE_* flags */
11722: const char *pText, int nText,
11723: int (*xToken)(
11724: void *pCtx, /* Copy of 2nd argument to xTokenize() */
11725: int tflags, /* Mask of FTS5_TOKEN_* flags */
11726: const char *pToken, /* Pointer to buffer containing token */
11727: int nToken, /* Size of token in bytes */
11728: int iStart, /* Byte offset of token within input text */
11729: int iEnd /* Byte offset of end of token within input text */
11730: )
11731: );
11732: };
11733:
11734: /* Flags that may be passed as the third argument to xTokenize() */
11735: #define FTS5_TOKENIZE_QUERY 0x0001
11736: #define FTS5_TOKENIZE_PREFIX 0x0002
11737: #define FTS5_TOKENIZE_DOCUMENT 0x0004
11738: #define FTS5_TOKENIZE_AUX 0x0008
11739:
11740: /* Flags that may be passed by the tokenizer implementation back to FTS5
11741: ** as the third argument to the supplied xToken callback. */
11742: #define FTS5_TOKEN_COLOCATED 0x0001 /* Same position as prev. token */
11743:
11744: /*
11745: ** END OF CUSTOM TOKENIZERS
11746: *************************************************************************/
11747:
11748: /*************************************************************************
11749: ** FTS5 EXTENSION REGISTRATION API
11750: */
11751: typedef struct fts5_api fts5_api;
11752: struct fts5_api {
11753: int iVersion; /* Currently always set to 2 */
11754:
11755: /* Create a new tokenizer */
11756: int (*xCreateTokenizer)(
11757: fts5_api *pApi,
11758: const char *zName,
11759: void *pContext,
11760: fts5_tokenizer *pTokenizer,
11761: void (*xDestroy)(void*)
11762: );
11763:
11764: /* Find an existing tokenizer */
11765: int (*xFindTokenizer)(
11766: fts5_api *pApi,
11767: const char *zName,
11768: void **ppContext,
11769: fts5_tokenizer *pTokenizer
11770: );
11771:
11772: /* Create a new auxiliary function */
11773: int (*xCreateFunction)(
11774: fts5_api *pApi,
11775: const char *zName,
11776: void *pContext,
11777: fts5_extension_function xFunction,
11778: void (*xDestroy)(void*)
11779: );
11780: };
11781:
11782: /*
11783: ** END OF REGISTRATION API
11784: *************************************************************************/
11785:
11786: #ifdef __cplusplus
11787: } /* end of the 'extern "C"' block */
11788: #endif
11789:
11790: #endif /* _FTS5_H */
11791:
11792: /******** End of fts5.h *********/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to sqlite3.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / elwix / files / sqlite / dist