Annotation of win32/sql/sqlite/include/sqlite3.h, revision 1.4
1.1 misha 1: /*
2: ** 2001 September 15
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
1.2 misha 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 to make minor changes if
22: ** 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
26: ** on how SQLite interfaces are suppose to operate.
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.
1.1 misha 32: **
1.4 ! misha 33: ** @(#) $Id: sqlite.h.in,v 1.291 2008/03/08 12:37:31 drh Exp $
1.1 misha 34: */
35: #ifndef _SQLITE3_H_
36: #define _SQLITE3_H_
37: #include <stdarg.h> /* Needed for the definition of va_list */
38:
39: /*
40: ** Make sure we can call this stuff from C++.
41: */
42: #ifdef __cplusplus
43: extern "C" {
44: #endif
45:
1.2 misha 46:
47: /*
48: ** Add the ability to override 'extern'
49: */
50: #ifndef SQLITE_EXTERN
51: # define SQLITE_EXTERN extern
52: #endif
53:
1.1 misha 54: /*
1.2 misha 55: ** Make sure these symbols where not defined by some previous header
56: ** file.
1.1 misha 57: */
58: #ifdef SQLITE_VERSION
59: # undef SQLITE_VERSION
1.2 misha 60: #endif
61: #ifdef SQLITE_VERSION_NUMBER
62: # undef SQLITE_VERSION_NUMBER
1.1 misha 63: #endif
64:
65: /*
1.4 ! misha 66: ** CAPI3REF: Compile-Time Library Version Numbers {F10010}
1.2 misha 67: **
1.4 ! misha 68: ** The SQLITE_VERSION and SQLITE_VERSION_NUMBER #defines in
! 69: ** the sqlite3.h file specify the version of SQLite with which
! 70: ** that header file is associated.
! 71: **
! 72: ** The "version" of SQLite is a string of the form "X.Y.Z".
! 73: ** The phrase "alpha" or "beta" might be appended after the Z.
! 74: ** The X value is major version number always 3 in SQLite3.
! 75: ** The X value only changes when backwards compatibility is
! 76: ** broken and we intend to never break
! 77: ** backwards compatibility. The Y value is the minor version
! 78: ** number and only changes when
1.2 misha 79: ** there are major feature enhancements that are forwards compatible
1.4 ! misha 80: ** but not backwards compatible. The Z value is release number
! 81: ** and is incremented with
1.2 misha 82: ** each release but resets back to 0 when Y is incremented.
83: **
1.4 ! misha 84: ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
! 85: **
! 86: ** INVARIANTS:
! 87: **
! 88: ** {F10011} The SQLITE_VERSION #define in the sqlite3.h header file
! 89: ** evaluates to a string literal that is the SQLite version
! 90: ** with which the header file is associated.
1.2 misha 91: **
1.4 ! misha 92: ** {F10014} The SQLITE_VERSION_NUMBER #define resolves to an integer
! 93: ** with the value (X*1000000 + Y*1000 + Z) where X, Y, and
! 94: ** Z are the major version, minor version, and release number.
1.2 misha 95: */
1.4 ! misha 96: #define SQLITE_VERSION "3.5.7"
! 97: #define SQLITE_VERSION_NUMBER 3005007
1.2 misha 98:
99: /*
1.4 ! misha 100: ** CAPI3REF: Run-Time Library Version Numbers {F10020}
! 101: ** KEYWORDS: sqlite3_version
! 102: **
! 103: ** These features provide the same information as the [SQLITE_VERSION]
! 104: ** and [SQLITE_VERSION_NUMBER] #defines in the header, but are associated
! 105: ** with the library instead of the header file. Cautious programmers might
! 106: ** include a check in their application to verify that
! 107: ** sqlite3_libversion_number() always returns the value
! 108: ** [SQLITE_VERSION_NUMBER].
1.2 misha 109: **
1.4 ! misha 110: ** The sqlite3_libversion() function returns the same information as is
! 111: ** in the sqlite3_version[] string constant. The function is provided
! 112: ** for use in DLLs since DLL users usually do not have direct access to string
1.2 misha 113: ** constants within the DLL.
1.4 ! misha 114: **
! 115: ** INVARIANTS:
! 116: **
! 117: ** {F10021} The [sqlite3_libversion_number()] interface returns an integer
! 118: ** equal to [SQLITE_VERSION_NUMBER].
! 119: **
! 120: ** {F10022} The [sqlite3_version] string constant contains the text of the
! 121: ** [SQLITE_VERSION] string.
! 122: **
! 123: ** {F10023} The [sqlite3_libversion()] function returns
! 124: ** a pointer to the [sqlite3_version] string constant.
1.1 misha 125: */
1.2 misha 126: SQLITE_EXTERN const char sqlite3_version[];
1.1 misha 127: const char *sqlite3_libversion(void);
1.2 misha 128: int sqlite3_libversion_number(void);
1.1 misha 129:
130: /*
1.4 ! misha 131: ** CAPI3REF: Test To See If The Library Is Threadsafe {F10100}
1.2 misha 132: **
1.4 ! misha 133: ** SQLite can be compiled with or without mutexes. When
! 134: ** the SQLITE_THREADSAFE C preprocessor macro is true, mutexes
! 135: ** are enabled and SQLite is threadsafe. When that macro is false,
! 136: ** the mutexes are omitted. Without the mutexes, it is not safe
! 137: ** to use SQLite from more than one thread.
! 138: **
! 139: ** There is a measurable performance penalty for enabling mutexes.
! 140: ** So if speed is of utmost importance, it makes sense to disable
! 141: ** the mutexes. But for maximum safety, mutexes should be enabled.
! 142: ** The default behavior is for mutexes to be enabled.
! 143: **
! 144: ** This interface can be used by a program to make sure that the
! 145: ** version of SQLite that it is linking against was compiled with
! 146: ** the desired setting of the SQLITE_THREADSAFE macro.
! 147: **
! 148: ** INVARIANTS:
! 149: **
! 150: ** {F10101} The [sqlite3_threadsafe()] function returns nonzero if
! 151: ** SQLite was compiled with its mutexes enabled or zero
! 152: ** if SQLite was compiled with mutexes disabled.
1.2 misha 153: */
154: int sqlite3_threadsafe(void);
155:
156: /*
1.4 ! misha 157: ** CAPI3REF: Database Connection Handle {F12000}
! 158: ** KEYWORDS: {database connection}
1.2 misha 159: **
160: ** Each open SQLite database is represented by pointer to an instance of the
161: ** opaque structure named "sqlite3". It is useful to think of an sqlite3
162: ** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and
163: ** [sqlite3_open_v2()] interfaces are its constructors
164: ** and [sqlite3_close()] is its destructor. There are many other interfaces
165: ** (such as [sqlite3_prepare_v2()], [sqlite3_create_function()], and
166: ** [sqlite3_busy_timeout()] to name but three) that are methods on this
167: ** object.
1.1 misha 168: */
169: typedef struct sqlite3 sqlite3;
170:
171:
172: /*
1.4 ! misha 173: ** CAPI3REF: 64-Bit Integer Types {F10200}
! 174: ** KEYWORDS: sqlite_int64 sqlite_uint64
! 175: **
! 176: ** Because there is no cross-platform way to specify 64-bit integer types
! 177: ** SQLite includes typedefs for 64-bit signed and unsigned integers.
! 178: **
! 179: ** The sqlite3_int64 and sqlite3_uint64 are the preferred type
! 180: ** definitions. The sqlite_int64 and sqlite_uint64 types are
! 181: ** supported for backwards compatibility only.
! 182: **
! 183: ** INVARIANTS:
1.2 misha 184: **
1.4 ! misha 185: ** {F10201} The [sqlite_int64] and [sqlite3_int64] types specify a
! 186: ** 64-bit signed integer.
1.2 misha 187: **
1.4 ! misha 188: ** {F10202} The [sqlite_uint64] and [sqlite3_uint64] types specify
! 189: ** a 64-bit unsigned integer.
1.1 misha 190: */
1.2 misha 191: #ifdef SQLITE_INT64_TYPE
192: typedef SQLITE_INT64_TYPE sqlite_int64;
193: typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
194: #elif defined(_MSC_VER) || defined(__BORLANDC__)
1.1 misha 195: typedef __int64 sqlite_int64;
196: typedef unsigned __int64 sqlite_uint64;
197: #else
198: typedef long long int sqlite_int64;
199: typedef unsigned long long int sqlite_uint64;
200: #endif
1.2 misha 201: typedef sqlite_int64 sqlite3_int64;
202: typedef sqlite_uint64 sqlite3_uint64;
1.1 misha 203:
1.2 misha 204: /*
205: ** If compiling for a processor that lacks floating point support,
206: ** substitute integer for floating-point
207: */
208: #ifdef SQLITE_OMIT_FLOATING_POINT
209: # define double sqlite3_int64
210: #endif
1.1 misha 211:
212: /*
1.4 ! misha 213: ** CAPI3REF: Closing A Database Connection {F12010}
! 214: **
! 215: ** This routine is the destructor for the [sqlite3] object.
! 216: **
! 217: ** Applications should [sqlite3_finalize | finalize] all
! 218: ** [prepared statements] and
! 219: ** [sqlite3_blob_close | close] all [sqlite3_blob | BLOBs]
! 220: ** associated with the [sqlite3] object prior
! 221: ** to attempting to close the [sqlite3] object.
! 222: **
! 223: ** <todo>What happens to pending transactions? Are they
! 224: ** rolled back, or abandoned?</todo>
! 225: **
! 226: ** INVARIANTS:
1.1 misha 227: **
1.4 ! misha 228: ** {F12011} The [sqlite3_close()] interface destroys an [sqlite3] object
! 229: ** allocated by a prior call to [sqlite3_open()],
! 230: ** [sqlite3_open16()], or [sqlite3_open_v2()].
! 231: **
! 232: ** {F12012} The [sqlite3_close()] function releases all memory used by the
! 233: ** connection and closes all open files.
! 234: **
! 235: ** {F12013} If the database connection contains
! 236: ** [prepared statements] that have not been
! 237: ** finalized by [sqlite3_finalize()], then [sqlite3_close()]
! 238: ** returns [SQLITE_BUSY] and leaves the connection open.
! 239: **
! 240: ** {F12014} Giving sqlite3_close() a NULL pointer is a harmless no-op.
! 241: **
! 242: ** LIMITATIONS:
! 243: **
! 244: ** {U12015} The parameter to [sqlite3_close()] must be an [sqlite3] object
! 245: ** pointer previously obtained from [sqlite3_open()] or the
! 246: ** equivalent, or NULL.
! 247: **
! 248: ** {U12016} The parameter to [sqlite3_close()] must not have been previously
! 249: ** closed.
1.1 misha 250: */
251: int sqlite3_close(sqlite3 *);
252:
253: /*
254: ** The type for a callback function.
1.2 misha 255: ** This is legacy and deprecated. It is included for historical
256: ** compatibility and is not documented.
1.1 misha 257: */
258: typedef int (*sqlite3_callback)(void*,int,char**, char**);
259:
260: /*
1.4 ! misha 261: ** CAPI3REF: One-Step Query Execution Interface {F12100}
! 262: **
! 263: ** The sqlite3_exec() interface is a convenient way of running
! 264: ** one or more SQL statements without a lot of C code. The
! 265: ** SQL statements are passed in as the second parameter to
! 266: ** sqlite3_exec(). The statements are evaluated one by one
! 267: ** until either an error or an interrupt is encountered or
! 268: ** until they are all done. The 3rd parameter is an optional
! 269: ** callback that is invoked once for each row of any query results
! 270: ** produced by the SQL statements. The 5th parameter tells where
! 271: ** to write any error messages.
! 272: **
! 273: ** The sqlite3_exec() interface is implemented in terms of
! 274: ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
! 275: ** The sqlite3_exec() routine does nothing that cannot be done
! 276: ** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
! 277: ** The sqlite3_exec() is just a convenient wrapper.
! 278: **
! 279: ** INVARIANTS:
! 280: **
! 281: ** {F12101} The [sqlite3_exec()] interface evaluates zero or more UTF-8
! 282: ** encoded, semicolon-separated, SQL statements in the
! 283: ** zero-terminated string of its 2nd parameter within the
! 284: ** context of the [sqlite3] object given in the 1st parameter.
! 285: **
! 286: ** {F12104} The return value of [sqlite3_exec()] is SQLITE_OK if all
! 287: ** SQL statements run successfully.
! 288: **
! 289: ** {F12105} The return value of [sqlite3_exec()] is an appropriate
! 290: ** non-zero error code if any SQL statement fails.
! 291: **
! 292: ** {F12107} If one or more of the SQL statements handed to [sqlite3_exec()]
! 293: ** return results and the 3rd parameter is not NULL, then
! 294: ** the callback function specified by the 3rd parameter is
! 295: ** invoked once for each row of result.
! 296: **
! 297: ** {F12110} If the callback returns a non-zero value then [sqlite3_exec()]
! 298: ** will aborted the SQL statement it is currently evaluating,
! 299: ** skip all subsequent SQL statements, and return [SQLITE_ABORT].
! 300: ** <todo>What happens to *errmsg here? Does the result code for
! 301: ** sqlite3_errcode() get set?</todo>
! 302: **
! 303: ** {F12113} The [sqlite3_exec()] routine will pass its 4th parameter through
! 304: ** as the 1st parameter of the callback.
! 305: **
! 306: ** {F12116} The [sqlite3_exec()] routine sets the 2nd parameter of its
! 307: ** callback to be the number of columns in the current row of
! 308: ** result.
! 309: **
! 310: ** {F12119} The [sqlite3_exec()] routine sets the 3rd parameter of its
! 311: ** callback to be an array of pointers to strings holding the
! 312: ** values for each column in the current result set row as
! 313: ** obtained from [sqlite3_column_text()].
! 314: **
! 315: ** {F12122} The [sqlite3_exec()] routine sets the 4th parameter of its
! 316: ** callback to be an array of pointers to strings holding the
! 317: ** names of result columns as obtained from [sqlite3_column_name()].
! 318: **
! 319: ** {F12125} If the 3rd parameter to [sqlite3_exec()] is NULL then
! 320: ** [sqlite3_exec()] never invokes a callback. All query
! 321: ** results are silently discarded.
! 322: **
! 323: ** {F12128} If an error occurs while parsing or evaluating any of the SQL
! 324: ** statements handed to [sqlite3_exec()] then [sqlite3_exec()] will
! 325: ** return an [error code] other than [SQLITE_OK].
! 326: **
! 327: ** {F12131} If an error occurs while parsing or evaluating any of the SQL
! 328: ** handed to [sqlite3_exec()] and if the 5th parameter (errmsg)
! 329: ** to [sqlite3_exec()] is not NULL, then an error message is
! 330: ** allocated using the equivalent of [sqlite3_mprintf()] and
! 331: ** *errmsg is made to point to that message.
! 332: **
! 333: ** {F12134} The [sqlite3_exec()] routine does not change the value of
! 334: ** *errmsg if errmsg is NULL or if there are no errors.
! 335: **
! 336: ** {F12137} The [sqlite3_exec()] function sets the error code and message
! 337: ** accessible via [sqlite3_errcode()], [sqlite3_errmsg()], and
! 338: ** [sqlite3_errmsg16()].
1.2 misha 339: **
1.4 ! misha 340: ** LIMITATIONS:
1.1 misha 341: **
1.4 ! misha 342: ** {U12141} The first parameter to [sqlite3_exec()] must be an valid and open
! 343: ** [database connection].
! 344: **
! 345: ** {U12142} The database connection must not be closed while
! 346: ** [sqlite3_exec()] is running.
! 347: **
! 348: ** {U12143} The calling function is should use [sqlite3_free()] to free
! 349: ** the memory that *errmsg is left pointing at once the error
! 350: ** message is no longer needed.
! 351: **
! 352: ** {U12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()]
! 353: ** must remain unchanged while [sqlite3_exec()] is running.
1.1 misha 354: */
355: int sqlite3_exec(
1.2 misha 356: sqlite3*, /* An open database */
357: const char *sql, /* SQL to be evaluted */
358: int (*callback)(void*,int,char**,char**), /* Callback function */
359: void *, /* 1st argument to callback */
360: char **errmsg /* Error msg written here */
1.1 misha 361: );
362:
363: /*
1.4 ! misha 364: ** CAPI3REF: Result Codes {F10210}
! 365: ** KEYWORDS: SQLITE_OK {error code} {error codes}
1.2 misha 366: **
367: ** Many SQLite functions return an integer result code from the set shown
1.4 ! misha 368: ** here in order to indicates success or failure.
1.2 misha 369: **
370: ** See also: [SQLITE_IOERR_READ | extended result codes]
1.1 misha 371: */
372: #define SQLITE_OK 0 /* Successful result */
1.2 misha 373: /* beginning-of-error-codes */
1.1 misha 374: #define SQLITE_ERROR 1 /* SQL error or missing database */
1.4 ! misha 375: #define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */
1.1 misha 376: #define SQLITE_PERM 3 /* Access permission denied */
377: #define SQLITE_ABORT 4 /* Callback routine requested an abort */
378: #define SQLITE_BUSY 5 /* The database file is locked */
379: #define SQLITE_LOCKED 6 /* A table in the database is locked */
380: #define SQLITE_NOMEM 7 /* A malloc() failed */
381: #define SQLITE_READONLY 8 /* Attempt to write a readonly database */
382: #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
383: #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
384: #define SQLITE_CORRUPT 11 /* The database disk image is malformed */
1.2 misha 385: #define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */
1.1 misha 386: #define SQLITE_FULL 13 /* Insertion failed because database is full */
387: #define SQLITE_CANTOPEN 14 /* Unable to open the database file */
1.2 misha 388: #define SQLITE_PROTOCOL 15 /* NOT USED. Database lock protocol error */
1.1 misha 389: #define SQLITE_EMPTY 16 /* Database is empty */
390: #define SQLITE_SCHEMA 17 /* The database schema changed */
1.2 misha 391: #define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
392: #define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
1.1 misha 393: #define SQLITE_MISMATCH 20 /* Data type mismatch */
394: #define SQLITE_MISUSE 21 /* Library used incorrectly */
395: #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
396: #define SQLITE_AUTH 23 /* Authorization denied */
397: #define SQLITE_FORMAT 24 /* Auxiliary database format error */
398: #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
399: #define SQLITE_NOTADB 26 /* File opened that is not a database file */
400: #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
401: #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
1.2 misha 402: /* end-of-error-codes */
1.1 misha 403:
404: /*
1.4 ! misha 405: ** CAPI3REF: Extended Result Codes {F10220}
! 406: ** KEYWORDS: {extended error code} {extended error codes}
! 407: ** KEYWORDS: {extended result codes}
1.1 misha 408: **
1.2 misha 409: ** In its default configuration, SQLite API routines return one of 26 integer
1.4 ! misha 410: ** [SQLITE_OK | result codes]. However, experience has shown that
1.2 misha 411: ** many of these result codes are too course-grained. They do not provide as
1.4 ! misha 412: ** much information about problems as programmers might like. In an effort to
1.2 misha 413: ** address this, newer versions of SQLite (version 3.3.8 and later) include
414: ** support for additional result codes that provide more detailed information
1.4 ! misha 415: ** about errors. The extended result codes are enabled or disabled
! 416: ** for each database connection using the [sqlite3_extended_result_codes()]
! 417: ** API.
1.2 misha 418: **
1.4 ! misha 419: ** Some of the available extended result codes are listed here.
! 420: ** One may expect the number of extended result codes will be expand
1.2 misha 421: ** over time. Software that uses extended result codes should expect
422: ** to see new result codes in future releases of SQLite.
423: **
424: ** The SQLITE_OK result code will never be extended. It will always
425: ** be exactly zero.
1.4 ! misha 426: **
! 427: ** INVARIANTS:
! 428: **
! 429: ** {F10223} The symbolic name for an extended result code always contains
! 430: ** a related primary result code as a prefix.
! 431: **
! 432: ** {F10224} Primary result code names contain a single "_" character.
! 433: **
! 434: ** {F10225} Extended result code names contain two or more "_" characters.
! 435: **
! 436: ** {F10226} The numeric value of an extended result code contains the
! 437: ** numeric value of its corresponding primary result code in
! 438: ** its least significant 8 bits.
1.2 misha 439: */
440: #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))
441: #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))
442: #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8))
443: #define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8))
444: #define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8))
445: #define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8))
446: #define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8))
447: #define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8))
448: #define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8))
449: #define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8))
450: #define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8))
451: #define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8))
452:
453: /*
1.4 ! misha 454: ** CAPI3REF: Flags For File Open Operations {F10230}
1.2 misha 455: **
1.4 ! misha 456: ** These bit values are intended for use in the
! 457: ** 3rd parameter to the [sqlite3_open_v2()] interface and
! 458: ** in the 4th parameter to the xOpen method of the
1.2 misha 459: ** [sqlite3_vfs] object.
460: */
461: #define SQLITE_OPEN_READONLY 0x00000001
462: #define SQLITE_OPEN_READWRITE 0x00000002
463: #define SQLITE_OPEN_CREATE 0x00000004
464: #define SQLITE_OPEN_DELETEONCLOSE 0x00000008
465: #define SQLITE_OPEN_EXCLUSIVE 0x00000010
466: #define SQLITE_OPEN_MAIN_DB 0x00000100
467: #define SQLITE_OPEN_TEMP_DB 0x00000200
468: #define SQLITE_OPEN_TRANSIENT_DB 0x00000400
469: #define SQLITE_OPEN_MAIN_JOURNAL 0x00000800
470: #define SQLITE_OPEN_TEMP_JOURNAL 0x00001000
471: #define SQLITE_OPEN_SUBJOURNAL 0x00002000
472: #define SQLITE_OPEN_MASTER_JOURNAL 0x00004000
473:
474: /*
1.4 ! misha 475: ** CAPI3REF: Device Characteristics {F10240}
1.2 misha 476: **
477: ** The xDeviceCapabilities method of the [sqlite3_io_methods]
1.4 ! misha 478: ** object returns an integer which is a vector of the these
1.2 misha 479: ** bit values expressing I/O characteristics of the mass storage
480: ** device that holds the file that the [sqlite3_io_methods]
481: ** refers to.
482: **
483: ** The SQLITE_IOCAP_ATOMIC property means that all writes of
484: ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
485: ** mean that writes of blocks that are nnn bytes in size and
486: ** are aligned to an address which is an integer multiple of
487: ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
488: ** that when data is appended to a file, the data is appended
489: ** first then the size of the file is extended, never the other
490: ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
491: ** information is written to disk in the same order as calls
492: ** to xWrite().
493: */
494: #define SQLITE_IOCAP_ATOMIC 0x00000001
495: #define SQLITE_IOCAP_ATOMIC512 0x00000002
496: #define SQLITE_IOCAP_ATOMIC1K 0x00000004
497: #define SQLITE_IOCAP_ATOMIC2K 0x00000008
498: #define SQLITE_IOCAP_ATOMIC4K 0x00000010
499: #define SQLITE_IOCAP_ATOMIC8K 0x00000020
500: #define SQLITE_IOCAP_ATOMIC16K 0x00000040
501: #define SQLITE_IOCAP_ATOMIC32K 0x00000080
502: #define SQLITE_IOCAP_ATOMIC64K 0x00000100
503: #define SQLITE_IOCAP_SAFE_APPEND 0x00000200
504: #define SQLITE_IOCAP_SEQUENTIAL 0x00000400
505:
506: /*
1.4 ! misha 507: ** CAPI3REF: File Locking Levels {F10250}
1.2 misha 508: **
1.4 ! misha 509: ** SQLite uses one of these integer values as the second
1.2 misha 510: ** argument to calls it makes to the xLock() and xUnlock() methods
511: ** of an [sqlite3_io_methods] object.
512: */
513: #define SQLITE_LOCK_NONE 0
514: #define SQLITE_LOCK_SHARED 1
515: #define SQLITE_LOCK_RESERVED 2
516: #define SQLITE_LOCK_PENDING 3
517: #define SQLITE_LOCK_EXCLUSIVE 4
518:
519: /*
1.4 ! misha 520: ** CAPI3REF: Synchronization Type Flags {F10260}
1.2 misha 521: **
1.4 ! misha 522: ** When SQLite invokes the xSync() method of an
! 523: ** [sqlite3_io_methods] object it uses a combination of
! 524: ** these integer values as the second argument.
1.2 misha 525: **
526: ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
527: ** sync operation only needs to flush data to mass storage. Inode
1.4 ! misha 528: ** information need not be flushed. The SQLITE_SYNC_NORMAL flag means
! 529: ** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means
1.2 misha 530: ** to use Mac OS-X style fullsync instead of fsync().
531: */
532: #define SQLITE_SYNC_NORMAL 0x00002
533: #define SQLITE_SYNC_FULL 0x00003
534: #define SQLITE_SYNC_DATAONLY 0x00010
535:
536:
537: /*
1.4 ! misha 538: ** CAPI3REF: OS Interface Open File Handle {F11110}
1.2 misha 539: **
540: ** An [sqlite3_file] object represents an open file in the OS
541: ** interface layer. Individual OS interface implementations will
542: ** want to subclass this object by appending additional fields
543: ** for their own use. The pMethods entry is a pointer to an
544: ** [sqlite3_io_methods] object that defines methods for performing
545: ** I/O operations on the open file.
546: */
547: typedef struct sqlite3_file sqlite3_file;
548: struct sqlite3_file {
549: const struct sqlite3_io_methods *pMethods; /* Methods for an open file */
550: };
551:
552: /*
1.4 ! misha 553: ** CAPI3REF: OS Interface File Virtual Methods Object {F11120}
1.2 misha 554: **
555: ** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to
1.4 ! misha 556: ** an instance of this object. This object defines the
1.2 misha 557: ** methods used to perform various operations against the open file.
558: **
559: ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
560: ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
561: * The second choice is an
562: ** OS-X style fullsync. The SQLITE_SYNC_DATA flag may be ORed in to
563: ** indicate that only the data of the file and not its inode needs to be
564: ** synced.
565: **
566: ** The integer values to xLock() and xUnlock() are one of
567: ** <ul>
568: ** <li> [SQLITE_LOCK_NONE],
569: ** <li> [SQLITE_LOCK_SHARED],
570: ** <li> [SQLITE_LOCK_RESERVED],
571: ** <li> [SQLITE_LOCK_PENDING], or
572: ** <li> [SQLITE_LOCK_EXCLUSIVE].
573: ** </ul>
574: ** xLock() increases the lock. xUnlock() decreases the lock.
575: ** The xCheckReservedLock() method looks
576: ** to see if any database connection, either in this
577: ** process or in some other process, is holding an RESERVED,
578: ** PENDING, or EXCLUSIVE lock on the file. It returns true
579: ** if such a lock exists and false if not.
580: **
581: ** The xFileControl() method is a generic interface that allows custom
582: ** VFS implementations to directly control an open file using the
583: ** [sqlite3_file_control()] interface. The second "op" argument
584: ** is an integer opcode. The third
585: ** argument is a generic pointer which is intended to be a pointer
586: ** to a structure that may contain arguments or space in which to
587: ** write return values. Potential uses for xFileControl() might be
588: ** functions to enable blocking locks with timeouts, to change the
589: ** locking strategy (for example to use dot-file locks), to inquire
590: ** about the status of a lock, or to break stale locks. The SQLite
591: ** core reserves opcodes less than 100 for its own use.
592: ** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
593: ** Applications that define a custom xFileControl method should use opcodes
594: ** greater than 100 to avoid conflicts.
595: **
596: ** The xSectorSize() method returns the sector size of the
597: ** device that underlies the file. The sector size is the
598: ** minimum write that can be performed without disturbing
599: ** other bytes in the file. The xDeviceCharacteristics()
600: ** method returns a bit vector describing behaviors of the
601: ** underlying device:
602: **
603: ** <ul>
604: ** <li> [SQLITE_IOCAP_ATOMIC]
605: ** <li> [SQLITE_IOCAP_ATOMIC512]
606: ** <li> [SQLITE_IOCAP_ATOMIC1K]
607: ** <li> [SQLITE_IOCAP_ATOMIC2K]
608: ** <li> [SQLITE_IOCAP_ATOMIC4K]
609: ** <li> [SQLITE_IOCAP_ATOMIC8K]
610: ** <li> [SQLITE_IOCAP_ATOMIC16K]
611: ** <li> [SQLITE_IOCAP_ATOMIC32K]
612: ** <li> [SQLITE_IOCAP_ATOMIC64K]
613: ** <li> [SQLITE_IOCAP_SAFE_APPEND]
614: ** <li> [SQLITE_IOCAP_SEQUENTIAL]
615: ** </ul>
616: **
617: ** The SQLITE_IOCAP_ATOMIC property means that all writes of
618: ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
619: ** mean that writes of blocks that are nnn bytes in size and
620: ** are aligned to an address which is an integer multiple of
621: ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
622: ** that when data is appended to a file, the data is appended
623: ** first then the size of the file is extended, never the other
624: ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
625: ** information is written to disk in the same order as calls
626: ** to xWrite().
627: */
628: typedef struct sqlite3_io_methods sqlite3_io_methods;
629: struct sqlite3_io_methods {
630: int iVersion;
631: int (*xClose)(sqlite3_file*);
632: int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
633: int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
634: int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
635: int (*xSync)(sqlite3_file*, int flags);
636: int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
637: int (*xLock)(sqlite3_file*, int);
638: int (*xUnlock)(sqlite3_file*, int);
639: int (*xCheckReservedLock)(sqlite3_file*);
640: int (*xFileControl)(sqlite3_file*, int op, void *pArg);
641: int (*xSectorSize)(sqlite3_file*);
642: int (*xDeviceCharacteristics)(sqlite3_file*);
643: /* Additional methods may be added in future releases */
644: };
645:
646: /*
1.4 ! misha 647: ** CAPI3REF: Standard File Control Opcodes {F11310}
1.2 misha 648: **
649: ** These integer constants are opcodes for the xFileControl method
650: ** of the [sqlite3_io_methods] object and to the [sqlite3_file_control()]
651: ** interface.
652: **
653: ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
1.4 ! misha 654: ** opcode causes the xFileControl method to write the current state of
1.2 misha 655: ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
656: ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
1.4 ! misha 657: ** into an integer that the pArg argument points to. This capability
1.2 misha 658: ** is used during testing and only needs to be supported when SQLITE_TEST
659: ** is defined.
660: */
661: #define SQLITE_FCNTL_LOCKSTATE 1
662:
663: /*
1.4 ! misha 664: ** CAPI3REF: Mutex Handle {F17110}
1.2 misha 665: **
666: ** The mutex module within SQLite defines [sqlite3_mutex] to be an
667: ** abstract type for a mutex object. The SQLite core never looks
668: ** at the internal representation of an [sqlite3_mutex]. It only
669: ** deals with pointers to the [sqlite3_mutex] object.
670: **
671: ** Mutexes are created using [sqlite3_mutex_alloc()].
672: */
673: typedef struct sqlite3_mutex sqlite3_mutex;
674:
675: /*
1.4 ! misha 676: ** CAPI3REF: OS Interface Object {F11140}
1.2 misha 677: **
678: ** An instance of this object defines the interface between the
679: ** SQLite core and the underlying operating system. The "vfs"
680: ** in the name of the object stands for "virtual file system".
681: **
682: ** The iVersion field is initially 1 but may be larger for future
683: ** versions of SQLite. Additional fields may be appended to this
684: ** object when the iVersion value is increased.
685: **
686: ** The szOsFile field is the size of the subclassed [sqlite3_file]
687: ** structure used by this VFS. mxPathname is the maximum length of
688: ** a pathname in this VFS.
689: **
1.4 ! misha 690: ** Registered sqlite3_vfs objects are kept on a linked list formed by
1.2 misha 691: ** the pNext pointer. The [sqlite3_vfs_register()]
692: ** and [sqlite3_vfs_unregister()] interfaces manage this list
693: ** in a thread-safe way. The [sqlite3_vfs_find()] interface
694: ** searches the list.
695: **
1.4 ! misha 696: ** The pNext field is the only field in the sqlite3_vfs
1.2 misha 697: ** structure that SQLite will ever modify. SQLite will only access
698: ** or modify this field while holding a particular static mutex.
699: ** The application should never modify anything within the sqlite3_vfs
700: ** object once the object has been registered.
701: **
702: ** The zName field holds the name of the VFS module. The name must
703: ** be unique across all VFS modules.
704: **
1.4 ! misha 705: ** {F11141} SQLite will guarantee that the zFilename string passed to
1.2 misha 706: ** xOpen() is a full pathname as generated by xFullPathname() and
707: ** that the string will be valid and unchanged until xClose() is
1.4 ! misha 708: ** called. {END} So the [sqlite3_file] can store a pointer to the
1.2 misha 709: ** filename if it needs to remember the filename for some reason.
710: **
1.4 ! misha 711: ** {F11142} The flags argument to xOpen() includes all bits set in
! 712: ** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()]
! 713: ** or [sqlite3_open16()] is used, then flags includes at least
! 714: ** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. {END}
1.2 misha 715: ** If xOpen() opens a file read-only then it sets *pOutFlags to
716: ** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be
717: ** set.
718: **
1.4 ! misha 719: ** {F11143} SQLite will also add one of the following flags to the xOpen()
1.2 misha 720: ** call, depending on the object being opened:
721: **
722: ** <ul>
723: ** <li> [SQLITE_OPEN_MAIN_DB]
724: ** <li> [SQLITE_OPEN_MAIN_JOURNAL]
725: ** <li> [SQLITE_OPEN_TEMP_DB]
726: ** <li> [SQLITE_OPEN_TEMP_JOURNAL]
727: ** <li> [SQLITE_OPEN_TRANSIENT_DB]
728: ** <li> [SQLITE_OPEN_SUBJOURNAL]
729: ** <li> [SQLITE_OPEN_MASTER_JOURNAL]
1.4 ! misha 730: ** </ul> {END}
1.2 misha 731: **
732: ** The file I/O implementation can use the object type flags to
733: ** changes the way it deals with files. For example, an application
1.4 ! misha 734: ** that does not care about crash recovery or rollback might make
! 735: ** the open of a journal file a no-op. Writes to this journal would
! 736: ** also be no-ops, and any attempt to read the journal would return
! 737: ** SQLITE_IOERR. Or the implementation might recognize that a database
! 738: ** file will be doing page-aligned sector reads and writes in a random
! 739: ** order and set up its I/O subsystem accordingly.
1.2 misha 740: **
741: ** SQLite might also add one of the following flags to the xOpen
742: ** method:
743: **
744: ** <ul>
745: ** <li> [SQLITE_OPEN_DELETEONCLOSE]
746: ** <li> [SQLITE_OPEN_EXCLUSIVE]
747: ** </ul>
748: **
1.4 ! misha 749: ** {F11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
! 750: ** deleted when it is closed. {F11146} The [SQLITE_OPEN_DELETEONCLOSE]
! 751: ** will be set for TEMP databases, journals and for subjournals.
! 752: ** {F11147} The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
1.2 misha 753: ** for exclusive access. This flag is set for all files except
1.4 ! misha 754: ** for the main database file. {END}
1.2 misha 755: **
1.4 ! misha 756: ** {F11148} At least szOsFile bytes of memory are allocated by SQLite
! 757: ** to hold the [sqlite3_file] structure passed as the third
! 758: ** argument to xOpen. {END} The xOpen method does not have to
! 759: ** allocate the structure; it should just fill it in.
1.2 misha 760: **
1.4 ! misha 761: ** {F11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
1.2 misha 762: ** to test for the existance of a file,
763: ** or [SQLITE_ACCESS_READWRITE] to test to see
764: ** if a file is readable and writable, or [SQLITE_ACCESS_READ]
1.4 ! misha 765: ** to test to see if a file is at least readable. {END} The file can be a
1.2 misha 766: ** directory.
767: **
1.4 ! misha 768: ** {F11150} SQLite will always allocate at least mxPathname+1 bytes for
! 769: ** the output buffers for xGetTempname and xFullPathname. {F11151} The exact
1.2 misha 770: ** size of the output buffer is also passed as a parameter to both
1.4 ! misha 771: ** methods. {END} If the output buffer is not large enough, SQLITE_CANTOPEN
1.2 misha 772: ** should be returned. As this is handled as a fatal error by SQLite,
1.4 ! misha 773: ** vfs implementations should endeavor to prevent this by setting
1.2 misha 774: ** mxPathname to a sufficiently large value.
775: **
776: ** The xRandomness(), xSleep(), and xCurrentTime() interfaces
777: ** are not strictly a part of the filesystem, but they are
778: ** included in the VFS structure for completeness.
779: ** The xRandomness() function attempts to return nBytes bytes
780: ** of good-quality randomness into zOut. The return value is
781: ** the actual number of bytes of randomness obtained. The
1.4 ! misha 782: ** xSleep() method causes the calling thread to sleep for at
1.2 misha 783: ** least the number of microseconds given. The xCurrentTime()
784: ** method returns a Julian Day Number for the current date and
785: ** time.
786: */
787: typedef struct sqlite3_vfs sqlite3_vfs;
788: struct sqlite3_vfs {
789: int iVersion; /* Structure version number */
790: int szOsFile; /* Size of subclassed sqlite3_file */
791: int mxPathname; /* Maximum file pathname length */
792: sqlite3_vfs *pNext; /* Next registered VFS */
793: const char *zName; /* Name of this virtual file system */
794: void *pAppData; /* Pointer to application-specific data */
795: int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
796: int flags, int *pOutFlags);
797: int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
798: int (*xAccess)(sqlite3_vfs*, const char *zName, int flags);
799: int (*xGetTempname)(sqlite3_vfs*, int nOut, char *zOut);
800: int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
801: void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
802: void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
803: void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol);
804: void (*xDlClose)(sqlite3_vfs*, void*);
805: int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
806: int (*xSleep)(sqlite3_vfs*, int microseconds);
807: int (*xCurrentTime)(sqlite3_vfs*, double*);
808: /* New fields may be appended in figure versions. The iVersion
809: ** value will increment whenever this happens. */
810: };
811:
812: /*
1.4 ! misha 813: ** CAPI3REF: Flags for the xAccess VFS method {F11190}
1.2 misha 814: **
1.4 ! misha 815: ** {F11191} These integer constants can be used as the third parameter to
! 816: ** the xAccess method of an [sqlite3_vfs] object. {END} They determine
! 817: ** what kind of permissions the xAccess method is
! 818: ** looking for. {F11192} With SQLITE_ACCESS_EXISTS, the xAccess method
! 819: ** simply checks to see if the file exists. {F11193} With
! 820: ** SQLITE_ACCESS_READWRITE, the xAccess method checks to see
! 821: ** if the file is both readable and writable. {F11194} With
! 822: ** SQLITE_ACCESS_READ the xAccess method
1.2 misha 823: ** checks to see if the file is readable.
824: */
825: #define SQLITE_ACCESS_EXISTS 0
826: #define SQLITE_ACCESS_READWRITE 1
827: #define SQLITE_ACCESS_READ 2
828:
829: /*
1.4 ! misha 830: ** CAPI3REF: Enable Or Disable Extended Result Codes {F12200}
1.2 misha 831: **
1.4 ! misha 832: ** The sqlite3_extended_result_codes() routine enables or disables the
! 833: ** [SQLITE_IOERR_READ | extended result codes] feature of SQLite.
! 834: ** The extended result codes are disabled by default for historical
! 835: ** compatibility.
! 836: **
! 837: ** INVARIANTS:
! 838: **
! 839: ** {F12201} Each new [database connection] has the
! 840: ** [extended result codes] feature
! 841: ** disabled by default.
! 842: **
! 843: ** {F12202} The [sqlite3_extended_result_codes(D,F)] interface will enable
! 844: ** [extended result codes] for the
! 845: ** [database connection] D if the F parameter
! 846: ** is true, or disable them if F is false.
1.2 misha 847: */
848: int sqlite3_extended_result_codes(sqlite3*, int onoff);
849:
850: /*
1.4 ! misha 851: ** CAPI3REF: Last Insert Rowid {F12220}
1.2 misha 852: **
1.4 ! misha 853: ** Each entry in an SQLite table has a unique 64-bit signed
! 854: ** integer key called the "rowid". The rowid is always available
! 855: ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
! 856: ** names are not also used by explicitly declared columns. If
! 857: ** the table has a column of type INTEGER PRIMARY KEY then that column
! 858: ** is another alias for the rowid.
! 859: **
! 860: ** This routine returns the rowid of the most recent
! 861: ** successful INSERT into the database from the database connection
! 862: ** shown in the first argument. If no successful inserts
! 863: ** have ever occurred on this database connection, zero is returned.
1.2 misha 864: **
865: ** If an INSERT occurs within a trigger, then the rowid of the
866: ** inserted row is returned by this routine as long as the trigger
867: ** is running. But once the trigger terminates, the value returned
868: ** by this routine reverts to the last value inserted before the
869: ** trigger fired.
870: **
1.3 misha 871: ** An INSERT that fails due to a constraint violation is not a
872: ** successful insert and does not change the value returned by this
873: ** routine. Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
874: ** and INSERT OR ABORT make no changes to the return value of this
875: ** routine when their insertion fails. When INSERT OR REPLACE
876: ** encounters a constraint violation, it does not fail. The
877: ** INSERT continues to completion after deleting rows that caused
878: ** the constraint problem so INSERT OR REPLACE will always change
1.4 ! misha 879: ** the return value of this interface.
1.3 misha 880: **
1.4 ! misha 881: ** For the purposes of this routine, an insert is considered to
! 882: ** be successful even if it is subsequently rolled back.
! 883: **
! 884: ** INVARIANTS:
! 885: **
! 886: ** {F12221} The [sqlite3_last_insert_rowid()] function returns the
! 887: ** rowid of the most recent successful insert done
! 888: ** on the same database connection and within the same
! 889: ** trigger context, or zero if there have
! 890: ** been no qualifying inserts on that connection.
! 891: **
! 892: ** {F12223} The [sqlite3_last_insert_rowid()] function returns
! 893: ** same value when called from the same trigger context
! 894: ** immediately before and after a ROLLBACK.
! 895: **
! 896: ** LIMITATIONS:
! 897: **
! 898: ** {U12232} If a separate thread does a new insert on the same
! 899: ** database connection while the [sqlite3_last_insert_rowid()]
! 900: ** function is running and thus changes the last insert rowid,
! 901: ** then the value returned by [sqlite3_last_insert_rowid()] is
! 902: ** unpredictable and might not equal either the old or the new
! 903: ** last insert rowid.
1.1 misha 904: */
1.2 misha 905: sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
1.1 misha 906:
907: /*
1.4 ! misha 908: ** CAPI3REF: Count The Number Of Rows Modified {F12240}
1.2 misha 909: **
1.1 misha 910: ** This function returns the number of database rows that were changed
1.4 ! misha 911: ** or inserted or deleted by the most recently completed SQL statement
! 912: ** on the connection specified by the first parameter. Only
1.2 misha 913: ** changes that are directly specified by the INSERT, UPDATE, or
914: ** DELETE statement are counted. Auxiliary changes caused by
1.4 ! misha 915: ** triggers are not counted. Use the [sqlite3_total_changes()] function
1.2 misha 916: ** to find the total number of changes including changes caused by triggers.
917: **
1.4 ! misha 918: ** A "row change" is a change to a single row of a single table
! 919: ** caused by an INSERT, DELETE, or UPDATE statement. Rows that
! 920: ** are changed as side effects of REPLACE constraint resolution,
! 921: ** rollback, ABORT processing, DROP TABLE, or by any other
! 922: ** mechanisms do not count as direct row changes.
! 923: **
! 924: ** A "trigger context" is a scope of execution that begins and
! 925: ** ends with the script of a trigger. Most SQL statements are
! 926: ** evaluated outside of any trigger. This is the "top level"
! 927: ** trigger context. If a trigger fires from the top level, a
! 928: ** new trigger context is entered for the duration of that one
! 929: ** trigger. Subtriggers create subcontexts for their duration.
! 930: **
! 931: ** Calling [sqlite3_exec()] or [sqlite3_step()] recursively does
! 932: ** not create a new trigger context.
! 933: **
! 934: ** This function returns the number of direct row changes in the
! 935: ** most recent INSERT, UPDATE, or DELETE statement within the same
! 936: ** trigger context.
! 937: **
! 938: ** So when called from the top level, this function returns the
! 939: ** number of changes in the most recent INSERT, UPDATE, or DELETE
! 940: ** that also occurred at the top level.
! 941: ** Within the body of a trigger, the sqlite3_changes() interface
! 942: ** can be called to find the number of
1.2 misha 943: ** changes in the most recently completed INSERT, UPDATE, or DELETE
1.4 ! misha 944: ** statement within the body of the same trigger.
! 945: ** However, the number returned does not include in changes
! 946: ** caused by subtriggers since they have their own context.
! 947: **
! 948: ** SQLite implements the command "DELETE FROM table" without
! 949: ** a WHERE clause by dropping and recreating the table. (This is much
! 950: ** faster than going through and deleting individual elements from the
! 951: ** table.) Because of this optimization, the deletions in
! 952: ** "DELETE FROM table" are not row changes and will not be counted
! 953: ** by the sqlite3_changes() or [sqlite3_total_changes()] functions.
! 954: ** To get an accurate count of the number of rows deleted, use
! 955: ** "DELETE FROM table WHERE 1" instead.
1.1 misha 956: **
1.4 ! misha 957: ** INVARIANTS:
1.1 misha 958: **
1.4 ! misha 959: ** {F12241} The [sqlite3_changes()] function returns the number of
! 960: ** row changes caused by the most recent INSERT, UPDATE,
! 961: ** or DELETE statement on the same database connection and
! 962: ** within the same trigger context, or zero if there have
! 963: ** not been any qualifying row changes.
! 964: **
! 965: ** LIMITATIONS:
! 966: **
! 967: ** {U12252} If a separate thread makes changes on the same database connection
! 968: ** while [sqlite3_changes()] is running then the value returned
! 969: ** is unpredictable and unmeaningful.
1.1 misha 970: */
971: int sqlite3_changes(sqlite3*);
972:
973: /*
1.4 ! misha 974: ** CAPI3REF: Total Number Of Rows Modified {F12260}
1.2 misha 975: ***
1.4 ! misha 976: ** This function returns the number of row changes caused
! 977: ** by INSERT, UPDATE or DELETE statements since the database handle
! 978: ** was opened. The count includes all changes from all trigger
! 979: ** contexts. But the count does not include changes used to
! 980: ** implement REPLACE constraints, do rollbacks or ABORT processing,
! 981: ** or DROP table processing.
! 982: ** The changes
! 983: ** are counted as soon as the statement that makes them is completed
! 984: ** (when the statement handle is passed to [sqlite3_reset()] or
! 985: ** [sqlite3_finalize()]).
! 986: **
! 987: ** SQLite implements the command "DELETE FROM table" without
! 988: ** a WHERE clause by dropping and recreating the table. (This is much
! 989: ** faster than going
! 990: ** through and deleting individual elements from the table.) Because of
1.1 misha 991: ** this optimization, the change count for "DELETE FROM table" will be
992: ** zero regardless of the number of elements that were originally in the
993: ** table. To get an accurate count of the number of rows deleted, use
994: ** "DELETE FROM table WHERE 1" instead.
1.2 misha 995: **
1.4 ! misha 996: ** See also the [sqlite3_changes()] interface.
! 997: **
! 998: ** INVARIANTS:
! 999: **
! 1000: ** {F12261} The [sqlite3_total_changes()] returns the total number
! 1001: ** of row changes caused by INSERT, UPDATE, and/or DELETE
! 1002: ** statements on the same [database connection], in any
! 1003: ** trigger context, since the database connection was
! 1004: ** created.
! 1005: **
! 1006: ** LIMITATIONS:
! 1007: **
! 1008: ** {U12264} If a separate thread makes changes on the same database connection
! 1009: ** while [sqlite3_total_changes()] is running then the value
! 1010: ** returned is unpredictable and unmeaningful.
1.1 misha 1011: */
1012: int sqlite3_total_changes(sqlite3*);
1013:
1.2 misha 1014: /*
1.4 ! misha 1015: ** CAPI3REF: Interrupt A Long-Running Query {F12270}
1.2 misha 1016: **
1017: ** This function causes any pending database operation to abort and
1.4 ! misha 1018: ** return at its earliest opportunity. This routine is typically
1.1 misha 1019: ** called in response to a user action such as pressing "Cancel"
1020: ** or Ctrl-C where the user wants a long query operation to halt
1021: ** immediately.
1.2 misha 1022: **
1023: ** It is safe to call this routine from a thread different from the
1024: ** thread that is currently running the database operation. But it
1025: ** is not safe to call this routine with a database connection that
1026: ** is closed or might close before sqlite3_interrupt() returns.
1027: **
1.4 ! misha 1028: ** If an SQL is very nearly finished at the time when sqlite3_interrupt()
! 1029: ** is called, then it might not have an opportunity to be interrupted.
! 1030: ** It might continue to completion.
! 1031: ** An SQL operation that is interrupted will return
! 1032: ** [SQLITE_INTERRUPT]. If the interrupted SQL operation is an
! 1033: ** INSERT, UPDATE, or DELETE that is inside an explicit transaction,
! 1034: ** then the entire transaction will be rolled back automatically.
! 1035: ** A call to sqlite3_interrupt() has no effect on SQL statements
! 1036: ** that are started after sqlite3_interrupt() returns.
! 1037: **
! 1038: ** INVARIANTS:
! 1039: **
! 1040: ** {F12271} The [sqlite3_interrupt()] interface will force all running
! 1041: ** SQL statements associated with the same database connection
! 1042: ** to halt after processing at most one additional row of
! 1043: ** data.
! 1044: **
! 1045: ** {F12272} Any SQL statement that is interrupted by [sqlite3_interrupt()]
! 1046: ** will return [SQLITE_INTERRUPT].
! 1047: **
! 1048: ** LIMITATIONS:
! 1049: **
! 1050: ** {U12279} If the database connection closes while [sqlite3_interrupt()]
! 1051: ** is running then bad things will likely happen.
1.1 misha 1052: */
1053: void sqlite3_interrupt(sqlite3*);
1054:
1.2 misha 1055: /*
1.4 ! misha 1056: ** CAPI3REF: Determine If An SQL Statement Is Complete {F10510}
! 1057: **
! 1058: ** These routines are useful for command-line input to determine if the
! 1059: ** currently entered text seems to form complete a SQL statement or
! 1060: ** if additional input is needed before sending the text into
! 1061: ** SQLite for parsing. These routines return true if the input string
! 1062: ** appears to be a complete SQL statement. A statement is judged to be
! 1063: ** complete if it ends with a semicolon token and is not a fragment of a
! 1064: ** CREATE TRIGGER statement. Semicolons that are embedded within
! 1065: ** string literals or quoted identifier names or comments are not
! 1066: ** independent tokens (they are part of the token in which they are
! 1067: ** embedded) and thus do not count as a statement terminator.
! 1068: **
! 1069: ** These routines do not parse the SQL and
! 1070: ** so will not detect syntactically incorrect SQL.
! 1071: **
! 1072: ** INVARIANTS:
! 1073: **
! 1074: ** {F10511} The sqlite3_complete() and sqlite3_complete16() functions
! 1075: ** return true (non-zero) if and only if the last
! 1076: ** non-whitespace token in their input is a semicolon that
! 1077: ** is not in between the BEGIN and END of a CREATE TRIGGER
! 1078: ** statement.
! 1079: **
! 1080: ** LIMITATIONS:
1.2 misha 1081: **
1.4 ! misha 1082: ** {U10512} The input to sqlite3_complete() must be a zero-terminated
! 1083: ** UTF-8 string.
1.1 misha 1084: **
1.4 ! misha 1085: ** {U10513} The input to sqlite3_complete16() must be a zero-terminated
! 1086: ** UTF-16 string in native byte order.
1.1 misha 1087: */
1088: int sqlite3_complete(const char *sql);
1089: int sqlite3_complete16(const void *sql);
1090:
1091: /*
1.4 ! misha 1092: ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {F12310}
1.2 misha 1093: **
1.4 ! misha 1094: ** This routine identifies a callback function that might be
! 1095: ** invoked whenever an attempt is made to open a database table
1.2 misha 1096: ** that another thread or process has locked.
1097: ** If the busy callback is NULL, then [SQLITE_BUSY]
1.4 ! misha 1098: ** or [SQLITE_IOERR_BLOCKED]
1.2 misha 1099: ** is returned immediately upon encountering the lock.
1100: ** If the busy callback is not NULL, then the
1101: ** callback will be invoked with two arguments. The
1102: ** first argument to the handler is a copy of the void* pointer which
1103: ** is the third argument to this routine. The second argument to
1104: ** the handler is the number of times that the busy handler has
1.4 ! misha 1105: ** been invoked for this locking event. If the
1.2 misha 1106: ** busy callback returns 0, then no additional attempts are made to
1107: ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
1.4 ! misha 1108: ** If the callback returns non-zero, then another attempt
! 1109: ** is made to open the database for reading and the cycle repeats.
1.2 misha 1110: **
1111: ** The presence of a busy handler does not guarantee that
1112: ** it will be invoked when there is lock contention.
1113: ** If SQLite determines that invoking the busy handler could result in
1.4 ! misha 1114: ** a deadlock, it will go ahead and return [SQLITE_BUSY] or
! 1115: ** [SQLITE_IOERR_BLOCKED] instead of invoking the
! 1116: ** busy handler.
1.2 misha 1117: ** Consider a scenario where one process is holding a read lock that
1118: ** it is trying to promote to a reserved lock and
1119: ** a second process is holding a reserved lock that it is trying
1120: ** to promote to an exclusive lock. The first process cannot proceed
1121: ** because it is blocked by the second and the second process cannot
1122: ** proceed because it is blocked by the first. If both processes
1123: ** invoke the busy handlers, neither will make any progress. Therefore,
1124: ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
1125: ** will induce the first process to release its read lock and allow
1126: ** the second process to proceed.
1.1 misha 1127: **
1128: ** The default busy callback is NULL.
1129: **
1.4 ! misha 1130: ** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
! 1131: ** when SQLite is in the middle of a large transaction where all the
1.2 misha 1132: ** changes will not fit into the in-memory cache. SQLite will
1133: ** already hold a RESERVED lock on the database file, but it needs
1134: ** to promote this lock to EXCLUSIVE so that it can spill cache
1135: ** pages into the database file without harm to concurrent
1136: ** readers. If it is unable to promote the lock, then the in-memory
1137: ** cache will be left in an inconsistent state and so the error
1138: ** code is promoted from the relatively benign [SQLITE_BUSY] to
1139: ** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion
1.4 ! misha 1140: ** forces an automatic rollback of the changes. See the
1.2 misha 1141: ** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">
1142: ** CorruptionFollowingBusyError</a> wiki page for a discussion of why
1143: ** this is important.
1144: **
1145: ** There can only be a single busy handler defined for each database
1.4 ! misha 1146: ** connection. Setting a new busy handler clears any previous one.
1.2 misha 1147: ** Note that calling [sqlite3_busy_timeout()] will also set or clear
1148: ** the busy handler.
1149: **
1.4 ! misha 1150: ** INVARIANTS:
! 1151: **
! 1152: ** {F12311} The [sqlite3_busy_handler()] function replaces the busy handler
! 1153: ** callback in the database connection identified by the 1st
! 1154: ** parameter with a new busy handler identified by the 2nd and 3rd
! 1155: ** parameters.
! 1156: **
! 1157: ** {F12312} The default busy handler for new database connections is NULL.
! 1158: **
! 1159: ** {F12314} When two or more database connection share a common cache,
! 1160: ** the busy handler for the database connection currently using
! 1161: ** the cache is invoked when the cache encounters a lock.
! 1162: **
! 1163: ** {F12316} If a busy handler callback returns zero, then the SQLite
! 1164: ** interface that provoked the locking event will return
! 1165: ** [SQLITE_BUSY].
! 1166: **
! 1167: ** {F12318} SQLite will invokes the busy handler with two argument which
! 1168: ** are a copy of the pointer supplied by the 3rd parameter to
! 1169: ** [sqlite3_busy_handler()] and a count of the number of prior
! 1170: ** invocations of the busy handler for the same locking event.
! 1171: **
! 1172: ** LIMITATIONS:
! 1173: **
! 1174: ** {U12319} A busy handler should not call close the database connection
! 1175: ** or prepared statement that invoked the busy handler.
1.1 misha 1176: */
1177: int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
1178:
1179: /*
1.4 ! misha 1180: ** CAPI3REF: Set A Busy Timeout {F12340}
1.2 misha 1181: **
1.4 ! misha 1182: ** This routine sets a [sqlite3_busy_handler | busy handler]
! 1183: ** that sleeps for a while when a
1.1 misha 1184: ** table is locked. The handler will sleep multiple times until
1.4 ! misha 1185: ** at least "ms" milliseconds of sleeping have been done. {F12343} After
1.2 misha 1186: ** "ms" milliseconds of sleeping, the handler returns 0 which
1187: ** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
1.1 misha 1188: **
1189: ** Calling this routine with an argument less than or equal to zero
1190: ** turns off all busy handlers.
1.2 misha 1191: **
1192: ** There can only be a single busy handler for a particular database
1193: ** connection. If another busy handler was defined
1194: ** (using [sqlite3_busy_handler()]) prior to calling
1195: ** this routine, that other busy handler is cleared.
1.4 ! misha 1196: **
! 1197: ** INVARIANTS:
! 1198: **
! 1199: ** {F12341} The [sqlite3_busy_timeout()] function overrides any prior
! 1200: ** [sqlite3_busy_timeout()] or [sqlite3_busy_handler()] setting
! 1201: ** on the same database connection.
! 1202: **
! 1203: ** {F12343} If the 2nd parameter to [sqlite3_busy_timeout()] is less than
! 1204: ** or equal to zero, then the busy handler is cleared so that
! 1205: ** all subsequent locking events immediately return [SQLITE_BUSY].
! 1206: **
! 1207: ** {F12344} If the 2nd parameter to [sqlite3_busy_timeout()] is a positive
! 1208: ** number N, then a busy handler is set that repeatedly calls
! 1209: ** the xSleep() method in the VFS interface until either the
! 1210: ** lock clears or until the cumulative sleep time reported back
! 1211: ** by xSleep() exceeds N milliseconds.
1.1 misha 1212: */
1213: int sqlite3_busy_timeout(sqlite3*, int ms);
1214:
1215: /*
1.4 ! misha 1216: ** CAPI3REF: Convenience Routines For Running Queries {F12370}
1.2 misha 1217: **
1.4 ! misha 1218: ** Definition: A <b>result table</b> is memory data structure created by the
! 1219: ** [sqlite3_get_table()] interface. A result table records the
! 1220: ** complete query results from one or more queries.
! 1221: **
! 1222: ** The table conceptually has a number of rows and columns. But
! 1223: ** these numbers are not part of the result table itself. These
! 1224: ** numbers are obtained separately. Let N be the number of rows
! 1225: ** and M be the number of columns.
! 1226: **
! 1227: ** A result table is an array of pointers to zero-terminated
! 1228: ** UTF-8 strings. There are (N+1)*M elements in the array.
! 1229: ** The first M pointers point to zero-terminated strings that
! 1230: ** contain the names of the columns.
! 1231: ** The remaining entries all point to query results. NULL
! 1232: ** values are give a NULL pointer. All other values are in
! 1233: ** their UTF-8 zero-terminated string representation as returned by
! 1234: ** [sqlite3_column_text()].
! 1235: **
! 1236: ** A result table might consists of one or more memory allocations.
! 1237: ** It is not safe to pass a result table directly to [sqlite3_free()].
! 1238: ** A result table should be deallocated using [sqlite3_free_table()].
1.1 misha 1239: **
1.4 ! misha 1240: ** As an example of the result table format, suppose a query result
! 1241: ** is as follows:
1.1 misha 1242: **
1.2 misha 1243: ** <blockquote><pre>
1.1 misha 1244: ** Name | Age
1245: ** -----------------------
1246: ** Alice | 43
1247: ** Bob | 28
1248: ** Cindy | 21
1.2 misha 1249: ** </pre></blockquote>
1.1 misha 1250: **
1.4 ! misha 1251: ** There are two column (M==2) and three rows (N==3). Thus the
! 1252: ** result table has 8 entries. Suppose the result table is stored
! 1253: ** in an array names azResult. Then azResult holds this content:
1.1 misha 1254: **
1.2 misha 1255: ** <blockquote><pre>
1256: ** azResult[0] = "Name";
1257: ** azResult[1] = "Age";
1258: ** azResult[2] = "Alice";
1259: ** azResult[3] = "43";
1260: ** azResult[4] = "Bob";
1261: ** azResult[5] = "28";
1262: ** azResult[6] = "Cindy";
1263: ** azResult[7] = "21";
1264: ** </pre></blockquote>
1.1 misha 1265: **
1.4 ! misha 1266: ** The sqlite3_get_table() function evaluates one or more
! 1267: ** semicolon-separated SQL statements in the zero-terminated UTF-8
! 1268: ** string of its 2nd parameter. It returns a result table to the
! 1269: ** pointer given in its 3rd parameter.
1.1 misha 1270: **
1271: ** After the calling function has finished using the result, it should
1.4 ! misha 1272: ** pass the pointer to the result table to sqlite3_free_table() in order to
1.1 misha 1273: ** release the memory that was malloc-ed. Because of the way the
1.4 ! misha 1274: ** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
! 1275: ** function must not try to call [sqlite3_free()] directly. Only
! 1276: ** [sqlite3_free_table()] is able to release the memory properly and safely.
! 1277: **
! 1278: ** The sqlite3_get_table() interface is implemented as a wrapper around
! 1279: ** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access
! 1280: ** to any internal data structures of SQLite. It uses only the public
! 1281: ** interface defined here. As a consequence, errors that occur in the
! 1282: ** wrapper layer outside of the internal [sqlite3_exec()] call are not
! 1283: ** reflected in subsequent calls to [sqlite3_errcode()] or
! 1284: ** [sqlite3_errmsg()].
! 1285: **
! 1286: ** INVARIANTS:
! 1287: **
! 1288: ** {F12371} If a [sqlite3_get_table()] fails a memory allocation, then
! 1289: ** it frees the result table under construction, aborts the
! 1290: ** query in process, skips any subsequent queries, sets the
! 1291: ** *resultp output pointer to NULL and returns [SQLITE_NOMEM].
! 1292: **
! 1293: ** {F12373} If the ncolumn parameter to [sqlite3_get_table()] is not NULL
! 1294: ** then [sqlite3_get_table()] write the number of columns in the
! 1295: ** result set of the query into *ncolumn if the query is
! 1296: ** successful (if the function returns SQLITE_OK).
! 1297: **
! 1298: ** {F12374} If the nrow parameter to [sqlite3_get_table()] is not NULL
! 1299: ** then [sqlite3_get_table()] write the number of rows in the
! 1300: ** result set of the query into *nrow if the query is
! 1301: ** successful (if the function returns SQLITE_OK).
! 1302: **
! 1303: ** {F12376} The [sqlite3_get_table()] function sets its *ncolumn value
! 1304: ** to the number of columns in the result set of the query in the
! 1305: ** sql parameter, or to zero if the query in sql has an empty
! 1306: ** result set.
1.1 misha 1307: */
1308: int sqlite3_get_table(
1.4 ! misha 1309: sqlite3*, /* An open database */
! 1310: const char *sql, /* SQL to be evaluated */
! 1311: char ***pResult, /* Results of the query */
! 1312: int *nrow, /* Number of result rows written here */
! 1313: int *ncolumn, /* Number of result columns written here */
! 1314: char **errmsg /* Error msg written here */
1.1 misha 1315: );
1316: void sqlite3_free_table(char **result);
1317:
1318: /*
1.4 ! misha 1319: ** CAPI3REF: Formatted String Printing Functions {F17400}
1.2 misha 1320: **
1321: ** These routines are workalikes of the "printf()" family of functions
1322: ** from the standard C library.
1.1 misha 1323: **
1.2 misha 1324: ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
1325: ** results into memory obtained from [sqlite3_malloc()].
1326: ** The strings returned by these two routines should be
1.4 ! misha 1327: ** released by [sqlite3_free()]. Both routines return a
1.2 misha 1328: ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
1329: ** memory to hold the resulting string.
1330: **
1331: ** In sqlite3_snprintf() routine is similar to "snprintf()" from
1332: ** the standard C library. The result is written into the
1333: ** buffer supplied as the second parameter whose size is given by
1.4 ! misha 1334: ** the first parameter. Note that the order of the
1.2 misha 1335: ** first two parameters is reversed from snprintf(). This is an
1336: ** historical accident that cannot be fixed without breaking
1337: ** backwards compatibility. Note also that sqlite3_snprintf()
1338: ** returns a pointer to its buffer instead of the number of
1339: ** characters actually written into the buffer. We admit that
1340: ** the number of characters written would be a more useful return
1341: ** value but we cannot change the implementation of sqlite3_snprintf()
1342: ** now without breaking compatibility.
1343: **
1344: ** As long as the buffer size is greater than zero, sqlite3_snprintf()
1345: ** guarantees that the buffer is always zero-terminated. The first
1346: ** parameter "n" is the total size of the buffer, including space for
1347: ** the zero terminator. So the longest string that can be completely
1348: ** written will be n-1 characters.
1.1 misha 1349: **
1.2 misha 1350: ** These routines all implement some additional formatting
1351: ** options that are useful for constructing SQL statements.
1.1 misha 1352: ** All of the usual printf formatting options apply. In addition, there
1.2 misha 1353: ** is are "%q", "%Q", and "%z" options.
1354: **
1355: ** The %q option works like %s in that it substitutes a null-terminated
1.1 misha 1356: ** string from the argument list. But %q also doubles every '\'' character.
1357: ** %q is designed for use inside a string literal. By doubling each '\''
1358: ** character it escapes that character and allows it to be inserted into
1359: ** the string.
1360: **
1361: ** For example, so some string variable contains text as follows:
1362: **
1.2 misha 1363: ** <blockquote><pre>
1364: ** char *zText = "It's a happy day!";
1365: ** </pre></blockquote>
1366: **
1367: ** One can use this text in an SQL statement as follows:
1368: **
1369: ** <blockquote><pre>
1370: ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
1371: ** sqlite3_exec(db, zSQL, 0, 0, 0);
1372: ** sqlite3_free(zSQL);
1373: ** </pre></blockquote>
1.1 misha 1374: **
1375: ** Because the %q format string is used, the '\'' character in zText
1376: ** is escaped and the SQL generated is as follows:
1377: **
1.2 misha 1378: ** <blockquote><pre>
1379: ** INSERT INTO table1 VALUES('It''s a happy day!')
1380: ** </pre></blockquote>
1.1 misha 1381: **
1382: ** This is correct. Had we used %s instead of %q, the generated SQL
1383: ** would have looked like this:
1384: **
1.2 misha 1385: ** <blockquote><pre>
1386: ** INSERT INTO table1 VALUES('It's a happy day!');
1387: ** </pre></blockquote>
1.1 misha 1388: **
1389: ** This second example is an SQL syntax error. As a general rule you
1390: ** should always use %q instead of %s when inserting text into a string
1391: ** literal.
1.2 misha 1392: **
1393: ** The %Q option works like %q except it also adds single quotes around
1394: ** the outside of the total string. Or if the parameter in the argument
1395: ** list is a NULL pointer, %Q substitutes the text "NULL" (without single
1.4 ! misha 1396: ** quotes) in place of the %Q option. {END} So, for example, one could say:
1.2 misha 1397: **
1398: ** <blockquote><pre>
1399: ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
1400: ** sqlite3_exec(db, zSQL, 0, 0, 0);
1401: ** sqlite3_free(zSQL);
1402: ** </pre></blockquote>
1403: **
1404: ** The code above will render a correct SQL statement in the zSQL
1405: ** variable even if the zText variable is a NULL pointer.
1406: **
1407: ** The "%z" formatting option works exactly like "%s" with the
1408: ** addition that after the string has been read and copied into
1.4 ! misha 1409: ** the result, [sqlite3_free()] is called on the input string. {END}
! 1410: **
! 1411: ** INVARIANTS:
! 1412: **
! 1413: ** {F17403} The [sqlite3_mprintf()] and [sqlite3_vmprintf()] interfaces
! 1414: ** return either pointers to zero-terminated UTF-8 strings held in
! 1415: ** memory obtained from [sqlite3_malloc()] or NULL pointers if
! 1416: ** a call to [sqlite3_malloc()] fails.
! 1417: **
! 1418: ** {F17406} The [sqlite3_snprintf()] interface writes a zero-terminated
! 1419: ** UTF-8 string into the buffer pointed to by the second parameter
! 1420: ** provided that the first parameter is greater than zero.
! 1421: **
! 1422: ** {F17407} The [sqlite3_snprintf()] interface does not writes slots of
! 1423: ** its output buffer (the second parameter) outside the range
! 1424: ** of 0 through N-1 (where N is the first parameter)
! 1425: ** regardless of the length of the string
! 1426: ** requested by the format specification.
! 1427: **
1.1 misha 1428: */
1429: char *sqlite3_mprintf(const char*,...);
1430: char *sqlite3_vmprintf(const char*, va_list);
1431: char *sqlite3_snprintf(int,char*,const char*, ...);
1432:
1433: /*
1.4 ! misha 1434: ** CAPI3REF: Memory Allocation Subsystem {F17300}
! 1435: **
! 1436: ** The SQLite core uses these three routines for all of its own
! 1437: ** internal memory allocation needs. "Core" in the previous sentence
! 1438: ** does not include operating-system specific VFS implementation. The
! 1439: ** windows VFS uses native malloc and free for some operations.
! 1440: **
! 1441: ** The sqlite3_malloc() routine returns a pointer to a block
! 1442: ** of memory at least N bytes in length, where N is the parameter.
! 1443: ** If sqlite3_malloc() is unable to obtain sufficient free
! 1444: ** memory, it returns a NULL pointer. If the parameter N to
! 1445: ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
! 1446: ** a NULL pointer.
! 1447: **
! 1448: ** Calling sqlite3_free() with a pointer previously returned
! 1449: ** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
! 1450: ** that it might be reused. The sqlite3_free() routine is
! 1451: ** a no-op if is called with a NULL pointer. Passing a NULL pointer
! 1452: ** to sqlite3_free() is harmless. After being freed, memory
! 1453: ** should neither be read nor written. Even reading previously freed
! 1454: ** memory might result in a segmentation fault or other severe error.
! 1455: ** Memory corruption, a segmentation fault, or other severe error
! 1456: ** might result if sqlite3_free() is called with a non-NULL pointer that
! 1457: ** was not obtained from sqlite3_malloc() or sqlite3_free().
! 1458: **
! 1459: ** The sqlite3_realloc() interface attempts to resize a
! 1460: ** prior memory allocation to be at least N bytes, where N is the
! 1461: ** second parameter. The memory allocation to be resized is the first
! 1462: ** parameter. If the first parameter to sqlite3_realloc()
! 1463: ** is a NULL pointer then its behavior is identical to calling
! 1464: ** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc().
! 1465: ** If the second parameter to sqlite3_realloc() is zero or
! 1466: ** negative then the behavior is exactly the same as calling
! 1467: ** sqlite3_free(P) where P is the first parameter to sqlite3_realloc().
! 1468: ** Sqlite3_realloc() returns a pointer to a memory allocation
! 1469: ** of at least N bytes in size or NULL if sufficient memory is unavailable.
! 1470: ** If M is the size of the prior allocation, then min(N,M) bytes
! 1471: ** of the prior allocation are copied into the beginning of buffer returned
! 1472: ** by sqlite3_realloc() and the prior allocation is freed.
! 1473: ** If sqlite3_realloc() returns NULL, then the prior allocation
! 1474: ** is not freed.
1.2 misha 1475: **
1.4 ! misha 1476: ** The memory returned by sqlite3_malloc() and sqlite3_realloc()
! 1477: ** is always aligned to at least an 8 byte boundary. {END}
1.3 misha 1478: **
1.2 misha 1479: ** The default implementation
1480: ** of the memory allocation subsystem uses the malloc(), realloc()
1.4 ! misha 1481: ** and free() provided by the standard C library. {F17382} However, if
1.2 misha 1482: ** SQLite is compiled with the following C preprocessor macro
1483: **
1.3 misha 1484: ** <blockquote> SQLITE_MEMORY_SIZE=<i>NNN</i> </blockquote>
1.2 misha 1485: **
1.3 misha 1486: ** where <i>NNN</i> is an integer, then SQLite create a static
1487: ** array of at least <i>NNN</i> bytes in size and use that array
1.4 ! misha 1488: ** for all of its dynamic memory allocation needs. {END} Additional
! 1489: ** memory allocator options may be added in future releases.
1.3 misha 1490: **
1491: ** In SQLite version 3.5.0 and 3.5.1, it was possible to define
1492: ** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
1493: ** implementation of these routines to be omitted. That capability
1494: ** is no longer provided. Only built-in memory allocators can be
1495: ** used.
1.2 misha 1496: **
1.4 ! misha 1497: ** The windows OS interface layer calls
1.2 misha 1498: ** the system malloc() and free() directly when converting
1499: ** filenames between the UTF-8 encoding used by SQLite
1500: ** and whatever filename encoding is used by the particular windows
1501: ** installation. Memory allocation errors are detected, but
1502: ** they are reported back as [SQLITE_CANTOPEN] or
1503: ** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
1.4 ! misha 1504: **
! 1505: ** INVARIANTS:
! 1506: **
! 1507: ** {F17303} The [sqlite3_malloc(N)] interface returns either a pointer to
! 1508: ** newly checked-out block of at least N bytes of memory
! 1509: ** that is 8-byte aligned,
! 1510: ** or it returns NULL if it is unable to fulfill the request.
! 1511: **
! 1512: ** {F17304} The [sqlite3_malloc(N)] interface returns a NULL pointer if
! 1513: ** N is less than or equal to zero.
! 1514: **
! 1515: ** {F17305} The [sqlite3_free(P)] interface releases memory previously
! 1516: ** returned from [sqlite3_malloc()] or [sqlite3_realloc()],
! 1517: ** making it available for reuse.
! 1518: **
! 1519: ** {F17306} A call to [sqlite3_free(NULL)] is a harmless no-op.
! 1520: **
! 1521: ** {F17310} A call to [sqlite3_realloc(0,N)] is equivalent to a call
! 1522: ** to [sqlite3_malloc(N)].
! 1523: **
! 1524: ** {F17312} A call to [sqlite3_realloc(P,0)] is equivalent to a call
! 1525: ** to [sqlite3_free(P)].
! 1526: **
! 1527: ** {F17315} The SQLite core uses [sqlite3_malloc()], [sqlite3_realloc()],
! 1528: ** and [sqlite3_free()] for all of its memory allocation and
! 1529: ** deallocation needs.
! 1530: **
! 1531: ** {F17318} The [sqlite3_realloc(P,N)] interface returns either a pointer
! 1532: ** to a block of checked-out memory of at least N bytes in size
! 1533: ** that is 8-byte aligned, or a NULL pointer.
! 1534: **
! 1535: ** {F17321} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first
! 1536: ** copies the first K bytes of content from P into the newly allocated
! 1537: ** where K is the lessor of N and the size of the buffer P.
! 1538: **
! 1539: ** {F17322} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first
! 1540: ** releases the buffer P.
! 1541: **
! 1542: ** {F17323} When [sqlite3_realloc(P,N)] returns NULL, the buffer P is
! 1543: ** not modified or released.
! 1544: **
! 1545: ** LIMITATIONS:
! 1546: **
! 1547: ** {U17350} The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
! 1548: ** must be either NULL or else a pointer obtained from a prior
! 1549: ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that has
! 1550: ** not been released.
! 1551: **
! 1552: ** {U17351} The application must not read or write any part of
! 1553: ** a block of memory after it has been released using
! 1554: ** [sqlite3_free()] or [sqlite3_realloc()].
! 1555: **
1.2 misha 1556: */
1557: void *sqlite3_malloc(int);
1558: void *sqlite3_realloc(void*, int);
1559: void sqlite3_free(void*);
1560:
1561: /*
1.4 ! misha 1562: ** CAPI3REF: Memory Allocator Statistics {F17370}
1.2 misha 1563: **
1.4 ! misha 1564: ** SQLite provides these two interfaces for reporting on the status
! 1565: ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
! 1566: ** the memory allocation subsystem included within the SQLite.
! 1567: **
! 1568: ** INVARIANTS:
! 1569: **
! 1570: ** {F17371} The [sqlite3_memory_used()] routine returns the
! 1571: ** number of bytes of memory currently outstanding
! 1572: ** (malloced but not freed).
! 1573: **
! 1574: ** {F17373} The [sqlite3_memory_highwater()] routine returns the maximum
! 1575: ** value of [sqlite3_memory_used()]
! 1576: ** since the highwater mark was last reset.
! 1577: **
! 1578: ** {F17374} The values returned by [sqlite3_memory_used()] and
! 1579: ** [sqlite3_memory_highwater()] include any overhead
! 1580: ** added by SQLite in its implementation of [sqlite3_malloc()],
! 1581: ** but not overhead added by the any underlying system library
! 1582: ** routines that [sqlite3_malloc()] may call.
! 1583: **
! 1584: ** {F17375} The memory highwater mark is reset to the current value of
! 1585: ** [sqlite3_memory_used()] if and only if the parameter to
! 1586: ** [sqlite3_memory_highwater()] is true. The value returned
! 1587: ** by [sqlite3_memory_highwater(1)] is the highwater mark
! 1588: ** prior to the reset.
1.2 misha 1589: */
1590: sqlite3_int64 sqlite3_memory_used(void);
1591: sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
1592:
1593: /*
1.4 ! misha 1594: ** CAPI3REF: Compile-Time Authorization Callbacks {F12500}
! 1595: **
! 1596: ** This routine registers a authorizer callback with a particular
! 1597: ** database connection, supplied in the first argument.
1.2 misha 1598: ** The authorizer callback is invoked as SQL statements are being compiled
1599: ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
1600: ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various
1601: ** points during the compilation process, as logic is being created
1602: ** to perform various actions, the authorizer callback is invoked to
1603: ** see if those actions are allowed. The authorizer callback should
1604: ** return SQLITE_OK to allow the action, [SQLITE_IGNORE] to disallow the
1605: ** specific action but allow the SQL statement to continue to be
1606: ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
1.4 ! misha 1607: ** rejected with an error. If the authorizer callback returns
! 1608: ** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
! 1609: ** then [sqlite3_prepare_v2()] or equivalent call that triggered
! 1610: ** the authorizer will fail with an error message.
! 1611: **
! 1612: ** When the callback returns [SQLITE_OK], that means the operation
! 1613: ** requested is ok. When the callback returns [SQLITE_DENY], the
! 1614: ** [sqlite3_prepare_v2()] or equivalent call that triggered the
! 1615: ** authorizer will fail with an error message explaining that
! 1616: ** access is denied. If the authorizer code is [SQLITE_READ]
! 1617: ** and the callback returns [SQLITE_IGNORE] then the prepared
! 1618: ** statement is constructed to insert a NULL value in place of
! 1619: ** the table column that would have
! 1620: ** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE]
! 1621: ** return can be used to deny an untrusted user access to individual
! 1622: ** columns of a table.
1.2 misha 1623: **
1624: ** The first parameter to the authorizer callback is a copy of
1625: ** the third parameter to the sqlite3_set_authorizer() interface.
1626: ** The second parameter to the callback is an integer
1627: ** [SQLITE_COPY | action code] that specifies the particular action
1.4 ! misha 1628: ** to be authorized. The third through sixth
! 1629: ** parameters to the callback are zero-terminated strings that contain
! 1630: ** additional details about the action to be authorized.
1.2 misha 1631: **
1632: ** An authorizer is used when preparing SQL statements from an untrusted
1633: ** source, to ensure that the SQL statements do not try to access data
1634: ** that they are not allowed to see, or that they do not try to
1635: ** execute malicious statements that damage the database. For
1636: ** example, an application may allow a user to enter arbitrary
1637: ** SQL queries for evaluation by a database. But the application does
1638: ** not want the user to be able to make arbitrary changes to the
1639: ** database. An authorizer could then be put in place while the
1640: ** user-entered SQL is being prepared that disallows everything
1641: ** except SELECT statements.
1642: **
1643: ** Only a single authorizer can be in place on a database connection
1644: ** at a time. Each call to sqlite3_set_authorizer overrides the
1.4 ! misha 1645: ** previous call. Disable the authorizer by installing a NULL callback.
! 1646: ** The authorizer is disabled by default.
1.2 misha 1647: **
1648: ** Note that the authorizer callback is invoked only during
1649: ** [sqlite3_prepare()] or its variants. Authorization is not
1650: ** performed during statement evaluation in [sqlite3_step()].
1.4 ! misha 1651: **
! 1652: ** INVARIANTS:
! 1653: **
! 1654: ** {F12501} The [sqlite3_set_authorizer(D,...)] interface registers a
! 1655: ** authorizer callback with database connection D.
! 1656: **
! 1657: ** {F12502} The authorizer callback is invoked as SQL statements are
! 1658: ** being compiled
! 1659: **
! 1660: ** {F12503} If the authorizer callback returns any value other than
! 1661: ** [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] then
! 1662: ** the [sqlite3_prepare_v2()] or equivalent call that caused
! 1663: ** the authorizer callback to run shall fail with an
! 1664: ** [SQLITE_ERROR] error code and an appropriate error message.
! 1665: **
! 1666: ** {F12504} When the authorizer callback returns [SQLITE_OK], the operation
! 1667: ** described is coded normally.
! 1668: **
! 1669: ** {F12505} When the authorizer callback returns [SQLITE_DENY], the
! 1670: ** [sqlite3_prepare_v2()] or equivalent call that caused the
! 1671: ** authorizer callback to run shall fail
! 1672: ** with an [SQLITE_ERROR] error code and an error message
! 1673: ** explaining that access is denied.
! 1674: **
! 1675: ** {F12506} If the authorizer code (the 2nd parameter to the authorizer
! 1676: ** callback) is [SQLITE_READ] and the authorizer callback returns
! 1677: ** [SQLITE_IGNORE] then the prepared statement is constructed to
! 1678: ** insert a NULL value in place of the table column that would have
! 1679: ** been read if [SQLITE_OK] had been returned.
! 1680: **
! 1681: ** {F12507} If the authorizer code (the 2nd parameter to the authorizer
! 1682: ** callback) is anything other than [SQLITE_READ], then
! 1683: ** a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY].
! 1684: **
! 1685: ** {F12510} The first parameter to the authorizer callback is a copy of
! 1686: ** the third parameter to the [sqlite3_set_authorizer()] interface.
! 1687: **
! 1688: ** {F12511} The second parameter to the callback is an integer
! 1689: ** [SQLITE_COPY | action code] that specifies the particular action
! 1690: ** to be authorized.
! 1691: **
! 1692: ** {F12512} The third through sixth parameters to the callback are
! 1693: ** zero-terminated strings that contain
! 1694: ** additional details about the action to be authorized.
! 1695: **
! 1696: ** {F12520} Each call to [sqlite3_set_authorizer()] overrides the
! 1697: ** any previously installed authorizer.
! 1698: **
! 1699: ** {F12521} A NULL authorizer means that no authorization
! 1700: ** callback is invoked.
! 1701: **
! 1702: ** {F12522} The default authorizer is NULL.
1.1 misha 1703: */
1704: int sqlite3_set_authorizer(
1705: sqlite3*,
1706: int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
1707: void *pUserData
1708: );
1709:
1710: /*
1.4 ! misha 1711: ** CAPI3REF: Authorizer Return Codes {F12590}
1.2 misha 1712: **
1713: ** The [sqlite3_set_authorizer | authorizer callback function] must
1714: ** return either [SQLITE_OK] or one of these two constants in order
1715: ** to signal SQLite whether or not the action is permitted. See the
1716: ** [sqlite3_set_authorizer | authorizer documentation] for additional
1717: ** information.
1718: */
1719: #define SQLITE_DENY 1 /* Abort the SQL statement with an error */
1720: #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
1721:
1722: /*
1.4 ! misha 1723: ** CAPI3REF: Authorizer Action Codes {F12550}
1.2 misha 1724: **
1725: ** The [sqlite3_set_authorizer()] interface registers a callback function
1726: ** that is invoked to authorizer certain SQL statement actions. The
1727: ** second parameter to the callback is an integer code that specifies
1728: ** what action is being authorized. These are the integer action codes that
1729: ** the authorizer callback may be passed.
1730: **
1731: ** These action code values signify what kind of operation is to be
1.4 ! misha 1732: ** authorized. The 3rd and 4th parameters to the authorization
! 1733: ** callback function will be parameters or NULL depending on which of these
1.2 misha 1734: ** codes is used as the second parameter. The 5th parameter to the
1735: ** authorizer callback is the name of the database ("main", "temp",
1736: ** etc.) if applicable. The 6th parameter to the authorizer callback
1.1 misha 1737: ** is the name of the inner-most trigger or view that is responsible for
1738: ** the access attempt or NULL if this access attempt is directly from
1.2 misha 1739: ** top-level SQL code.
1.4 ! misha 1740: **
! 1741: ** INVARIANTS:
! 1742: **
! 1743: ** {F12551} The second parameter to an
! 1744: ** [sqlite3_set_authorizer | authorizer callback is always an integer
! 1745: ** [SQLITE_COPY | authorizer code] that specifies what action
! 1746: ** is being authorized.
! 1747: **
! 1748: ** {F12552} The 3rd and 4th parameters to the
! 1749: ** [sqlite3_set_authorizer | authorization callback function]
! 1750: ** will be parameters or NULL depending on which
! 1751: ** [SQLITE_COPY | authorizer code] is used as the second parameter.
! 1752: **
! 1753: ** {F12553} The 5th parameter to the
! 1754: ** [sqlite3_set_authorizer | authorizer callback] is the name
! 1755: ** of the database (example: "main", "temp", etc.) if applicable.
! 1756: **
! 1757: ** {F12554} The 6th parameter to the
! 1758: ** [sqlite3_set_authorizer | authorizer callback] is the name
! 1759: ** of the inner-most trigger or view that is responsible for
! 1760: ** the access attempt or NULL if this access attempt is directly from
! 1761: ** top-level SQL code.
1.1 misha 1762: */
1.2 misha 1763: /******************************************* 3rd ************ 4th ***********/
1.1 misha 1764: #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
1765: #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
1766: #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
1767: #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
1768: #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
1769: #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
1770: #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
1771: #define SQLITE_CREATE_VIEW 8 /* View Name NULL */
1772: #define SQLITE_DELETE 9 /* Table Name NULL */
1773: #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
1774: #define SQLITE_DROP_TABLE 11 /* Table Name NULL */
1775: #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
1776: #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
1777: #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
1778: #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
1779: #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
1780: #define SQLITE_DROP_VIEW 17 /* View Name NULL */
1781: #define SQLITE_INSERT 18 /* Table Name NULL */
1782: #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
1783: #define SQLITE_READ 20 /* Table Name Column Name */
1784: #define SQLITE_SELECT 21 /* NULL NULL */
1785: #define SQLITE_TRANSACTION 22 /* NULL NULL */
1786: #define SQLITE_UPDATE 23 /* Table Name Column Name */
1787: #define SQLITE_ATTACH 24 /* Filename NULL */
1788: #define SQLITE_DETACH 25 /* Database Name NULL */
1.2 misha 1789: #define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */
1790: #define SQLITE_REINDEX 27 /* Index Name NULL */
1791: #define SQLITE_ANALYZE 28 /* Table Name NULL */
1792: #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
1793: #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
1794: #define SQLITE_FUNCTION 31 /* Function Name NULL */
1795: #define SQLITE_COPY 0 /* No longer used */
1796:
1797: /*
1.4 ! misha 1798: ** CAPI3REF: Tracing And Profiling Functions {F12280}
1.2 misha 1799: **
1800: ** These routines register callback functions that can be used for
1801: ** tracing and profiling the execution of SQL statements.
1.4 ! misha 1802: **
! 1803: ** The callback function registered by sqlite3_trace() is invoked at
! 1804: ** various times when an SQL statement is being run by [sqlite3_step()].
! 1805: ** The callback returns a UTF-8 rendering of the SQL statement text
! 1806: ** as the statement first begins executing. Additional callbacks occur
! 1807: ** as each triggersubprogram is entered. The callbacks for triggers
! 1808: ** contain a UTF-8 SQL comment that identifies the trigger.
! 1809: **
1.2 misha 1810: ** The callback function registered by sqlite3_profile() is invoked
1.4 ! misha 1811: ** as each SQL statement finishes. The profile callback contains
! 1812: ** the original statement text and an estimate of wall-clock time
! 1813: ** of how long that statement took to run.
1.2 misha 1814: **
1815: ** The sqlite3_profile() API is currently considered experimental and
1.4 ! misha 1816: ** is subject to change or removal in a future release.
! 1817: **
! 1818: ** The trigger reporting feature of the trace callback is considered
! 1819: ** experimental and is subject to change or removal in future releases.
! 1820: ** Future versions of SQLite might also add new trace callback
! 1821: ** invocations.
! 1822: **
! 1823: ** INVARIANTS:
! 1824: **
! 1825: ** {F12281} The callback function registered by [sqlite3_trace()] is
! 1826: ** whenever an SQL statement first begins to execute and
! 1827: ** whenever a trigger subprogram first begins to run.
! 1828: **
! 1829: ** {F12282} Each call to [sqlite3_trace()] overrides the previously
! 1830: ** registered trace callback.
! 1831: **
! 1832: ** {F12283} A NULL trace callback disables tracing.
! 1833: **
! 1834: ** {F12284} The first argument to the trace callback is a copy of
! 1835: ** the pointer which was the 3rd argument to [sqlite3_trace()].
! 1836: **
! 1837: ** {F12285} The second argument to the trace callback is a
! 1838: ** zero-terminated UTF8 string containing the original text
! 1839: ** of the SQL statement as it was passed into [sqlite3_prepare_v2()]
! 1840: ** or the equivalent, or an SQL comment indicating the beginning
! 1841: ** of a trigger subprogram.
! 1842: **
! 1843: ** {F12287} The callback function registered by [sqlite3_profile()] is invoked
! 1844: ** as each SQL statement finishes.
! 1845: **
! 1846: ** {F12288} The first parameter to the profile callback is a copy of
! 1847: ** the 3rd parameter to [sqlite3_profile()].
! 1848: **
! 1849: ** {F12289} The second parameter to the profile callback is a
! 1850: ** zero-terminated UTF-8 string that contains the complete text of
! 1851: ** the SQL statement as it was processed by [sqlite3_prepare_v2()]
! 1852: ** or the equivalent.
! 1853: **
! 1854: ** {F12290} The third parameter to the profile callback is an estimate
! 1855: ** of the number of nanoseconds of wall-clock time required to
! 1856: ** run the SQL statement from start to finish.
1.1 misha 1857: */
1858: void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
1.2 misha 1859: void *sqlite3_profile(sqlite3*,
1860: void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
1.1 misha 1861:
1862: /*
1.4 ! misha 1863: ** CAPI3REF: Query Progress Callbacks {F12910}
1.2 misha 1864: **
1.4 ! misha 1865: ** This routine configures a callback function - the
! 1866: ** progress callback - that is invoked periodically during long
! 1867: ** running calls to [sqlite3_exec()], [sqlite3_step()] and
! 1868: ** [sqlite3_get_table()]. An example use for this
1.2 misha 1869: ** interface is to keep a GUI updated during a large query.
1.1 misha 1870: **
1.4 ! misha 1871: ** If the progress callback returns non-zero, the opertion is
! 1872: ** interrupted. This feature can be used to implement a
! 1873: ** "Cancel" button on a GUI dialog box.
! 1874: **
! 1875: ** INVARIANTS:
! 1876: **
! 1877: ** {F12911} The callback function registered by [sqlite3_progress_handler()]
! 1878: ** is invoked periodically during long running calls to
! 1879: ** [sqlite3_step()].
! 1880: **
! 1881: ** {F12912} The progress callback is invoked once for every N virtual
! 1882: ** machine opcodes, where N is the second argument to
! 1883: ** the [sqlite3_progress_handler()] call that registered
! 1884: ** the callback. <todo>What if N is less than 1?</todo>
! 1885: **
! 1886: ** {F12913} The progress callback itself is identified by the third
! 1887: ** argument to [sqlite3_progress_handler()].
! 1888: **
! 1889: ** {F12914} The fourth argument [sqlite3_progress_handler()] is a
! 1890: *** void pointer passed to the progress callback
! 1891: ** function each time it is invoked.
! 1892: **
! 1893: ** {F12915} If a call to [sqlite3_step()] results in fewer than
! 1894: ** N opcodes being executed,
! 1895: ** then the progress callback is never invoked. {END}
! 1896: **
! 1897: ** {F12916} Every call to [sqlite3_progress_handler()]
! 1898: ** overwrites any previously registere progress handler.
! 1899: **
! 1900: ** {F12917} If the progress handler callback is NULL then no progress
! 1901: ** handler is invoked.
! 1902: **
! 1903: ** {F12918} If the progress callback returns a result other than 0, then
! 1904: ** the behavior is a if [sqlite3_interrupt()] had been called.
1.1 misha 1905: */
1906: void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
1907:
1908: /*
1.4 ! misha 1909: ** CAPI3REF: Opening A New Database Connection {F12700}
1.1 misha 1910: **
1.4 ! misha 1911: ** These routines open an SQLite database file whose name
! 1912: ** is given by the filename argument.
! 1913: ** The filename argument is interpreted as UTF-8
! 1914: ** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16
1.2 misha 1915: ** in the native byte order for [sqlite3_open16()].
1.4 ! misha 1916: ** An [sqlite3*] handle is usually returned in *ppDb, even
! 1917: ** if an error occurs. The only exception is if SQLite is unable
! 1918: ** to allocate memory to hold the [sqlite3] object, a NULL will
! 1919: ** be written into *ppDb instead of a pointer to the [sqlite3] object.
! 1920: ** If the database is opened (and/or created)
! 1921: ** successfully, then [SQLITE_OK] is returned. Otherwise an
! 1922: ** error code is returned. The
1.2 misha 1923: ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
1.1 misha 1924: ** an English language description of the error.
1925: **
1.2 misha 1926: ** The default encoding for the database will be UTF-8 if
1927: ** [sqlite3_open()] or [sqlite3_open_v2()] is called and
1.4 ! misha 1928: ** UTF-16 in the native byte order if [sqlite3_open16()] is used.
1.1 misha 1929: **
1.4 ! misha 1930: ** Whether or not an error occurs when it is opened, resources
! 1931: ** associated with the [sqlite3*] handle should be released by passing it
! 1932: ** to [sqlite3_close()] when it is no longer required.
! 1933: **
! 1934: ** The [sqlite3_open_v2()] interface works like [sqlite3_open()]
! 1935: ** except that it acccepts two additional parameters for additional control
! 1936: ** over the new database connection. The flags parameter can be
! 1937: ** one of:
1.2 misha 1938: **
1939: ** <ol>
1940: ** <li> [SQLITE_OPEN_READONLY]
1941: ** <li> [SQLITE_OPEN_READWRITE]
1942: ** <li> [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]
1943: ** </ol>
1944: **
1.4 ! misha 1945: ** The first value opens the database read-only.
! 1946: ** If the database does not previously exist, an error is returned.
! 1947: ** The second option opens
1.2 misha 1948: ** the database for reading and writing if possible, or reading only if
1.4 ! misha 1949: ** if the file is write protected. In either case the database
! 1950: ** must already exist or an error is returned. The third option
! 1951: ** opens the database for reading and writing and creates it if it does
! 1952: ** not already exist.
1.2 misha 1953: ** The third options is behavior that is always used for [sqlite3_open()]
1954: ** and [sqlite3_open16()].
1955: **
1956: ** If the filename is ":memory:", then an private
1957: ** in-memory database is created for the connection. This in-memory
1958: ** database will vanish when the database connection is closed. Future
1959: ** version of SQLite might make use of additional special filenames
1960: ** that begin with the ":" character. It is recommended that
1961: ** when a database filename really does begin with
1962: ** ":" that you prefix the filename with a pathname like "./" to
1963: ** avoid ambiguity.
1964: **
1965: ** If the filename is an empty string, then a private temporary
1966: ** on-disk database will be created. This private database will be
1967: ** automatically deleted as soon as the database connection is closed.
1968: **
1969: ** The fourth parameter to sqlite3_open_v2() is the name of the
1970: ** [sqlite3_vfs] object that defines the operating system
1971: ** interface that the new database connection should use. If the
1972: ** fourth parameter is a NULL pointer then the default [sqlite3_vfs]
1973: ** object is used.
1974: **
1975: ** <b>Note to windows users:</b> The encoding used for the filename argument
1976: ** of [sqlite3_open()] and [sqlite3_open_v2()] must be UTF-8, not whatever
1977: ** codepage is currently defined. Filenames containing international
1978: ** characters must be converted to UTF-8 prior to passing them into
1979: ** [sqlite3_open()] or [sqlite3_open_v2()].
1.4 ! misha 1980: **
! 1981: ** INVARIANTS:
! 1982: **
! 1983: ** {F12701} The [sqlite3_open()], [sqlite3_open16()], and
! 1984: ** [sqlite3_open_v2()] interfaces create a new
! 1985: ** [database connection] associated with
! 1986: ** the database file given in their first parameter.
! 1987: **
! 1988: ** {F12702} The filename argument is interpreted as UTF-8
! 1989: ** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16
! 1990: ** in the native byte order for [sqlite3_open16()].
! 1991: **
! 1992: ** {F12703} A successful invocation of [sqlite3_open()], [sqlite3_open16()],
! 1993: ** or [sqlite3_open_v2()] writes a pointer to a new
! 1994: ** [database connection] into *ppDb.
! 1995: **
! 1996: ** {F12704} The [sqlite3_open()], [sqlite3_open16()], and
! 1997: ** [sqlite3_open_v2()] interfaces return [SQLITE_OK] upon success,
! 1998: ** or an appropriate [error code] on failure.
! 1999: **
! 2000: ** {F12706} The default text encoding for a new database created using
! 2001: ** [sqlite3_open()] or [sqlite3_open_v2()] will be UTF-8.
! 2002: **
! 2003: ** {F12707} The default text encoding for a new database created using
! 2004: ** [sqlite3_open16()] will be UTF-16.
! 2005: **
! 2006: ** {F12709} The [sqlite3_open(F,D)] interface is equivalent to
! 2007: ** [sqlite3_open_v2(F,D,G,0)] where the G parameter is
! 2008: ** [SQLITE_OPEN_READWRITE]|[SQLITE_OPEN_CREATE].
! 2009: **
! 2010: ** {F12711} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the
! 2011: ** bit value [SQLITE_OPEN_READONLY] then the database is opened
! 2012: ** for reading only.
! 2013: **
! 2014: ** {F12712} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the
! 2015: ** bit value [SQLITE_OPEN_READWRITE] then the database is opened
! 2016: ** reading and writing if possible, or for reading only if the
! 2017: ** file is write protected by the operating system.
! 2018: **
! 2019: ** {F12713} If the G parameter to [sqlite3_open(v2(F,D,G,V)] omits the
! 2020: ** bit value [SQLITE_OPEN_CREATE] and the database does not
! 2021: ** previously exist, an error is returned.
! 2022: **
! 2023: ** {F12714} If the G parameter to [sqlite3_open(v2(F,D,G,V)] contains the
! 2024: ** bit value [SQLITE_OPEN_CREATE] and the database does not
! 2025: ** previously exist, then an attempt is made to create and
! 2026: ** initialize the database.
! 2027: **
! 2028: ** {F12717} If the filename argument to [sqlite3_open()], [sqlite3_open16()],
! 2029: ** or [sqlite3_open_v2()] is ":memory:", then an private,
! 2030: ** ephemeral, in-memory database is created for the connection.
! 2031: ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required
! 2032: ** in sqlite3_open_v2()?</todo>
! 2033: **
! 2034: ** {F12719} If the filename is NULL or an empty string, then a private,
! 2035: ** ephermeral on-disk database will be created.
! 2036: ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required
! 2037: ** in sqlite3_open_v2()?</todo>
! 2038: **
! 2039: ** {F12721} The [database connection] created by
! 2040: ** [sqlite3_open_v2(F,D,G,V)] will use the
! 2041: ** [sqlite3_vfs] object identified by the V parameter, or
! 2042: ** the default [sqlite3_vfs] object is V is a NULL pointer.
1.1 misha 2043: */
2044: int sqlite3_open(
2045: const char *filename, /* Database filename (UTF-8) */
2046: sqlite3 **ppDb /* OUT: SQLite db handle */
2047: );
2048: int sqlite3_open16(
2049: const void *filename, /* Database filename (UTF-16) */
2050: sqlite3 **ppDb /* OUT: SQLite db handle */
2051: );
1.2 misha 2052: int sqlite3_open_v2(
2053: const char *filename, /* Database filename (UTF-8) */
2054: sqlite3 **ppDb, /* OUT: SQLite db handle */
2055: int flags, /* Flags */
2056: const char *zVfs /* Name of VFS module to use */
2057: );
1.1 misha 2058:
2059: /*
1.4 ! misha 2060: ** CAPI3REF: Error Codes And Messages {F12800}
1.2 misha 2061: **
2062: ** The sqlite3_errcode() interface returns the numeric
2063: ** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code]
2064: ** for the most recent failed sqlite3_* API call associated
1.4 ! misha 2065: ** with [sqlite3] handle 'db'. If a prior API call failed but the
1.2 misha 2066: ** most recent API call succeeded, the return value from sqlite3_errcode()
1.4 ! misha 2067: ** is undefined.
1.2 misha 2068: **
2069: ** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
2070: ** text that describes the error, as either UTF8 or UTF16 respectively.
1.4 ! misha 2071: ** Memory to hold the error message string is managed internally.
! 2072: ** The application does not need to worry with freeing the result.
! 2073: ** However, the error string might be overwritten or deallocated by
! 2074: ** subsequent calls to other SQLite interface functions.
! 2075: **
! 2076: ** INVARIANTS:
! 2077: **
! 2078: ** {F12801} The [sqlite3_errcode(D)] interface returns the numeric
! 2079: ** [SQLITE_OK | result code] or
! 2080: ** [SQLITE_IOERR_READ | extended result code]
! 2081: ** for the most recently failed interface call associated
! 2082: ** with [database connection] D.
! 2083: **
! 2084: ** {F12803} The [sqlite3_errmsg(D)] and [sqlite3_errmsg16(D)]
! 2085: ** interfaces return English-language text that describes
! 2086: ** the error in the mostly recently failed interface call,
! 2087: ** encoded as either UTF8 or UTF16 respectively.
! 2088: **
! 2089: ** {F12807} The strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()]
! 2090: ** are valid until the next SQLite interface call.
! 2091: **
! 2092: ** {F12808} Calls to API routines that do not return an error code
! 2093: ** (example: [sqlite3_data_count()]) do not
! 2094: ** change the error code or message returned by
! 2095: ** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()].
! 2096: **
! 2097: ** {F12809} Interfaces that are not associated with a specific
! 2098: ** [database connection] (examples:
! 2099: ** [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()]
! 2100: ** do not change the values returned by
! 2101: ** [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()].
1.1 misha 2102: */
2103: int sqlite3_errcode(sqlite3 *db);
1.2 misha 2104: const char *sqlite3_errmsg(sqlite3*);
2105: const void *sqlite3_errmsg16(sqlite3*);
1.1 misha 2106:
2107: /*
1.4 ! misha 2108: ** CAPI3REF: SQL Statement Object {F13000}
! 2109: ** KEYWORDS: {prepared statement} {prepared statements}
1.2 misha 2110: **
1.4 ! misha 2111: ** An instance of this object represent single SQL statements. This
! 2112: ** object is variously known as a "prepared statement" or a
1.2 misha 2113: ** "compiled SQL statement" or simply as a "statement".
2114: **
2115: ** The life of a statement object goes something like this:
1.1 misha 2116: **
1.2 misha 2117: ** <ol>
2118: ** <li> Create the object using [sqlite3_prepare_v2()] or a related
2119: ** function.
2120: ** <li> Bind values to host parameters using
2121: ** [sqlite3_bind_blob | sqlite3_bind_* interfaces].
2122: ** <li> Run the SQL by calling [sqlite3_step()] one or more times.
2123: ** <li> Reset the statement using [sqlite3_reset()] then go back
2124: ** to step 2. Do this zero or more times.
2125: ** <li> Destroy the object using [sqlite3_finalize()].
2126: ** </ol>
1.1 misha 2127: **
1.2 misha 2128: ** Refer to documentation on individual methods above for additional
2129: ** information.
1.1 misha 2130: */
2131: typedef struct sqlite3_stmt sqlite3_stmt;
2132:
2133: /*
1.4 ! misha 2134: ** CAPI3REF: Compiling An SQL Statement {F13010}
1.2 misha 2135: **
1.1 misha 2136: ** To execute an SQL query, it must first be compiled into a byte-code
1.2 misha 2137: ** program using one of these routines.
2138: **
1.4 ! misha 2139: ** The first argument "db" is an [database connection]
1.2 misha 2140: ** obtained from a prior call to [sqlite3_open()], [sqlite3_open_v2()]
1.4 ! misha 2141: ** or [sqlite3_open16()].
1.2 misha 2142: ** The second argument "zSql" is the statement to be compiled, encoded
2143: ** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2()
2144: ** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2()
1.4 ! misha 2145: ** use UTF-16. {END}
1.2 misha 2146: **
2147: ** If the nByte argument is less
1.4 ! misha 2148: ** than zero, then zSql is read up to the first zero terminator.
! 2149: ** If nByte is non-negative, then it is the maximum number of
1.2 misha 2150: ** bytes read from zSql. When nByte is non-negative, the
1.4 ! misha 2151: ** zSql string ends at either the first '\000' or '\u0000' character or
! 2152: ** until the nByte-th byte, whichever comes first. {END}
1.1 misha 2153: **
1.4 ! misha 2154: ** *pzTail is made to point to the first byte past the end of the
! 2155: ** first SQL statement in zSql. These routines only compiles the first
! 2156: ** statement in zSql, so *pzTail is left pointing to what remains
! 2157: ** uncompiled.
! 2158: **
! 2159: ** *ppStmt is left pointing to a compiled [prepared statement] that can be
! 2160: ** executed using [sqlite3_step()]. Or if there is an error, *ppStmt is
! 2161: ** set to NULL. If the input text contains no SQL (if the input
! 2162: ** is and empty string or a comment) then *ppStmt is set to NULL.
! 2163: ** {U13018} The calling procedure is responsible for deleting the
! 2164: ** compiled SQL statement
1.2 misha 2165: ** using [sqlite3_finalize()] after it has finished with it.
2166: **
2167: ** On success, [SQLITE_OK] is returned. Otherwise an
1.4 ! misha 2168: ** [error code] is returned.
1.2 misha 2169: **
2170: ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
2171: ** recommended for all new programs. The two older interfaces are retained
2172: ** for backwards compatibility, but their use is discouraged.
2173: ** In the "v2" interfaces, the prepared statement
2174: ** that is returned (the [sqlite3_stmt] object) contains a copy of the
1.4 ! misha 2175: ** original SQL text. {END} This causes the [sqlite3_step()] interface to
1.2 misha 2176: ** behave a differently in two ways:
2177: **
2178: ** <ol>
2179: ** <li>
2180: ** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
2181: ** always used to do, [sqlite3_step()] will automatically recompile the SQL
1.4 ! misha 2182: ** statement and try to run it again. If the schema has changed in
! 2183: ** a way that makes the statement no longer valid, [sqlite3_step()] will still
! 2184: ** return [SQLITE_SCHEMA]. But unlike the legacy behavior,
! 2185: ** [SQLITE_SCHEMA] is now a fatal error. Calling
! 2186: ** [sqlite3_prepare_v2()] again will not make the
! 2187: ** error go away. Note: use [sqlite3_errmsg()] to find the text
! 2188: ** of the parsing error that results in an [SQLITE_SCHEMA] return. {END}
1.2 misha 2189: ** </li>
2190: **
2191: ** <li>
2192: ** When an error occurs,
2193: ** [sqlite3_step()] will return one of the detailed
1.4 ! misha 2194: ** [error codes] or [extended error codes].
1.2 misha 2195: ** The legacy behavior was that [sqlite3_step()] would only return a generic
2196: ** [SQLITE_ERROR] result code and you would have to make a second call to
2197: ** [sqlite3_reset()] in order to find the underlying cause of the problem.
2198: ** With the "v2" prepare interfaces, the underlying reason for the error is
2199: ** returned immediately.
2200: ** </li>
2201: ** </ol>
1.4 ! misha 2202: **
! 2203: ** INVARIANTS:
! 2204: **
! 2205: ** {F13011} The [sqlite3_prepare(db,zSql,...)] and
! 2206: ** [sqlite3_prepare_v2(db,zSql,...)] interfaces interpret the
! 2207: ** text in their zSql parameter as UTF-8.
! 2208: **
! 2209: ** {F13012} The [sqlite3_prepare16(db,zSql,...)] and
! 2210: ** [sqlite3_prepare16_v2(db,zSql,...)] interfaces interpret the
! 2211: ** text in their zSql parameter as UTF-16 in the native byte order.
! 2212: **
! 2213: ** {F13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)]
! 2214: ** and its variants is less than zero, then SQL text is
! 2215: ** read from zSql is read up to the first zero terminator.
! 2216: **
! 2217: ** {F13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)]
! 2218: ** and its variants is non-negative, then nBytes bytes
! 2219: ** SQL text is read from zSql.
! 2220: **
! 2221: ** {F13015} In [sqlite3_prepare_v2(db,zSql,N,P,pzTail)] and its variants
! 2222: ** if the zSql input text contains more than one SQL statement
! 2223: ** and pzTail is not NULL, then *pzTail is made to point to the
! 2224: ** first byte past the end of the first SQL statement in zSql.
! 2225: ** <todo>What does *pzTail point to if there is one statement?</todo>
! 2226: **
! 2227: ** {F13016} A successful call to [sqlite3_prepare_v2(db,zSql,N,ppStmt,...)]
! 2228: ** or one of its variants writes into *ppStmt a pointer to a new
! 2229: ** [prepared statement] or a pointer to NULL
! 2230: ** if zSql contains nothing other than whitespace or comments.
! 2231: **
! 2232: ** {F13019} The [sqlite3_prepare_v2()] interface and its variants return
! 2233: ** [SQLITE_OK] or an appropriate [error code] upon failure.
! 2234: **
! 2235: ** {F13021} Before [sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail)] or its
! 2236: ** variants returns an error (any value other than [SQLITE_OK])
! 2237: ** it first sets *ppStmt to NULL.
1.1 misha 2238: */
2239: int sqlite3_prepare(
2240: sqlite3 *db, /* Database handle */
2241: const char *zSql, /* SQL statement, UTF-8 encoded */
1.2 misha 2242: int nByte, /* Maximum length of zSql in bytes. */
2243: sqlite3_stmt **ppStmt, /* OUT: Statement handle */
2244: const char **pzTail /* OUT: Pointer to unused portion of zSql */
2245: );
2246: int sqlite3_prepare_v2(
2247: sqlite3 *db, /* Database handle */
2248: const char *zSql, /* SQL statement, UTF-8 encoded */
2249: int nByte, /* Maximum length of zSql in bytes. */
1.1 misha 2250: sqlite3_stmt **ppStmt, /* OUT: Statement handle */
2251: const char **pzTail /* OUT: Pointer to unused portion of zSql */
2252: );
2253: int sqlite3_prepare16(
2254: sqlite3 *db, /* Database handle */
2255: const void *zSql, /* SQL statement, UTF-16 encoded */
1.2 misha 2256: int nByte, /* Maximum length of zSql in bytes. */
2257: sqlite3_stmt **ppStmt, /* OUT: Statement handle */
2258: const void **pzTail /* OUT: Pointer to unused portion of zSql */
2259: );
2260: int sqlite3_prepare16_v2(
2261: sqlite3 *db, /* Database handle */
2262: const void *zSql, /* SQL statement, UTF-16 encoded */
2263: int nByte, /* Maximum length of zSql in bytes. */
1.1 misha 2264: sqlite3_stmt **ppStmt, /* OUT: Statement handle */
2265: const void **pzTail /* OUT: Pointer to unused portion of zSql */
2266: );
2267:
2268: /*
1.4 ! misha 2269: ** CAPIREF: Retrieving Statement SQL {F13100}
! 2270: **
! 2271: ** This intereface can be used to retrieve a saved copy of the original
! 2272: ** SQL text used to create a [prepared statement].
! 2273: **
! 2274: ** INVARIANTS:
! 2275: **
! 2276: ** {F13101} If the [prepared statement] passed as
! 2277: ** the an argument to [sqlite3_sql()] was compiled
! 2278: ** compiled using either [sqlite3_prepare_v2()] or
! 2279: ** [sqlite3_prepare16_v2()],
! 2280: ** then [sqlite3_sql()] function returns a pointer to a
! 2281: ** zero-terminated string containing a UTF-8 rendering
! 2282: ** of the original SQL statement.
! 2283: **
! 2284: ** {F13102} If the [prepared statement] passed as
! 2285: ** the an argument to [sqlite3_sql()] was compiled
! 2286: ** compiled using either [sqlite3_prepare()] or
! 2287: ** [sqlite3_prepare16()],
! 2288: ** then [sqlite3_sql()] function returns a NULL pointer.
! 2289: **
! 2290: ** {F13103} The string returned by [sqlite3_sql(S)] is valid until the
! 2291: ** [prepared statement] S is deleted using [sqlite3_finalize(S)].
! 2292: */
! 2293: const char *sqlite3_sql(sqlite3_stmt *pStmt);
! 2294:
! 2295: /*
! 2296: ** CAPI3REF: Dynamically Typed Value Object {F15000}
1.2 misha 2297: **
1.4 ! misha 2298: ** SQLite uses the sqlite3_value object to represent all values
! 2299: ** that are or can be stored in a database table.
! 2300: ** SQLite uses dynamic typing for the values it stores.
! 2301: ** Values stored in sqlite3_value objects can be
! 2302: ** be integers, floating point values, strings, BLOBs, or NULL.
1.2 misha 2303: */
2304: typedef struct Mem sqlite3_value;
2305:
2306: /*
1.4 ! misha 2307: ** CAPI3REF: SQL Function Context Object {F16001}
1.2 misha 2308: **
2309: ** The context in which an SQL function executes is stored in an
1.4 ! misha 2310: ** sqlite3_context object. A pointer to an sqlite3_context
! 2311: ** object is always first parameter to application-defined SQL functions.
1.1 misha 2312: */
2313: typedef struct sqlite3_context sqlite3_context;
2314:
2315: /*
1.4 ! misha 2316: ** CAPI3REF: Binding Values To Prepared Statements {F13500}
1.2 misha 2317: **
1.4 ! misha 2318: ** In the SQL strings input to [sqlite3_prepare_v2()] and its
! 2319: ** variants, literals may be replace by a parameter in one
! 2320: ** of these forms:
1.2 misha 2321: **
2322: ** <ul>
2323: ** <li> ?
2324: ** <li> ?NNN
1.4 ! misha 2325: ** <li> :VVV
! 2326: ** <li> @VVV
1.2 misha 2327: ** <li> $VVV
2328: ** </ul>
2329: **
2330: ** In the parameter forms shown above NNN is an integer literal,
1.4 ! misha 2331: ** VVV alpha-numeric parameter name.
! 2332: ** The values of these parameters (also called "host parameter names"
! 2333: ** or "SQL parameters")
1.2 misha 2334: ** can be set using the sqlite3_bind_*() routines defined here.
2335: **
1.4 ! misha 2336: ** The first argument to the sqlite3_bind_*() routines always
! 2337: ** is a pointer to the [sqlite3_stmt] object returned from
! 2338: ** [sqlite3_prepare_v2()] or its variants. The second
! 2339: ** argument is the index of the parameter to be set. The
! 2340: ** first parameter has an index of 1. When the same named
! 2341: ** parameter is used more than once, second and subsequent
! 2342: ** occurrences have the same index as the first occurrence.
! 2343: ** The index for named parameters can be looked up using the
! 2344: ** [sqlite3_bind_parameter_name()] API if desired. The index
! 2345: ** for "?NNN" parameters is the value of NNN.
1.2 misha 2346: ** The NNN value must be between 1 and the compile-time
2347: ** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999).
2348: **
2349: ** The third argument is the value to bind to the parameter.
2350: **
2351: ** In those
2352: ** routines that have a fourth argument, its value is the number of bytes
1.4 ! misha 2353: ** in the parameter. To be clear: the value is the number of <u>bytes</u>
! 2354: ** in the value, not the number of characters. The number
1.2 misha 2355: ** of bytes does not include the zero-terminator at the end of strings.
2356: ** If the fourth parameter is negative, the length of the string is
2357: ** number of bytes up to the first zero terminator.
1.1 misha 2358: **
1.2 misha 2359: ** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
1.1 misha 2360: ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
1.4 ! misha 2361: ** string after SQLite has finished with it. If the fifth argument is
! 2362: ** the special value [SQLITE_STATIC], then SQLite assumes that the
! 2363: ** information is in static, unmanaged space and does not need to be freed.
! 2364: ** If the fifth argument has the value [SQLITE_TRANSIENT], then
! 2365: ** SQLite makes its own private copy of the data immediately, before
! 2366: ** the sqlite3_bind_*() routine returns.
1.2 misha 2367: **
1.4 ! misha 2368: ** The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
1.2 misha 2369: ** is filled with zeros. A zeroblob uses a fixed amount of memory
2370: ** (just an integer to hold it size) while it is being processed.
2371: ** Zeroblobs are intended to serve as place-holders for BLOBs whose
2372: ** content is later written using
1.4 ! misha 2373: ** [sqlite3_blob_open | increment BLOB I/O] routines. A negative
1.2 misha 2374: ** value for the zeroblob results in a zero-length BLOB.
2375: **
2376: ** The sqlite3_bind_*() routines must be called after
2377: ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and
2378: ** before [sqlite3_step()].
2379: ** Bindings are not cleared by the [sqlite3_reset()] routine.
2380: ** Unbound parameters are interpreted as NULL.
2381: **
2382: ** These routines return [SQLITE_OK] on success or an error code if
2383: ** anything goes wrong. [SQLITE_RANGE] is returned if the parameter
2384: ** index is out of range. [SQLITE_NOMEM] is returned if malloc fails.
1.4 ! misha 2385: ** [SQLITE_MISUSE] might be returned if these routines are called on a
! 2386: ** virtual machine that is the wrong state or which has already been finalized.
! 2387: ** Detection of misuse is unreliable. Applications should not depend
! 2388: ** on SQLITE_MISUSE returns. SQLITE_MISUSE is intended to indicate a
! 2389: ** a logic error in the application. Future versions of SQLite might
! 2390: ** panic rather than return SQLITE_MISUSE.
! 2391: **
! 2392: ** See also: [sqlite3_bind_parameter_count()],
! 2393: ** [sqlite3_bind_parameter_name()], and
! 2394: ** [sqlite3_bind_parameter_index()].
! 2395: **
! 2396: ** INVARIANTS:
! 2397: **
! 2398: ** {F13506} The [sqlite3_prepare | SQL statement compiler] recognizes
! 2399: ** tokens of the forms "?", "?NNN", "$VVV", ":VVV", and "@VVV"
! 2400: ** as SQL parameters, where NNN is any sequence of one or more
! 2401: ** digits and where VVV is any sequence of one or more
! 2402: ** alphanumeric characters or "::" optionally followed by
! 2403: ** a string containing no spaces and contained within parentheses.
! 2404: **
! 2405: ** {F13509} The initial value of an SQL parameter is NULL.
! 2406: **
! 2407: ** {F13512} The index of an "?" SQL parameter is one larger than the
! 2408: ** largest index of SQL parameter to the left, or 1 if
! 2409: ** the "?" is the leftmost SQL parameter.
! 2410: **
! 2411: ** {F13515} The index of an "?NNN" SQL parameter is the integer NNN.
! 2412: **
! 2413: ** {F13518} The index of an ":VVV", "$VVV", or "@VVV" SQL parameter is
! 2414: ** the same as the index of leftmost occurances of the same
! 2415: ** parameter, or one more than the largest index over all
! 2416: ** parameters to the left if this is the first occurrance
! 2417: ** of this parameter, or 1 if this is the leftmost parameter.
! 2418: **
! 2419: ** {F13521} The [sqlite3_prepare | SQL statement compiler] fail with
! 2420: ** an [SQLITE_RANGE] error if the index of an SQL parameter
! 2421: ** is less than 1 or greater than SQLITE_MAX_VARIABLE_NUMBER.
! 2422: **
! 2423: ** {F13524} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,V,...)]
! 2424: ** associate the value V with all SQL parameters having an
! 2425: ** index of N in the [prepared statement] S.
! 2426: **
! 2427: ** {F13527} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,...)]
! 2428: ** override prior calls with the same values of S and N.
! 2429: **
! 2430: ** {F13530} Bindings established by [sqlite3_bind_text | sqlite3_bind(S,...)]
! 2431: ** persist across calls to [sqlite3_reset(S)].
! 2432: **
! 2433: ** {F13533} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
! 2434: ** [sqlite3_bind_text(S,N,V,L,D)], or
! 2435: ** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds the first L
! 2436: ** bytes of the blob or string pointed to by V, when L
! 2437: ** is non-negative.
! 2438: **
! 2439: ** {F13536} In calls to [sqlite3_bind_text(S,N,V,L,D)] or
! 2440: ** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds characters
! 2441: ** from V through the first zero character when L is negative.
! 2442: **
! 2443: ** {F13539} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
! 2444: ** [sqlite3_bind_text(S,N,V,L,D)], or
! 2445: ** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special
! 2446: ** constant [SQLITE_STATIC], SQLite assumes that the value V
! 2447: ** is held in static unmanaged space that will not change
! 2448: ** during the lifetime of the binding.
! 2449: **
! 2450: ** {F13542} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
! 2451: ** [sqlite3_bind_text(S,N,V,L,D)], or
! 2452: ** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special
! 2453: ** constant [SQLITE_TRANSIENT], the routine makes a
! 2454: ** private copy of V value before it returns.
! 2455: **
! 2456: ** {F13545} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
! 2457: ** [sqlite3_bind_text(S,N,V,L,D)], or
! 2458: ** [sqlite3_bind_text16(S,N,V,L,D)] when D is a pointer to
! 2459: ** a function, SQLite invokes that function to destroy the
! 2460: ** V value after it has finished using the V value.
! 2461: **
! 2462: ** {F13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound
! 2463: ** is a blob of L bytes, or a zero-length blob if L is negative.
1.1 misha 2464: */
2465: int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
2466: int sqlite3_bind_double(sqlite3_stmt*, int, double);
2467: int sqlite3_bind_int(sqlite3_stmt*, int, int);
1.2 misha 2468: int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
1.1 misha 2469: int sqlite3_bind_null(sqlite3_stmt*, int);
2470: int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
2471: int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
2472: int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
1.2 misha 2473: int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
1.1 misha 2474:
2475: /*
1.4 ! misha 2476: ** CAPI3REF: Number Of SQL Parameters {F13600}
1.2 misha 2477: **
1.4 ! misha 2478: ** This routine can be used to find the number of SQL parameters
! 2479: ** in a prepared statement. SQL parameters are tokens of the
! 2480: ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
! 2481: ** place-holders for values that are [sqlite3_bind_blob | bound]
! 2482: ** to the parameters at a later time.
! 2483: **
! 2484: ** This routine actually returns the index of the largest parameter.
! 2485: ** For all forms except ?NNN, this will correspond to the number of
! 2486: ** unique parameters. If parameters of the ?NNN are used, there may
! 2487: ** be gaps in the list.
! 2488: **
! 2489: ** See also: [sqlite3_bind_blob|sqlite3_bind()],
! 2490: ** [sqlite3_bind_parameter_name()], and
! 2491: ** [sqlite3_bind_parameter_index()].
! 2492: **
! 2493: ** INVARIANTS:
! 2494: **
! 2495: ** {F13601} The [sqlite3_bind_parameter_count(S)] interface returns
! 2496: ** the largest index of all SQL parameters in the
! 2497: ** [prepared statement] S, or 0 if S
! 2498: ** contains no SQL parameters.
1.1 misha 2499: */
2500: int sqlite3_bind_parameter_count(sqlite3_stmt*);
2501:
2502: /*
1.4 ! misha 2503: ** CAPI3REF: Name Of A Host Parameter {F13620}
1.2 misha 2504: **
1.4 ! misha 2505: ** This routine returns a pointer to the name of the n-th
! 2506: ** SQL parameter in a [prepared statement].
! 2507: ** SQL parameters of the form ":AAA" or "@AAA" or "$AAA" have a name
! 2508: ** which is the string ":AAA" or "@AAA" or "$VVV".
1.2 misha 2509: ** In other words, the initial ":" or "$" or "@"
2510: ** is included as part of the name.
2511: ** Parameters of the form "?" or "?NNN" have no name.
2512: **
1.4 ! misha 2513: ** The first host parameter has an index of 1, not 0.
1.2 misha 2514: **
1.4 ! misha 2515: ** If the value n is out of range or if the n-th parameter is
! 2516: ** nameless, then NULL is returned. The returned string is
! 2517: ** always in the UTF-8 encoding even if the named parameter was
! 2518: ** originally specified as UTF-16 in [sqlite3_prepare16()] or
! 2519: ** [sqlite3_prepare16_v2()].
! 2520: **
! 2521: ** See also: [sqlite3_bind_blob|sqlite3_bind()],
! 2522: ** [sqlite3_bind_parameter_count()], and
! 2523: ** [sqlite3_bind_parameter_index()].
! 2524: **
! 2525: ** INVARIANTS:
! 2526: **
! 2527: ** {F13621} The [sqlite3_bind_parameter_name(S,N)] interface returns
! 2528: ** a UTF-8 rendering of the name of the SQL parameter in
! 2529: ** [prepared statement] S having index N, or
! 2530: ** NULL if there is no SQL parameter with index N or if the
! 2531: ** parameter with index N is an anonymous parameter "?" or
! 2532: ** a numbered parameter "?NNN".
1.1 misha 2533: */
2534: const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
2535:
2536: /*
1.4 ! misha 2537: ** CAPI3REF: Index Of A Parameter With A Given Name {F13640}
1.2 misha 2538: **
1.4 ! misha 2539: ** Return the index of an SQL parameter given its name. The
! 2540: ** index value returned is suitable for use as the second
! 2541: ** parameter to [sqlite3_bind_blob|sqlite3_bind()]. A zero
! 2542: ** is returned if no matching parameter is found. The parameter
! 2543: ** name must be given in UTF-8 even if the original statement
! 2544: ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].
! 2545: **
! 2546: ** See also: [sqlite3_bind_blob|sqlite3_bind()],
! 2547: ** [sqlite3_bind_parameter_count()], and
! 2548: ** [sqlite3_bind_parameter_index()].
! 2549: **
! 2550: ** INVARIANTS:
! 2551: **
! 2552: ** {F13641} The [sqlite3_bind_parameter_index(S,N)] interface returns
! 2553: ** the index of SQL parameter in [prepared statement]
! 2554: ** S whose name matches the UTF-8 string N, or 0 if there is
! 2555: ** no match.
1.1 misha 2556: */
2557: int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
2558:
2559: /*
1.4 ! misha 2560: ** CAPI3REF: Reset All Bindings On A Prepared Statement {F13660}
1.2 misha 2561: **
2562: ** Contrary to the intuition of many, [sqlite3_reset()] does not
2563: ** reset the [sqlite3_bind_blob | bindings] on a
1.4 ! misha 2564: ** [prepared statement]. Use this routine to
1.2 misha 2565: ** reset all host parameters to NULL.
1.4 ! misha 2566: **
! 2567: ** INVARIANTS:
! 2568: **
! 2569: ** {F13661} The [sqlite3_clear_bindings(S)] interface resets all
! 2570: ** SQL parameter bindings in [prepared statement] S
! 2571: ** back to NULL.
1.1 misha 2572: */
1.2 misha 2573: int sqlite3_clear_bindings(sqlite3_stmt*);
1.1 misha 2574:
2575: /*
1.4 ! misha 2576: ** CAPI3REF: Number Of Columns In A Result Set {F13710}
1.2 misha 2577: **
2578: ** Return the number of columns in the result set returned by the
1.4 ! misha 2579: ** [prepared statement]. This routine returns 0
1.2 misha 2580: ** if pStmt is an SQL statement that does not return data (for
2581: ** example an UPDATE).
1.4 ! misha 2582: **
! 2583: ** INVARIANTS:
! 2584: **
! 2585: ** {F13711} The [sqlite3_column_count(S)] interface returns the number of
! 2586: ** columns in the result set generated by the
! 2587: ** [prepared statement] S, or 0 if S does not generate
! 2588: ** a result set.
1.2 misha 2589: */
2590: int sqlite3_column_count(sqlite3_stmt *pStmt);
1.1 misha 2591:
2592: /*
1.4 ! misha 2593: ** CAPI3REF: Column Names In A Result Set {F13720}
1.2 misha 2594: **
2595: ** These routines return the name assigned to a particular column
2596: ** in the result set of a SELECT statement. The sqlite3_column_name()
1.4 ! misha 2597: ** interface returns a pointer to a zero-terminated UTF8 string
! 2598: ** and sqlite3_column_name16() returns a pointer to a zero-terminated
! 2599: ** UTF16 string. The first parameter is the
! 2600: ** [prepared statement] that implements the SELECT statement.
1.2 misha 2601: ** The second parameter is the column number. The left-most column is
2602: ** number 0.
2603: **
2604: ** The returned string pointer is valid until either the
1.4 ! misha 2605: ** [prepared statement] is destroyed by [sqlite3_finalize()]
1.2 misha 2606: ** or until the next call sqlite3_column_name() or sqlite3_column_name16()
2607: ** on the same column.
2608: **
2609: ** If sqlite3_malloc() fails during the processing of either routine
2610: ** (for example during a conversion from UTF-8 to UTF-16) then a
2611: ** NULL pointer is returned.
1.4 ! misha 2612: **
! 2613: ** The name of a result column is the value of the "AS" clause for
! 2614: ** that column, if there is an AS clause. If there is no AS clause
! 2615: ** then the name of the column is unspecified and may change from
! 2616: ** one release of SQLite to the next.
! 2617: **
! 2618: ** INVARIANTS:
! 2619: **
! 2620: ** {F13721} A successful invocation of the [sqlite3_column_name(S,N)]
! 2621: ** interface returns the name
! 2622: ** of the Nth column (where 0 is the left-most column) for the
! 2623: ** result set of [prepared statement] S as a
! 2624: ** zero-terminated UTF-8 string.
! 2625: **
! 2626: ** {F13723} A successful invocation of the [sqlite3_column_name16(S,N)]
! 2627: ** interface returns the name
! 2628: ** of the Nth column (where 0 is the left-most column) for the
! 2629: ** result set of [prepared statement] S as a
! 2630: ** zero-terminated UTF-16 string in the native byte order.
! 2631: **
! 2632: ** {F13724} The [sqlite3_column_name()] and [sqlite3_column_name16()]
! 2633: ** interfaces return a NULL pointer if they are unable to
! 2634: ** allocate memory memory to hold there normal return strings.
! 2635: **
! 2636: ** {F13725} If the N parameter to [sqlite3_column_name(S,N)] or
! 2637: ** [sqlite3_column_name16(S,N)] is out of range, then the
! 2638: ** interfaces returns a NULL pointer.
! 2639: **
! 2640: ** {F13726} The strings returned by [sqlite3_column_name(S,N)] and
! 2641: ** [sqlite3_column_name16(S,N)] are valid until the next
! 2642: ** call to either routine with the same S and N parameters
! 2643: ** or until [sqlite3_finalize(S)] is called.
! 2644: **
! 2645: ** {F13727} When a result column of a [SELECT] statement contains
! 2646: ** an AS clause, the name of that column is the indentifier
! 2647: ** to the right of the AS keyword.
1.2 misha 2648: */
2649: const char *sqlite3_column_name(sqlite3_stmt*, int N);
2650: const void *sqlite3_column_name16(sqlite3_stmt*, int N);
2651:
2652: /*
1.4 ! misha 2653: ** CAPI3REF: Source Of Data In A Query Result {F13740}
1.2 misha 2654: **
2655: ** These routines provide a means to determine what column of what
2656: ** table in which database a result of a SELECT statement comes from.
2657: ** The name of the database or table or column can be returned as
2658: ** either a UTF8 or UTF16 string. The _database_ routines return
2659: ** the database name, the _table_ routines return the table name, and
2660: ** the origin_ routines return the column name.
2661: ** The returned string is valid until
1.4 ! misha 2662: ** the [prepared statement] is destroyed using
1.2 misha 2663: ** [sqlite3_finalize()] or until the same information is requested
2664: ** again in a different encoding.
2665: **
2666: ** The names returned are the original un-aliased names of the
2667: ** database, table, and column.
2668: **
1.4 ! misha 2669: ** The first argument to the following calls is a [prepared statement].
1.2 misha 2670: ** These functions return information about the Nth column returned by
2671: ** the statement, where N is the second function argument.
2672: **
2673: ** If the Nth column returned by the statement is an expression
2674: ** or subquery and is not a column value, then all of these functions
1.4 ! misha 2675: ** return NULL. These routine might also return NULL if a memory
! 2676: ** allocation error occurs. Otherwise, they return the
1.2 misha 2677: ** name of the attached database, table and column that query result
2678: ** column was extracted from.
2679: **
1.4 ! misha 2680: ** As with all other SQLite APIs, those postfixed with "16" return
! 2681: ** UTF-16 encoded strings, the other functions return UTF-8. {END}
1.2 misha 2682: **
2683: ** These APIs are only available if the library was compiled with the
2684: ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
2685: **
1.4 ! misha 2686: ** {U13751}
1.2 misha 2687: ** If two or more threads call one or more of these routines against the same
2688: ** prepared statement and column at the same time then the results are
2689: ** undefined.
1.4 ! misha 2690: **
! 2691: ** INVARIANTS:
! 2692: **
! 2693: ** {F13741} The [sqlite3_column_database_name(S,N)] interface returns either
! 2694: ** the UTF-8 zero-terminated name of the database from which the
! 2695: ** Nth result column of [prepared statement] S
! 2696: ** is extracted, or NULL if the the Nth column of S is a
! 2697: ** general expression or if unable to allocate memory
! 2698: ** to store the name.
! 2699: **
! 2700: ** {F13742} The [sqlite3_column_database_name16(S,N)] interface returns either
! 2701: ** the UTF-16 native byte order
! 2702: ** zero-terminated name of the database from which the
! 2703: ** Nth result column of [prepared statement] S
! 2704: ** is extracted, or NULL if the the Nth column of S is a
! 2705: ** general expression or if unable to allocate memory
! 2706: ** to store the name.
! 2707: **
! 2708: ** {F13743} The [sqlite3_column_table_name(S,N)] interface returns either
! 2709: ** the UTF-8 zero-terminated name of the table from which the
! 2710: ** Nth result column of [prepared statement] S
! 2711: ** is extracted, or NULL if the the Nth column of S is a
! 2712: ** general expression or if unable to allocate memory
! 2713: ** to store the name.
! 2714: **
! 2715: ** {F13744} The [sqlite3_column_table_name16(S,N)] interface returns either
! 2716: ** the UTF-16 native byte order
! 2717: ** zero-terminated name of the table from which the
! 2718: ** Nth result column of [prepared statement] S
! 2719: ** is extracted, or NULL if the the Nth column of S is a
! 2720: ** general expression or if unable to allocate memory
! 2721: ** to store the name.
! 2722: **
! 2723: ** {F13745} The [sqlite3_column_origin_name(S,N)] interface returns either
! 2724: ** the UTF-8 zero-terminated name of the table column from which the
! 2725: ** Nth result column of [prepared statement] S
! 2726: ** is extracted, or NULL if the the Nth column of S is a
! 2727: ** general expression or if unable to allocate memory
! 2728: ** to store the name.
! 2729: **
! 2730: ** {F13746} The [sqlite3_column_origin_name16(S,N)] interface returns either
! 2731: ** the UTF-16 native byte order
! 2732: ** zero-terminated name of the table column from which the
! 2733: ** Nth result column of [prepared statement] S
! 2734: ** is extracted, or NULL if the the Nth column of S is a
! 2735: ** general expression or if unable to allocate memory
! 2736: ** to store the name.
! 2737: **
! 2738: ** {F13748} The return values from
! 2739: ** [sqlite3_column_database_name|column metadata interfaces]
! 2740: ** are valid
! 2741: ** for the lifetime of the [prepared statement]
! 2742: ** or until the encoding is changed by another metadata
! 2743: ** interface call for the same prepared statement and column.
! 2744: **
! 2745: ** LIMITATIONS:
! 2746: **
! 2747: ** {U13751} If two or more threads call one or more
! 2748: ** [sqlite3_column_database_name|column metadata interfaces]
! 2749: ** the same [prepared statement] and result column
! 2750: ** at the same time then the results are undefined.
1.2 misha 2751: */
2752: const char *sqlite3_column_database_name(sqlite3_stmt*,int);
2753: const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
2754: const char *sqlite3_column_table_name(sqlite3_stmt*,int);
2755: const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
2756: const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
2757: const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
2758:
2759: /*
1.4 ! misha 2760: ** CAPI3REF: Declared Datatype Of A Query Result {F13760}
1.2 misha 2761: **
1.4 ! misha 2762: ** The first parameter is a [prepared statement].
1.2 misha 2763: ** If this statement is a SELECT statement and the Nth column of the
1.4 ! misha 2764: ** returned result set of that SELECT is a table column (not an
1.2 misha 2765: ** expression or subquery) then the declared type of the table
1.4 ! misha 2766: ** column is returned. If the Nth column of the result set is an
1.2 misha 2767: ** expression or subquery, then a NULL pointer is returned.
1.4 ! misha 2768: ** The returned string is always UTF-8 encoded. {END}
! 2769: ** For example, in the database schema:
1.1 misha 2770: **
2771: ** CREATE TABLE t1(c1 VARIANT);
2772: **
2773: ** And the following statement compiled:
2774: **
1.2 misha 2775: ** SELECT c1 + 1, c1 FROM t1;
1.1 misha 2776: **
2777: ** Then this routine would return the string "VARIANT" for the second
2778: ** result column (i==1), and a NULL pointer for the first result column
2779: ** (i==0).
1.2 misha 2780: **
2781: ** SQLite uses dynamic run-time typing. So just because a column
2782: ** is declared to contain a particular type does not mean that the
2783: ** data stored in that column is of the declared type. SQLite is
2784: ** strongly typed, but the typing is dynamic not static. Type
2785: ** is associated with individual values, not with the containers
2786: ** used to hold those values.
1.4 ! misha 2787: **
! 2788: ** INVARIANTS:
! 2789: **
! 2790: ** {F13761} A successful call to [sqlite3_column_decltype(S,N)]
! 2791: ** returns a zero-terminated UTF-8 string containing the
! 2792: ** the declared datatype of the table column that appears
! 2793: ** as the Nth column (numbered from 0) of the result set to the
! 2794: ** [prepared statement] S.
! 2795: **
! 2796: ** {F13762} A successful call to [sqlite3_column_decltype16(S,N)]
! 2797: ** returns a zero-terminated UTF-16 native byte order string
! 2798: ** containing the declared datatype of the table column that appears
! 2799: ** as the Nth column (numbered from 0) of the result set to the
! 2800: ** [prepared statement] S.
! 2801: **
! 2802: ** {F13763} If N is less than 0 or N is greater than or equal to
! 2803: ** the number of columns in [prepared statement] S
! 2804: ** or if the Nth column of S is an expression or subquery rather
! 2805: ** than a table column or if a memory allocation failure
! 2806: ** occurs during encoding conversions, then
! 2807: ** calls to [sqlite3_column_decltype(S,N)] or
! 2808: ** [sqlite3_column_decltype16(S,N)] return NULL.
1.1 misha 2809: */
1.4 ! misha 2810: const char *sqlite3_column_decltype(sqlite3_stmt*,int);
1.1 misha 2811: const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
2812:
2813: /*
1.4 ! misha 2814: ** CAPI3REF: Evaluate An SQL Statement {F13200}
1.2 misha 2815: **
1.4 ! misha 2816: ** After an [prepared statement] has been prepared with a call
1.2 misha 2817: ** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of
2818: ** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()],
2819: ** then this function must be called one or more times to evaluate the
2820: ** statement.
2821: **
2822: ** The details of the behavior of this sqlite3_step() interface depend
2823: ** on whether the statement was prepared using the newer "v2" interface
2824: ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
2825: ** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the
2826: ** new "v2" interface is recommended for new applications but the legacy
2827: ** interface will continue to be supported.
2828: **
2829: ** In the lagacy interface, the return value will be either [SQLITE_BUSY],
2830: ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
2831: ** With the "v2" interface, any of the other [SQLITE_OK | result code]
2832: ** or [SQLITE_IOERR_READ | extended result code] might be returned as
2833: ** well.
2834: **
2835: ** [SQLITE_BUSY] means that the database engine was unable to acquire the
2836: ** database locks it needs to do its job. If the statement is a COMMIT
2837: ** or occurs outside of an explicit transaction, then you can retry the
2838: ** statement. If the statement is not a COMMIT and occurs within a
2839: ** explicit transaction then you should rollback the transaction before
2840: ** continuing.
1.1 misha 2841: **
1.2 misha 2842: ** [SQLITE_DONE] means that the statement has finished executing
1.1 misha 2843: ** successfully. sqlite3_step() should not be called again on this virtual
1.2 misha 2844: ** machine without first calling [sqlite3_reset()] to reset the virtual
2845: ** machine back to its initial state.
1.1 misha 2846: **
2847: ** If the SQL statement being executed returns any data, then
1.2 misha 2848: ** [SQLITE_ROW] is returned each time a new row of data is ready
1.1 misha 2849: ** for processing by the caller. The values may be accessed using
1.2 misha 2850: ** the [sqlite3_column_int | column access functions].
2851: ** sqlite3_step() is called again to retrieve the next row of data.
1.1 misha 2852: **
1.2 misha 2853: ** [SQLITE_ERROR] means that a run-time error (such as a constraint
1.1 misha 2854: ** violation) has occurred. sqlite3_step() should not be called again on
1.2 misha 2855: ** the VM. More information may be found by calling [sqlite3_errmsg()].
2856: ** With the legacy interface, a more specific error code (example:
2857: ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
2858: ** can be obtained by calling [sqlite3_reset()] on the
1.4 ! misha 2859: ** [prepared statement]. In the "v2" interface,
1.2 misha 2860: ** the more specific error code is returned directly by sqlite3_step().
2861: **
2862: ** [SQLITE_MISUSE] means that the this routine was called inappropriately.
1.4 ! misha 2863: ** Perhaps it was called on a [prepared statement] that has
1.2 misha 2864: ** already been [sqlite3_finalize | finalized] or on one that had
2865: ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could
2866: ** be the case that the same database connection is being used by two or
2867: ** more threads at the same moment in time.
2868: **
2869: ** <b>Goofy Interface Alert:</b>
2870: ** In the legacy interface,
2871: ** the sqlite3_step() API always returns a generic error code,
2872: ** [SQLITE_ERROR], following any error other than [SQLITE_BUSY]
2873: ** and [SQLITE_MISUSE]. You must call [sqlite3_reset()] or
2874: ** [sqlite3_finalize()] in order to find one of the specific
1.4 ! misha 2875: ** [error codes] that better describes the error.
1.2 misha 2876: ** We admit that this is a goofy design. The problem has been fixed
2877: ** with the "v2" interface. If you prepare all of your SQL statements
2878: ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
2879: ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the
1.4 ! misha 2880: ** more specific [error codes] are returned directly
1.2 misha 2881: ** by sqlite3_step(). The use of the "v2" interface is recommended.
1.4 ! misha 2882: **
! 2883: ** INVARIANTS:
! 2884: **
! 2885: ** {F13202} If [prepared statement] S is ready to be
! 2886: ** run, then [sqlite3_step(S)] advances that prepared statement
! 2887: ** until to completion or until it is ready to return another
! 2888: ** row of the result set or an interrupt or run-time error occurs.
! 2889: **
! 2890: ** {F15304} When a call to [sqlite3_step(S)] causes the
! 2891: ** [prepared statement] S to run to completion,
! 2892: ** the function returns [SQLITE_DONE].
! 2893: **
! 2894: ** {F15306} When a call to [sqlite3_step(S)] stops because it is ready
! 2895: ** to return another row of the result set, it returns
! 2896: ** [SQLITE_ROW].
! 2897: **
! 2898: ** {F15308} If a call to [sqlite3_step(S)] encounters an
! 2899: ** [sqlite3_interrupt|interrupt] or a run-time error,
! 2900: ** it returns an appropraite error code that is not one of
! 2901: ** [SQLITE_OK], [SQLITE_ROW], or [SQLITE_DONE].
! 2902: **
! 2903: ** {F15310} If an [sqlite3_interrupt|interrupt] or run-time error
! 2904: ** occurs during a call to [sqlite3_step(S)]
! 2905: ** for a [prepared statement] S created using
! 2906: ** legacy interfaces [sqlite3_prepare()] or
! 2907: ** [sqlite3_prepare16()] then the function returns either
! 2908: ** [SQLITE_ERROR], [SQLITE_BUSY], or [SQLITE_MISUSE].
1.1 misha 2909: */
2910: int sqlite3_step(sqlite3_stmt*);
2911:
2912: /*
1.4 ! misha 2913: ** CAPI3REF: Number of columns in a result set {F13770}
1.2 misha 2914: **
1.1 misha 2915: ** Return the number of values in the current row of the result set.
2916: **
1.4 ! misha 2917: ** INVARIANTS:
! 2918: **
! 2919: ** {F13771} After a call to [sqlite3_step(S)] that returns
! 2920: ** [SQLITE_ROW], the [sqlite3_data_count(S)] routine
! 2921: ** will return the same value as the
! 2922: ** [sqlite3_column_count(S)] function.
! 2923: **
! 2924: ** {F13772} After [sqlite3_step(S)] has returned any value other than
! 2925: ** [SQLITE_ROW] or before [sqlite3_step(S)] has been
! 2926: ** called on the [prepared statement] for
! 2927: ** the first time since it was [sqlite3_prepare|prepared]
! 2928: ** or [sqlite3_reset|reset], the [sqlite3_data_count(S)]
! 2929: ** routine returns zero.
1.1 misha 2930: */
2931: int sqlite3_data_count(sqlite3_stmt *pStmt);
2932:
2933: /*
1.4 ! misha 2934: ** CAPI3REF: Fundamental Datatypes {F10265}
! 2935: ** KEYWORDS: SQLITE_TEXT
1.2 misha 2936: **
1.4 ! misha 2937: ** {F10266}Every value in SQLite has one of five fundamental datatypes:
1.2 misha 2938: **
2939: ** <ul>
2940: ** <li> 64-bit signed integer
2941: ** <li> 64-bit IEEE floating point number
2942: ** <li> string
2943: ** <li> BLOB
2944: ** <li> NULL
1.4 ! misha 2945: ** </ul> {END}
1.2 misha 2946: **
2947: ** These constants are codes for each of those types.
2948: **
2949: ** Note that the SQLITE_TEXT constant was also used in SQLite version 2
2950: ** for a completely different meaning. Software that links against both
2951: ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT not
2952: ** SQLITE_TEXT.
1.1 misha 2953: */
2954: #define SQLITE_INTEGER 1
2955: #define SQLITE_FLOAT 2
2956: #define SQLITE_BLOB 4
2957: #define SQLITE_NULL 5
2958: #ifdef SQLITE_TEXT
2959: # undef SQLITE_TEXT
2960: #else
2961: # define SQLITE_TEXT 3
2962: #endif
2963: #define SQLITE3_TEXT 3
2964:
2965: /*
1.4 ! misha 2966: ** CAPI3REF: Results Values From A Query {F13800}
! 2967: **
! 2968: ** These routines form the "result set query" interface.
1.2 misha 2969: **
2970: ** These routines return information about
2971: ** a single column of the current result row of a query. In every
2972: ** case the first argument is a pointer to the
1.4 ! misha 2973: ** [prepared statement] that is being
1.2 misha 2974: ** evaluated (the [sqlite3_stmt*] that was returned from
2975: ** [sqlite3_prepare_v2()] or one of its variants) and
1.1 misha 2976: ** the second argument is the index of the column for which information
1.2 misha 2977: ** should be returned. The left-most column of the result set
2978: ** has an index of 0.
1.1 misha 2979: **
2980: ** If the SQL statement is not currently point to a valid row, or if the
1.2 misha 2981: ** the column index is out of range, the result is undefined.
2982: ** These routines may only be called when the most recent call to
2983: ** [sqlite3_step()] has returned [SQLITE_ROW] and neither
2984: ** [sqlite3_reset()] nor [sqlite3_finalize()] has been call subsequently.
2985: ** If any of these routines are called after [sqlite3_reset()] or
2986: ** [sqlite3_finalize()] or after [sqlite3_step()] has returned
2987: ** something other than [SQLITE_ROW], the results are undefined.
2988: ** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
2989: ** are called from a different thread while any of these routines
2990: ** are pending, then the results are undefined.
2991: **
2992: ** The sqlite3_column_type() routine returns
2993: ** [SQLITE_INTEGER | datatype code] for the initial data type
2994: ** of the result column. The returned value is one of [SQLITE_INTEGER],
2995: ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value
2996: ** returned by sqlite3_column_type() is only meaningful if no type
2997: ** conversions have occurred as described below. After a type conversion,
2998: ** the value returned by sqlite3_column_type() is undefined. Future
2999: ** versions of SQLite may change the behavior of sqlite3_column_type()
3000: ** following a type conversion.
3001: **
3002: ** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
3003: ** routine returns the number of bytes in that BLOB or string.
3004: ** If the result is a UTF-16 string, then sqlite3_column_bytes() converts
3005: ** the string to UTF-8 and then returns the number of bytes.
3006: ** If the result is a numeric value then sqlite3_column_bytes() uses
3007: ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
3008: ** the number of bytes in that string.
3009: ** The value returned does not include the zero terminator at the end
3010: ** of the string. For clarity: the value returned is the number of
3011: ** bytes in the string, not the number of characters.
3012: **
3013: ** Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
1.4 ! misha 3014: ** even empty strings, are always zero terminated. The return
1.2 misha 3015: ** value from sqlite3_column_blob() for a zero-length blob is an arbitrary
3016: ** pointer, possibly even a NULL pointer.
3017: **
3018: ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
1.4 ! misha 3019: ** but leaves the result in UTF-16 in native byte order instead of UTF-8.
1.2 misha 3020: ** The zero terminator is not included in this count.
1.1 misha 3021: **
3022: ** These routines attempt to convert the value where appropriate. For
3023: ** example, if the internal representation is FLOAT and a text result
1.2 misha 3024: ** is requested, [sqlite3_snprintf()] is used internally to do the conversion
1.1 misha 3025: ** automatically. The following table details the conversions that
3026: ** are applied:
3027: **
1.2 misha 3028: ** <blockquote>
3029: ** <table border="1">
3030: ** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion
3031: **
3032: ** <tr><td> NULL <td> INTEGER <td> Result is 0
3033: ** <tr><td> NULL <td> FLOAT <td> Result is 0.0
3034: ** <tr><td> NULL <td> TEXT <td> Result is NULL pointer
3035: ** <tr><td> NULL <td> BLOB <td> Result is NULL pointer
3036: ** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float
3037: ** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer
3038: ** <tr><td> INTEGER <td> BLOB <td> Same as for INTEGER->TEXT
3039: ** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer
3040: ** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float
3041: ** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT
3042: ** <tr><td> TEXT <td> INTEGER <td> Use atoi()
3043: ** <tr><td> TEXT <td> FLOAT <td> Use atof()
3044: ** <tr><td> TEXT <td> BLOB <td> No change
3045: ** <tr><td> BLOB <td> INTEGER <td> Convert to TEXT then use atoi()
3046: ** <tr><td> BLOB <td> FLOAT <td> Convert to TEXT then use atof()
3047: ** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed
3048: ** </table>
3049: ** </blockquote>
3050: **
3051: ** The table above makes reference to standard C library functions atoi()
3052: ** and atof(). SQLite does not really use these functions. It has its
3053: ** on equavalent internal routines. The atoi() and atof() names are
3054: ** used in the table for brevity and because they are familiar to most
3055: ** C programmers.
3056: **
3057: ** Note that when type conversions occur, pointers returned by prior
3058: ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
3059: ** sqlite3_column_text16() may be invalidated.
3060: ** Type conversions and pointer invalidations might occur
3061: ** in the following cases:
3062: **
3063: ** <ul>
3064: ** <li><p> The initial content is a BLOB and sqlite3_column_text()
3065: ** or sqlite3_column_text16() is called. A zero-terminator might
3066: ** need to be added to the string.</p></li>
3067: **
3068: ** <li><p> The initial content is UTF-8 text and sqlite3_column_bytes16() or
3069: ** sqlite3_column_text16() is called. The content must be converted
3070: ** to UTF-16.</p></li>
3071: **
3072: ** <li><p> The initial content is UTF-16 text and sqlite3_column_bytes() or
3073: ** sqlite3_column_text() is called. The content must be converted
3074: ** to UTF-8.</p></li>
3075: ** </ul>
3076: **
3077: ** Conversions between UTF-16be and UTF-16le are always done in place and do
3078: ** not invalidate a prior pointer, though of course the content of the buffer
3079: ** that the prior pointer points to will have been modified. Other kinds
3080: ** of conversion are done in place when it is possible, but sometime it is
3081: ** not possible and in those cases prior pointers are invalidated.
3082: **
3083: ** The safest and easiest to remember policy is to invoke these routines
3084: ** in one of the following ways:
3085: **
3086: ** <ul>
3087: ** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
3088: ** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
3089: ** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
3090: ** </ul>
3091: **
3092: ** In other words, you should call sqlite3_column_text(), sqlite3_column_blob(),
3093: ** or sqlite3_column_text16() first to force the result into the desired
3094: ** format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to
3095: ** find the size of the result. Do not mix call to sqlite3_column_text() or
3096: ** sqlite3_column_blob() with calls to sqlite3_column_bytes16(). And do not
3097: ** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().
3098: **
3099: ** The pointers returned are valid until a type conversion occurs as
3100: ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
3101: ** [sqlite3_finalize()] is called. The memory space used to hold strings
3102: ** and blobs is freed automatically. Do <b>not</b> pass the pointers returned
3103: ** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
3104: ** [sqlite3_free()].
3105: **
3106: ** If a memory allocation error occurs during the evaluation of any
3107: ** of these routines, a default value is returned. The default value
3108: ** is either the integer 0, the floating point number 0.0, or a NULL
3109: ** pointer. Subsequent calls to [sqlite3_errcode()] will return
3110: ** [SQLITE_NOMEM].
1.4 ! misha 3111: **
! 3112: ** INVARIANTS:
! 3113: **
! 3114: ** {F13803} The [sqlite3_column_blob(S,N)] interface converts the
! 3115: ** Nth column in the current row of the result set for
! 3116: ** [prepared statement] S into a blob and then returns a
! 3117: ** pointer to the converted value.
! 3118: **
! 3119: ** {F13806} The [sqlite3_column_bytes(S,N)] interface returns the
! 3120: ** number of bytes in the blob or string (exclusive of the
! 3121: ** zero terminator on the string) that was returned by the
! 3122: ** most recent call to [sqlite3_column_blob(S,N)] or
! 3123: ** [sqlite3_column_text(S,N)].
! 3124: **
! 3125: ** {F13809} The [sqlite3_column_bytes16(S,N)] interface returns the
! 3126: ** number of bytes in the string (exclusive of the
! 3127: ** zero terminator on the string) that was returned by the
! 3128: ** most recent call to [sqlite3_column_text16(S,N)].
! 3129: **
! 3130: ** {F13812} The [sqlite3_column_double(S,N)] interface converts the
! 3131: ** Nth column in the current row of the result set for
! 3132: ** [prepared statement] S into a floating point value and
! 3133: ** returns a copy of that value.
! 3134: **
! 3135: ** {F13815} The [sqlite3_column_int(S,N)] interface converts the
! 3136: ** Nth column in the current row of the result set for
! 3137: ** [prepared statement] S into a 64-bit signed integer and
! 3138: ** returns the lower 32 bits of that integer.
! 3139: **
! 3140: ** {F13818} The [sqlite3_column_int64(S,N)] interface converts the
! 3141: ** Nth column in the current row of the result set for
! 3142: ** [prepared statement] S into a 64-bit signed integer and
! 3143: ** returns a copy of that integer.
! 3144: **
! 3145: ** {F13821} The [sqlite3_column_text(S,N)] interface converts the
! 3146: ** Nth column in the current row of the result set for
! 3147: ** [prepared statement] S into a zero-terminated UTF-8
! 3148: ** string and returns a pointer to that string.
! 3149: **
! 3150: ** {F13824} The [sqlite3_column_text16(S,N)] interface converts the
! 3151: ** Nth column in the current row of the result set for
! 3152: ** [prepared statement] S into a zero-terminated 2-byte
! 3153: ** aligned UTF-16 native byte order
! 3154: ** string and returns a pointer to that string.
! 3155: **
! 3156: ** {F13827} The [sqlite3_column_type(S,N)] interface returns
! 3157: ** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT],
! 3158: ** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for
! 3159: ** the Nth column in the current row of the result set for
! 3160: ** [prepared statement] S.
! 3161: **
! 3162: ** {F13830} The [sqlite3_column_value(S,N)] interface returns a
! 3163: ** pointer to the [sqlite3_value] object that for the
! 3164: ** Nth column in the current row of the result set for
! 3165: ** [prepared statement] S.
1.1 misha 3166: */
3167: const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
3168: int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
3169: int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
3170: double sqlite3_column_double(sqlite3_stmt*, int iCol);
3171: int sqlite3_column_int(sqlite3_stmt*, int iCol);
1.2 misha 3172: sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
1.1 misha 3173: const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
3174: const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
3175: int sqlite3_column_type(sqlite3_stmt*, int iCol);
1.2 misha 3176: sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
1.1 misha 3177:
3178: /*
1.4 ! misha 3179: ** CAPI3REF: Destroy A Prepared Statement Object {F13300}
1.2 misha 3180: **
3181: ** The sqlite3_finalize() function is called to delete a
1.4 ! misha 3182: ** [prepared statement]. If the statement was
1.2 misha 3183: ** executed successfully, or not executed at all, then SQLITE_OK is returned.
3184: ** If execution of the statement failed then an
1.4 ! misha 3185: ** [error code] or [extended error code]
1.2 misha 3186: ** is returned.
1.1 misha 3187: **
3188: ** This routine can be called at any point during the execution of the
1.4 ! misha 3189: ** [prepared statement]. If the virtual machine has not
1.2 misha 3190: ** completed execution when this routine is called, that is like
3191: ** encountering an error or an interrupt. (See [sqlite3_interrupt()].)
3192: ** Incomplete updates may be rolled back and transactions cancelled,
3193: ** depending on the circumstances, and the
1.4 ! misha 3194: ** [error code] returned will be [SQLITE_ABORT].
! 3195: **
! 3196: ** INVARIANTS:
! 3197: **
! 3198: ** {F11302} The [sqlite3_finalize(S)] interface destroys the
! 3199: ** [prepared statement] S and releases all
! 3200: ** memory and file resources held by that object.
! 3201: **
! 3202: ** {F11304} If the most recent call to [sqlite3_step(S)] for the
! 3203: ** [prepared statement] S returned an error,
! 3204: ** then [sqlite3_finalize(S)] returns that same error.
1.1 misha 3205: */
3206: int sqlite3_finalize(sqlite3_stmt *pStmt);
3207:
3208: /*
1.4 ! misha 3209: ** CAPI3REF: Reset A Prepared Statement Object {F13330}
1.2 misha 3210: **
3211: ** The sqlite3_reset() function is called to reset a
1.4 ! misha 3212: ** [prepared statement] object.
! 3213: ** back to its initial state, ready to be re-executed.
1.1 misha 3214: ** Any SQL statement variables that had values bound to them using
1.2 misha 3215: ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
3216: ** Use [sqlite3_clear_bindings()] to reset the bindings.
1.4 ! misha 3217: **
! 3218: ** {F11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S
! 3219: ** back to the beginning of its program.
! 3220: **
! 3221: ** {F11334} If the most recent call to [sqlite3_step(S)] for
! 3222: ** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
! 3223: ** or if [sqlite3_step(S)] has never before been called on S,
! 3224: ** then [sqlite3_reset(S)] returns [SQLITE_OK].
! 3225: **
! 3226: ** {F11336} If the most recent call to [sqlite3_step(S)] for
! 3227: ** [prepared statement] S indicated an error, then
! 3228: ** [sqlite3_reset(S)] returns an appropriate [error code].
! 3229: **
! 3230: ** {F11338} The [sqlite3_reset(S)] interface does not change the values
! 3231: ** of any [sqlite3_bind_blob|bindings] on [prepared statement] S.
1.1 misha 3232: */
3233: int sqlite3_reset(sqlite3_stmt *pStmt);
3234:
3235: /*
1.4 ! misha 3236: ** CAPI3REF: Create Or Redefine SQL Functions {F16100}
! 3237: ** KEYWORDS: {function creation routines}
1.2 misha 3238: **
1.4 ! misha 3239: ** These two functions (collectively known as
! 3240: ** "function creation routines") are used to add SQL functions or aggregates
1.2 misha 3241: ** or to redefine the behavior of existing SQL functions or aggregates. The
1.1 misha 3242: ** difference only between the two is that the second parameter, the
3243: ** name of the (scalar) function or aggregate, is encoded in UTF-8 for
3244: ** sqlite3_create_function() and UTF-16 for sqlite3_create_function16().
3245: **
1.4 ! misha 3246: ** The first parameter is the [database connection] to which the SQL
! 3247: ** function is to be added. If a single
! 3248: ** program uses more than one [database connection] internally, then SQL
! 3249: ** functions must be added individually to each [database connection].
1.2 misha 3250: **
3251: ** The second parameter is the name of the SQL function to be created
3252: ** or redefined.
3253: ** The length of the name is limited to 255 bytes, exclusive of the
3254: ** zero-terminator. Note that the name length limit is in bytes, not
3255: ** characters. Any attempt to create a function with a longer name
3256: ** will result in an SQLITE_ERROR error.
1.1 misha 3257: **
1.2 misha 3258: ** The third parameter is the number of arguments that the SQL function or
3259: ** aggregate takes. If this parameter is negative, then the SQL function or
1.1 misha 3260: ** aggregate may take any number of arguments.
3261: **
1.2 misha 3262: ** The fourth parameter, eTextRep, specifies what
3263: ** [SQLITE_UTF8 | text encoding] this SQL function prefers for
3264: ** its parameters. Any SQL function implementation should be able to work
3265: ** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be
3266: ** more efficient with one encoding than another. It is allowed to
3267: ** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
3268: ** times with the same function but with different values of eTextRep.
3269: ** When multiple implementations of the same function are available, SQLite
3270: ** will pick the one that involves the least amount of data conversion.
3271: ** If there is only a single implementation which does not care what
3272: ** text encoding is used, then the fourth argument should be
3273: ** [SQLITE_ANY].
3274: **
3275: ** The fifth parameter is an arbitrary pointer. The implementation
3276: ** of the function can gain access to this pointer using
3277: ** [sqlite3_user_data()].
1.1 misha 3278: **
3279: ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are
1.2 misha 3280: ** pointers to C-language functions that implement the SQL
3281: ** function or aggregate. A scalar SQL function requires an implementation of
1.1 misha 3282: ** the xFunc callback only, NULL pointers should be passed as the xStep
1.2 misha 3283: ** and xFinal parameters. An aggregate SQL function requires an implementation
3284: ** of xStep and xFinal and NULL should be passed for xFunc. To delete an
3285: ** existing SQL function or aggregate, pass NULL for all three function
3286: ** callback.
3287: **
3288: ** It is permitted to register multiple implementations of the same
3289: ** functions with the same name but with either differing numbers of
3290: ** arguments or differing perferred text encodings. SQLite will use
3291: ** the implementation most closely matches the way in which the
3292: ** SQL function is used.
1.4 ! misha 3293: **
! 3294: ** INVARIANTS:
! 3295: **
! 3296: ** {F16103} The [sqlite3_create_function16()] interface behaves exactly
! 3297: ** like [sqlite3_create_function()] in every way except that it
! 3298: ** interprets the zFunctionName argument as
! 3299: ** zero-terminated UTF-16 native byte order instead of as a
! 3300: ** zero-terminated UTF-8.
! 3301: **
! 3302: ** {F16106} A successful invocation of
! 3303: ** the [sqlite3_create_function(D,X,N,E,...)] interface registers
! 3304: ** or replaces callback functions in [database connection] D
! 3305: ** used to implement the SQL function named X with N parameters
! 3306: ** and having a perferred text encoding of E.
! 3307: **
! 3308: ** {F16109} A successful call to [sqlite3_create_function(D,X,N,E,P,F,S,L)]
! 3309: ** replaces the P, F, S, and L values from any prior calls with
! 3310: ** the same D, X, N, and E values.
! 3311: **
! 3312: ** {F16112} The [sqlite3_create_function(D,X,...)] interface fails with
! 3313: ** a return code of [SQLITE_ERROR] if the SQL function name X is
! 3314: ** longer than 255 bytes exclusive of the zero terminator.
! 3315: **
! 3316: ** {F16118} Either F must be NULL and S and L are non-NULL or else F
! 3317: ** is non-NULL and S and L are NULL, otherwise
! 3318: ** [sqlite3_create_function(D,X,N,E,P,F,S,L)] returns [SQLITE_ERROR].
! 3319: **
! 3320: ** {F16121} The [sqlite3_create_function(D,...)] interface fails with an
! 3321: ** error code of [SQLITE_BUSY] if there exist [prepared statements]
! 3322: ** associated with the [database connection] D.
! 3323: **
! 3324: ** {F16124} The [sqlite3_create_function(D,X,N,...)] interface fails with an
! 3325: ** error code of [SQLITE_ERROR] if parameter N (specifying the number
! 3326: ** of arguments to the SQL function being registered) is less
! 3327: ** than -1 or greater than 127.
! 3328: **
! 3329: ** {F16127} When N is non-negative, the [sqlite3_create_function(D,X,N,...)]
! 3330: ** interface causes callbacks to be invoked for the SQL function
! 3331: ** named X when the number of arguments to the SQL function is
! 3332: ** exactly N.
! 3333: **
! 3334: ** {F16130} When N is -1, the [sqlite3_create_function(D,X,N,...)]
! 3335: ** interface causes callbacks to be invoked for the SQL function
! 3336: ** named X with any number of arguments.
! 3337: **
! 3338: ** {F16133} When calls to [sqlite3_create_function(D,X,N,...)]
! 3339: ** specify multiple implementations of the same function X
! 3340: ** and when one implementation has N>=0 and the other has N=(-1)
! 3341: ** the implementation with a non-zero N is preferred.
! 3342: **
! 3343: ** {F16136} When calls to [sqlite3_create_function(D,X,N,E,...)]
! 3344: ** specify multiple implementations of the same function X with
! 3345: ** the same number of arguments N but with different
! 3346: ** encodings E, then the implementation where E matches the
! 3347: ** database encoding is preferred.
! 3348: **
! 3349: ** {F16139} For an aggregate SQL function created using
! 3350: ** [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finializer
! 3351: ** function L will always be invoked exactly once if the
! 3352: ** step function S is called one or more times.
1.1 misha 3353: */
3354: int sqlite3_create_function(
1.4 ! misha 3355: sqlite3 *db,
1.1 misha 3356: const char *zFunctionName,
3357: int nArg,
3358: int eTextRep,
1.4 ! misha 3359: void *pApp,
1.1 misha 3360: void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
3361: void (*xStep)(sqlite3_context*,int,sqlite3_value**),
3362: void (*xFinal)(sqlite3_context*)
3363: );
3364: int sqlite3_create_function16(
1.4 ! misha 3365: sqlite3 *db,
1.1 misha 3366: const void *zFunctionName,
3367: int nArg,
3368: int eTextRep,
1.4 ! misha 3369: void *pApp,
1.1 misha 3370: void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
3371: void (*xStep)(sqlite3_context*,int,sqlite3_value**),
3372: void (*xFinal)(sqlite3_context*)
3373: );
3374:
3375: /*
1.4 ! misha 3376: ** CAPI3REF: Text Encodings {F10267}
1.2 misha 3377: **
3378: ** These constant define integer codes that represent the various
3379: ** text encodings supported by SQLite.
3380: */
3381: #define SQLITE_UTF8 1
3382: #define SQLITE_UTF16LE 2
3383: #define SQLITE_UTF16BE 3
3384: #define SQLITE_UTF16 4 /* Use native byte order */
3385: #define SQLITE_ANY 5 /* sqlite3_create_function only */
3386: #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
3387:
3388: /*
3389: ** CAPI3REF: Obsolete Functions
3390: **
3391: ** These functions are all now obsolete. In order to maintain
3392: ** backwards compatibility with older code, we continue to support
3393: ** these functions. However, new development projects should avoid
3394: ** the use of these functions. To help encourage people to avoid
3395: ** using these functions, we are not going to tell you want they do.
1.1 misha 3396: */
3397: int sqlite3_aggregate_count(sqlite3_context*);
1.2 misha 3398: int sqlite3_expired(sqlite3_stmt*);
3399: int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
3400: int sqlite3_global_recover(void);
3401: void sqlite3_thread_cleanup(void);
1.3 misha 3402: int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64);
1.2 misha 3403:
3404: /*
1.4 ! misha 3405: ** CAPI3REF: Obtaining SQL Function Parameter Values {F15100}
1.2 misha 3406: **
3407: ** The C-language implementation of SQL functions and aggregates uses
3408: ** this set of interface routines to access the parameter values on
3409: ** the function or aggregate.
3410: **
3411: ** The xFunc (for scalar functions) or xStep (for aggregates) parameters
3412: ** to [sqlite3_create_function()] and [sqlite3_create_function16()]
3413: ** define callbacks that implement the SQL functions and aggregates.
3414: ** The 4th parameter to these callbacks is an array of pointers to
3415: ** [sqlite3_value] objects. There is one [sqlite3_value] object for
3416: ** each parameter to the SQL function. These routines are used to
3417: ** extract values from the [sqlite3_value] objects.
3418: **
3419: ** These routines work just like the corresponding
3420: ** [sqlite3_column_blob | sqlite3_column_* routines] except that
3421: ** these routines take a single [sqlite3_value*] pointer instead
3422: ** of an [sqlite3_stmt*] pointer and an integer column number.
3423: **
3424: ** The sqlite3_value_text16() interface extracts a UTF16 string
3425: ** in the native byte-order of the host machine. The
3426: ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
3427: ** extract UTF16 strings as big-endian and little-endian respectively.
3428: **
3429: ** The sqlite3_value_numeric_type() interface attempts to apply
3430: ** numeric affinity to the value. This means that an attempt is
3431: ** made to convert the value to an integer or floating point. If
1.4 ! misha 3432: ** such a conversion is possible without loss of information (in other
! 3433: ** words if the value is a string that looks like a number)
! 3434: ** then the conversion is done. Otherwise no conversion occurs. The
1.2 misha 3435: ** [SQLITE_INTEGER | datatype] after conversion is returned.
3436: **
3437: ** Please pay particular attention to the fact that the pointer that
3438: ** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or
3439: ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
3440: ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
3441: ** or [sqlite3_value_text16()].
3442: **
3443: ** These routines must be called from the same thread as
3444: ** the SQL function that supplied the sqlite3_value* parameters.
3445: ** Or, if the sqlite3_value* argument comes from the [sqlite3_column_value()]
3446: ** interface, then these routines should be called from the same thread
3447: ** that ran [sqlite3_column_value()].
1.4 ! misha 3448: **
! 3449: **
! 3450: ** INVARIANTS:
! 3451: **
! 3452: ** {F15103} The [sqlite3_value_blob(V)] interface converts the
! 3453: ** [sqlite3_value] object V into a blob and then returns a
! 3454: ** pointer to the converted value.
! 3455: **
! 3456: ** {F15106} The [sqlite3_value_bytes(V)] interface returns the
! 3457: ** number of bytes in the blob or string (exclusive of the
! 3458: ** zero terminator on the string) that was returned by the
! 3459: ** most recent call to [sqlite3_value_blob(V)] or
! 3460: ** [sqlite3_value_text(V)].
! 3461: **
! 3462: ** {F15109} The [sqlite3_value_bytes16(V)] interface returns the
! 3463: ** number of bytes in the string (exclusive of the
! 3464: ** zero terminator on the string) that was returned by the
! 3465: ** most recent call to [sqlite3_value_text16(V)],
! 3466: ** [sqlite3_value_text16be(V)], or [sqlite3_value_text16le(V)].
! 3467: **
! 3468: ** {F15112} The [sqlite3_value_double(V)] interface converts the
! 3469: ** [sqlite3_value] object V into a floating point value and
! 3470: ** returns a copy of that value.
! 3471: **
! 3472: ** {F15115} The [sqlite3_value_int(V)] interface converts the
! 3473: ** [sqlite3_value] object V into a 64-bit signed integer and
! 3474: ** returns the lower 32 bits of that integer.
! 3475: **
! 3476: ** {F15118} The [sqlite3_value_int64(V)] interface converts the
! 3477: ** [sqlite3_value] object V into a 64-bit signed integer and
! 3478: ** returns a copy of that integer.
! 3479: **
! 3480: ** {F15121} The [sqlite3_value_text(V)] interface converts the
! 3481: ** [sqlite3_value] object V into a zero-terminated UTF-8
! 3482: ** string and returns a pointer to that string.
! 3483: **
! 3484: ** {F15124} The [sqlite3_value_text16(V)] interface converts the
! 3485: ** [sqlite3_value] object V into a zero-terminated 2-byte
! 3486: ** aligned UTF-16 native byte order
! 3487: ** string and returns a pointer to that string.
! 3488: **
! 3489: ** {F15127} The [sqlite3_value_text16be(V)] interface converts the
! 3490: ** [sqlite3_value] object V into a zero-terminated 2-byte
! 3491: ** aligned UTF-16 big-endian
! 3492: ** string and returns a pointer to that string.
! 3493: **
! 3494: ** {F15130} The [sqlite3_value_text16le(V)] interface converts the
! 3495: ** [sqlite3_value] object V into a zero-terminated 2-byte
! 3496: ** aligned UTF-16 little-endian
! 3497: ** string and returns a pointer to that string.
! 3498: **
! 3499: ** {F15133} The [sqlite3_value_type(V)] interface returns
! 3500: ** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT],
! 3501: ** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for
! 3502: ** the [sqlite3_value] object V.
! 3503: **
! 3504: ** {F15136} The [sqlite3_value_numeric_type(V)] interface converts
! 3505: ** the [sqlite3_value] object V into either an integer or
! 3506: ** a floating point value if it can do so without loss of
! 3507: ** information, and returns one of [SQLITE_NULL],
! 3508: ** [SQLITE_INTEGER], [SQLITE_FLOAT], [SQLITE_TEXT], or
! 3509: ** [SQLITE_BLOB] as appropriate for
! 3510: ** the [sqlite3_value] object V after the conversion attempt.
1.1 misha 3511: */
3512: const void *sqlite3_value_blob(sqlite3_value*);
3513: int sqlite3_value_bytes(sqlite3_value*);
3514: int sqlite3_value_bytes16(sqlite3_value*);
3515: double sqlite3_value_double(sqlite3_value*);
3516: int sqlite3_value_int(sqlite3_value*);
1.2 misha 3517: sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
1.1 misha 3518: const unsigned char *sqlite3_value_text(sqlite3_value*);
3519: const void *sqlite3_value_text16(sqlite3_value*);
3520: const void *sqlite3_value_text16le(sqlite3_value*);
3521: const void *sqlite3_value_text16be(sqlite3_value*);
3522: int sqlite3_value_type(sqlite3_value*);
1.2 misha 3523: int sqlite3_value_numeric_type(sqlite3_value*);
1.1 misha 3524:
3525: /*
1.4 ! misha 3526: ** CAPI3REF: Obtain Aggregate Function Context {F16210}
1.2 misha 3527: **
3528: ** The implementation of aggregate SQL functions use this routine to allocate
1.4 ! misha 3529: ** a structure for storing their state.
! 3530: ** The first time the sqlite3_aggregate_context() routine is
! 3531: ** is called for a particular aggregate, SQLite allocates nBytes of memory
! 3532: ** zeros that memory, and returns a pointer to it.
! 3533: ** On second and subsequent calls to sqlite3_aggregate_context()
! 3534: ** for the same aggregate function index, the same buffer is returned.
! 3535: ** The implementation
1.1 misha 3536: ** of the aggregate can use the returned buffer to accumulate data.
3537: **
1.4 ! misha 3538: ** SQLite automatically frees the allocated buffer when the aggregate
1.2 misha 3539: ** query concludes.
3540: **
3541: ** The first parameter should be a copy of the
3542: ** [sqlite3_context | SQL function context] that is the first
3543: ** parameter to the callback routine that implements the aggregate
3544: ** function.
3545: **
3546: ** This routine must be called from the same thread in which
3547: ** the aggregate SQL function is running.
1.4 ! misha 3548: **
! 3549: ** INVARIANTS:
! 3550: **
! 3551: ** {F16211} The first invocation of [sqlite3_aggregate_context(C,N)] for
! 3552: ** a particular instance of an aggregate function (for a particular
! 3553: ** context C) causes SQLite to allocation N bytes of memory,
! 3554: ** zero that memory, and return a pointer to the allocationed
! 3555: ** memory.
! 3556: **
! 3557: ** {F16213} If a memory allocation error occurs during
! 3558: ** [sqlite3_aggregate_context(C,N)] then the function returns 0.
! 3559: **
! 3560: ** {F16215} Second and subsequent invocations of
! 3561: ** [sqlite3_aggregate_context(C,N)] for the same context pointer C
! 3562: ** ignore the N parameter and return a pointer to the same
! 3563: ** block of memory returned by the first invocation.
! 3564: **
! 3565: ** {F16217} The memory allocated by [sqlite3_aggregate_context(C,N)] is
! 3566: ** automatically freed on the next call to [sqlite3_reset()]
! 3567: ** or [sqlite3_finalize()] for the [prepared statement] containing
! 3568: ** the aggregate function associated with context C.
1.1 misha 3569: */
3570: void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
3571:
3572: /*
1.4 ! misha 3573: ** CAPI3REF: User Data For Functions {F16240}
1.2 misha 3574: **
1.4 ! misha 3575: ** The sqlite3_user_data() interface returns a copy of
! 3576: ** the pointer that was the pUserData parameter (the 5th parameter)
! 3577: ** of the the [sqlite3_create_function()]
! 3578: ** and [sqlite3_create_function16()] routines that originally
! 3579: ** registered the application defined function. {END}
1.2 misha 3580: **
3581: ** This routine must be called from the same thread in which
1.4 ! misha 3582: ** the application-defined function is running.
! 3583: **
! 3584: ** INVARIANTS:
! 3585: **
! 3586: ** {F16243} The [sqlite3_user_data(C)] interface returns a copy of the
! 3587: ** P pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)]
! 3588: ** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that
! 3589: ** registered the SQL function associated with
! 3590: ** [sqlite3_context] C.
1.1 misha 3591: */
3592: void *sqlite3_user_data(sqlite3_context*);
3593:
3594: /*
1.4 ! misha 3595: ** CAPI3REF: Function Auxiliary Data {F16270}
1.2 misha 3596: **
3597: ** The following two functions may be used by scalar SQL functions to
1.1 misha 3598: ** associate meta-data with argument values. If the same value is passed to
1.2 misha 3599: ** multiple invocations of the same SQL function during query execution, under
1.1 misha 3600: ** some circumstances the associated meta-data may be preserved. This may
3601: ** be used, for example, to add a regular-expression matching scalar
3602: ** function. The compiled version of the regular expression is stored as
3603: ** meta-data associated with the SQL value passed as the regular expression
1.2 misha 3604: ** pattern. The compiled regular expression can be reused on multiple
3605: ** invocations of the same function so that the original pattern string
3606: ** does not need to be recompiled on each invocation.
1.1 misha 3607: **
1.2 misha 3608: ** The sqlite3_get_auxdata() interface returns a pointer to the meta-data
1.4 ! misha 3609: ** associated by the sqlite3_set_auxdata() function with the Nth argument
! 3610: ** value to the application-defined function.
! 3611: ** If no meta-data has been ever been set for the Nth
! 3612: ** argument of the function, or if the cooresponding function parameter
! 3613: ** has changed since the meta-data was set, then sqlite3_get_auxdata()
! 3614: ** returns a NULL pointer.
! 3615: **
! 3616: ** The sqlite3_set_auxdata() interface saves the meta-data
! 3617: ** pointed to by its 3rd parameter as the meta-data for the N-th
! 3618: ** argument of the application-defined function. Subsequent
! 3619: ** calls to sqlite3_get_auxdata() might return this data, if it has
! 3620: ** not been destroyed.
! 3621: ** If it is not NULL, SQLite will invoke the destructor
! 3622: ** function given by the 4th parameter to sqlite3_set_auxdata() on
! 3623: ** the meta-data when the corresponding function parameter changes
! 3624: ** or when the SQL statement completes, whichever comes first.
! 3625: **
! 3626: ** SQLite is free to call the destructor and drop meta-data on
! 3627: ** any parameter of any function at any time. The only guarantee
! 3628: ** is that the destructor will be called before the metadata is
! 3629: ** dropped.
1.1 misha 3630: **
3631: ** In practice, meta-data is preserved between function calls for
3632: ** expressions that are constant at compile time. This includes literal
3633: ** values and SQL variables.
1.2 misha 3634: **
3635: ** These routines must be called from the same thread in which
3636: ** the SQL function is running.
1.4 ! misha 3637: **
! 3638: ** INVARIANTS:
! 3639: **
! 3640: ** {F16272} The [sqlite3_get_auxdata(C,N)] interface returns a pointer
! 3641: ** to metadata associated with the Nth parameter of the SQL function
! 3642: ** whose context is C, or NULL if there is no metadata associated
! 3643: ** with that parameter.
! 3644: **
! 3645: ** {F16274} The [sqlite3_set_auxdata(C,N,P,D)] interface assigns a metadata
! 3646: ** pointer P to the Nth parameter of the SQL function with context
! 3647: ** C.
! 3648: **
! 3649: ** {F16276} SQLite will invoke the destructor D with a single argument
! 3650: ** which is the metadata pointer P following a call to
! 3651: ** [sqlite3_set_auxdata(C,N,P,D)] when SQLite ceases to hold
! 3652: ** the metadata.
! 3653: **
! 3654: ** {F16277} SQLite ceases to hold metadata for an SQL function parameter
! 3655: ** when the value of that parameter changes.
! 3656: **
! 3657: ** {F16278} When [sqlite3_set_auxdata(C,N,P,D)] is invoked, the destructor
! 3658: ** is called for any prior metadata associated with the same function
! 3659: ** context C and parameter N.
! 3660: **
! 3661: ** {F16279} SQLite will call destructors for any metadata it is holding
! 3662: ** in a particular [prepared statement] S when either
! 3663: ** [sqlite3_reset(S)] or [sqlite3_finalize(S)] is called.
1.1 misha 3664: */
1.4 ! misha 3665: void *sqlite3_get_auxdata(sqlite3_context*, int N);
! 3666: void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
1.1 misha 3667:
3668:
3669: /*
1.4 ! misha 3670: ** CAPI3REF: Constants Defining Special Destructor Behavior {F10280}
1.2 misha 3671: **
1.1 misha 3672: ** These are special value for the destructor that is passed in as the
1.2 misha 3673: ** final argument to routines like [sqlite3_result_blob()]. If the destructor
1.1 misha 3674: ** argument is SQLITE_STATIC, it means that the content pointer is constant
3675: ** and will never change. It does not need to be destroyed. The
3676: ** SQLITE_TRANSIENT value means that the content will likely change in
3677: ** the near future and that SQLite should make its own private copy of
3678: ** the content before returning.
1.2 misha 3679: **
3680: ** The typedef is necessary to work around problems in certain
3681: ** C++ compilers. See ticket #2191.
1.1 misha 3682: */
1.2 misha 3683: typedef void (*sqlite3_destructor_type)(void*);
3684: #define SQLITE_STATIC ((sqlite3_destructor_type)0)
3685: #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1)
3686:
3687: /*
1.4 ! misha 3688: ** CAPI3REF: Setting The Result Of An SQL Function {F16400}
1.2 misha 3689: **
3690: ** These routines are used by the xFunc or xFinal callbacks that
3691: ** implement SQL functions and aggregates. See
3692: ** [sqlite3_create_function()] and [sqlite3_create_function16()]
3693: ** for additional information.
3694: **
3695: ** These functions work very much like the
3696: ** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used
3697: ** to bind values to host parameters in prepared statements.
3698: ** Refer to the
3699: ** [sqlite3_bind_blob | sqlite3_bind_* documentation] for
3700: ** additional information.
3701: **
1.4 ! misha 3702: ** The sqlite3_result_blob() interface sets the result from
! 3703: ** an application defined function to be the BLOB whose content is pointed
! 3704: ** to by the second parameter and which is N bytes long where N is the
! 3705: ** third parameter.
! 3706: ** The sqlite3_result_zeroblob() inerfaces set the result of
! 3707: ** the application defined function to be a BLOB containing all zero
! 3708: ** bytes and N bytes in size, where N is the value of the 2nd parameter.
! 3709: **
! 3710: ** The sqlite3_result_double() interface sets the result from
! 3711: ** an application defined function to be a floating point value specified
! 3712: ** by its 2nd argument.
! 3713: **
1.2 misha 3714: ** The sqlite3_result_error() and sqlite3_result_error16() functions
1.4 ! misha 3715: ** cause the implemented SQL function to throw an exception.
! 3716: ** SQLite uses the string pointed to by the
! 3717: ** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
! 3718: ** as the text of an error message. SQLite interprets the error
! 3719: ** message string from sqlite3_result_error() as UTF8. SQLite
! 3720: ** interprets the string from sqlite3_result_error16() as UTF16 in native
! 3721: ** byte order. If the third parameter to sqlite3_result_error()
! 3722: ** or sqlite3_result_error16() is negative then SQLite takes as the error
! 3723: ** message all text up through the first zero character.
! 3724: ** If the third parameter to sqlite3_result_error() or
! 3725: ** sqlite3_result_error16() is non-negative then SQLite takes that many
! 3726: ** bytes (not characters) from the 2nd parameter as the error message.
! 3727: ** The sqlite3_result_error() and sqlite3_result_error16()
! 3728: ** routines make a copy private copy of the error message text before
! 3729: ** they return. Hence, the calling function can deallocate or
! 3730: ** modify the text after they return without harm.
! 3731: ** The sqlite3_result_error_code() function changes the error code
! 3732: ** returned by SQLite as a result of an error in a function. By default,
! 3733: ** the error code is SQLITE_ERROR.
! 3734: **
! 3735: ** The sqlite3_result_toobig() interface causes SQLite
! 3736: ** to throw an error indicating that a string or BLOB is to long
! 3737: ** to represent. The sqlite3_result_nomem() interface
! 3738: ** causes SQLite to throw an exception indicating that the a
! 3739: ** memory allocation failed.
! 3740: **
! 3741: ** The sqlite3_result_int() interface sets the return value
! 3742: ** of the application-defined function to be the 32-bit signed integer
! 3743: ** value given in the 2nd argument.
! 3744: ** The sqlite3_result_int64() interface sets the return value
! 3745: ** of the application-defined function to be the 64-bit signed integer
! 3746: ** value given in the 2nd argument.
! 3747: **
! 3748: ** The sqlite3_result_null() interface sets the return value
! 3749: ** of the application-defined function to be NULL.
! 3750: **
! 3751: ** The sqlite3_result_text(), sqlite3_result_text16(),
! 3752: ** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
! 3753: ** set the return value of the application-defined function to be
! 3754: ** a text string which is represented as UTF-8, UTF-16 native byte order,
! 3755: ** UTF-16 little endian, or UTF-16 big endian, respectively.
! 3756: ** SQLite takes the text result from the application from
! 3757: ** the 2nd parameter of the sqlite3_result_text* interfaces.
! 3758: ** If the 3rd parameter to the sqlite3_result_text* interfaces
! 3759: ** is negative, then SQLite takes result text from the 2nd parameter
! 3760: ** through the first zero character.
! 3761: ** If the 3rd parameter to the sqlite3_result_text* interfaces
! 3762: ** is non-negative, then as many bytes (not characters) of the text
! 3763: ** pointed to by the 2nd parameter are taken as the application-defined
! 3764: ** function result.
! 3765: ** If the 4th parameter to the sqlite3_result_text* interfaces
! 3766: ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
! 3767: ** function as the destructor on the text or blob result when it has
! 3768: ** finished using that result.
! 3769: ** If the 4th parameter to the sqlite3_result_text* interfaces
! 3770: ** or sqlite3_result_blob is the special constant SQLITE_STATIC, then
! 3771: ** SQLite assumes that the text or blob result is constant space and
! 3772: ** does not copy the space or call a destructor when it has
! 3773: ** finished using that result.
! 3774: ** If the 4th parameter to the sqlite3_result_text* interfaces
! 3775: ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
! 3776: ** then SQLite makes a copy of the result into space obtained from
! 3777: ** from [sqlite3_malloc()] before it returns.
! 3778: **
! 3779: ** The sqlite3_result_value() interface sets the result of
! 3780: ** the application-defined function to be a copy the [sqlite3_value]
! 3781: ** object specified by the 2nd parameter. The
! 3782: ** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
! 3783: ** so that [sqlite3_value] specified in the parameter may change or
! 3784: ** be deallocated after sqlite3_result_value() returns without harm.
! 3785: **
! 3786: ** If these routines are called from within the different thread
! 3787: ** than the one containing the application-defined function that recieved
! 3788: ** the [sqlite3_context] pointer, the results are undefined.
! 3789: **
! 3790: ** INVARIANTS:
! 3791: **
! 3792: ** {F16403} The default return value from any SQL function is NULL.
! 3793: **
! 3794: ** {F16406} The [sqlite3_result_blob(C,V,N,D)] interface changes the
! 3795: ** return value of function C to be a blob that is N bytes
! 3796: ** in length and with content pointed to by V.
! 3797: **
! 3798: ** {F16409} The [sqlite3_result_double(C,V)] interface changes the
! 3799: ** return value of function C to be the floating point value V.
! 3800: **
! 3801: ** {F16412} The [sqlite3_result_error(C,V,N)] interface changes the return
! 3802: ** value of function C to be an exception with error code
! 3803: ** [SQLITE_ERROR] and a UTF8 error message copied from V up to the
! 3804: ** first zero byte or until N bytes are read if N is positive.
! 3805: **
! 3806: ** {F16415} The [sqlite3_result_error16(C,V,N)] interface changes the return
! 3807: ** value of function C to be an exception with error code
! 3808: ** [SQLITE_ERROR] and a UTF16 native byte order error message
! 3809: ** copied from V up to the first zero terminator or until N bytes
! 3810: ** are read if N is positive.
! 3811: **
! 3812: ** {F16418} The [sqlite3_result_error_toobig(C)] interface changes the return
! 3813: ** value of the function C to be an exception with error code
! 3814: ** [SQLITE_TOOBIG] and an appropriate error message.
! 3815: **
! 3816: ** {F16421} The [sqlite3_result_error_nomem(C)] interface changes the return
! 3817: ** value of the function C to be an exception with error code
! 3818: ** [SQLITE_NOMEM] and an appropriate error message.
! 3819: **
! 3820: ** {F16424} The [sqlite3_result_error_code(C,E)] interface changes the return
! 3821: ** value of the function C to be an exception with error code E.
! 3822: ** The error message text is unchanged.
! 3823: **
! 3824: ** {F16427} The [sqlite3_result_int(C,V)] interface changes the
! 3825: ** return value of function C to be the 32-bit integer value V.
! 3826: **
! 3827: ** {F16430} The [sqlite3_result_int64(C,V)] interface changes the
! 3828: ** return value of function C to be the 64-bit integer value V.
! 3829: **
! 3830: ** {F16433} The [sqlite3_result_null(C)] interface changes the
! 3831: ** return value of function C to be NULL.
! 3832: **
! 3833: ** {F16436} The [sqlite3_result_text(C,V,N,D)] interface changes the
! 3834: ** return value of function C to be the UTF8 string
! 3835: ** V up through the first zero or until N bytes are read if N
! 3836: ** is positive.
! 3837: **
! 3838: ** {F16439} The [sqlite3_result_text16(C,V,N,D)] interface changes the
! 3839: ** return value of function C to be the UTF16 native byte order
! 3840: ** string V up through the first zero or until N bytes are read if N
! 3841: ** is positive.
! 3842: **
! 3843: ** {F16442} The [sqlite3_result_text16be(C,V,N,D)] interface changes the
! 3844: ** return value of function C to be the UTF16 big-endian
! 3845: ** string V up through the first zero or until N bytes are read if N
! 3846: ** is positive.
! 3847: **
! 3848: ** {F16445} The [sqlite3_result_text16le(C,V,N,D)] interface changes the
! 3849: ** return value of function C to be the UTF16 little-endian
! 3850: ** string V up through the first zero or until N bytes are read if N
! 3851: ** is positive.
! 3852: **
! 3853: ** {F16448} The [sqlite3_result_value(C,V)] interface changes the
! 3854: ** return value of function C to be [sqlite3_value] object V.
! 3855: **
! 3856: ** {F16451} The [sqlite3_result_zeroblob(C,N)] interface changes the
! 3857: ** return value of function C to be an N-byte blob of all zeros.
! 3858: **
! 3859: ** {F16454} The [sqlite3_result_error()] and [sqlite3_result_error16()]
! 3860: ** interfaces make a copy of their error message strings before
! 3861: ** returning.
! 3862: **
! 3863: ** {F16457} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
! 3864: ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
! 3865: ** [sqlite3_result_text16be(C,V,N,D)], or
! 3866: ** [sqlite3_result_text16le(C,V,N,D)] is the constant [SQLITE_STATIC]
! 3867: ** then no destructor is ever called on the pointer V and SQLite
! 3868: ** assumes that V is immutable.
! 3869: **
! 3870: ** {F16460} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
! 3871: ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
! 3872: ** [sqlite3_result_text16be(C,V,N,D)], or
! 3873: ** [sqlite3_result_text16le(C,V,N,D)] is the constant
! 3874: ** [SQLITE_TRANSIENT] then the interfaces makes a copy of the
! 3875: ** content of V and retains the copy.
! 3876: **
! 3877: ** {F16463} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
! 3878: ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
! 3879: ** [sqlite3_result_text16be(C,V,N,D)], or
! 3880: ** [sqlite3_result_text16le(C,V,N,D)] is some value other than
! 3881: ** the constants [SQLITE_STATIC] and [SQLITE_TRANSIENT] then
! 3882: ** SQLite will invoke the destructor D with V as its only argument
! 3883: ** when it has finished with the V value.
1.1 misha 3884: */
3885: void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
3886: void sqlite3_result_double(sqlite3_context*, double);
3887: void sqlite3_result_error(sqlite3_context*, const char*, int);
3888: void sqlite3_result_error16(sqlite3_context*, const void*, int);
1.2 misha 3889: void sqlite3_result_error_toobig(sqlite3_context*);
3890: void sqlite3_result_error_nomem(sqlite3_context*);
1.4 ! misha 3891: void sqlite3_result_error_code(sqlite3_context*, int);
1.1 misha 3892: void sqlite3_result_int(sqlite3_context*, int);
1.2 misha 3893: void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
1.1 misha 3894: void sqlite3_result_null(sqlite3_context*);
3895: void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
3896: void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
3897: void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
3898: void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
3899: void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
1.2 misha 3900: void sqlite3_result_zeroblob(sqlite3_context*, int n);
1.1 misha 3901:
3902: /*
1.4 ! misha 3903: ** CAPI3REF: Define New Collating Sequences {F16600}
1.2 misha 3904: **
3905: ** These functions are used to add new collation sequences to the
3906: ** [sqlite3*] handle specified as the first argument.
1.1 misha 3907: **
3908: ** The name of the new collation sequence is specified as a UTF-8 string
1.2 misha 3909: ** for sqlite3_create_collation() and sqlite3_create_collation_v2()
1.4 ! misha 3910: ** and a UTF-16 string for sqlite3_create_collation16(). In all cases
1.2 misha 3911: ** the name is passed as the second function argument.
1.1 misha 3912: **
1.3 misha 3913: ** The third argument may be one of the constants [SQLITE_UTF8],
1.2 misha 3914: ** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied
1.1 misha 3915: ** routine expects to be passed pointers to strings encoded using UTF-8,
1.4 ! misha 3916: ** UTF-16 little-endian or UTF-16 big-endian respectively. The
1.3 misha 3917: ** third argument might also be [SQLITE_UTF16_ALIGNED] to indicate that
3918: ** the routine expects pointers to 16-bit word aligned strings
3919: ** of UTF16 in the native byte order of the host computer.
1.1 misha 3920: **
3921: ** A pointer to the user supplied routine must be passed as the fifth
1.4 ! misha 3922: ** argument. If it is NULL, this is the same as deleting the collation
! 3923: ** sequence (so that SQLite cannot call it anymore).
! 3924: ** Each time the application
1.1 misha 3925: ** supplied function is invoked, it is passed a copy of the void* passed as
3926: ** the fourth argument to sqlite3_create_collation() or
3927: ** sqlite3_create_collation16() as its first parameter.
3928: **
1.4 ! misha 3929: ** The remaining arguments to the application-supplied routine are two strings,
! 3930: ** each represented by a (length, data) pair and encoded in the encoding
1.1 misha 3931: ** that was passed as the third argument when the collation sequence was
1.4 ! misha 3932: ** registered. {END} The application defined collation routine should
! 3933: ** return negative, zero or positive if
1.1 misha 3934: ** the first string is less than, equal to, or greater than the second
3935: ** string. i.e. (STRING1 - STRING2).
1.2 misha 3936: **
3937: ** The sqlite3_create_collation_v2() works like sqlite3_create_collation()
3938: ** excapt that it takes an extra argument which is a destructor for
3939: ** the collation. The destructor is called when the collation is
3940: ** destroyed and is passed a copy of the fourth parameter void* pointer
1.4 ! misha 3941: ** of the sqlite3_create_collation_v2().
! 3942: ** Collations are destroyed when
1.2 misha 3943: ** they are overridden by later calls to the collation creation functions
3944: ** or when the [sqlite3*] database handle is closed using [sqlite3_close()].
3945: **
1.4 ! misha 3946: ** INVARIANTS:
! 3947: **
! 3948: ** {F16603} A successful call to the
! 3949: ** [sqlite3_create_collation_v2(B,X,E,P,F,D)] interface
! 3950: ** registers function F as the comparison function used to
! 3951: ** implement collation X on [database connection] B for
! 3952: ** databases having encoding E.
! 3953: **
! 3954: ** {F16604} SQLite understands the X parameter to
! 3955: ** [sqlite3_create_collation_v2(B,X,E,P,F,D)] as a zero-terminated
! 3956: ** UTF-8 string in which case is ignored for ASCII characters and
! 3957: ** is significant for non-ASCII characters.
! 3958: **
! 3959: ** {F16606} Successive calls to [sqlite3_create_collation_v2(B,X,E,P,F,D)]
! 3960: ** with the same values for B, X, and E, override prior values
! 3961: ** of P, F, and D.
! 3962: **
! 3963: ** {F16609} The destructor D in [sqlite3_create_collation_v2(B,X,E,P,F,D)]
! 3964: ** is not NULL then it is called with argument P when the
! 3965: ** collating function is dropped by SQLite.
! 3966: **
! 3967: ** {F16612} A collating function is dropped when it is overloaded.
! 3968: **
! 3969: ** {F16615} A collating function is dropped when the database connection
! 3970: ** is closed using [sqlite3_close()].
! 3971: **
! 3972: ** {F16618} The pointer P in [sqlite3_create_collation_v2(B,X,E,P,F,D)]
! 3973: ** is passed through as the first parameter to the comparison
! 3974: ** function F for all subsequent invocations of F.
! 3975: **
! 3976: ** {F16621} A call to [sqlite3_create_collation(B,X,E,P,F)] is exactly
! 3977: ** the same as a call to [sqlite3_create_collation_v2()] with
! 3978: ** the same parameters and a NULL destructor.
! 3979: **
! 3980: ** {F16624} Following a [sqlite3_create_collation_v2(B,X,E,P,F,D)],
! 3981: ** SQLite uses the comparison function F for all text comparison
! 3982: ** operations on [database connection] B on text values that
! 3983: ** use the collating sequence name X.
! 3984: **
! 3985: ** {F16627} The [sqlite3_create_collation16(B,X,E,P,F)] works the same
! 3986: ** as [sqlite3_create_collation(B,X,E,P,F)] except that the
! 3987: ** collation name X is understood as UTF-16 in native byte order
! 3988: ** instead of UTF-8.
! 3989: **
! 3990: ** {F16630} When multiple comparison functions are available for the same
! 3991: ** collating sequence, SQLite chooses the one whose text encoding
! 3992: ** requires the least amount of conversion from the default
! 3993: ** text encoding of the database.
1.1 misha 3994: */
3995: int sqlite3_create_collation(
3996: sqlite3*,
3997: const char *zName,
3998: int eTextRep,
3999: void*,
4000: int(*xCompare)(void*,int,const void*,int,const void*)
4001: );
1.2 misha 4002: int sqlite3_create_collation_v2(
4003: sqlite3*,
4004: const char *zName,
4005: int eTextRep,
4006: void*,
4007: int(*xCompare)(void*,int,const void*,int,const void*),
4008: void(*xDestroy)(void*)
4009: );
1.1 misha 4010: int sqlite3_create_collation16(
4011: sqlite3*,
4012: const char *zName,
4013: int eTextRep,
4014: void*,
4015: int(*xCompare)(void*,int,const void*,int,const void*)
4016: );
4017:
4018: /*
1.4 ! misha 4019: ** CAPI3REF: Collation Needed Callbacks {F16700}
1.2 misha 4020: **
1.1 misha 4021: ** To avoid having to register all collation sequences before a database
4022: ** can be used, a single callback function may be registered with the
4023: ** database handle to be called whenever an undefined collation sequence is
4024: ** required.
4025: **
4026: ** If the function is registered using the sqlite3_collation_needed() API,
4027: ** then it is passed the names of undefined collation sequences as strings
1.4 ! misha 4028: ** encoded in UTF-8. {F16703} If sqlite3_collation_needed16() is used, the names
1.1 misha 4029: ** are passed as UTF-16 in machine native byte order. A call to either
4030: ** function replaces any existing callback.
4031: **
1.2 misha 4032: ** When the callback is invoked, the first argument passed is a copy
1.1 misha 4033: ** of the second argument to sqlite3_collation_needed() or
1.4 ! misha 4034: ** sqlite3_collation_needed16(). The second argument is the database
! 4035: ** handle. The third argument is one of [SQLITE_UTF8],
! 4036: ** [SQLITE_UTF16BE], or [SQLITE_UTF16LE], indicating the most
! 4037: ** desirable form of the collation sequence function required.
! 4038: ** The fourth parameter is the name of the
1.1 misha 4039: ** required collation sequence.
4040: **
1.2 misha 4041: ** The callback function should register the desired collation using
4042: ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
4043: ** [sqlite3_create_collation_v2()].
1.4 ! misha 4044: **
! 4045: ** INVARIANTS:
! 4046: **
! 4047: ** {F16702} A successful call to [sqlite3_collation_needed(D,P,F)]
! 4048: ** or [sqlite3_collation_needed16(D,P,F)] causes
! 4049: ** the [database connection] D to invoke callback F with first
! 4050: ** parameter P whenever it needs a comparison function for a
! 4051: ** collating sequence that it does not know about.
! 4052: **
! 4053: ** {F16704} Each successful call to [sqlite3_collation_needed()] or
! 4054: ** [sqlite3_collation_needed16()] overrides the callback registered
! 4055: ** on the same [database connection] by prior calls to either
! 4056: ** interface.
! 4057: **
! 4058: ** {F16706} The name of the requested collating function passed in the
! 4059: ** 4th parameter to the callback is in UTF-8 if the callback
! 4060: ** was registered using [sqlite3_collation_needed()] and
! 4061: ** is in UTF-16 native byte order if the callback was
! 4062: ** registered using [sqlite3_collation_needed16()].
! 4063: **
! 4064: **
1.1 misha 4065: */
4066: int sqlite3_collation_needed(
4067: sqlite3*,
4068: void*,
4069: void(*)(void*,sqlite3*,int eTextRep,const char*)
4070: );
4071: int sqlite3_collation_needed16(
4072: sqlite3*,
4073: void*,
4074: void(*)(void*,sqlite3*,int eTextRep,const void*)
4075: );
4076:
4077: /*
4078: ** Specify the key for an encrypted database. This routine should be
4079: ** called right after sqlite3_open().
4080: **
4081: ** The code to implement this API is not available in the public release
4082: ** of SQLite.
4083: */
4084: int sqlite3_key(
4085: sqlite3 *db, /* Database to be rekeyed */
4086: const void *pKey, int nKey /* The key */
4087: );
4088:
4089: /*
4090: ** Change the key on an open database. If the current database is not
4091: ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the
4092: ** database is decrypted.
4093: **
4094: ** The code to implement this API is not available in the public release
4095: ** of SQLite.
4096: */
4097: int sqlite3_rekey(
4098: sqlite3 *db, /* Database to be rekeyed */
4099: const void *pKey, int nKey /* The new key */
4100: );
4101:
4102: /*
1.4 ! misha 4103: ** CAPI3REF: Suspend Execution For A Short Time {F10530}
1.2 misha 4104: **
1.4 ! misha 4105: ** The sqlite3_sleep() function
! 4106: ** causes the current thread to suspend execution
! 4107: ** for at least a number of milliseconds specified in its parameter.
1.2 misha 4108: **
4109: ** If the operating system does not support sleep requests with
4110: ** millisecond time resolution, then the time will be rounded up to
4111: ** the nearest second. The number of milliseconds of sleep actually
4112: ** requested from the operating system is returned.
4113: **
4114: ** SQLite implements this interface by calling the xSleep()
4115: ** method of the default [sqlite3_vfs] object.
1.4 ! misha 4116: **
! 4117: ** INVARIANTS:
! 4118: **
! 4119: ** {F10533} The [sqlite3_sleep(M)] interface invokes the xSleep
! 4120: ** method of the default [sqlite3_vfs|VFS] in order to
! 4121: ** suspend execution of the current thread for at least
! 4122: ** M milliseconds.
! 4123: **
! 4124: ** {F10536} The [sqlite3_sleep(M)] interface returns the number of
! 4125: ** milliseconds of sleep actually requested of the operating
! 4126: ** system, which might be larger than the parameter M.
1.2 misha 4127: */
4128: int sqlite3_sleep(int);
4129:
4130: /*
1.4 ! misha 4131: ** CAPI3REF: Name Of The Folder Holding Temporary Files {F10310}
1.2 misha 4132: **
4133: ** If this global variable is made to point to a string which is
4134: ** the name of a folder (a.ka. directory), then all temporary files
1.1 misha 4135: ** created by SQLite will be placed in that directory. If this variable
4136: ** is NULL pointer, then SQLite does a search for an appropriate temporary
4137: ** file directory.
4138: **
1.2 misha 4139: ** It is not safe to modify this variable once a database connection
4140: ** has been opened. It is intended that this variable be set once
4141: ** as part of process initialization and before any SQLite interface
4142: ** routines have been call and remain unchanged thereafter.
4143: */
4144: SQLITE_EXTERN char *sqlite3_temp_directory;
4145:
4146: /*
1.4 ! misha 4147: ** CAPI3REF: Test To See If The Database Is In Auto-Commit Mode {F12930}
1.2 misha 4148: **
1.4 ! misha 4149: ** The sqlite3_get_autocommit() interfaces returns non-zero or
! 4150: ** zero if the given database connection is or is not in autocommit mode,
! 4151: ** respectively. Autocommit mode is on
! 4152: ** by default. Autocommit mode is disabled by a [BEGIN] statement.
! 4153: ** Autocommit mode is reenabled by a [COMMIT] or [ROLLBACK].
1.2 misha 4154: **
4155: ** If certain kinds of errors occur on a statement within a multi-statement
4156: ** transactions (errors including [SQLITE_FULL], [SQLITE_IOERR],
4157: ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
4158: ** transaction might be rolled back automatically. The only way to
4159: ** find out if SQLite automatically rolled back the transaction after
4160: ** an error is to use this function.
4161: **
1.4 ! misha 4162: ** INVARIANTS:
! 4163: **
! 4164: ** {F12931} The [sqlite3_get_autocommit(D)] interface returns non-zero or
! 4165: ** zero if the [database connection] D is or is not in autocommit
! 4166: ** mode, respectively.
! 4167: **
! 4168: ** {F12932} Autocommit mode is on by default.
! 4169: **
! 4170: ** {F12933} Autocommit mode is disabled by a successful [BEGIN] statement.
! 4171: **
! 4172: ** {F12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK]
! 4173: ** statement.
! 4174: **
! 4175: **
! 4176: ** LIMITATIONS:
! 4177: ***
! 4178: ** {U12936} If another thread changes the autocommit status of the database
! 4179: ** connection while this routine is running, then the return value
! 4180: ** is undefined.
1.2 misha 4181: */
4182: int sqlite3_get_autocommit(sqlite3*);
4183:
4184: /*
1.4 ! misha 4185: ** CAPI3REF: Find The Database Handle Of A Prepared Statement {F13120}
1.2 misha 4186: **
1.4 ! misha 4187: ** The sqlite3_db_handle interface
! 4188: ** returns the [sqlite3*] database handle to which a
! 4189: ** [prepared statement] belongs.
! 4190: ** The database handle returned by sqlite3_db_handle
! 4191: ** is the same database handle that was
1.2 misha 4192: ** the first argument to the [sqlite3_prepare_v2()] or its variants
4193: ** that was used to create the statement in the first place.
1.4 ! misha 4194: **
! 4195: ** INVARIANTS:
! 4196: **
! 4197: ** {F13123} The [sqlite3_db_handle(S)] interface returns a pointer
! 4198: ** to the [database connection] associated with
! 4199: ** [prepared statement] S.
1.2 misha 4200: */
4201: sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
4202:
4203:
4204: /*
1.4 ! misha 4205: ** CAPI3REF: Commit And Rollback Notification Callbacks {F12950}
1.2 misha 4206: **
1.4 ! misha 4207: ** The sqlite3_commit_hook() interface registers a callback
! 4208: ** function to be invoked whenever a transaction is committed.
! 4209: ** Any callback set by a previous call to sqlite3_commit_hook()
! 4210: ** for the same database connection is overridden.
! 4211: ** The sqlite3_rollback_hook() interface registers a callback
! 4212: ** function to be invoked whenever a transaction is committed.
! 4213: ** Any callback set by a previous call to sqlite3_commit_hook()
! 4214: ** for the same database connection is overridden.
! 4215: ** The pArg argument is passed through
1.2 misha 4216: ** to the callback. If the callback on a commit hook function
4217: ** returns non-zero, then the commit is converted into a rollback.
4218: **
1.4 ! misha 4219: ** If another function was previously registered, its
! 4220: ** pArg value is returned. Otherwise NULL is returned.
1.2 misha 4221: **
4222: ** Registering a NULL function disables the callback.
4223: **
4224: ** For the purposes of this API, a transaction is said to have been
4225: ** rolled back if an explicit "ROLLBACK" statement is executed, or
1.4 ! misha 4226: ** an error or constraint causes an implicit rollback to occur.
! 4227: ** The rollback callback is not invoked if a transaction is
! 4228: ** automatically rolled back because the database connection is closed.
! 4229: ** The rollback callback is not invoked if a transaction is
! 4230: ** rolled back because a commit callback returned non-zero.
! 4231: ** <todo> Check on this </todo>
1.2 misha 4232: **
4233: ** These are experimental interfaces and are subject to change.
1.4 ! misha 4234: **
! 4235: ** INVARIANTS:
! 4236: **
! 4237: ** {F12951} The [sqlite3_commit_hook(D,F,P)] interface registers the
! 4238: ** callback function F to be invoked with argument P whenever
! 4239: ** a transaction commits on [database connection] D.
! 4240: **
! 4241: ** {F12952} The [sqlite3_commit_hook(D,F,P)] interface returns the P
! 4242: ** argument from the previous call with the same
! 4243: ** [database connection ] D , or NULL on the first call
! 4244: ** for a particular [database connection] D.
! 4245: **
! 4246: ** {F12953} Each call to [sqlite3_commit_hook()] overwrites the callback
! 4247: ** registered by prior calls.
! 4248: **
! 4249: ** {F12954} If the F argument to [sqlite3_commit_hook(D,F,P)] is NULL
! 4250: ** then the commit hook callback is cancelled and no callback
! 4251: ** is invoked when a transaction commits.
! 4252: **
! 4253: ** {F12955} If the commit callback returns non-zero then the commit is
! 4254: ** converted into a rollback.
! 4255: **
! 4256: ** {F12961} The [sqlite3_rollback_hook(D,F,P)] interface registers the
! 4257: ** callback function F to be invoked with argument P whenever
! 4258: ** a transaction rolls back on [database connection] D.
! 4259: **
! 4260: ** {F12962} The [sqlite3_rollback_hook(D,F,P)] interface returns the P
! 4261: ** argument from the previous call with the same
! 4262: ** [database connection ] D , or NULL on the first call
! 4263: ** for a particular [database connection] D.
! 4264: **
! 4265: ** {F12963} Each call to [sqlite3_rollback_hook()] overwrites the callback
! 4266: ** registered by prior calls.
! 4267: **
! 4268: ** {F12964} If the F argument to [sqlite3_rollback_hook(D,F,P)] is NULL
! 4269: ** then the rollback hook callback is cancelled and no callback
! 4270: ** is invoked when a transaction rolls back.
1.2 misha 4271: */
4272: void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
4273: void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
4274:
4275: /*
1.4 ! misha 4276: ** CAPI3REF: Data Change Notification Callbacks {F12970}
1.2 misha 4277: **
1.4 ! misha 4278: ** The sqlite3_update_hook() interface
! 4279: ** registers a callback function with the database connection identified by the
1.2 misha 4280: ** first argument to be invoked whenever a row is updated, inserted or deleted.
4281: ** Any callback set by a previous call to this function for the same
4282: ** database connection is overridden.
4283: **
4284: ** The second argument is a pointer to the function to invoke when a
1.4 ! misha 4285: ** row is updated, inserted or deleted.
! 4286: ** The first argument to the callback is
! 4287: ** a copy of the third argument to sqlite3_update_hook().
! 4288: ** The second callback
! 4289: ** argument is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],
! 4290: ** depending on the operation that caused the callback to be invoked.
! 4291: ** The third and
1.2 misha 4292: ** fourth arguments to the callback contain pointers to the database and
1.4 ! misha 4293: ** table name containing the affected row.
! 4294: ** The final callback parameter is
! 4295: ** the rowid of the row.
! 4296: ** In the case of an update, this is the rowid after
1.2 misha 4297: ** the update takes place.
4298: **
4299: ** The update hook is not invoked when internal system tables are
4300: ** modified (i.e. sqlite_master and sqlite_sequence).
4301: **
1.4 ! misha 4302: ** If another function was previously registered, its pArg value
! 4303: ** is returned. Otherwise NULL is returned.
! 4304: **
! 4305: ** INVARIANTS:
! 4306: **
! 4307: ** {F12971} The [sqlite3_update_hook(D,F,P)] interface causes callback
! 4308: ** function F to be invoked with first parameter P whenever
! 4309: ** a table row is modified, inserted, or deleted on
! 4310: ** [database connection] D.
! 4311: **
! 4312: ** {F12973} The [sqlite3_update_hook(D,F,P)] interface returns the value
! 4313: ** of P for the previous call on the same [database connection] D,
! 4314: ** or NULL for the first call.
! 4315: **
! 4316: ** {F12975} If the update hook callback F in [sqlite3_update_hook(D,F,P)]
! 4317: ** is NULL then the no update callbacks are made.
! 4318: **
! 4319: ** {F12977} Each call to [sqlite3_update_hook(D,F,P)] overrides prior calls
! 4320: ** to the same interface on the same [database connection] D.
! 4321: **
! 4322: ** {F12979} The update hook callback is not invoked when internal system
! 4323: ** tables such as sqlite_master and sqlite_sequence are modified.
! 4324: **
! 4325: ** {F12981} The second parameter to the update callback
! 4326: ** is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],
! 4327: ** depending on the operation that caused the callback to be invoked.
! 4328: **
! 4329: ** {F12983} The third and fourth arguments to the callback contain pointers
! 4330: ** to zero-terminated UTF-8 strings which are the names of the
! 4331: ** database and table that is being updated.
! 4332:
! 4333: ** {F12985} The final callback parameter is the rowid of the row after
! 4334: ** the change occurs.
1.2 misha 4335: */
4336: void *sqlite3_update_hook(
4337: sqlite3*,
4338: void(*)(void *,int ,char const *,char const *,sqlite3_int64),
4339: void*
4340: );
4341:
4342: /*
1.4 ! misha 4343: ** CAPI3REF: Enable Or Disable Shared Pager Cache {F10330}
1.2 misha 4344: **
4345: ** This routine enables or disables the sharing of the database cache
4346: ** and schema data structures between connections to the same database.
4347: ** Sharing is enabled if the argument is true and disabled if the argument
4348: ** is false.
4349: **
1.4 ! misha 4350: ** Cache sharing is enabled and disabled
! 4351: ** for an entire process. {END} This is a change as of SQLite version 3.5.0.
! 4352: ** In prior versions of SQLite, sharing was
1.2 misha 4353: ** enabled or disabled for each thread separately.
4354: **
4355: ** The cache sharing mode set by this interface effects all subsequent
4356: ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
1.4 ! misha 4357: ** Existing database connections continue use the sharing mode
! 4358: ** that was in effect at the time they were opened.
1.2 misha 4359: **
1.4 ! misha 4360: ** Virtual tables cannot be used with a shared cache. When shared
1.2 misha 4361: ** cache is enabled, the [sqlite3_create_module()] API used to register
4362: ** virtual tables will always return an error.
4363: **
4364: ** This routine returns [SQLITE_OK] if shared cache was
1.4 ! misha 4365: ** enabled or disabled successfully. An [error code]
1.2 misha 4366: ** is returned otherwise.
4367: **
1.4 ! misha 4368: ** Shared cache is disabled by default. But this might change in
1.2 misha 4369: ** future releases of SQLite. Applications that care about shared
4370: ** cache setting should set it explicitly.
1.4 ! misha 4371: **
! 4372: ** INVARIANTS:
! 4373: **
! 4374: ** {F10331} A successful invocation of [sqlite3_enable_shared_cache(B)]
! 4375: ** will enable or disable shared cache mode for any subsequently
! 4376: ** created [database connection] in the same process.
! 4377: **
! 4378: ** {F10336} When shared cache is enabled, the [sqlite3_create_module()]
! 4379: ** interface will always return an error.
! 4380: **
! 4381: ** {F10337} The [sqlite3_enable_shared_cache(B)] interface returns
! 4382: ** [SQLITE_OK] if shared cache was enabled or disabled successfully.
! 4383: **
! 4384: ** {F10339} Shared cache is disabled by default.
1.2 misha 4385: */
4386: int sqlite3_enable_shared_cache(int);
4387:
4388: /*
1.4 ! misha 4389: ** CAPI3REF: Attempt To Free Heap Memory {F17340}
1.2 misha 4390: **
1.4 ! misha 4391: ** The sqlite3_release_memory() interface attempts to
! 4392: ** free N bytes of heap memory by deallocating non-essential memory
! 4393: ** allocations held by the database labrary. {END} Memory used
! 4394: ** to cache database pages to improve performance is an example of
! 4395: ** non-essential memory. Sqlite3_release_memory() returns
! 4396: ** the number of bytes actually freed, which might be more or less
! 4397: ** than the amount requested.
! 4398: **
! 4399: ** INVARIANTS:
! 4400: **
! 4401: ** {F17341} The [sqlite3_release_memory(N)] interface attempts to
! 4402: ** free N bytes of heap memory by deallocating non-essential
! 4403: ** memory allocations held by the database labrary.
! 4404: **
! 4405: ** {F16342} The [sqlite3_release_memory(N)] returns the number
! 4406: ** of bytes actually freed, which might be more or less
! 4407: ** than the amount requested.
1.2 misha 4408: */
4409: int sqlite3_release_memory(int);
4410:
4411: /*
1.4 ! misha 4412: ** CAPI3REF: Impose A Limit On Heap Size {F17350}
1.2 misha 4413: **
1.4 ! misha 4414: ** The sqlite3_soft_heap_limit() interface
! 4415: ** places a "soft" limit on the amount of heap memory that may be allocated
! 4416: ** by SQLite. If an internal allocation is requested
! 4417: ** that would exceed the soft heap limit, [sqlite3_release_memory()] is
1.2 misha 4418: ** invoked one or more times to free up some space before the allocation
4419: ** is made.
4420: **
1.4 ! misha 4421: ** The limit is called "soft", because if
! 4422: ** [sqlite3_release_memory()] cannot
1.2 misha 4423: ** free sufficient memory to prevent the limit from being exceeded,
4424: ** the memory is allocated anyway and the current operation proceeds.
4425: **
4426: ** A negative or zero value for N means that there is no soft heap limit and
4427: ** [sqlite3_release_memory()] will only be called when memory is exhausted.
4428: ** The default value for the soft heap limit is zero.
4429: **
1.4 ! misha 4430: ** SQLite makes a best effort to honor the soft heap limit.
! 4431: ** But if the soft heap limit cannot honored, execution will
1.2 misha 4432: ** continue without error or notification. This is why the limit is
4433: ** called a "soft" limit. It is advisory only.
4434: **
4435: ** Prior to SQLite version 3.5.0, this routine only constrained the memory
4436: ** allocated by a single thread - the same thread in which this routine
4437: ** runs. Beginning with SQLite version 3.5.0, the soft heap limit is
1.4 ! misha 4438: ** applied to all threads. The value specified for the soft heap limit
! 4439: ** is an upper bound on the total memory allocation for all threads. In
1.2 misha 4440: ** version 3.5.0 there is no mechanism for limiting the heap usage for
4441: ** individual threads.
1.4 ! misha 4442: **
! 4443: ** INVARIANTS:
! 4444: **
! 4445: ** {F16351} The [sqlite3_soft_heap_limit(N)] interface places a soft limit
! 4446: ** of N bytes on the amount of heap memory that may be allocated
! 4447: ** using [sqlite3_malloc()] or [sqlite3_realloc()] at any point
! 4448: ** in time.
! 4449: **
! 4450: ** {F16352} If a call to [sqlite3_malloc()] or [sqlite3_realloc()] would
! 4451: ** cause the total amount of allocated memory to exceed the
! 4452: ** soft heap limit, then [sqlite3_release_memory()] is invoked
! 4453: ** in an attempt to reduce the memory usage prior to proceeding
! 4454: ** with the memory allocation attempt.
! 4455: **
! 4456: ** {F16353} Calls to [sqlite3_malloc()] or [sqlite3_realloc()] that trigger
! 4457: ** attempts to reduce memory usage through the soft heap limit
! 4458: ** mechanism continue even if the attempt to reduce memory
! 4459: ** usage is unsuccessful.
! 4460: **
! 4461: ** {F16354} A negative or zero value for N in a call to
! 4462: ** [sqlite3_soft_heap_limit(N)] means that there is no soft
! 4463: ** heap limit and [sqlite3_release_memory()] will only be
! 4464: ** called when memory is completely exhausted.
! 4465: **
! 4466: ** {F16355} The default value for the soft heap limit is zero.
! 4467: **
! 4468: ** {F16358} Each call to [sqlite3_soft_heap_limit(N)] overrides the
! 4469: ** values set by all prior calls.
1.2 misha 4470: */
4471: void sqlite3_soft_heap_limit(int);
4472:
4473: /*
1.4 ! misha 4474: ** CAPI3REF: Extract Metadata About A Column Of A Table {F12850}
1.2 misha 4475: **
4476: ** This routine
4477: ** returns meta-data about a specific column of a specific database
4478: ** table accessible using the connection handle passed as the first function
4479: ** argument.
4480: **
4481: ** The column is identified by the second, third and fourth parameters to
4482: ** this function. The second parameter is either the name of the database
4483: ** (i.e. "main", "temp" or an attached database) containing the specified
4484: ** table or NULL. If it is NULL, then all attached databases are searched
4485: ** for the table using the same algorithm as the database engine uses to
4486: ** resolve unqualified table references.
4487: **
4488: ** The third and fourth parameters to this function are the table and column
4489: ** name of the desired column, respectively. Neither of these parameters
4490: ** may be NULL.
4491: **
4492: ** Meta information is returned by writing to the memory locations passed as
4493: ** the 5th and subsequent parameters to this function. Any of these
4494: ** arguments may be NULL, in which case the corresponding element of meta
4495: ** information is ommitted.
4496: **
4497: ** <pre>
4498: ** Parameter Output Type Description
4499: ** -----------------------------------
4500: **
4501: ** 5th const char* Data type
4502: ** 6th const char* Name of the default collation sequence
4503: ** 7th int True if the column has a NOT NULL constraint
4504: ** 8th int True if the column is part of the PRIMARY KEY
4505: ** 9th int True if the column is AUTOINCREMENT
4506: ** </pre>
4507: **
4508: **
4509: ** The memory pointed to by the character pointers returned for the
4510: ** declaration type and collation sequence is valid only until the next
4511: ** call to any sqlite API function.
4512: **
4513: ** If the specified table is actually a view, then an error is returned.
4514: **
4515: ** If the specified column is "rowid", "oid" or "_rowid_" and an
4516: ** INTEGER PRIMARY KEY column has been explicitly declared, then the output
4517: ** parameters are set for the explicitly declared column. If there is no
4518: ** explicitly declared IPK column, then the output parameters are set as
4519: ** follows:
4520: **
4521: ** <pre>
4522: ** data type: "INTEGER"
4523: ** collation sequence: "BINARY"
4524: ** not null: 0
4525: ** primary key: 1
4526: ** auto increment: 0
4527: ** </pre>
4528: **
4529: ** This function may load one or more schemas from database files. If an
4530: ** error occurs during this process, or if the requested table or column
4531: ** cannot be found, an SQLITE error code is returned and an error message
4532: ** left in the database handle (to be retrieved using sqlite3_errmsg()).
4533: **
4534: ** This API is only available if the library was compiled with the
4535: ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
4536: */
4537: int sqlite3_table_column_metadata(
4538: sqlite3 *db, /* Connection handle */
4539: const char *zDbName, /* Database name or NULL */
4540: const char *zTableName, /* Table name */
4541: const char *zColumnName, /* Column name */
4542: char const **pzDataType, /* OUTPUT: Declared data type */
4543: char const **pzCollSeq, /* OUTPUT: Collation sequence name */
4544: int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */
4545: int *pPrimaryKey, /* OUTPUT: True if column part of PK */
4546: int *pAutoinc /* OUTPUT: True if column is auto-increment */
4547: );
4548:
4549: /*
1.4 ! misha 4550: ** CAPI3REF: Load An Extension {F12600}
1.2 misha 4551: **
1.4 ! misha 4552: ** {F12601} The sqlite3_load_extension() interface
! 4553: ** attempts to load an SQLite extension library contained in the file
! 4554: ** zFile. {F12602} The entry point is zProc. {F12603} zProc may be 0
! 4555: ** in which case the name of the entry point defaults
! 4556: ** to "sqlite3_extension_init".
! 4557: **
! 4558: ** {F12604} The sqlite3_load_extension() interface shall
! 4559: ** return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
! 4560: **
! 4561: ** {F12605}
! 4562: ** If an error occurs and pzErrMsg is not 0, then the
! 4563: ** sqlite3_load_extension() interface shall attempt to fill *pzErrMsg with
! 4564: ** error message text stored in memory obtained from [sqlite3_malloc()].
! 4565: ** {END} The calling function should free this memory
1.2 misha 4566: ** by calling [sqlite3_free()].
4567: **
1.4 ! misha 4568: ** {F12606}
1.2 misha 4569: ** Extension loading must be enabled using [sqlite3_enable_load_extension()]
4570: ** prior to calling this API or an error will be returned.
4571: */
4572: int sqlite3_load_extension(
4573: sqlite3 *db, /* Load the extension into this database connection */
4574: const char *zFile, /* Name of the shared library containing extension */
4575: const char *zProc, /* Entry point. Derived from zFile if 0 */
4576: char **pzErrMsg /* Put error message here if not 0 */
4577: );
4578:
4579: /*
1.4 ! misha 4580: ** CAPI3REF: Enable Or Disable Extension Loading {F12620}
1.2 misha 4581: **
4582: ** So as not to open security holes in older applications that are
4583: ** unprepared to deal with extension loading, and as a means of disabling
4584: ** extension loading while evaluating user-entered SQL, the following
4585: ** API is provided to turn the [sqlite3_load_extension()] mechanism on and
1.4 ! misha 4586: ** off. {F12622} It is off by default. {END} See ticket #1863.
1.2 misha 4587: **
1.4 ! misha 4588: ** {F12621} Call the sqlite3_enable_load_extension() routine
! 4589: ** with onoff==1 to turn extension loading on
! 4590: ** and call it with onoff==0 to turn it back off again. {END}
1.2 misha 4591: */
4592: int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
4593:
4594: /*
1.4 ! misha 4595: ** CAPI3REF: Make Arrangements To Automatically Load An Extension {F12640}
1.2 misha 4596: **
1.4 ! misha 4597: ** {F12641} This function
! 4598: ** registers an extension entry point that is automatically invoked
1.2 misha 4599: ** whenever a new database connection is opened using
1.4 ! misha 4600: ** [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()]. {END}
1.2 misha 4601: **
4602: ** This API can be invoked at program startup in order to register
4603: ** one or more statically linked extensions that will be available
4604: ** to all new database connections.
4605: **
1.4 ! misha 4606: ** {F12642} Duplicate extensions are detected so calling this routine multiple
1.2 misha 4607: ** times with the same extension is harmless.
4608: **
1.4 ! misha 4609: ** {F12643} This routine stores a pointer to the extension in an array
! 4610: ** that is obtained from sqlite_malloc(). {END} If you run a memory leak
1.2 misha 4611: ** checker on your program and it reports a leak because of this
1.4 ! misha 4612: ** array, then invoke [sqlite3_reset_auto_extension()] prior
1.2 misha 4613: ** to shutdown to free the memory.
4614: **
1.4 ! misha 4615: ** {F12644} Automatic extensions apply across all threads. {END}
1.2 misha 4616: **
4617: ** This interface is experimental and is subject to change or
4618: ** removal in future releases of SQLite.
4619: */
4620: int sqlite3_auto_extension(void *xEntryPoint);
4621:
4622:
4623: /*
1.4 ! misha 4624: ** CAPI3REF: Reset Automatic Extension Loading {F12660}
1.2 misha 4625: **
1.4 ! misha 4626: ** {F12661} This function disables all previously registered
! 4627: ** automatic extensions. {END} This
! 4628: ** routine undoes the effect of all prior [sqlite3_auto_extension()]
1.2 misha 4629: ** calls.
4630: **
1.4 ! misha 4631: ** {F12662} This call disabled automatic extensions in all threads. {END}
1.2 misha 4632: **
4633: ** This interface is experimental and is subject to change or
4634: ** removal in future releases of SQLite.
4635: */
4636: void sqlite3_reset_auto_extension(void);
4637:
4638:
4639: /*
4640: ****** EXPERIMENTAL - subject to change without notice **************
4641: **
4642: ** The interface to the virtual-table mechanism is currently considered
4643: ** to be experimental. The interface might change in incompatible ways.
4644: ** If this is a problem for you, do not use the interface at this time.
4645: **
4646: ** When the virtual-table mechanism stablizes, we will declare the
4647: ** interface fixed, support it indefinitely, and remove this comment.
4648: */
4649:
4650: /*
4651: ** Structures used by the virtual table interface
4652: */
4653: typedef struct sqlite3_vtab sqlite3_vtab;
4654: typedef struct sqlite3_index_info sqlite3_index_info;
4655: typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
4656: typedef struct sqlite3_module sqlite3_module;
4657:
4658: /*
1.4 ! misha 4659: ** CAPI3REF: Virtual Table Object {F18000}
! 4660: ** KEYWORDS: sqlite3_module
! 4661: **
1.2 misha 4662: ** A module is a class of virtual tables. Each module is defined
4663: ** by an instance of the following structure. This structure consists
4664: ** mostly of methods for the module.
4665: */
4666: struct sqlite3_module {
4667: int iVersion;
4668: int (*xCreate)(sqlite3*, void *pAux,
4669: int argc, const char *const*argv,
4670: sqlite3_vtab **ppVTab, char**);
4671: int (*xConnect)(sqlite3*, void *pAux,
4672: int argc, const char *const*argv,
4673: sqlite3_vtab **ppVTab, char**);
4674: int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
4675: int (*xDisconnect)(sqlite3_vtab *pVTab);
4676: int (*xDestroy)(sqlite3_vtab *pVTab);
4677: int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
4678: int (*xClose)(sqlite3_vtab_cursor*);
4679: int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
4680: int argc, sqlite3_value **argv);
4681: int (*xNext)(sqlite3_vtab_cursor*);
4682: int (*xEof)(sqlite3_vtab_cursor*);
4683: int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
4684: int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
4685: int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
4686: int (*xBegin)(sqlite3_vtab *pVTab);
4687: int (*xSync)(sqlite3_vtab *pVTab);
4688: int (*xCommit)(sqlite3_vtab *pVTab);
4689: int (*xRollback)(sqlite3_vtab *pVTab);
4690: int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
4691: void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
4692: void **ppArg);
4693:
4694: int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
4695: };
4696:
4697: /*
1.4 ! misha 4698: ** CAPI3REF: Virtual Table Indexing Information {F18100}
! 4699: ** KEYWORDS: sqlite3_index_info
! 4700: **
1.2 misha 4701: ** The sqlite3_index_info structure and its substructures is used to
4702: ** pass information into and receive the reply from the xBestIndex
4703: ** method of an sqlite3_module. The fields under **Inputs** are the
4704: ** inputs to xBestIndex and are read-only. xBestIndex inserts its
4705: ** results into the **Outputs** fields.
4706: **
4707: ** The aConstraint[] array records WHERE clause constraints of the
4708: ** form:
4709: **
4710: ** column OP expr
4711: **
1.4 ! misha 4712: ** Where OP is =, <, <=, >, or >=.
! 4713: ** The particular operator is stored
1.2 misha 4714: ** in aConstraint[].op. The index of the column is stored in
4715: ** aConstraint[].iColumn. aConstraint[].usable is TRUE if the
4716: ** expr on the right-hand side can be evaluated (and thus the constraint
4717: ** is usable) and false if it cannot.
4718: **
4719: ** The optimizer automatically inverts terms of the form "expr OP column"
4720: ** and makes other simplifications to the WHERE clause in an attempt to
4721: ** get as many WHERE clause terms into the form shown above as possible.
4722: ** The aConstraint[] array only reports WHERE clause terms in the correct
4723: ** form that refer to the particular virtual table being queried.
4724: **
4725: ** Information about the ORDER BY clause is stored in aOrderBy[].
4726: ** Each term of aOrderBy records a column of the ORDER BY clause.
4727: **
4728: ** The xBestIndex method must fill aConstraintUsage[] with information
4729: ** about what parameters to pass to xFilter. If argvIndex>0 then
4730: ** the right-hand side of the corresponding aConstraint[] is evaluated
4731: ** and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit
4732: ** is true, then the constraint is assumed to be fully handled by the
4733: ** virtual table and is not checked again by SQLite.
4734: **
4735: ** The idxNum and idxPtr values are recorded and passed into xFilter.
4736: ** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true.
4737: **
4738: ** The orderByConsumed means that output from xFilter will occur in
4739: ** the correct order to satisfy the ORDER BY clause so that no separate
4740: ** sorting step is required.
4741: **
4742: ** The estimatedCost value is an estimate of the cost of doing the
4743: ** particular lookup. A full scan of a table with N entries should have
4744: ** a cost of N. A binary search of a table of N entries should have a
4745: ** cost of approximately log(N).
4746: */
4747: struct sqlite3_index_info {
4748: /* Inputs */
4749: int nConstraint; /* Number of entries in aConstraint */
4750: struct sqlite3_index_constraint {
4751: int iColumn; /* Column on left-hand side of constraint */
4752: unsigned char op; /* Constraint operator */
4753: unsigned char usable; /* True if this constraint is usable */
4754: int iTermOffset; /* Used internally - xBestIndex should ignore */
4755: } *aConstraint; /* Table of WHERE clause constraints */
4756: int nOrderBy; /* Number of terms in the ORDER BY clause */
4757: struct sqlite3_index_orderby {
4758: int iColumn; /* Column number */
4759: unsigned char desc; /* True for DESC. False for ASC. */
4760: } *aOrderBy; /* The ORDER BY clause */
4761:
4762: /* Outputs */
4763: struct sqlite3_index_constraint_usage {
4764: int argvIndex; /* if >0, constraint is part of argv to xFilter */
4765: unsigned char omit; /* Do not code a test for this constraint */
4766: } *aConstraintUsage;
4767: int idxNum; /* Number used to identify the index */
4768: char *idxStr; /* String, possibly obtained from sqlite3_malloc */
4769: int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
4770: int orderByConsumed; /* True if output is already ordered */
4771: double estimatedCost; /* Estimated cost of using this index */
4772: };
4773: #define SQLITE_INDEX_CONSTRAINT_EQ 2
4774: #define SQLITE_INDEX_CONSTRAINT_GT 4
4775: #define SQLITE_INDEX_CONSTRAINT_LE 8
4776: #define SQLITE_INDEX_CONSTRAINT_LT 16
4777: #define SQLITE_INDEX_CONSTRAINT_GE 32
4778: #define SQLITE_INDEX_CONSTRAINT_MATCH 64
4779:
4780: /*
1.4 ! misha 4781: ** CAPI3REF: Register A Virtual Table Implementation {F18200}
! 4782: **
1.2 misha 4783: ** This routine is used to register a new module name with an SQLite
4784: ** connection. Module names must be registered before creating new
4785: ** virtual tables on the module, or before using preexisting virtual
4786: ** tables of the module.
4787: */
4788: int sqlite3_create_module(
4789: sqlite3 *db, /* SQLite connection to register module with */
4790: const char *zName, /* Name of the module */
4791: const sqlite3_module *, /* Methods for the module */
4792: void * /* Client data for xCreate/xConnect */
4793: );
4794:
4795: /*
1.4 ! misha 4796: ** CAPI3REF: Register A Virtual Table Implementation {F18210}
! 4797: **
1.2 misha 4798: ** This routine is identical to the sqlite3_create_module() method above,
4799: ** except that it allows a destructor function to be specified. It is
4800: ** even more experimental than the rest of the virtual tables API.
4801: */
4802: int sqlite3_create_module_v2(
4803: sqlite3 *db, /* SQLite connection to register module with */
4804: const char *zName, /* Name of the module */
4805: const sqlite3_module *, /* Methods for the module */
4806: void *, /* Client data for xCreate/xConnect */
4807: void(*xDestroy)(void*) /* Module destructor function */
4808: );
4809:
4810: /*
1.4 ! misha 4811: ** CAPI3REF: Virtual Table Instance Object {F18010}
! 4812: ** KEYWORDS: sqlite3_vtab
! 4813: **
1.2 misha 4814: ** Every module implementation uses a subclass of the following structure
4815: ** to describe a particular instance of the module. Each subclass will
4816: ** be tailored to the specific needs of the module implementation. The
4817: ** purpose of this superclass is to define certain fields that are common
4818: ** to all module implementations.
4819: **
4820: ** Virtual tables methods can set an error message by assigning a
4821: ** string obtained from sqlite3_mprintf() to zErrMsg. The method should
4822: ** take care that any prior string is freed by a call to sqlite3_free()
4823: ** prior to assigning a new string to zErrMsg. After the error message
4824: ** is delivered up to the client application, the string will be automatically
4825: ** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note
4826: ** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field
4827: ** since virtual tables are commonly implemented in loadable extensions which
4828: ** do not have access to sqlite3MPrintf() or sqlite3Free().
4829: */
4830: struct sqlite3_vtab {
4831: const sqlite3_module *pModule; /* The module for this virtual table */
4832: int nRef; /* Used internally */
4833: char *zErrMsg; /* Error message from sqlite3_mprintf() */
4834: /* Virtual table implementations will typically add additional fields */
4835: };
4836:
1.4 ! misha 4837: /*
! 4838: ** CAPI3REF: Virtual Table Cursor Object {F18020}
! 4839: ** KEYWORDS: sqlite3_vtab_cursor
! 4840: **
! 4841: ** Every module implementation uses a subclass of the following structure
1.2 misha 4842: ** to describe cursors that point into the virtual table and are used
4843: ** to loop through the virtual table. Cursors are created using the
4844: ** xOpen method of the module. Each module implementation will define
4845: ** the content of a cursor structure to suit its own needs.
4846: **
4847: ** This superclass exists in order to define fields of the cursor that
4848: ** are common to all implementations.
4849: */
4850: struct sqlite3_vtab_cursor {
4851: sqlite3_vtab *pVtab; /* Virtual table of this cursor */
4852: /* Virtual table implementations will typically add additional fields */
4853: };
4854:
4855: /*
1.4 ! misha 4856: ** CAPI3REF: Declare The Schema Of A Virtual Table {F18280}
! 4857: **
1.2 misha 4858: ** The xCreate and xConnect methods of a module use the following API
4859: ** to declare the format (the names and datatypes of the columns) of
4860: ** the virtual tables they implement.
4861: */
4862: int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable);
4863:
4864: /*
1.4 ! misha 4865: ** CAPI3REF: Overload A Function For A Virtual Table {F18300}
! 4866: **
1.2 misha 4867: ** Virtual tables can provide alternative implementations of functions
4868: ** using the xFindFunction method. But global versions of those functions
4869: ** must exist in order to be overloaded.
4870: **
4871: ** This API makes sure a global version of a function with a particular
4872: ** name and number of parameters exists. If no such function exists
4873: ** before this API is called, a new function is created. The implementation
4874: ** of the new function always causes an exception to be thrown. So
4875: ** the new function is not good for anything by itself. Its only
4876: ** purpose is to be a place-holder function that can be overloaded
4877: ** by virtual tables.
4878: **
4879: ** This API should be considered part of the virtual table interface,
4880: ** which is experimental and subject to change.
4881: */
4882: int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
4883:
4884: /*
4885: ** The interface to the virtual-table mechanism defined above (back up
4886: ** to a comment remarkably similar to this one) is currently considered
4887: ** to be experimental. The interface might change in incompatible ways.
4888: ** If this is a problem for you, do not use the interface at this time.
4889: **
4890: ** When the virtual-table mechanism stabilizes, we will declare the
4891: ** interface fixed, support it indefinitely, and remove this comment.
4892: **
4893: ****** EXPERIMENTAL - subject to change without notice **************
4894: */
4895:
4896: /*
1.4 ! misha 4897: ** CAPI3REF: A Handle To An Open BLOB {F17800}
1.2 misha 4898: **
1.4 ! misha 4899: ** An instance of this object represents an open BLOB on which
! 4900: ** incremental I/O can be preformed.
! 4901: ** Objects of this type are created by
1.2 misha 4902: ** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()].
4903: ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
4904: ** can be used to read or write small subsections of the blob.
4905: ** The [sqlite3_blob_bytes()] interface returns the size of the
4906: ** blob in bytes.
4907: */
4908: typedef struct sqlite3_blob sqlite3_blob;
4909:
4910: /*
1.4 ! misha 4911: ** CAPI3REF: Open A BLOB For Incremental I/O {F17810}
1.2 misha 4912: **
1.4 ! misha 4913: ** This interfaces opens a handle to the blob located
! 4914: ** in row iRow,, column zColumn, table zTable in database zDb;
! 4915: ** in other words, the same blob that would be selected by:
1.2 misha 4916: **
4917: ** <pre>
4918: ** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;
1.4 ! misha 4919: ** </pre> {END}
1.2 misha 4920: **
4921: ** If the flags parameter is non-zero, the blob is opened for
4922: ** read and write access. If it is zero, the blob is opened for read
4923: ** access.
4924: **
4925: ** On success, [SQLITE_OK] is returned and the new
1.4 ! misha 4926: ** [sqlite3_blob | blob handle] is written to *ppBlob.
1.2 misha 4927: ** Otherwise an error code is returned and
4928: ** any value written to *ppBlob should not be used by the caller.
4929: ** This function sets the database-handle error code and message
4930: ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()].
1.4 ! misha 4931: **
! 4932: ** INVARIANTS:
! 4933: **
! 4934: ** {F17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)]
! 4935: ** interface opens an [sqlite3_blob] object P on the blob
! 4936: ** in column C of table T in database B on [database connection] D.
! 4937: **
! 4938: ** {F17814} A successful invocation of [sqlite3_blob_open(D,...)] starts
! 4939: ** a new transaction on [database connection] D if that connection
! 4940: ** is not already in a transaction.
! 4941: **
! 4942: ** {F17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface opens the blob
! 4943: ** for read and write access if and only if the F parameter
! 4944: ** is non-zero.
! 4945: **
! 4946: ** {F17819} The [sqlite3_blob_open()] interface returns [SQLITE_OK] on
! 4947: ** success and an appropriate [error code] on failure.
! 4948: **
! 4949: ** {F17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)]
! 4950: ** then subsequent calls to [sqlite3_errcode(D)],
! 4951: ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return
! 4952: ** information approprate for that error.
1.2 misha 4953: */
4954: int sqlite3_blob_open(
4955: sqlite3*,
4956: const char *zDb,
4957: const char *zTable,
4958: const char *zColumn,
4959: sqlite3_int64 iRow,
4960: int flags,
4961: sqlite3_blob **ppBlob
4962: );
4963:
4964: /*
1.4 ! misha 4965: ** CAPI3REF: Close A BLOB Handle {F17830}
1.2 misha 4966: **
4967: ** Close an open [sqlite3_blob | blob handle].
1.4 ! misha 4968: **
! 4969: ** Closing a BLOB shall cause the current transaction to commit
! 4970: ** if there are no other BLOBs, no pending prepared statements, and the
! 4971: ** database connection is in autocommit mode.
! 4972: ** If any writes were made to the BLOB, they might be held in cache
! 4973: ** until the close operation if they will fit. {END}
! 4974: ** Closing the BLOB often forces the changes
! 4975: ** out to disk and so if any I/O errors occur, they will likely occur
! 4976: ** at the time when the BLOB is closed. {F17833} Any errors that occur during
! 4977: ** closing are reported as a non-zero return value.
! 4978: **
! 4979: ** The BLOB is closed unconditionally. Even if this routine returns
! 4980: ** an error code, the BLOB is still closed.
! 4981: **
! 4982: ** INVARIANTS:
! 4983: **
! 4984: ** {F17833} The [sqlite3_blob_close(P)] interface closes an
! 4985: ** [sqlite3_blob] object P previously opened using
! 4986: ** [sqlite3_blob_open()].
! 4987: **
! 4988: ** {F17836} Closing an [sqlite3_blob] object using
! 4989: ** [sqlite3_blob_close()] shall cause the current transaction to
! 4990: ** commit if there are no other open [sqlite3_blob] objects
! 4991: ** or [prepared statements] on the same [database connection] and
! 4992: ** the [database connection] is in
! 4993: ** [sqlite3_get_autocommit | autocommit mode].
! 4994: **
! 4995: ** {F17839} The [sqlite3_blob_close(P)] interfaces closes the
! 4996: ** [sqlite3_blob] object P unconditionally, even if
! 4997: ** [sqlite3_blob_close(P)] returns something other than [SQLITE_OK].
! 4998: **
1.2 misha 4999: */
5000: int sqlite3_blob_close(sqlite3_blob *);
5001:
5002: /*
1.4 ! misha 5003: ** CAPI3REF: Return The Size Of An Open BLOB {F17840}
1.2 misha 5004: **
5005: ** Return the size in bytes of the blob accessible via the open
1.4 ! misha 5006: ** [sqlite3_blob] object in its only argument.
! 5007: **
! 5008: ** INVARIANTS:
! 5009: **
! 5010: ** {F17843} The [sqlite3_blob_bytes(P)] interface returns the size
! 5011: ** in bytes of the BLOB that the [sqlite3_blob] object P
! 5012: ** refers to.
1.2 misha 5013: */
5014: int sqlite3_blob_bytes(sqlite3_blob *);
5015:
5016: /*
1.4 ! misha 5017: ** CAPI3REF: Read Data From A BLOB Incrementally {F17850}
1.2 misha 5018: **
5019: ** This function is used to read data from an open
5020: ** [sqlite3_blob | blob-handle] into a caller supplied buffer.
1.4 ! misha 5021: ** N bytes of data are copied into buffer
! 5022: ** Z from the open blob, starting at offset iOffset.
! 5023: **
! 5024: ** If offset iOffset is less than N bytes from the end of the blob,
! 5025: ** [SQLITE_ERROR] is returned and no data is read. If N or iOffset is
! 5026: ** less than zero [SQLITE_ERROR] is returned and no data is read.
1.2 misha 5027: **
5028: ** On success, SQLITE_OK is returned. Otherwise, an
1.4 ! misha 5029: ** [error code] or an [extended error code] is returned.
! 5030: **
! 5031: ** INVARIANTS:
! 5032: **
! 5033: ** {F17853} The [sqlite3_blob_read(P,Z,N,X)] interface reads N bytes
! 5034: ** beginning at offset X from
! 5035: ** the blob that [sqlite3_blob] object P refers to
! 5036: ** and writes those N bytes into buffer Z.
! 5037: **
! 5038: ** {F17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the blob
! 5039: ** is less than N+X bytes, then the function returns [SQLITE_ERROR]
! 5040: ** and nothing is read from the blob.
! 5041: **
! 5042: ** {F17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero
! 5043: ** then the function returns [SQLITE_ERROR]
! 5044: ** and nothing is read from the blob.
! 5045: **
! 5046: ** {F17862} The [sqlite3_blob_read(P,Z,N,X)] interface returns [SQLITE_OK]
! 5047: ** if N bytes where successfully read into buffer Z.
! 5048: **
! 5049: ** {F17865} If the requested read could not be completed,
! 5050: ** the [sqlite3_blob_read(P,Z,N,X)] interface returns an
! 5051: ** appropriate [error code] or [extended error code].
! 5052: **
! 5053: ** {F17868} If an error occurs during evaluation of [sqlite3_blob_read(D,...)]
! 5054: ** then subsequent calls to [sqlite3_errcode(D)],
! 5055: ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return
! 5056: ** information approprate for that error.
1.1 misha 5057: */
1.4 ! misha 5058: int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
1.2 misha 5059:
5060: /*
1.4 ! misha 5061: ** CAPI3REF: Write Data Into A BLOB Incrementally {F17870}
1.2 misha 5062: **
5063: ** This function is used to write data into an open
5064: ** [sqlite3_blob | blob-handle] from a user supplied buffer.
5065: ** n bytes of data are copied from the buffer
5066: ** pointed to by z into the open blob, starting at offset iOffset.
5067: **
5068: ** If the [sqlite3_blob | blob-handle] passed as the first argument
5069: ** was not opened for writing (the flags parameter to [sqlite3_blob_open()]
5070: *** was zero), this function returns [SQLITE_READONLY].
5071: **
1.4 ! misha 5072: ** This function may only modify the contents of the blob; it is
! 5073: ** not possible to increase the size of a blob using this API.
! 5074: ** If offset iOffset is less than n bytes from the end of the blob,
! 5075: ** [SQLITE_ERROR] is returned and no data is written. If n is
! 5076: ** less than zero [SQLITE_ERROR] is returned and no data is written.
1.2 misha 5077: **
5078: ** On success, SQLITE_OK is returned. Otherwise, an
1.4 ! misha 5079: ** [error code] or an [extended error code] is returned.
! 5080: **
! 5081: ** INVARIANTS:
! 5082: **
! 5083: ** {F17873} The [sqlite3_blob_write(P,Z,N,X)] interface writes N bytes
! 5084: ** from buffer Z into
! 5085: ** the blob that [sqlite3_blob] object P refers to
! 5086: ** beginning at an offset of X into the blob.
! 5087: **
! 5088: ** {F17875} The [sqlite3_blob_write(P,Z,N,X)] interface returns
! 5089: ** [SQLITE_READONLY] if the [sqlite3_blob] object P was
! 5090: ** [sqlite3_blob_open | opened] for reading only.
! 5091: **
! 5092: ** {F17876} In [sqlite3_blob_write(P,Z,N,X)] if the size of the blob
! 5093: ** is less than N+X bytes, then the function returns [SQLITE_ERROR]
! 5094: ** and nothing is written into the blob.
! 5095: **
! 5096: ** {F17879} In [sqlite3_blob_write(P,Z,N,X)] if X or N is less than zero
! 5097: ** then the function returns [SQLITE_ERROR]
! 5098: ** and nothing is written into the blob.
! 5099: **
! 5100: ** {F17882} The [sqlite3_blob_write(P,Z,N,X)] interface returns [SQLITE_OK]
! 5101: ** if N bytes where successfully written into blob.
! 5102: **
! 5103: ** {F17885} If the requested write could not be completed,
! 5104: ** the [sqlite3_blob_write(P,Z,N,X)] interface returns an
! 5105: ** appropriate [error code] or [extended error code].
! 5106: **
! 5107: ** {F17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)]
! 5108: ** then subsequent calls to [sqlite3_errcode(D)],
! 5109: ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return
! 5110: ** information approprate for that error.
1.2 misha 5111: */
5112: int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
5113:
5114: /*
1.4 ! misha 5115: ** CAPI3REF: Virtual File System Objects {F11200}
1.2 misha 5116: **
5117: ** A virtual filesystem (VFS) is an [sqlite3_vfs] object
5118: ** that SQLite uses to interact
1.4 ! misha 5119: ** with the underlying operating system. Most SQLite builds come with a
1.2 misha 5120: ** single default VFS that is appropriate for the host computer.
5121: ** New VFSes can be registered and existing VFSes can be unregistered.
5122: ** The following interfaces are provided.
5123: **
1.4 ! misha 5124: ** The sqlite3_vfs_find() interface returns a pointer to
! 5125: ** a VFS given its name. Names are case sensitive.
! 5126: ** Names are zero-terminated UTF-8 strings.
! 5127: ** If there is no match, a NULL
1.2 misha 5128: ** pointer is returned. If zVfsName is NULL then the default
1.4 ! misha 5129: ** VFS is returned.
1.2 misha 5130: **
1.4 ! misha 5131: ** New VFSes are registered with sqlite3_vfs_register().
! 5132: ** Each new VFS becomes the default VFS if the makeDflt flag is set.
1.2 misha 5133: ** The same VFS can be registered multiple times without injury.
5134: ** To make an existing VFS into the default VFS, register it again
5135: ** with the makeDflt flag set. If two different VFSes with the
5136: ** same name are registered, the behavior is undefined. If a
5137: ** VFS is registered with a name that is NULL or an empty string,
5138: ** then the behavior is undefined.
5139: **
5140: ** Unregister a VFS with the sqlite3_vfs_unregister() interface.
5141: ** If the default VFS is unregistered, another VFS is chosen as
5142: ** the default. The choice for the new VFS is arbitrary.
1.4 ! misha 5143: **
! 5144: ** INVARIANTS:
! 5145: **
! 5146: ** {F11203} The [sqlite3_vfs_find(N)] interface returns a pointer to the
! 5147: ** registered [sqlite3_vfs] object whose name exactly matches
! 5148: ** the zero-terminated UTF-8 string N, or it returns NULL if
! 5149: ** there is no match.
! 5150: **
! 5151: ** {F11206} If the N parameter to [sqlite3_vfs_find(N)] is NULL then
! 5152: ** the function returns a pointer to the default [sqlite3_vfs]
! 5153: ** object if there is one, or NULL if there is no default
! 5154: ** [sqlite3_vfs] object.
! 5155: **
! 5156: ** {F11209} The [sqlite3_vfs_register(P,F)] interface registers the
! 5157: ** well-formed [sqlite3_vfs] object P using the name given
! 5158: ** by the zName field of the object.
! 5159: **
! 5160: ** {F11212} Using the [sqlite3_vfs_register(P,F)] interface to register
! 5161: ** the same [sqlite3_vfs] object multiple times is a harmless no-op.
! 5162: **
! 5163: ** {F11215} The [sqlite3_vfs_register(P,F)] interface makes the
! 5164: ** the [sqlite3_vfs] object P the default [sqlite3_vfs] object
! 5165: ** if F is non-zero.
! 5166: **
! 5167: ** {F11218} The [sqlite3_vfs_unregister(P)] interface unregisters the
! 5168: ** [sqlite3_vfs] object P so that it is no longer returned by
! 5169: ** subsequent calls to [sqlite3_vfs_find()].
1.2 misha 5170: */
5171: sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
5172: int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
5173: int sqlite3_vfs_unregister(sqlite3_vfs*);
5174:
5175: /*
1.4 ! misha 5176: ** CAPI3REF: Mutexes {F17000}
1.2 misha 5177: **
5178: ** The SQLite core uses these routines for thread
5179: ** synchronization. Though they are intended for internal
5180: ** use by SQLite, code that links against SQLite is
5181: ** permitted to use any of these routines.
5182: **
5183: ** The SQLite source code contains multiple implementations
5184: ** of these mutex routines. An appropriate implementation
5185: ** is selected automatically at compile-time. The following
5186: ** implementations are available in the SQLite core:
5187: **
5188: ** <ul>
5189: ** <li> SQLITE_MUTEX_OS2
5190: ** <li> SQLITE_MUTEX_PTHREAD
5191: ** <li> SQLITE_MUTEX_W32
5192: ** <li> SQLITE_MUTEX_NOOP
5193: ** </ul>
5194: **
5195: ** The SQLITE_MUTEX_NOOP implementation is a set of routines
5196: ** that does no real locking and is appropriate for use in
5197: ** a single-threaded application. The SQLITE_MUTEX_OS2,
5198: ** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations
5199: ** are appropriate for use on os/2, unix, and windows.
5200: **
5201: ** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
5202: ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
5203: ** implementation is included with the library. The
5204: ** mutex interface routines defined here become external
5205: ** references in the SQLite library for which implementations
5206: ** must be provided by the application. This facility allows an
5207: ** application that links against SQLite to provide its own mutex
5208: ** implementation without having to modify the SQLite core.
5209: **
1.4 ! misha 5210: ** {F17011} The sqlite3_mutex_alloc() routine allocates a new
! 5211: ** mutex and returns a pointer to it. {F17012} If it returns NULL
! 5212: ** that means that a mutex could not be allocated. {F17013} SQLite
! 5213: ** will unwind its stack and return an error. {F17014} The argument
1.2 misha 5214: ** to sqlite3_mutex_alloc() is one of these integer constants:
5215: **
5216: ** <ul>
5217: ** <li> SQLITE_MUTEX_FAST
5218: ** <li> SQLITE_MUTEX_RECURSIVE
5219: ** <li> SQLITE_MUTEX_STATIC_MASTER
5220: ** <li> SQLITE_MUTEX_STATIC_MEM
5221: ** <li> SQLITE_MUTEX_STATIC_MEM2
5222: ** <li> SQLITE_MUTEX_STATIC_PRNG
5223: ** <li> SQLITE_MUTEX_STATIC_LRU
1.4 ! misha 5224: ** </ul> {END}
1.2 misha 5225: **
1.4 ! misha 5226: ** {F17015} The first two constants cause sqlite3_mutex_alloc() to create
1.2 misha 5227: ** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
1.4 ! misha 5228: ** is used but not necessarily so when SQLITE_MUTEX_FAST is used. {END}
1.2 misha 5229: ** The mutex implementation does not need to make a distinction
5230: ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
1.4 ! misha 5231: ** not want to. {F17016} But SQLite will only request a recursive mutex in
! 5232: ** cases where it really needs one. {END} If a faster non-recursive mutex
1.2 misha 5233: ** implementation is available on the host platform, the mutex subsystem
5234: ** might return such a mutex in response to SQLITE_MUTEX_FAST.
5235: **
1.4 ! misha 5236: ** {F17017} The other allowed parameters to sqlite3_mutex_alloc() each return
! 5237: ** a pointer to a static preexisting mutex. {END} Four static mutexes are
1.2 misha 5238: ** used by the current version of SQLite. Future versions of SQLite
5239: ** may add additional static mutexes. Static mutexes are for internal
5240: ** use by SQLite only. Applications that use SQLite mutexes should
5241: ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
5242: ** SQLITE_MUTEX_RECURSIVE.
5243: **
1.4 ! misha 5244: ** {F17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
1.2 misha 5245: ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
1.4 ! misha 5246: ** returns a different mutex on every call. {F17034} But for the static
1.2 misha 5247: ** mutex types, the same mutex is returned on every call that has
1.4 ! misha 5248: ** the same type number. {END}
1.2 misha 5249: **
1.4 ! misha 5250: ** {F17019} The sqlite3_mutex_free() routine deallocates a previously
! 5251: ** allocated dynamic mutex. {F17020} SQLite is careful to deallocate every
! 5252: ** dynamic mutex that it allocates. {U17021} The dynamic mutexes must not be in
! 5253: ** use when they are deallocated. {U17022} Attempting to deallocate a static
! 5254: ** mutex results in undefined behavior. {F17023} SQLite never deallocates
! 5255: ** a static mutex. {END}
1.2 misha 5256: **
5257: ** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
1.4 ! misha 5258: ** to enter a mutex. {F17024} If another thread is already within the mutex,
1.2 misha 5259: ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
1.4 ! misha 5260: ** SQLITE_BUSY. {F17025} The sqlite3_mutex_try() interface returns SQLITE_OK
! 5261: ** upon successful entry. {F17026} Mutexes created using
! 5262: ** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
! 5263: ** {F17027} In such cases the,
1.2 misha 5264: ** mutex must be exited an equal number of times before another thread
1.4 ! misha 5265: ** can enter. {U17028} If the same thread tries to enter any other
! 5266: ** kind of mutex more than once, the behavior is undefined.
! 5267: ** {F17029} SQLite will never exhibit
! 5268: ** such behavior in its own use of mutexes. {END}
1.2 misha 5269: **
5270: ** Some systems (ex: windows95) do not the operation implemented by
5271: ** sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() will
1.4 ! misha 5272: ** always return SQLITE_BUSY. {F17030} The SQLite core only ever uses
! 5273: ** sqlite3_mutex_try() as an optimization so this is acceptable behavior. {END}
1.2 misha 5274: **
1.4 ! misha 5275: ** {F17031} The sqlite3_mutex_leave() routine exits a mutex that was
! 5276: ** previously entered by the same thread. {U17032} The behavior
1.2 misha 5277: ** is undefined if the mutex is not currently entered by the
1.4 ! misha 5278: ** calling thread or is not currently allocated. {F17033} SQLite will
! 5279: ** never do either. {END}
1.2 misha 5280: **
5281: ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
5282: */
5283: sqlite3_mutex *sqlite3_mutex_alloc(int);
5284: void sqlite3_mutex_free(sqlite3_mutex*);
5285: void sqlite3_mutex_enter(sqlite3_mutex*);
5286: int sqlite3_mutex_try(sqlite3_mutex*);
5287: void sqlite3_mutex_leave(sqlite3_mutex*);
5288:
5289: /*
1.4 ! misha 5290: ** CAPI3REF: Mutex Verifcation Routines {F17080}
1.2 misha 5291: **
5292: ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
1.4 ! misha 5293: ** are intended for use inside assert() statements. {F17081} The SQLite core
1.2 misha 5294: ** never uses these routines except inside an assert() and applications
1.4 ! misha 5295: ** are advised to follow the lead of the core. {F17082} The core only
1.2 misha 5296: ** provides implementations for these routines when it is compiled
1.4 ! misha 5297: ** with the SQLITE_DEBUG flag. {U17087} External mutex implementations
1.2 misha 5298: ** are only required to provide these routines if SQLITE_DEBUG is
5299: ** defined and if NDEBUG is not defined.
5300: **
1.4 ! misha 5301: ** {F17083} These routines should return true if the mutex in their argument
! 5302: ** is held or not held, respectively, by the calling thread. {END}
1.2 misha 5303: **
1.4 ! misha 5304: ** {X17084} The implementation is not required to provided versions of these
1.2 misha 5305: ** routines that actually work.
5306: ** If the implementation does not provide working
5307: ** versions of these routines, it should at least provide stubs
5308: ** that always return true so that one does not get spurious
1.4 ! misha 5309: ** assertion failures. {END}
1.2 misha 5310: **
1.4 ! misha 5311: ** {F17085} If the argument to sqlite3_mutex_held() is a NULL pointer then
! 5312: ** the routine should return 1. {END} This seems counter-intuitive since
1.2 misha 5313: ** clearly the mutex cannot be held if it does not exist. But the
5314: ** the reason the mutex does not exist is because the build is not
5315: ** using mutexes. And we do not want the assert() containing the
5316: ** call to sqlite3_mutex_held() to fail, so a non-zero return is
1.4 ! misha 5317: ** the appropriate thing to do. {F17086} The sqlite3_mutex_notheld()
1.2 misha 5318: ** interface should also return 1 when given a NULL pointer.
5319: */
5320: int sqlite3_mutex_held(sqlite3_mutex*);
5321: int sqlite3_mutex_notheld(sqlite3_mutex*);
5322:
5323: /*
1.4 ! misha 5324: ** CAPI3REF: Mutex Types {F17001}
1.2 misha 5325: **
1.4 ! misha 5326: ** {F17002} The [sqlite3_mutex_alloc()] interface takes a single argument
! 5327: ** which is one of these integer constants. {END}
1.2 misha 5328: */
5329: #define SQLITE_MUTEX_FAST 0
5330: #define SQLITE_MUTEX_RECURSIVE 1
5331: #define SQLITE_MUTEX_STATIC_MASTER 2
5332: #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */
5333: #define SQLITE_MUTEX_STATIC_MEM2 4 /* sqlite3_release_memory() */
5334: #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */
5335: #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
5336:
5337: /*
1.4 ! misha 5338: ** CAPI3REF: Low-Level Control Of Database Files {F11300}
1.2 misha 5339: **
1.4 ! misha 5340: ** {F11301} The [sqlite3_file_control()] interface makes a direct call to the
1.2 misha 5341: ** xFileControl method for the [sqlite3_io_methods] object associated
1.4 ! misha 5342: ** with a particular database identified by the second argument. {F11302} The
1.2 misha 5343: ** name of the database is the name assigned to the database by the
5344: ** <a href="lang_attach.html">ATTACH</a> SQL command that opened the
1.4 ! misha 5345: ** database. {F11303} To control the main database file, use the name "main"
! 5346: ** or a NULL pointer. {F11304} The third and fourth parameters to this routine
1.2 misha 5347: ** are passed directly through to the second and third parameters of
1.4 ! misha 5348: ** the xFileControl method. {F11305} The return value of the xFileControl
1.2 misha 5349: ** method becomes the return value of this routine.
5350: **
1.4 ! misha 5351: ** {F11306} If the second parameter (zDbName) does not match the name of any
! 5352: ** open database file, then SQLITE_ERROR is returned. {F11307} This error
1.2 misha 5353: ** code is not remembered and will not be recalled by [sqlite3_errcode()]
1.4 ! misha 5354: ** or [sqlite3_errmsg()]. {U11308} The underlying xFileControl method might
! 5355: ** also return SQLITE_ERROR. {U11309} There is no way to distinguish between
1.2 misha 5356: ** an incorrect zDbName and an SQLITE_ERROR return from the underlying
1.4 ! misha 5357: ** xFileControl method. {END}
1.2 misha 5358: **
5359: ** See also: [SQLITE_FCNTL_LOCKSTATE]
5360: */
5361: int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
5362:
5363: /*
1.4 ! misha 5364: ** CAPI3REF: Testing Interface {F11400}
! 5365: **
! 5366: ** The sqlite3_test_control() interface is used to read out internal
! 5367: ** state of SQLite and to inject faults into SQLite for testing
! 5368: ** purposes. The first parameter a operation code that determines
! 5369: ** the number, meaning, and operation of all subsequent parameters.
! 5370: **
! 5371: ** This interface is not for use by applications. It exists solely
! 5372: ** for verifying the correct operation of the SQLite library. Depending
! 5373: ** on how the SQLite library is compiled, this interface might not exist.
! 5374: **
! 5375: ** The details of the operation codes, their meanings, the parameters
! 5376: ** they take, and what they do are all subject to change without notice.
! 5377: ** Unlike most of the SQLite API, this function is not guaranteed to
! 5378: ** operate consistently from one release to the next.
! 5379: */
! 5380: int sqlite3_test_control(int op, ...);
! 5381:
! 5382: /*
! 5383: ** CAPI3REF: Testing Interface Operation Codes {F11410}
! 5384: **
! 5385: ** These constants are the valid operation code parameters used
! 5386: ** as the first argument to [sqlite3_test_control()].
! 5387: **
! 5388: ** These parameters and their meansing are subject to change
! 5389: ** without notice. These values are for testing purposes only.
! 5390: ** Applications should not use any of these parameters or the
! 5391: ** [sqlite3_test_control()] interface.
! 5392: */
! 5393: #define SQLITE_TESTCTRL_FAULT_CONFIG 1
! 5394: #define SQLITE_TESTCTRL_FAULT_FAILURES 2
! 5395: #define SQLITE_TESTCTRL_FAULT_BENIGN_FAILURES 3
! 5396: #define SQLITE_TESTCTRL_FAULT_PENDING 4
! 5397:
! 5398:
! 5399:
! 5400:
! 5401:
! 5402: /*
1.2 misha 5403: ** Undo the hack that converts floating point types to integer for
5404: ** builds on processors without floating point support.
5405: */
5406: #ifdef SQLITE_OMIT_FLOATING_POINT
5407: # undef double
5408: #endif
1.1 misha 5409:
5410: #ifdef __cplusplus
5411: } /* End of the 'extern "C"' block */
5412: #endif
5413: #endif
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to sqlite3.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / sql / sqlite / include