Annotation of win32/sql/sqlite/include/sqlite3.h, revision 1.2
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.2 ! misha 33: ** @(#) $Id: sqlite.h.in,v 1.266 2007/10/03 20:15:28 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.2 ! misha 66: ** CAPI3REF: Compile-Time Library Version Numbers
! 67: **
! 68: ** The version of the SQLite library is contained in the sqlite3.h
! 69: ** header file in a #define named SQLITE_VERSION. The SQLITE_VERSION
! 70: ** macro resolves to a string constant.
! 71: **
! 72: ** The format of the version string is "X.Y.Z", where
! 73: ** X is the major version number, Y is the minor version number and Z
! 74: ** is the release number. The X.Y.Z might be followed by "alpha" or "beta".
! 75: ** For example "3.1.1beta".
! 76: **
! 77: ** The X value is always 3 in SQLite. The X value only changes when
! 78: ** backwards compatibility is broken and we intend to never break
! 79: ** backwards compatibility. The Y value only changes when
! 80: ** there are major feature enhancements that are forwards compatible
! 81: ** but not backwards compatible. The Z value is incremented with
! 82: ** each release but resets back to 0 when Y is incremented.
! 83: **
! 84: ** The SQLITE_VERSION_NUMBER is an integer with the value
! 85: ** (X*1000000 + Y*1000 + Z). For example, for version "3.1.1beta",
! 86: ** SQLITE_VERSION_NUMBER is set to 3001001. To detect if they are using
! 87: ** version 3.1.1 or greater at compile time, programs may use the test
! 88: ** (SQLITE_VERSION_NUMBER>=3001001).
! 89: **
! 90: ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
! 91: */
! 92: #define SQLITE_VERSION "3.5.1"
! 93: #define SQLITE_VERSION_NUMBER 3005001
! 94:
! 95: /*
! 96: ** CAPI3REF: Run-Time Library Version Numbers
! 97: **
! 98: ** These routines return values equivalent to the header constants
! 99: ** [SQLITE_VERSION] and [SQLITE_VERSION_NUMBER]. The values returned
! 100: ** by this routines should only be different from the header values
! 101: ** if you compile your program using an sqlite3.h header from a
! 102: ** different version of SQLite that the version of the library you
! 103: ** link against.
! 104: **
! 105: ** The sqlite3_version[] string constant contains the text of the
! 106: ** [SQLITE_VERSION] string. The sqlite3_libversion() function returns
! 107: ** a poiner to the sqlite3_version[] string constant. The function
! 108: ** is provided for DLL users who can only access functions and not
! 109: ** constants within the DLL.
1.1 misha 110: */
1.2 ! misha 111: SQLITE_EXTERN const char sqlite3_version[];
1.1 misha 112: const char *sqlite3_libversion(void);
1.2 ! misha 113: int sqlite3_libversion_number(void);
1.1 misha 114:
115: /*
1.2 ! misha 116: ** CAPI3REF: Test To See If The Library Is Threadsafe
! 117: **
! 118: ** This routine returns TRUE (nonzero) if SQLite was compiled with
! 119: ** all of its mutexes enabled and is thus threadsafe. It returns
! 120: ** zero if the particular build is for single-threaded operation
! 121: ** only.
! 122: **
! 123: ** Really all this routine does is return true if SQLite was compiled
! 124: ** with the -DSQLITE_THREADSAFE=1 option and false if
! 125: ** compiled with -DSQLITE_THREADSAFE=0. If SQLite uses an
! 126: ** application-defined mutex subsystem, malloc subsystem, collating
! 127: ** sequence, VFS, SQL function, progress callback, commit hook,
! 128: ** extension, or other accessories and these add-ons are not
! 129: ** threadsafe, then clearly the combination will not be threadsafe
! 130: ** either. Hence, this routine never reports that the library
! 131: ** is guaranteed to be threadsafe, only when it is guaranteed not
! 132: ** to be.
! 133: **
! 134: ** This is an experimental API and may go away or change in future
! 135: ** releases.
! 136: */
! 137: int sqlite3_threadsafe(void);
! 138:
! 139: /*
! 140: ** CAPI3REF: Database Connection Handle
! 141: **
! 142: ** Each open SQLite database is represented by pointer to an instance of the
! 143: ** opaque structure named "sqlite3". It is useful to think of an sqlite3
! 144: ** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and
! 145: ** [sqlite3_open_v2()] interfaces are its constructors
! 146: ** and [sqlite3_close()] is its destructor. There are many other interfaces
! 147: ** (such as [sqlite3_prepare_v2()], [sqlite3_create_function()], and
! 148: ** [sqlite3_busy_timeout()] to name but three) that are methods on this
! 149: ** object.
1.1 misha 150: */
151: typedef struct sqlite3 sqlite3;
152:
153:
154: /*
1.2 ! misha 155: ** CAPI3REF: 64-Bit Integer Types
! 156: **
1.1 misha 157: ** Some compilers do not support the "long long" datatype. So we have
1.2 ! misha 158: ** to do compiler-specific typedefs for 64-bit signed and unsigned integers.
! 159: **
! 160: ** Many SQLite interface functions require a 64-bit integer arguments.
! 161: ** Those interfaces are declared using this typedef.
1.1 misha 162: */
1.2 ! misha 163: #ifdef SQLITE_INT64_TYPE
! 164: typedef SQLITE_INT64_TYPE sqlite_int64;
! 165: typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
! 166: #elif defined(_MSC_VER) || defined(__BORLANDC__)
1.1 misha 167: typedef __int64 sqlite_int64;
168: typedef unsigned __int64 sqlite_uint64;
169: #else
170: typedef long long int sqlite_int64;
171: typedef unsigned long long int sqlite_uint64;
172: #endif
1.2 ! misha 173: typedef sqlite_int64 sqlite3_int64;
! 174: typedef sqlite_uint64 sqlite3_uint64;
1.1 misha 175:
1.2 ! misha 176: /*
! 177: ** If compiling for a processor that lacks floating point support,
! 178: ** substitute integer for floating-point
! 179: */
! 180: #ifdef SQLITE_OMIT_FLOATING_POINT
! 181: # define double sqlite3_int64
! 182: #endif
1.1 misha 183:
184: /*
1.2 ! misha 185: ** CAPI3REF: Closing A Database Connection
1.1 misha 186: **
187: ** Call this function with a pointer to a structure that was previously
1.2 ! misha 188: ** returned from [sqlite3_open()], [sqlite3_open16()], or
! 189: ** [sqlite3_open_v2()] and the corresponding database will by
! 190: ** closed.
! 191: **
! 192: ** All SQL statements prepared using [sqlite3_prepare_v2()] or
! 193: ** [sqlite3_prepare16_v2()] must be destroyed using [sqlite3_finalize()]
! 194: ** before this routine is called. Otherwise, SQLITE_BUSY is returned and the
! 195: ** database connection remains open.
1.1 misha 196: **
1.2 ! misha 197: ** Passing this routine a database connection that has already been
! 198: ** closed results in undefined behavior. If other interfaces that
! 199: ** reference the same database connection are pending (either in the
! 200: ** same thread or in different threads) when this routine is called,
! 201: ** then the behavior is undefined and is almost certainly undesirable.
1.1 misha 202: */
203: int sqlite3_close(sqlite3 *);
204:
205: /*
206: ** The type for a callback function.
1.2 ! misha 207: ** This is legacy and deprecated. It is included for historical
! 208: ** compatibility and is not documented.
1.1 misha 209: */
210: typedef int (*sqlite3_callback)(void*,int,char**, char**);
211:
212: /*
1.2 ! misha 213: ** CAPI3REF: One-Step Query Execution Interface
! 214: **
! 215: ** This interface is used to do a one-time evaluatation of zero
! 216: ** or more SQL statements. UTF-8 text of the SQL statements to
! 217: ** be evaluted is passed in as the second parameter. The statements
! 218: ** are prepared one by one using [sqlite3_prepare()], evaluated
! 219: ** using [sqlite3_step()], then destroyed using [sqlite3_finalize()].
1.1 misha 220: **
221: ** If one or more of the SQL statements are queries, then
222: ** the callback function specified by the 3rd parameter is
223: ** invoked once for each row of the query result. This callback
224: ** should normally return 0. If the callback returns a non-zero
225: ** value then the query is aborted, all subsequent SQL statements
1.2 ! misha 226: ** are skipped and the sqlite3_exec() function returns the [SQLITE_ABORT].
1.1 misha 227: **
1.2 ! misha 228: ** The 4th parameter to this interface is an arbitrary pointer that is
! 229: ** passed through to the callback function as its first parameter.
1.1 misha 230: **
231: ** The 2nd parameter to the callback function is the number of
232: ** columns in the query result. The 3rd parameter to the callback
1.2 ! misha 233: ** is an array of strings holding the values for each column
! 234: ** as extracted using [sqlite3_column_text()].
! 235: ** The 4th parameter to the callback is an array of strings
! 236: ** obtained using [sqlite3_column_name()] and holding
1.1 misha 237: ** the names of each column.
238: **
239: ** The callback function may be NULL, even for queries. A NULL
240: ** callback is not an error. It just means that no callback
241: ** will be invoked.
242: **
243: ** If an error occurs while parsing or evaluating the SQL (but
244: ** not while executing the callback) then an appropriate error
1.2 ! misha 245: ** message is written into memory obtained from [sqlite3_malloc()] and
1.1 misha 246: ** *errmsg is made to point to that message. The calling function
1.2 ! misha 247: ** is responsible for freeing the memory using [sqlite3_free()].
! 248: ** If errmsg==NULL, then no error message is ever written.
1.1 misha 249: **
250: ** The return value is is SQLITE_OK if there are no errors and
1.2 ! misha 251: ** some other [SQLITE_OK | return code] if there is an error.
! 252: ** The particular return value depends on the type of error.
1.1 misha 253: **
254: */
255: int sqlite3_exec(
1.2 ! misha 256: sqlite3*, /* An open database */
! 257: const char *sql, /* SQL to be evaluted */
! 258: int (*callback)(void*,int,char**,char**), /* Callback function */
! 259: void *, /* 1st argument to callback */
! 260: char **errmsg /* Error msg written here */
1.1 misha 261: );
262:
263: /*
1.2 ! misha 264: ** CAPI3REF: Result Codes
! 265: ** KEYWORDS: SQLITE_OK
! 266: **
! 267: ** Many SQLite functions return an integer result code from the set shown
! 268: ** above in order to indicates success or failure.
! 269: **
! 270: ** The result codes above are the only ones returned by SQLite in its
! 271: ** default configuration. However, the [sqlite3_extended_result_codes()]
! 272: ** API can be used to set a database connectoin to return more detailed
! 273: ** result codes.
! 274: **
! 275: ** See also: [SQLITE_IOERR_READ | extended result codes]
! 276: **
1.1 misha 277: */
278: #define SQLITE_OK 0 /* Successful result */
1.2 ! misha 279: /* beginning-of-error-codes */
1.1 misha 280: #define SQLITE_ERROR 1 /* SQL error or missing database */
1.2 ! misha 281: #define SQLITE_INTERNAL 2 /* NOT USED. Internal logic error in SQLite */
1.1 misha 282: #define SQLITE_PERM 3 /* Access permission denied */
283: #define SQLITE_ABORT 4 /* Callback routine requested an abort */
284: #define SQLITE_BUSY 5 /* The database file is locked */
285: #define SQLITE_LOCKED 6 /* A table in the database is locked */
286: #define SQLITE_NOMEM 7 /* A malloc() failed */
287: #define SQLITE_READONLY 8 /* Attempt to write a readonly database */
288: #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
289: #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
290: #define SQLITE_CORRUPT 11 /* The database disk image is malformed */
1.2 ! misha 291: #define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */
1.1 misha 292: #define SQLITE_FULL 13 /* Insertion failed because database is full */
293: #define SQLITE_CANTOPEN 14 /* Unable to open the database file */
1.2 ! misha 294: #define SQLITE_PROTOCOL 15 /* NOT USED. Database lock protocol error */
1.1 misha 295: #define SQLITE_EMPTY 16 /* Database is empty */
296: #define SQLITE_SCHEMA 17 /* The database schema changed */
1.2 ! misha 297: #define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
! 298: #define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
1.1 misha 299: #define SQLITE_MISMATCH 20 /* Data type mismatch */
300: #define SQLITE_MISUSE 21 /* Library used incorrectly */
301: #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
302: #define SQLITE_AUTH 23 /* Authorization denied */
303: #define SQLITE_FORMAT 24 /* Auxiliary database format error */
304: #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
305: #define SQLITE_NOTADB 26 /* File opened that is not a database file */
306: #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
307: #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
1.2 ! misha 308: /* end-of-error-codes */
1.1 misha 309:
310: /*
1.2 ! misha 311: ** CAPI3REF: Extended Result Codes
1.1 misha 312: **
1.2 ! misha 313: ** In its default configuration, SQLite API routines return one of 26 integer
! 314: ** result codes described at result-codes. However, experience has shown that
! 315: ** many of these result codes are too course-grained. They do not provide as
! 316: ** much information about problems as users might like. In an effort to
! 317: ** address this, newer versions of SQLite (version 3.3.8 and later) include
! 318: ** support for additional result codes that provide more detailed information
! 319: ** about errors. The extended result codes are enabled (or disabled) for
! 320: ** each database
! 321: ** connection using the [sqlite3_extended_result_codes()] API.
! 322: **
! 323: ** Some of the available extended result codes are listed above.
! 324: ** We expect the number of extended result codes will be expand
! 325: ** over time. Software that uses extended result codes should expect
! 326: ** to see new result codes in future releases of SQLite.
! 327: **
! 328: ** The symbolic name for an extended result code always contains a related
! 329: ** primary result code as a prefix. Primary result codes contain a single
! 330: ** "_" character. Extended result codes contain two or more "_" characters.
! 331: ** The numeric value of an extended result code can be converted to its
! 332: ** corresponding primary result code by masking off the lower 8 bytes.
! 333: **
! 334: ** The SQLITE_OK result code will never be extended. It will always
! 335: ** be exactly zero.
! 336: */
! 337: #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))
! 338: #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))
! 339: #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8))
! 340: #define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8))
! 341: #define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8))
! 342: #define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8))
! 343: #define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8))
! 344: #define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8))
! 345: #define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8))
! 346: #define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8))
! 347: #define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8))
! 348: #define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8))
! 349:
! 350: /*
! 351: ** CAPI3REF: Flags For File Open Operations
! 352: **
! 353: ** Combination of the following bit values are used as the
! 354: ** third argument to the [sqlite3_open_v2()] interface and
! 355: ** as fourth argument to the xOpen method of the
! 356: ** [sqlite3_vfs] object.
! 357: **
! 358: */
! 359: #define SQLITE_OPEN_READONLY 0x00000001
! 360: #define SQLITE_OPEN_READWRITE 0x00000002
! 361: #define SQLITE_OPEN_CREATE 0x00000004
! 362: #define SQLITE_OPEN_DELETEONCLOSE 0x00000008
! 363: #define SQLITE_OPEN_EXCLUSIVE 0x00000010
! 364: #define SQLITE_OPEN_MAIN_DB 0x00000100
! 365: #define SQLITE_OPEN_TEMP_DB 0x00000200
! 366: #define SQLITE_OPEN_TRANSIENT_DB 0x00000400
! 367: #define SQLITE_OPEN_MAIN_JOURNAL 0x00000800
! 368: #define SQLITE_OPEN_TEMP_JOURNAL 0x00001000
! 369: #define SQLITE_OPEN_SUBJOURNAL 0x00002000
! 370: #define SQLITE_OPEN_MASTER_JOURNAL 0x00004000
! 371:
! 372: /*
! 373: ** CAPI3REF: Device Characteristics
! 374: **
! 375: ** The xDeviceCapabilities method of the [sqlite3_io_methods]
! 376: ** object returns an integer which is a vector of the following
! 377: ** bit values expressing I/O characteristics of the mass storage
! 378: ** device that holds the file that the [sqlite3_io_methods]
! 379: ** refers to.
! 380: **
! 381: ** The SQLITE_IOCAP_ATOMIC property means that all writes of
! 382: ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
! 383: ** mean that writes of blocks that are nnn bytes in size and
! 384: ** are aligned to an address which is an integer multiple of
! 385: ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
! 386: ** that when data is appended to a file, the data is appended
! 387: ** first then the size of the file is extended, never the other
! 388: ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
! 389: ** information is written to disk in the same order as calls
! 390: ** to xWrite().
! 391: */
! 392: #define SQLITE_IOCAP_ATOMIC 0x00000001
! 393: #define SQLITE_IOCAP_ATOMIC512 0x00000002
! 394: #define SQLITE_IOCAP_ATOMIC1K 0x00000004
! 395: #define SQLITE_IOCAP_ATOMIC2K 0x00000008
! 396: #define SQLITE_IOCAP_ATOMIC4K 0x00000010
! 397: #define SQLITE_IOCAP_ATOMIC8K 0x00000020
! 398: #define SQLITE_IOCAP_ATOMIC16K 0x00000040
! 399: #define SQLITE_IOCAP_ATOMIC32K 0x00000080
! 400: #define SQLITE_IOCAP_ATOMIC64K 0x00000100
! 401: #define SQLITE_IOCAP_SAFE_APPEND 0x00000200
! 402: #define SQLITE_IOCAP_SEQUENTIAL 0x00000400
! 403:
! 404: /*
! 405: ** CAPI3REF: File Locking Levels
! 406: **
! 407: ** SQLite uses one of the following integer values as the second
! 408: ** argument to calls it makes to the xLock() and xUnlock() methods
! 409: ** of an [sqlite3_io_methods] object.
! 410: */
! 411: #define SQLITE_LOCK_NONE 0
! 412: #define SQLITE_LOCK_SHARED 1
! 413: #define SQLITE_LOCK_RESERVED 2
! 414: #define SQLITE_LOCK_PENDING 3
! 415: #define SQLITE_LOCK_EXCLUSIVE 4
! 416:
! 417: /*
! 418: ** CAPI3REF: Synchronization Type Flags
! 419: **
! 420: ** When SQLite invokes the xSync() method of an [sqlite3_io_methods]
! 421: ** object it uses a combination of the following integer values as
! 422: ** the second argument.
! 423: **
! 424: ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
! 425: ** sync operation only needs to flush data to mass storage. Inode
! 426: ** information need not be flushed. The SQLITE_SYNC_NORMAL means
! 427: ** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means
! 428: ** to use Mac OS-X style fullsync instead of fsync().
! 429: */
! 430: #define SQLITE_SYNC_NORMAL 0x00002
! 431: #define SQLITE_SYNC_FULL 0x00003
! 432: #define SQLITE_SYNC_DATAONLY 0x00010
! 433:
! 434:
! 435: /*
! 436: ** CAPI3REF: OS Interface Open File Handle
! 437: **
! 438: ** An [sqlite3_file] object represents an open file in the OS
! 439: ** interface layer. Individual OS interface implementations will
! 440: ** want to subclass this object by appending additional fields
! 441: ** for their own use. The pMethods entry is a pointer to an
! 442: ** [sqlite3_io_methods] object that defines methods for performing
! 443: ** I/O operations on the open file.
! 444: */
! 445: typedef struct sqlite3_file sqlite3_file;
! 446: struct sqlite3_file {
! 447: const struct sqlite3_io_methods *pMethods; /* Methods for an open file */
! 448: };
! 449:
! 450: /*
! 451: ** CAPI3REF: OS Interface File Virtual Methods Object
! 452: **
! 453: ** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to
! 454: ** an instance of the this object. This object defines the
! 455: ** methods used to perform various operations against the open file.
! 456: **
! 457: ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
! 458: ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
! 459: * The second choice is an
! 460: ** OS-X style fullsync. The SQLITE_SYNC_DATA flag may be ORed in to
! 461: ** indicate that only the data of the file and not its inode needs to be
! 462: ** synced.
! 463: **
! 464: ** The integer values to xLock() and xUnlock() are one of
! 465: ** <ul>
! 466: ** <li> [SQLITE_LOCK_NONE],
! 467: ** <li> [SQLITE_LOCK_SHARED],
! 468: ** <li> [SQLITE_LOCK_RESERVED],
! 469: ** <li> [SQLITE_LOCK_PENDING], or
! 470: ** <li> [SQLITE_LOCK_EXCLUSIVE].
! 471: ** </ul>
! 472: ** xLock() increases the lock. xUnlock() decreases the lock.
! 473: ** The xCheckReservedLock() method looks
! 474: ** to see if any database connection, either in this
! 475: ** process or in some other process, is holding an RESERVED,
! 476: ** PENDING, or EXCLUSIVE lock on the file. It returns true
! 477: ** if such a lock exists and false if not.
! 478: **
! 479: ** The xFileControl() method is a generic interface that allows custom
! 480: ** VFS implementations to directly control an open file using the
! 481: ** [sqlite3_file_control()] interface. The second "op" argument
! 482: ** is an integer opcode. The third
! 483: ** argument is a generic pointer which is intended to be a pointer
! 484: ** to a structure that may contain arguments or space in which to
! 485: ** write return values. Potential uses for xFileControl() might be
! 486: ** functions to enable blocking locks with timeouts, to change the
! 487: ** locking strategy (for example to use dot-file locks), to inquire
! 488: ** about the status of a lock, or to break stale locks. The SQLite
! 489: ** core reserves opcodes less than 100 for its own use.
! 490: ** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
! 491: ** Applications that define a custom xFileControl method should use opcodes
! 492: ** greater than 100 to avoid conflicts.
! 493: **
! 494: ** The xSectorSize() method returns the sector size of the
! 495: ** device that underlies the file. The sector size is the
! 496: ** minimum write that can be performed without disturbing
! 497: ** other bytes in the file. The xDeviceCharacteristics()
! 498: ** method returns a bit vector describing behaviors of the
! 499: ** underlying device:
! 500: **
! 501: ** <ul>
! 502: ** <li> [SQLITE_IOCAP_ATOMIC]
! 503: ** <li> [SQLITE_IOCAP_ATOMIC512]
! 504: ** <li> [SQLITE_IOCAP_ATOMIC1K]
! 505: ** <li> [SQLITE_IOCAP_ATOMIC2K]
! 506: ** <li> [SQLITE_IOCAP_ATOMIC4K]
! 507: ** <li> [SQLITE_IOCAP_ATOMIC8K]
! 508: ** <li> [SQLITE_IOCAP_ATOMIC16K]
! 509: ** <li> [SQLITE_IOCAP_ATOMIC32K]
! 510: ** <li> [SQLITE_IOCAP_ATOMIC64K]
! 511: ** <li> [SQLITE_IOCAP_SAFE_APPEND]
! 512: ** <li> [SQLITE_IOCAP_SEQUENTIAL]
! 513: ** </ul>
! 514: **
! 515: ** The SQLITE_IOCAP_ATOMIC property means that all writes of
! 516: ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
! 517: ** mean that writes of blocks that are nnn bytes in size and
! 518: ** are aligned to an address which is an integer multiple of
! 519: ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
! 520: ** that when data is appended to a file, the data is appended
! 521: ** first then the size of the file is extended, never the other
! 522: ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
! 523: ** information is written to disk in the same order as calls
! 524: ** to xWrite().
! 525: */
! 526: typedef struct sqlite3_io_methods sqlite3_io_methods;
! 527: struct sqlite3_io_methods {
! 528: int iVersion;
! 529: int (*xClose)(sqlite3_file*);
! 530: int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
! 531: int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
! 532: int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
! 533: int (*xSync)(sqlite3_file*, int flags);
! 534: int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
! 535: int (*xLock)(sqlite3_file*, int);
! 536: int (*xUnlock)(sqlite3_file*, int);
! 537: int (*xCheckReservedLock)(sqlite3_file*);
! 538: int (*xFileControl)(sqlite3_file*, int op, void *pArg);
! 539: int (*xSectorSize)(sqlite3_file*);
! 540: int (*xDeviceCharacteristics)(sqlite3_file*);
! 541: /* Additional methods may be added in future releases */
! 542: };
! 543:
! 544: /*
! 545: ** CAPI3REF: Standard File Control Opcodes
! 546: **
! 547: ** These integer constants are opcodes for the xFileControl method
! 548: ** of the [sqlite3_io_methods] object and to the [sqlite3_file_control()]
! 549: ** interface.
! 550: **
! 551: ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
! 552: ** opcode cases the xFileControl method to write the current state of
! 553: ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
! 554: ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
! 555: ** into an integer that the pArg argument points to. This capability
! 556: ** is used during testing and only needs to be supported when SQLITE_TEST
! 557: ** is defined.
! 558: */
! 559: #define SQLITE_FCNTL_LOCKSTATE 1
! 560:
! 561: /*
! 562: ** CAPI3REF: Mutex Handle
! 563: **
! 564: ** The mutex module within SQLite defines [sqlite3_mutex] to be an
! 565: ** abstract type for a mutex object. The SQLite core never looks
! 566: ** at the internal representation of an [sqlite3_mutex]. It only
! 567: ** deals with pointers to the [sqlite3_mutex] object.
! 568: **
! 569: ** Mutexes are created using [sqlite3_mutex_alloc()].
! 570: */
! 571: typedef struct sqlite3_mutex sqlite3_mutex;
! 572:
! 573: /*
! 574: ** CAPI3REF: OS Interface Object
! 575: **
! 576: ** An instance of this object defines the interface between the
! 577: ** SQLite core and the underlying operating system. The "vfs"
! 578: ** in the name of the object stands for "virtual file system".
! 579: **
! 580: ** The iVersion field is initially 1 but may be larger for future
! 581: ** versions of SQLite. Additional fields may be appended to this
! 582: ** object when the iVersion value is increased.
! 583: **
! 584: ** The szOsFile field is the size of the subclassed [sqlite3_file]
! 585: ** structure used by this VFS. mxPathname is the maximum length of
! 586: ** a pathname in this VFS.
! 587: **
! 588: ** Registered vfs modules are kept on a linked list formed by
! 589: ** the pNext pointer. The [sqlite3_vfs_register()]
! 590: ** and [sqlite3_vfs_unregister()] interfaces manage this list
! 591: ** in a thread-safe way. The [sqlite3_vfs_find()] interface
! 592: ** searches the list.
! 593: **
! 594: ** The pNext field is the only fields in the sqlite3_vfs
! 595: ** structure that SQLite will ever modify. SQLite will only access
! 596: ** or modify this field while holding a particular static mutex.
! 597: ** The application should never modify anything within the sqlite3_vfs
! 598: ** object once the object has been registered.
! 599: **
! 600: ** The zName field holds the name of the VFS module. The name must
! 601: ** be unique across all VFS modules.
! 602: **
! 603: ** SQLite will guarantee that the zFilename string passed to
! 604: ** xOpen() is a full pathname as generated by xFullPathname() and
! 605: ** that the string will be valid and unchanged until xClose() is
! 606: ** called. So the [sqlite3_file] can store a pointer to the
! 607: ** filename if it needs to remember the filename for some reason.
! 608: **
! 609: ** The flags argument to xOpen() is a copy of the flags argument
! 610: ** to [sqlite3_open_v2()]. If [sqlite3_open()] or [sqlite3_open16()]
! 611: ** is used, then flags is [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
! 612: ** If xOpen() opens a file read-only then it sets *pOutFlags to
! 613: ** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be
! 614: ** set.
! 615: **
! 616: ** SQLite will also add one of the following flags to the xOpen()
! 617: ** call, depending on the object being opened:
! 618: **
! 619: ** <ul>
! 620: ** <li> [SQLITE_OPEN_MAIN_DB]
! 621: ** <li> [SQLITE_OPEN_MAIN_JOURNAL]
! 622: ** <li> [SQLITE_OPEN_TEMP_DB]
! 623: ** <li> [SQLITE_OPEN_TEMP_JOURNAL]
! 624: ** <li> [SQLITE_OPEN_TRANSIENT_DB]
! 625: ** <li> [SQLITE_OPEN_SUBJOURNAL]
! 626: ** <li> [SQLITE_OPEN_MASTER_JOURNAL]
! 627: ** </ul>
! 628: **
! 629: ** The file I/O implementation can use the object type flags to
! 630: ** changes the way it deals with files. For example, an application
! 631: ** that does not care about crash recovery or rollback, might make
! 632: ** the open of a journal file a no-op. Writes to this journal are
! 633: ** also a no-op. Any attempt to read the journal return SQLITE_IOERR.
! 634: ** Or the implementation might recognize the a database file will
! 635: ** be doing page-aligned sector reads and writes in a random order
! 636: ** and set up its I/O subsystem accordingly.
! 637: **
! 638: ** SQLite might also add one of the following flags to the xOpen
! 639: ** method:
! 640: **
! 641: ** <ul>
! 642: ** <li> [SQLITE_OPEN_DELETEONCLOSE]
! 643: ** <li> [SQLITE_OPEN_EXCLUSIVE]
! 644: ** </ul>
! 645: **
! 646: ** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
! 647: ** deleted when it is closed. This will always be set for TEMP
! 648: ** databases and journals and for subjournals. The
! 649: ** [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
! 650: ** for exclusive access. This flag is set for all files except
! 651: ** for the main database file.
! 652: **
! 653: ** Space to hold the [sqlite3_file] structure passed as the third
! 654: ** argument to xOpen is allocated by caller (the SQLite core).
! 655: ** szOsFile bytes are allocated for this object. The xOpen method
! 656: ** fills in the allocated space.
! 657: **
! 658: ** The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
! 659: ** to test for the existance of a file,
! 660: ** or [SQLITE_ACCESS_READWRITE] to test to see
! 661: ** if a file is readable and writable, or [SQLITE_ACCESS_READ]
! 662: ** to test to see if a file is at least readable. The file can be a
! 663: ** directory.
! 664: **
! 665: ** SQLite will always allocate at least mxPathname+1 byte for
! 666: ** the output buffers for xGetTempname and xFullPathname. The exact
! 667: ** size of the output buffer is also passed as a parameter to both
! 668: ** methods. If the output buffer is not large enough, SQLITE_CANTOPEN
! 669: ** should be returned. As this is handled as a fatal error by SQLite,
! 670: ** vfs implementations should endevour to prevent this by setting
! 671: ** mxPathname to a sufficiently large value.
! 672: **
! 673: ** The xRandomness(), xSleep(), and xCurrentTime() interfaces
! 674: ** are not strictly a part of the filesystem, but they are
! 675: ** included in the VFS structure for completeness.
! 676: ** The xRandomness() function attempts to return nBytes bytes
! 677: ** of good-quality randomness into zOut. The return value is
! 678: ** the actual number of bytes of randomness obtained. The
! 679: ** xSleep() method cause the calling thread to sleep for at
! 680: ** least the number of microseconds given. The xCurrentTime()
! 681: ** method returns a Julian Day Number for the current date and
! 682: ** time.
! 683: */
! 684: typedef struct sqlite3_vfs sqlite3_vfs;
! 685: struct sqlite3_vfs {
! 686: int iVersion; /* Structure version number */
! 687: int szOsFile; /* Size of subclassed sqlite3_file */
! 688: int mxPathname; /* Maximum file pathname length */
! 689: sqlite3_vfs *pNext; /* Next registered VFS */
! 690: const char *zName; /* Name of this virtual file system */
! 691: void *pAppData; /* Pointer to application-specific data */
! 692: int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
! 693: int flags, int *pOutFlags);
! 694: int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
! 695: int (*xAccess)(sqlite3_vfs*, const char *zName, int flags);
! 696: int (*xGetTempname)(sqlite3_vfs*, int nOut, char *zOut);
! 697: int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
! 698: void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
! 699: void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
! 700: void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol);
! 701: void (*xDlClose)(sqlite3_vfs*, void*);
! 702: int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
! 703: int (*xSleep)(sqlite3_vfs*, int microseconds);
! 704: int (*xCurrentTime)(sqlite3_vfs*, double*);
! 705: /* New fields may be appended in figure versions. The iVersion
! 706: ** value will increment whenever this happens. */
! 707: };
! 708:
! 709: /*
! 710: ** CAPI3REF: Flags for the xAccess VFS method
! 711: **
! 712: ** These integer constants can be used as the third parameter to
! 713: ** the xAccess method of an [sqlite3_vfs] object. They determine
! 714: ** the kind of what kind of permissions the xAccess method is
! 715: ** looking for. With SQLITE_ACCESS_EXISTS, the xAccess method
! 716: ** simply checks to see if the file exists. With SQLITE_ACCESS_READWRITE,
! 717: ** the xAccess method checks to see if the file is both readable
! 718: ** and writable. With SQLITE_ACCESS_READ the xAccess method
! 719: ** checks to see if the file is readable.
! 720: */
! 721: #define SQLITE_ACCESS_EXISTS 0
! 722: #define SQLITE_ACCESS_READWRITE 1
! 723: #define SQLITE_ACCESS_READ 2
! 724:
! 725: /*
! 726: ** CAPI3REF: Enable Or Disable Extended Result Codes
! 727: **
! 728: ** This routine enables or disables the
! 729: ** [SQLITE_IOERR_READ | extended result codes] feature.
! 730: ** By default, SQLite API routines return one of only 26 integer
! 731: ** [SQLITE_OK | result codes]. When extended result codes
! 732: ** are enabled by this routine, the repetoire of result codes can be
! 733: ** much larger and can (hopefully) provide more detailed information
! 734: ** about the cause of an error.
! 735: **
! 736: ** The second argument is a boolean value that turns extended result
! 737: ** codes on and off. Extended result codes are off by default for
! 738: ** backwards compatibility with older versions of SQLite.
! 739: */
! 740: int sqlite3_extended_result_codes(sqlite3*, int onoff);
! 741:
! 742: /*
! 743: ** CAPI3REF: Last Insert Rowid
! 744: **
! 745: ** Each entry in an SQLite table has a unique 64-bit signed integer key
! 746: ** called the "rowid". The rowid is always available as an undeclared
! 747: ** column named ROWID, OID, or _ROWID_. If the table has a column of
! 748: ** type INTEGER PRIMARY KEY then that column is another an alias for the
! 749: ** rowid.
! 750: **
! 751: ** This routine returns the rowid of the most recent INSERT into
! 752: ** the database from the database connection given in the first
! 753: ** argument. If no inserts have ever occurred on this database
! 754: ** connection, zero is returned.
! 755: **
! 756: ** If an INSERT occurs within a trigger, then the rowid of the
! 757: ** inserted row is returned by this routine as long as the trigger
! 758: ** is running. But once the trigger terminates, the value returned
! 759: ** by this routine reverts to the last value inserted before the
! 760: ** trigger fired.
! 761: **
! 762: ** If another thread does a new insert on the same database connection
! 763: ** while this routine is running and thus changes the last insert rowid,
! 764: ** then the return value of this routine is undefined.
1.1 misha 765: */
1.2 ! misha 766: sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
1.1 misha 767:
768: /*
1.2 ! misha 769: ** CAPI3REF: Count The Number Of Rows Modified
! 770: **
1.1 misha 771: ** This function returns the number of database rows that were changed
1.2 ! misha 772: ** (or inserted or deleted) by the most recent SQL statement. Only
! 773: ** changes that are directly specified by the INSERT, UPDATE, or
! 774: ** DELETE statement are counted. Auxiliary changes caused by
! 775: ** triggers are not counted. Use the [sqlite3_total_changes()] function
! 776: ** to find the total number of changes including changes caused by triggers.
! 777: **
! 778: ** Within the body of a trigger, the sqlite3_changes() interface can be
! 779: ** called to find the number of
! 780: ** changes in the most recently completed INSERT, UPDATE, or DELETE
! 781: ** statement within the body of the trigger.
1.1 misha 782: **
783: ** All changes are counted, even if they were later undone by a
784: ** ROLLBACK or ABORT. Except, changes associated with creating and
785: ** dropping tables are not counted.
786: **
1.2 ! misha 787: ** If a callback invokes [sqlite3_exec()] or [sqlite3_step()] recursively,
! 788: ** then the changes in the inner, recursive call are counted together
! 789: ** with the changes in the outer call.
1.1 misha 790: **
791: ** SQLite implements the command "DELETE FROM table" without a WHERE clause
792: ** by dropping and recreating the table. (This is much faster than going
1.2 ! misha 793: ** through and deleting individual elements from the table.) Because of
1.1 misha 794: ** this optimization, the change count for "DELETE FROM table" will be
795: ** zero regardless of the number of elements that were originally in the
796: ** table. To get an accurate count of the number of rows deleted, use
797: ** "DELETE FROM table WHERE 1" instead.
1.2 ! misha 798: **
! 799: ** If another thread makes changes on the same database connection
! 800: ** while this routine is running then the return value of this routine
! 801: ** is undefined.
1.1 misha 802: */
803: int sqlite3_changes(sqlite3*);
804:
805: /*
1.2 ! misha 806: ** CAPI3REF: Total Number Of Rows Modified
! 807: ***
1.1 misha 808: ** This function returns the number of database rows that have been
809: ** modified by INSERT, UPDATE or DELETE statements since the database handle
810: ** was opened. This includes UPDATE, INSERT and DELETE statements executed
811: ** as part of trigger programs. All changes are counted as soon as the
812: ** statement that makes them is completed (when the statement handle is
1.2 ! misha 813: ** passed to [sqlite3_reset()] or [sqlite3_finalize()]).
! 814: **
! 815: ** See also the [sqlite3_change()] interface.
1.1 misha 816: **
817: ** SQLite implements the command "DELETE FROM table" without a WHERE clause
818: ** by dropping and recreating the table. (This is much faster than going
819: ** through and deleting individual elements form the table.) Because of
820: ** this optimization, the change count for "DELETE FROM table" will be
821: ** zero regardless of the number of elements that were originally in the
822: ** table. To get an accurate count of the number of rows deleted, use
823: ** "DELETE FROM table WHERE 1" instead.
1.2 ! misha 824: **
! 825: ** If another thread makes changes on the same database connection
! 826: ** while this routine is running then the return value of this routine
! 827: ** is undefined.
1.1 misha 828: */
829: int sqlite3_total_changes(sqlite3*);
830:
1.2 ! misha 831: /*
! 832: ** CAPI3REF: Interrupt A Long-Running Query
! 833: **
! 834: ** This function causes any pending database operation to abort and
1.1 misha 835: ** return at its earliest opportunity. This routine is typically
836: ** called in response to a user action such as pressing "Cancel"
837: ** or Ctrl-C where the user wants a long query operation to halt
838: ** immediately.
1.2 ! misha 839: **
! 840: ** It is safe to call this routine from a thread different from the
! 841: ** thread that is currently running the database operation. But it
! 842: ** is not safe to call this routine with a database connection that
! 843: ** is closed or might close before sqlite3_interrupt() returns.
! 844: **
! 845: ** The SQL operation that is interrupted will return [SQLITE_INTERRUPT].
! 846: ** If an interrupted operation was an update that is inside an
! 847: ** explicit transaction, then the entire transaction will be rolled
! 848: ** back automatically.
1.1 misha 849: */
850: void sqlite3_interrupt(sqlite3*);
851:
1.2 ! misha 852: /*
! 853: ** CAPI3REF: Determine If An SQL Statement Is Complete
! 854: **
! 855: ** These functions return true if the given input string comprises
1.1 misha 856: ** one or more complete SQL statements. For the sqlite3_complete() call,
857: ** the parameter must be a nul-terminated UTF-8 string. For
858: ** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string
859: ** is required.
860: **
1.2 ! misha 861: ** These routines are useful for command-line input to determine if the
! 862: ** currently entered text forms one or more complete SQL statements or
! 863: ** if additional input is needed before sending the statements into
! 864: ** SQLite for parsing. The algorithm is simple. If the
! 865: ** last token other than spaces and comments is a semicolon, then return
! 866: ** true. Actually, the algorithm is a little more complicated than that
! 867: ** in order to deal with triggers, but the basic idea is the same: the
! 868: ** statement is not complete unless it ends in a semicolon.
1.1 misha 869: */
870: int sqlite3_complete(const char *sql);
871: int sqlite3_complete16(const void *sql);
872:
873: /*
1.2 ! misha 874: ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
! 875: **
! 876: ** This routine identifies a callback function that might be invoked
! 877: ** whenever an attempt is made to open a database table
! 878: ** that another thread or process has locked.
! 879: ** If the busy callback is NULL, then [SQLITE_BUSY]
! 880: ** (or sometimes [SQLITE_IOERR_BLOCKED])
! 881: ** is returned immediately upon encountering the lock.
! 882: ** If the busy callback is not NULL, then the
! 883: ** callback will be invoked with two arguments. The
! 884: ** first argument to the handler is a copy of the void* pointer which
! 885: ** is the third argument to this routine. The second argument to
! 886: ** the handler is the number of times that the busy handler has
! 887: ** been invoked for this locking event. If the
! 888: ** busy callback returns 0, then no additional attempts are made to
! 889: ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
! 890: ** If the callback returns non-zero, then another attempt is made to open the
! 891: ** database for reading and the cycle repeats.
! 892: **
! 893: ** The presence of a busy handler does not guarantee that
! 894: ** it will be invoked when there is lock contention.
! 895: ** If SQLite determines that invoking the busy handler could result in
! 896: ** a deadlock, it will return [SQLITE_BUSY] instead.
! 897: ** Consider a scenario where one process is holding a read lock that
! 898: ** it is trying to promote to a reserved lock and
! 899: ** a second process is holding a reserved lock that it is trying
! 900: ** to promote to an exclusive lock. The first process cannot proceed
! 901: ** because it is blocked by the second and the second process cannot
! 902: ** proceed because it is blocked by the first. If both processes
! 903: ** invoke the busy handlers, neither will make any progress. Therefore,
! 904: ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
! 905: ** will induce the first process to release its read lock and allow
! 906: ** the second process to proceed.
1.1 misha 907: **
908: ** The default busy callback is NULL.
909: **
1.2 ! misha 910: ** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED] when
! 911: ** SQLite is in the middle of a large transaction where all the
! 912: ** changes will not fit into the in-memory cache. SQLite will
! 913: ** already hold a RESERVED lock on the database file, but it needs
! 914: ** to promote this lock to EXCLUSIVE so that it can spill cache
! 915: ** pages into the database file without harm to concurrent
! 916: ** readers. If it is unable to promote the lock, then the in-memory
! 917: ** cache will be left in an inconsistent state and so the error
! 918: ** code is promoted from the relatively benign [SQLITE_BUSY] to
! 919: ** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion
! 920: ** forces an automatic rollback of the changes. See the
! 921: ** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">
! 922: ** CorruptionFollowingBusyError</a> wiki page for a discussion of why
! 923: ** this is important.
! 924: **
1.1 misha 925: ** Sqlite is re-entrant, so the busy handler may start a new query.
926: ** (It is not clear why anyone would every want to do this, but it
927: ** is allowed, in theory.) But the busy handler may not close the
928: ** database. Closing the database from a busy handler will delete
929: ** data structures out from under the executing query and will
1.2 ! misha 930: ** probably result in a segmentation fault or other runtime error.
! 931: **
! 932: ** There can only be a single busy handler defined for each database
! 933: ** connection. Setting a new busy handler clears any previous one.
! 934: ** Note that calling [sqlite3_busy_timeout()] will also set or clear
! 935: ** the busy handler.
! 936: **
! 937: ** When operating in [sqlite3_enable_shared_cache | shared cache mode],
! 938: ** only a single busy handler can be defined for each database file.
! 939: ** So if two database connections share a single cache, then changing
! 940: ** the busy handler on one connection will also change the busy
! 941: ** handler in the other connection. The busy handler is invoked
! 942: ** in the thread that was running when the SQLITE_BUSY was hit.
1.1 misha 943: */
944: int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
945:
946: /*
1.2 ! misha 947: ** CAPI3REF: Set A Busy Timeout
! 948: **
1.1 misha 949: ** This routine sets a busy handler that sleeps for a while when a
950: ** table is locked. The handler will sleep multiple times until
1.2 ! misha 951: ** at least "ms" milliseconds of sleeping have been done. After
! 952: ** "ms" milliseconds of sleeping, the handler returns 0 which
! 953: ** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
1.1 misha 954: **
955: ** Calling this routine with an argument less than or equal to zero
956: ** turns off all busy handlers.
1.2 ! misha 957: **
! 958: ** There can only be a single busy handler for a particular database
! 959: ** connection. If another busy handler was defined
! 960: ** (using [sqlite3_busy_handler()]) prior to calling
! 961: ** this routine, that other busy handler is cleared.
1.1 misha 962: */
963: int sqlite3_busy_timeout(sqlite3*, int ms);
964:
965: /*
1.2 ! misha 966: ** CAPI3REF: Convenience Routines For Running Queries
! 967: **
! 968: ** This next routine is a convenience wrapper around [sqlite3_exec()].
1.1 misha 969: ** Instead of invoking a user-supplied callback for each row of the
970: ** result, this routine remembers each row of the result in memory
1.2 ! misha 971: ** obtained from [sqlite3_malloc()], then returns all of the result after the
1.1 misha 972: ** query has finished.
973: **
974: ** As an example, suppose the query result where this table:
975: **
1.2 ! misha 976: ** <blockquote><pre>
1.1 misha 977: ** Name | Age
978: ** -----------------------
979: ** Alice | 43
980: ** Bob | 28
981: ** Cindy | 21
1.2 ! misha 982: ** </pre></blockquote>
1.1 misha 983: **
984: ** If the 3rd argument were &azResult then after the function returns
985: ** azResult will contain the following data:
986: **
1.2 ! misha 987: ** <blockquote><pre>
! 988: ** azResult[0] = "Name";
! 989: ** azResult[1] = "Age";
! 990: ** azResult[2] = "Alice";
! 991: ** azResult[3] = "43";
! 992: ** azResult[4] = "Bob";
! 993: ** azResult[5] = "28";
! 994: ** azResult[6] = "Cindy";
! 995: ** azResult[7] = "21";
! 996: ** </pre></blockquote>
1.1 misha 997: **
998: ** Notice that there is an extra row of data containing the column
999: ** headers. But the *nrow return value is still 3. *ncolumn is
1000: ** set to 2. In general, the number of values inserted into azResult
1001: ** will be ((*nrow) + 1)*(*ncolumn).
1002: **
1003: ** After the calling function has finished using the result, it should
1004: ** pass the result data pointer to sqlite3_free_table() in order to
1005: ** release the memory that was malloc-ed. Because of the way the
1.2 ! misha 1006: ** [sqlite3_malloc()] happens, the calling function must not try to call
! 1007: ** [sqlite3_free()] directly. Only [sqlite3_free_table()] is able to release
1.1 misha 1008: ** the memory properly and safely.
1009: **
1.2 ! misha 1010: ** The return value of this routine is the same as from [sqlite3_exec()].
1.1 misha 1011: */
1012: int sqlite3_get_table(
1.2 ! misha 1013: sqlite3*, /* An open database */
1.1 misha 1014: const char *sql, /* SQL to be executed */
1015: char ***resultp, /* Result written to a char *[] that this points to */
1016: int *nrow, /* Number of result rows written here */
1017: int *ncolumn, /* Number of result columns written here */
1018: char **errmsg /* Error msg written here */
1019: );
1020: void sqlite3_free_table(char **result);
1021:
1022: /*
1.2 ! misha 1023: ** CAPI3REF: Formatted String Printing Functions
! 1024: **
! 1025: ** These routines are workalikes of the "printf()" family of functions
! 1026: ** from the standard C library.
1.1 misha 1027: **
1.2 ! misha 1028: ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
! 1029: ** results into memory obtained from [sqlite3_malloc()].
! 1030: ** The strings returned by these two routines should be
! 1031: ** released by [sqlite3_free()]. Both routines return a
! 1032: ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
! 1033: ** memory to hold the resulting string.
! 1034: **
! 1035: ** In sqlite3_snprintf() routine is similar to "snprintf()" from
! 1036: ** the standard C library. The result is written into the
! 1037: ** buffer supplied as the second parameter whose size is given by
! 1038: ** the first parameter. Note that the order of the
! 1039: ** first two parameters is reversed from snprintf(). This is an
! 1040: ** historical accident that cannot be fixed without breaking
! 1041: ** backwards compatibility. Note also that sqlite3_snprintf()
! 1042: ** returns a pointer to its buffer instead of the number of
! 1043: ** characters actually written into the buffer. We admit that
! 1044: ** the number of characters written would be a more useful return
! 1045: ** value but we cannot change the implementation of sqlite3_snprintf()
! 1046: ** now without breaking compatibility.
! 1047: **
! 1048: ** As long as the buffer size is greater than zero, sqlite3_snprintf()
! 1049: ** guarantees that the buffer is always zero-terminated. The first
! 1050: ** parameter "n" is the total size of the buffer, including space for
! 1051: ** the zero terminator. So the longest string that can be completely
! 1052: ** written will be n-1 characters.
1.1 misha 1053: **
1.2 ! misha 1054: ** These routines all implement some additional formatting
! 1055: ** options that are useful for constructing SQL statements.
1.1 misha 1056: ** All of the usual printf formatting options apply. In addition, there
1.2 ! misha 1057: ** is are "%q", "%Q", and "%z" options.
! 1058: **
! 1059: ** The %q option works like %s in that it substitutes a null-terminated
1.1 misha 1060: ** string from the argument list. But %q also doubles every '\'' character.
1061: ** %q is designed for use inside a string literal. By doubling each '\''
1062: ** character it escapes that character and allows it to be inserted into
1063: ** the string.
1064: **
1065: ** For example, so some string variable contains text as follows:
1066: **
1.2 ! misha 1067: ** <blockquote><pre>
! 1068: ** char *zText = "It's a happy day!";
! 1069: ** </pre></blockquote>
! 1070: **
! 1071: ** One can use this text in an SQL statement as follows:
! 1072: **
! 1073: ** <blockquote><pre>
! 1074: ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
! 1075: ** sqlite3_exec(db, zSQL, 0, 0, 0);
! 1076: ** sqlite3_free(zSQL);
! 1077: ** </pre></blockquote>
1.1 misha 1078: **
1079: ** Because the %q format string is used, the '\'' character in zText
1080: ** is escaped and the SQL generated is as follows:
1081: **
1.2 ! misha 1082: ** <blockquote><pre>
! 1083: ** INSERT INTO table1 VALUES('It''s a happy day!')
! 1084: ** </pre></blockquote>
1.1 misha 1085: **
1086: ** This is correct. Had we used %s instead of %q, the generated SQL
1087: ** would have looked like this:
1088: **
1.2 ! misha 1089: ** <blockquote><pre>
! 1090: ** INSERT INTO table1 VALUES('It's a happy day!');
! 1091: ** </pre></blockquote>
1.1 misha 1092: **
1093: ** This second example is an SQL syntax error. As a general rule you
1094: ** should always use %q instead of %s when inserting text into a string
1095: ** literal.
1.2 ! misha 1096: **
! 1097: ** The %Q option works like %q except it also adds single quotes around
! 1098: ** the outside of the total string. Or if the parameter in the argument
! 1099: ** list is a NULL pointer, %Q substitutes the text "NULL" (without single
! 1100: ** quotes) in place of the %Q option. So, for example, one could say:
! 1101: **
! 1102: ** <blockquote><pre>
! 1103: ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
! 1104: ** sqlite3_exec(db, zSQL, 0, 0, 0);
! 1105: ** sqlite3_free(zSQL);
! 1106: ** </pre></blockquote>
! 1107: **
! 1108: ** The code above will render a correct SQL statement in the zSQL
! 1109: ** variable even if the zText variable is a NULL pointer.
! 1110: **
! 1111: ** The "%z" formatting option works exactly like "%s" with the
! 1112: ** addition that after the string has been read and copied into
! 1113: ** the result, [sqlite3_free()] is called on the input string.
1.1 misha 1114: */
1115: char *sqlite3_mprintf(const char*,...);
1116: char *sqlite3_vmprintf(const char*, va_list);
1117: char *sqlite3_snprintf(int,char*,const char*, ...);
1118:
1119: /*
1.2 ! misha 1120: ** CAPI3REF: Memory Allocation Subsystem
! 1121: **
! 1122: ** The SQLite core uses these three routines for all of its own
! 1123: ** internal memory allocation needs. (See the exception below.)
! 1124: ** The default implementation
! 1125: ** of the memory allocation subsystem uses the malloc(), realloc()
! 1126: ** and free() provided by the standard C library. However, if
! 1127: ** SQLite is compiled with the following C preprocessor macro
! 1128: **
! 1129: ** <blockquote> SQLITE_OMIT_MEMORY_ALLOCATION </blockquote>
! 1130: **
! 1131: ** then no implementation is provided for these routines by
! 1132: ** SQLite. The application that links against SQLite is
! 1133: ** expected to provide its own implementation. If the application
! 1134: ** does provide its own implementation for these routines, then
! 1135: ** it must also provide an implementations for
! 1136: ** [sqlite3_memory_alarm()], [sqlite3_memory_used()], and
! 1137: ** [sqlite3_memory_highwater()]. The alternative implementations
! 1138: ** for these last three routines need not actually work, but
! 1139: ** stub functions at least are needed to statisfy the linker.
! 1140: ** SQLite never calls [sqlite3_memory_highwater()] itself, but
! 1141: ** the symbol is included in a table as part of the
! 1142: ** [sqlite3_load_extension()] interface. The
! 1143: ** [sqlite3_memory_alarm()] and [sqlite3_memory_used()] interfaces
! 1144: ** are called by [sqlite3_soft_heap_limit()] and working implementations
! 1145: ** of both routines must be provided if [sqlite3_soft_heap_limit()]
! 1146: ** is to operate correctly.
! 1147: **
! 1148: ** <b>Exception:</b> The windows OS interface layer calls
! 1149: ** the system malloc() and free() directly when converting
! 1150: ** filenames between the UTF-8 encoding used by SQLite
! 1151: ** and whatever filename encoding is used by the particular windows
! 1152: ** installation. Memory allocation errors are detected, but
! 1153: ** they are reported back as [SQLITE_CANTOPEN] or
! 1154: ** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
! 1155: */
! 1156: void *sqlite3_malloc(int);
! 1157: void *sqlite3_realloc(void*, int);
! 1158: void sqlite3_free(void*);
! 1159:
! 1160: /*
! 1161: ** CAPI3REF: Memory Allocator Statistics
! 1162: **
! 1163: ** In addition to the basic three allocation routines
! 1164: ** [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()],
! 1165: ** the memory allocation subsystem included with the SQLite
! 1166: ** sources provides the interfaces shown below.
! 1167: **
! 1168: ** The first of these two routines returns the amount of memory
! 1169: ** currently outstanding (malloced but not freed). The second
! 1170: ** returns the largest instantaneous amount of outstanding
! 1171: ** memory. The highwater mark is reset if the argument is
! 1172: ** true.
! 1173: **
! 1174: ** The implementation of these routines in the SQLite core
! 1175: ** is omitted if the application is compiled with the
! 1176: ** SQLITE_OMIT_MEMORY_ALLOCATION macro defined. In that case,
! 1177: ** the application that links SQLite must provide its own
! 1178: ** alternative implementation. See the documentation on
! 1179: ** [sqlite3_malloc()] for additional information.
! 1180: */
! 1181: sqlite3_int64 sqlite3_memory_used(void);
! 1182: sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
! 1183:
! 1184: /*
! 1185: ** CAPI3REF: Memory Allocation Alarms
! 1186: **
! 1187: ** The [sqlite3_memory_alarm] routine is used to register
! 1188: ** a callback on memory allocation events.
! 1189: **
! 1190: ** This routine registers or clears a callbacks that fires when
! 1191: ** the amount of memory allocated exceeds iThreshold. Only
! 1192: ** a single callback can be registered at a time. Each call
! 1193: ** to [sqlite3_memory_alarm()] overwrites the previous callback.
! 1194: ** The callback is disabled by setting xCallback to a NULL
! 1195: ** pointer.
! 1196: **
! 1197: ** The parameters to the callback are the pArg value, the
! 1198: ** amount of memory currently in use, and the size of the
! 1199: ** allocation that provoked the callback. The callback will
! 1200: ** presumably invoke [sqlite3_free()] to free up memory space.
! 1201: ** The callback may invoke [sqlite3_malloc()] or [sqlite3_realloc()]
! 1202: ** but if it does, no additional callbacks will be invoked by
! 1203: ** the recursive calls.
! 1204: **
! 1205: ** The [sqlite3_soft_heap_limit()] interface works by registering
! 1206: ** a memory alarm at the soft heap limit and invoking
! 1207: ** [sqlite3_release_memory()] in the alarm callback. Application
! 1208: ** programs should not attempt to use the [sqlite3_memory_alarm()]
! 1209: ** interface because doing so will interfere with the
! 1210: ** [sqlite3_soft_heap_limit()] module. This interface is exposed
! 1211: ** only so that applications can provide their own
! 1212: ** alternative implementation when the SQLite core is
! 1213: ** compiled with SQLITE_OMIT_MEMORY_ALLOCATION.
! 1214: */
! 1215: int sqlite3_memory_alarm(
! 1216: void(*xCallback)(void *pArg, sqlite3_int64 used, int N),
! 1217: void *pArg,
! 1218: sqlite3_int64 iThreshold
! 1219: );
! 1220:
! 1221:
! 1222: /*
! 1223: ** CAPI3REF: Compile-Time Authorization Callbacks
! 1224: ***
! 1225: ** This routine registers a authorizer callback with the SQLite library.
! 1226: ** The authorizer callback is invoked as SQL statements are being compiled
! 1227: ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
! 1228: ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various
! 1229: ** points during the compilation process, as logic is being created
! 1230: ** to perform various actions, the authorizer callback is invoked to
! 1231: ** see if those actions are allowed. The authorizer callback should
! 1232: ** return SQLITE_OK to allow the action, [SQLITE_IGNORE] to disallow the
! 1233: ** specific action but allow the SQL statement to continue to be
! 1234: ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
! 1235: ** rejected with an error.
! 1236: **
! 1237: ** Depending on the action, the [SQLITE_IGNORE] and [SQLITE_DENY] return
! 1238: ** codes might mean something different or they might mean the same
! 1239: ** thing. If the action is, for example, to perform a delete opertion,
! 1240: ** then [SQLITE_IGNORE] and [SQLITE_DENY] both cause the statement compilation
! 1241: ** to fail with an error. But if the action is to read a specific column
! 1242: ** from a specific table, then [SQLITE_DENY] will cause the entire
! 1243: ** statement to fail but [SQLITE_IGNORE] will cause a NULL value to be
! 1244: ** read instead of the actual column value.
! 1245: **
! 1246: ** The first parameter to the authorizer callback is a copy of
! 1247: ** the third parameter to the sqlite3_set_authorizer() interface.
! 1248: ** The second parameter to the callback is an integer
! 1249: ** [SQLITE_COPY | action code] that specifies the particular action
! 1250: ** to be authorized. The available action codes are
! 1251: ** [SQLITE_COPY | documented separately]. The third through sixth
! 1252: ** parameters to the callback are strings that contain additional
! 1253: ** details about the action to be authorized.
! 1254: **
! 1255: ** An authorizer is used when preparing SQL statements from an untrusted
! 1256: ** source, to ensure that the SQL statements do not try to access data
! 1257: ** that they are not allowed to see, or that they do not try to
! 1258: ** execute malicious statements that damage the database. For
! 1259: ** example, an application may allow a user to enter arbitrary
! 1260: ** SQL queries for evaluation by a database. But the application does
! 1261: ** not want the user to be able to make arbitrary changes to the
! 1262: ** database. An authorizer could then be put in place while the
! 1263: ** user-entered SQL is being prepared that disallows everything
! 1264: ** except SELECT statements.
! 1265: **
! 1266: ** Only a single authorizer can be in place on a database connection
! 1267: ** at a time. Each call to sqlite3_set_authorizer overrides the
! 1268: ** previous call. A NULL authorizer means that no authorization
! 1269: ** callback is invoked. The default authorizer is NULL.
! 1270: **
! 1271: ** Note that the authorizer callback is invoked only during
! 1272: ** [sqlite3_prepare()] or its variants. Authorization is not
! 1273: ** performed during statement evaluation in [sqlite3_step()].
1.1 misha 1274: */
1275: int sqlite3_set_authorizer(
1276: sqlite3*,
1277: int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
1278: void *pUserData
1279: );
1280:
1281: /*
1.2 ! misha 1282: ** CAPI3REF: Authorizer Return Codes
! 1283: **
! 1284: ** The [sqlite3_set_authorizer | authorizer callback function] must
! 1285: ** return either [SQLITE_OK] or one of these two constants in order
! 1286: ** to signal SQLite whether or not the action is permitted. See the
! 1287: ** [sqlite3_set_authorizer | authorizer documentation] for additional
! 1288: ** information.
! 1289: */
! 1290: #define SQLITE_DENY 1 /* Abort the SQL statement with an error */
! 1291: #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
! 1292:
! 1293: /*
! 1294: ** CAPI3REF: Authorizer Action Codes
! 1295: **
! 1296: ** The [sqlite3_set_authorizer()] interface registers a callback function
! 1297: ** that is invoked to authorizer certain SQL statement actions. The
! 1298: ** second parameter to the callback is an integer code that specifies
! 1299: ** what action is being authorized. These are the integer action codes that
! 1300: ** the authorizer callback may be passed.
! 1301: **
! 1302: ** These action code values signify what kind of operation is to be
! 1303: ** authorized. The 3rd and 4th parameters to the authorization callback
! 1304: ** function will be parameters or NULL depending on which of these
! 1305: ** codes is used as the second parameter. The 5th parameter to the
! 1306: ** authorizer callback is the name of the database ("main", "temp",
! 1307: ** etc.) if applicable. The 6th parameter to the authorizer callback
1.1 misha 1308: ** is the name of the inner-most trigger or view that is responsible for
1309: ** the access attempt or NULL if this access attempt is directly from
1.2 ! misha 1310: ** top-level SQL code.
1.1 misha 1311: */
1.2 ! misha 1312: /******************************************* 3rd ************ 4th ***********/
1.1 misha 1313: #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
1314: #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
1315: #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
1316: #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
1317: #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
1318: #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
1319: #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
1320: #define SQLITE_CREATE_VIEW 8 /* View Name NULL */
1321: #define SQLITE_DELETE 9 /* Table Name NULL */
1322: #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
1323: #define SQLITE_DROP_TABLE 11 /* Table Name NULL */
1324: #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
1325: #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
1326: #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
1327: #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
1328: #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
1329: #define SQLITE_DROP_VIEW 17 /* View Name NULL */
1330: #define SQLITE_INSERT 18 /* Table Name NULL */
1331: #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
1332: #define SQLITE_READ 20 /* Table Name Column Name */
1333: #define SQLITE_SELECT 21 /* NULL NULL */
1334: #define SQLITE_TRANSACTION 22 /* NULL NULL */
1335: #define SQLITE_UPDATE 23 /* Table Name Column Name */
1336: #define SQLITE_ATTACH 24 /* Filename NULL */
1337: #define SQLITE_DETACH 25 /* Database Name NULL */
1.2 ! misha 1338: #define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */
! 1339: #define SQLITE_REINDEX 27 /* Index Name NULL */
! 1340: #define SQLITE_ANALYZE 28 /* Table Name NULL */
! 1341: #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
! 1342: #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
! 1343: #define SQLITE_FUNCTION 31 /* Function Name NULL */
! 1344: #define SQLITE_COPY 0 /* No longer used */
! 1345:
! 1346: /*
! 1347: ** CAPI3REF: Tracing And Profiling Functions
! 1348: **
! 1349: ** These routines register callback functions that can be used for
! 1350: ** tracing and profiling the execution of SQL statements.
! 1351: ** The callback function registered by sqlite3_trace() is invoked
! 1352: ** at the first [sqlite3_step()] for the evaluation of an SQL statement.
! 1353: ** The callback function registered by sqlite3_profile() is invoked
! 1354: ** as each SQL statement finishes and includes
! 1355: ** information on how long that statement ran.
! 1356: **
! 1357: ** The sqlite3_profile() API is currently considered experimental and
! 1358: ** is subject to change.
1.1 misha 1359: */
1360: void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
1.2 ! misha 1361: void *sqlite3_profile(sqlite3*,
! 1362: void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
1.1 misha 1363:
1364: /*
1.2 ! misha 1365: ** CAPI3REF: Query Progress Callbacks
! 1366: **
1.1 misha 1367: ** This routine configures a callback function - the progress callback - that
1.2 ! misha 1368: ** is invoked periodically during long running calls to [sqlite3_exec()],
! 1369: ** [sqlite3_step()] and [sqlite3_get_table()]. An example use for this
! 1370: ** interface is to keep a GUI updated during a large query.
1.1 misha 1371: **
1372: ** The progress callback is invoked once for every N virtual machine opcodes,
1373: ** where N is the second argument to this function. The progress callback
1374: ** itself is identified by the third argument to this function. The fourth
1375: ** argument to this function is a void pointer passed to the progress callback
1376: ** function each time it is invoked.
1377: **
1.2 ! misha 1378: ** If a call to [sqlite3_exec()], [sqlite3_step()], or [sqlite3_get_table()]
! 1379: ** results in fewer than N opcodes being executed, then the progress
! 1380: ** callback is never invoked.
1.1 misha 1381: **
1.2 ! misha 1382: ** Only a single progress callback function may be registered for each
! 1383: ** open database connection. Every call to sqlite3_progress_handler()
! 1384: ** overwrites the results of the previous call.
1.1 misha 1385: ** To remove the progress callback altogether, pass NULL as the third
1386: ** argument to this function.
1387: **
1388: ** If the progress callback returns a result other than 0, then the current
1.2 ! misha 1389: ** query is immediately terminated and any database changes rolled back.
! 1390: ** The containing [sqlite3_exec()], [sqlite3_step()], or
! 1391: ** [sqlite3_get_table()] call returns SQLITE_INTERRUPT. This feature
! 1392: ** can be used, for example, to implement the "Cancel" button on a
! 1393: ** progress dialog box in a GUI.
1.1 misha 1394: */
1395: void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
1396:
1397: /*
1.2 ! misha 1398: ** CAPI3REF: Opening A New Database Connection
1.1 misha 1399: **
1400: ** Open the sqlite database file "filename". The "filename" is UTF-8
1.2 ! misha 1401: ** encoded for [sqlite3_open()] and [sqlite3_open_v2()] and UTF-16 encoded
! 1402: ** in the native byte order for [sqlite3_open16()].
! 1403: ** An [sqlite3*] handle is returned in *ppDb, even
1.1 misha 1404: ** if an error occurs. If the database is opened (or created) successfully,
1.2 ! misha 1405: ** then [SQLITE_OK] is returned. Otherwise an error code is returned. The
! 1406: ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
1.1 misha 1407: ** an English language description of the error.
1408: **
1.2 ! misha 1409: ** The default encoding for the database will be UTF-8 if
! 1410: ** [sqlite3_open()] or [sqlite3_open_v2()] is called and
! 1411: ** UTF-16 if [sqlite3_open16()] is used.
1.1 misha 1412: **
1413: ** Whether or not an error occurs when it is opened, resources associated
1.2 ! misha 1414: ** with the [sqlite3*] handle should be released by passing it to
! 1415: ** [sqlite3_close()] when it is no longer required.
! 1416: **
! 1417: ** The [sqlite3_open_v2()] interface works like [sqlite3_open()] except that
! 1418: ** provides two additional parameters for additional control over the
! 1419: ** new database connection. The flags parameter can be one of:
! 1420: **
! 1421: ** <ol>
! 1422: ** <li> [SQLITE_OPEN_READONLY]
! 1423: ** <li> [SQLITE_OPEN_READWRITE]
! 1424: ** <li> [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]
! 1425: ** </ol>
! 1426: **
! 1427: ** The first value opens the database read-only. If the database does
! 1428: ** not previously exist, an error is returned. The second option opens
! 1429: ** the database for reading and writing if possible, or reading only if
! 1430: ** if the file is write protected. In either case the database must already
! 1431: ** exist or an error is returned. The third option opens the database
! 1432: ** for reading and writing and creates it if it does not already exist.
! 1433: ** The third options is behavior that is always used for [sqlite3_open()]
! 1434: ** and [sqlite3_open16()].
! 1435: **
! 1436: ** If the filename is ":memory:", then an private
! 1437: ** in-memory database is created for the connection. This in-memory
! 1438: ** database will vanish when the database connection is closed. Future
! 1439: ** version of SQLite might make use of additional special filenames
! 1440: ** that begin with the ":" character. It is recommended that
! 1441: ** when a database filename really does begin with
! 1442: ** ":" that you prefix the filename with a pathname like "./" to
! 1443: ** avoid ambiguity.
! 1444: **
! 1445: ** If the filename is an empty string, then a private temporary
! 1446: ** on-disk database will be created. This private database will be
! 1447: ** automatically deleted as soon as the database connection is closed.
! 1448: **
! 1449: ** The fourth parameter to sqlite3_open_v2() is the name of the
! 1450: ** [sqlite3_vfs] object that defines the operating system
! 1451: ** interface that the new database connection should use. If the
! 1452: ** fourth parameter is a NULL pointer then the default [sqlite3_vfs]
! 1453: ** object is used.
! 1454: **
! 1455: ** <b>Note to windows users:</b> The encoding used for the filename argument
! 1456: ** of [sqlite3_open()] and [sqlite3_open_v2()] must be UTF-8, not whatever
! 1457: ** codepage is currently defined. Filenames containing international
! 1458: ** characters must be converted to UTF-8 prior to passing them into
! 1459: ** [sqlite3_open()] or [sqlite3_open_v2()].
1.1 misha 1460: */
1461: int sqlite3_open(
1462: const char *filename, /* Database filename (UTF-8) */
1463: sqlite3 **ppDb /* OUT: SQLite db handle */
1464: );
1465: int sqlite3_open16(
1466: const void *filename, /* Database filename (UTF-16) */
1467: sqlite3 **ppDb /* OUT: SQLite db handle */
1468: );
1.2 ! misha 1469: int sqlite3_open_v2(
! 1470: const char *filename, /* Database filename (UTF-8) */
! 1471: sqlite3 **ppDb, /* OUT: SQLite db handle */
! 1472: int flags, /* Flags */
! 1473: const char *zVfs /* Name of VFS module to use */
! 1474: );
1.1 misha 1475:
1476: /*
1.2 ! misha 1477: ** CAPI3REF: Error Codes And Messages
! 1478: **
! 1479: ** The sqlite3_errcode() interface returns the numeric
! 1480: ** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code]
! 1481: ** for the most recent failed sqlite3_* API call associated
! 1482: ** with [sqlite3] handle 'db'. If a prior API call failed but the
! 1483: ** most recent API call succeeded, the return value from sqlite3_errcode()
! 1484: ** is undefined.
! 1485: **
! 1486: ** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
! 1487: ** text that describes the error, as either UTF8 or UTF16 respectively.
! 1488: ** Memory to hold the error message string is managed internally. The
! 1489: ** string may be overwritten or deallocated by subsequent calls to SQLite
! 1490: ** interface functions.
1.1 misha 1491: **
1492: ** Calls to many sqlite3_* functions set the error code and string returned
1.2 ! misha 1493: ** by [sqlite3_errcode()], [sqlite3_errmsg()], and [sqlite3_errmsg16()]
! 1494: ** (overwriting the previous values). Note that calls to [sqlite3_errcode()],
! 1495: ** [sqlite3_errmsg()], and [sqlite3_errmsg16()] themselves do not affect the
! 1496: ** results of future invocations. Calls to API routines that do not return
! 1497: ** an error code (example: [sqlite3_data_count()]) do not
! 1498: ** change the error code returned by this routine. Interfaces that are
! 1499: ** not associated with a specific database connection (examples:
! 1500: ** [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()] do not change
! 1501: ** the return code.
1.1 misha 1502: **
1503: ** Assuming no other intervening sqlite3_* API calls are made, the error
1504: ** code returned by this function is associated with the same error as
1.2 ! misha 1505: ** the strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()].
1.1 misha 1506: */
1507: int sqlite3_errcode(sqlite3 *db);
1.2 ! misha 1508: const char *sqlite3_errmsg(sqlite3*);
! 1509: const void *sqlite3_errmsg16(sqlite3*);
1.1 misha 1510:
1511: /*
1.2 ! misha 1512: ** CAPI3REF: SQL Statement Object
! 1513: **
! 1514: ** Instance of this object represent single SQL statements. This
! 1515: ** is variously known as a "prepared statement" or a
! 1516: ** "compiled SQL statement" or simply as a "statement".
! 1517: **
! 1518: ** The life of a statement object goes something like this:
1.1 misha 1519: **
1.2 ! misha 1520: ** <ol>
! 1521: ** <li> Create the object using [sqlite3_prepare_v2()] or a related
! 1522: ** function.
! 1523: ** <li> Bind values to host parameters using
! 1524: ** [sqlite3_bind_blob | sqlite3_bind_* interfaces].
! 1525: ** <li> Run the SQL by calling [sqlite3_step()] one or more times.
! 1526: ** <li> Reset the statement using [sqlite3_reset()] then go back
! 1527: ** to step 2. Do this zero or more times.
! 1528: ** <li> Destroy the object using [sqlite3_finalize()].
! 1529: ** </ol>
1.1 misha 1530: **
1.2 ! misha 1531: ** Refer to documentation on individual methods above for additional
! 1532: ** information.
1.1 misha 1533: */
1534: typedef struct sqlite3_stmt sqlite3_stmt;
1535:
1536: /*
1.2 ! misha 1537: ** CAPI3REF: Compiling An SQL Statement
! 1538: **
1.1 misha 1539: ** To execute an SQL query, it must first be compiled into a byte-code
1.2 ! misha 1540: ** program using one of these routines.
! 1541: **
! 1542: ** The first argument "db" is an [sqlite3 | SQLite database handle]
! 1543: ** obtained from a prior call to [sqlite3_open()], [sqlite3_open_v2()]
! 1544: ** or [sqlite3_open16()].
! 1545: ** The second argument "zSql" is the statement to be compiled, encoded
! 1546: ** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2()
! 1547: ** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2()
! 1548: ** use UTF-16.
! 1549: **
! 1550: ** If the nByte argument is less
! 1551: ** than zero, then zSql is read up to the first zero terminator. If
! 1552: ** nByte is non-negative, then it is the maximum number of
! 1553: ** bytes read from zSql. When nByte is non-negative, the
! 1554: ** zSql string ends at either the first '\000' character or
! 1555: ** until the nByte-th byte, whichever comes first.
1.1 misha 1556: **
1557: ** *pzTail is made to point to the first byte past the end of the first
1558: ** SQL statement in zSql. This routine only compiles the first statement
1559: ** in zSql, so *pzTail is left pointing to what remains uncompiled.
1560: **
1.2 ! misha 1561: ** *ppStmt is left pointing to a compiled
! 1562: ** [sqlite3_stmt | SQL statement structure] that can be
! 1563: ** executed using [sqlite3_step()]. Or if there is an error, *ppStmt may be
1.1 misha 1564: ** set to NULL. If the input text contained no SQL (if the input is and
1.2 ! misha 1565: ** empty string or a comment) then *ppStmt is set to NULL. The calling
! 1566: ** procedure is responsible for deleting the compiled SQL statement
! 1567: ** using [sqlite3_finalize()] after it has finished with it.
! 1568: **
! 1569: ** On success, [SQLITE_OK] is returned. Otherwise an
! 1570: ** [SQLITE_ERROR | error code] is returned.
! 1571: **
! 1572: ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
! 1573: ** recommended for all new programs. The two older interfaces are retained
! 1574: ** for backwards compatibility, but their use is discouraged.
! 1575: ** In the "v2" interfaces, the prepared statement
! 1576: ** that is returned (the [sqlite3_stmt] object) contains a copy of the
! 1577: ** original SQL text. This causes the [sqlite3_step()] interface to
! 1578: ** behave a differently in two ways:
! 1579: **
! 1580: ** <ol>
! 1581: ** <li>
! 1582: ** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
! 1583: ** always used to do, [sqlite3_step()] will automatically recompile the SQL
! 1584: ** statement and try to run it again. If the schema has changed in a way
! 1585: ** that makes the statement no longer valid, [sqlite3_step()] will still
! 1586: ** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is
! 1587: ** now a fatal error. Calling [sqlite3_prepare_v2()] again will not make the
! 1588: ** error go away. Note: use [sqlite3_errmsg()] to find the text of the parsing
! 1589: ** error that results in an [SQLITE_SCHEMA] return.
! 1590: ** </li>
! 1591: **
! 1592: ** <li>
! 1593: ** When an error occurs,
! 1594: ** [sqlite3_step()] will return one of the detailed
! 1595: ** [SQLITE_ERROR | result codes] or
! 1596: ** [SQLITE_IOERR_READ | extended result codes] such as directly.
! 1597: ** The legacy behavior was that [sqlite3_step()] would only return a generic
! 1598: ** [SQLITE_ERROR] result code and you would have to make a second call to
! 1599: ** [sqlite3_reset()] in order to find the underlying cause of the problem.
! 1600: ** With the "v2" prepare interfaces, the underlying reason for the error is
! 1601: ** returned immediately.
! 1602: ** </li>
! 1603: ** </ol>
1.1 misha 1604: */
1605: int sqlite3_prepare(
1606: sqlite3 *db, /* Database handle */
1607: const char *zSql, /* SQL statement, UTF-8 encoded */
1.2 ! misha 1608: int nByte, /* Maximum length of zSql in bytes. */
! 1609: sqlite3_stmt **ppStmt, /* OUT: Statement handle */
! 1610: const char **pzTail /* OUT: Pointer to unused portion of zSql */
! 1611: );
! 1612: int sqlite3_prepare_v2(
! 1613: sqlite3 *db, /* Database handle */
! 1614: const char *zSql, /* SQL statement, UTF-8 encoded */
! 1615: int nByte, /* Maximum length of zSql in bytes. */
1.1 misha 1616: sqlite3_stmt **ppStmt, /* OUT: Statement handle */
1617: const char **pzTail /* OUT: Pointer to unused portion of zSql */
1618: );
1619: int sqlite3_prepare16(
1620: sqlite3 *db, /* Database handle */
1621: const void *zSql, /* SQL statement, UTF-16 encoded */
1.2 ! misha 1622: int nByte, /* Maximum length of zSql in bytes. */
! 1623: sqlite3_stmt **ppStmt, /* OUT: Statement handle */
! 1624: const void **pzTail /* OUT: Pointer to unused portion of zSql */
! 1625: );
! 1626: int sqlite3_prepare16_v2(
! 1627: sqlite3 *db, /* Database handle */
! 1628: const void *zSql, /* SQL statement, UTF-16 encoded */
! 1629: int nByte, /* Maximum length of zSql in bytes. */
1.1 misha 1630: sqlite3_stmt **ppStmt, /* OUT: Statement handle */
1631: const void **pzTail /* OUT: Pointer to unused portion of zSql */
1632: );
1633:
1634: /*
1.2 ! misha 1635: ** CAPI3REF: Dynamically Typed Value Object
! 1636: **
! 1637: ** SQLite uses dynamic typing for the values it stores. Values can
! 1638: ** be integers, floating point values, strings, BLOBs, or NULL. When
! 1639: ** passing around values internally, each value is represented as
! 1640: ** an instance of the sqlite3_value object.
! 1641: */
! 1642: typedef struct Mem sqlite3_value;
! 1643:
! 1644: /*
! 1645: ** CAPI3REF: SQL Function Context Object
! 1646: **
! 1647: ** The context in which an SQL function executes is stored in an
! 1648: ** sqlite3_context object. A pointer to such an object is the
! 1649: ** first parameter to user-defined SQL functions.
1.1 misha 1650: */
1651: typedef struct sqlite3_context sqlite3_context;
1652:
1653: /*
1.2 ! misha 1654: ** CAPI3REF: Binding Values To Prepared Statements
! 1655: **
! 1656: ** In the SQL strings input to [sqlite3_prepare_v2()] and its variants,
! 1657: ** one or more literals can be replace by a parameter in one of these
! 1658: ** forms:
! 1659: **
! 1660: ** <ul>
! 1661: ** <li> ?
! 1662: ** <li> ?NNN
! 1663: ** <li> :AAA
! 1664: ** <li> @AAA
! 1665: ** <li> $VVV
! 1666: ** </ul>
! 1667: **
! 1668: ** In the parameter forms shown above NNN is an integer literal,
! 1669: ** AAA is an alphanumeric identifier and VVV is a variable name according
! 1670: ** to the syntax rules of the TCL programming language.
! 1671: ** The values of these parameters (also called "host parameter names")
! 1672: ** can be set using the sqlite3_bind_*() routines defined here.
! 1673: **
! 1674: ** The first argument to the sqlite3_bind_*() routines always is a pointer
! 1675: ** to the [sqlite3_stmt] object returned from [sqlite3_prepare_v2()] or
! 1676: ** its variants. The second
! 1677: ** argument is the index of the parameter to be set. The first parameter has
! 1678: ** an index of 1. When the same named parameter is used more than once, second
! 1679: ** and subsequent
! 1680: ** occurrences have the same index as the first occurrence. The index for
! 1681: ** named parameters can be looked up using the
! 1682: ** [sqlite3_bind_parameter_name()] API if desired. The index for "?NNN"
! 1683: ** parametes is the value of NNN.
! 1684: ** The NNN value must be between 1 and the compile-time
! 1685: ** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999).
! 1686: ** See <a href="limits.html">limits.html</a> for additional information.
! 1687: **
! 1688: ** The third argument is the value to bind to the parameter.
! 1689: **
! 1690: ** In those
! 1691: ** routines that have a fourth argument, its value is the number of bytes
! 1692: ** in the parameter. To be clear: the value is the number of bytes in the
! 1693: ** string, not the number of characters. The number
! 1694: ** of bytes does not include the zero-terminator at the end of strings.
! 1695: ** If the fourth parameter is negative, the length of the string is
! 1696: ** number of bytes up to the first zero terminator.
1.1 misha 1697: **
1.2 ! misha 1698: ** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
1.1 misha 1699: ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
1700: ** text after SQLite has finished with it. If the fifth argument is the
1.2 ! misha 1701: ** special value [SQLITE_STATIC], then the library assumes that the information
1.1 misha 1702: ** is in static, unmanaged space and does not need to be freed. If the
1.2 ! misha 1703: ** fifth argument has the value [SQLITE_TRANSIENT], then SQLite makes its
! 1704: ** own private copy of the data immediately, before the sqlite3_bind_*()
! 1705: ** routine returns.
! 1706: **
! 1707: ** The sqlite3_bind_zeroblob() routine binds a BLOB of length n that
! 1708: ** is filled with zeros. A zeroblob uses a fixed amount of memory
! 1709: ** (just an integer to hold it size) while it is being processed.
! 1710: ** Zeroblobs are intended to serve as place-holders for BLOBs whose
! 1711: ** content is later written using
! 1712: ** [sqlite3_blob_open | increment BLOB I/O] routines. A negative
! 1713: ** value for the zeroblob results in a zero-length BLOB.
! 1714: **
! 1715: ** The sqlite3_bind_*() routines must be called after
! 1716: ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and
! 1717: ** before [sqlite3_step()].
! 1718: ** Bindings are not cleared by the [sqlite3_reset()] routine.
! 1719: ** Unbound parameters are interpreted as NULL.
! 1720: **
! 1721: ** These routines return [SQLITE_OK] on success or an error code if
! 1722: ** anything goes wrong. [SQLITE_RANGE] is returned if the parameter
! 1723: ** index is out of range. [SQLITE_NOMEM] is returned if malloc fails.
! 1724: ** [SQLITE_MISUSE] is returned if these routines are called on a virtual
! 1725: ** machine that is the wrong state or which has already been finalized.
1.1 misha 1726: */
1727: int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
1728: int sqlite3_bind_double(sqlite3_stmt*, int, double);
1729: int sqlite3_bind_int(sqlite3_stmt*, int, int);
1.2 ! misha 1730: int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
1.1 misha 1731: int sqlite3_bind_null(sqlite3_stmt*, int);
1732: int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
1733: int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
1734: int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
1.2 ! misha 1735: int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
1.1 misha 1736:
1737: /*
1.2 ! misha 1738: ** CAPI3REF: Number Of Host Parameters
! 1739: **
! 1740: ** Return the largest host parameter index in the precompiled statement given
! 1741: ** as the argument. When the host parameters are of the forms like ":AAA"
! 1742: ** or "?", then they are assigned sequential increasing numbers beginning
! 1743: ** with one, so the value returned is the number of parameters. However
! 1744: ** if the same host parameter name is used multiple times, each occurrance
! 1745: ** is given the same number, so the value returned in that case is the number
! 1746: ** of unique host parameter names. If host parameters of the form "?NNN"
! 1747: ** are used (where NNN is an integer) then there might be gaps in the
! 1748: ** numbering and the value returned by this interface is the index of the
! 1749: ** host parameter with the largest index value.
! 1750: **
! 1751: ** The prepared statement must not be [sqlite3_finalize | finalized]
! 1752: ** prior to this routine returnning. Otherwise the results are undefined
! 1753: ** and probably undesirable.
1.1 misha 1754: */
1755: int sqlite3_bind_parameter_count(sqlite3_stmt*);
1756:
1757: /*
1.2 ! misha 1758: ** CAPI3REF: Name Of A Host Parameter
! 1759: **
! 1760: ** This routine returns a pointer to the name of the n-th parameter in a
! 1761: ** [sqlite3_stmt | prepared statement].
! 1762: ** Host parameters of the form ":AAA" or "@AAA" or "$VVV" have a name
! 1763: ** which is the string ":AAA" or "@AAA" or "$VVV".
! 1764: ** In other words, the initial ":" or "$" or "@"
! 1765: ** is included as part of the name.
! 1766: ** Parameters of the form "?" or "?NNN" have no name.
! 1767: **
! 1768: ** The first bound parameter has an index of 1, not 0.
! 1769: **
! 1770: ** If the value n is out of range or if the n-th parameter is nameless,
! 1771: ** then NULL is returned. The returned string is always in the
! 1772: ** UTF-8 encoding even if the named parameter was originally specified
! 1773: ** as UTF-16 in [sqlite3_prepare16()] or [sqlite3_prepare16_v2()].
1.1 misha 1774: */
1775: const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
1776:
1777: /*
1.2 ! misha 1778: ** CAPI3REF: Index Of A Parameter With A Given Name
! 1779: **
! 1780: ** This routine returns the index of a host parameter with the given name.
! 1781: ** The name must match exactly. If no parameter with the given name is
! 1782: ** found, return 0. Parameter names must be UTF8.
1.1 misha 1783: */
1784: int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
1785:
1786: /*
1.2 ! misha 1787: ** CAPI3REF: Reset All Bindings On A Prepared Statement
! 1788: **
! 1789: ** Contrary to the intuition of many, [sqlite3_reset()] does not
! 1790: ** reset the [sqlite3_bind_blob | bindings] on a
! 1791: ** [sqlite3_stmt | prepared statement]. Use this routine to
! 1792: ** reset all host parameters to NULL.
1.1 misha 1793: */
1.2 ! misha 1794: int sqlite3_clear_bindings(sqlite3_stmt*);
1.1 misha 1795:
1796: /*
1.2 ! misha 1797: ** CAPI3REF: Number Of Columns In A Result Set
! 1798: **
! 1799: ** Return the number of columns in the result set returned by the
! 1800: ** [sqlite3_stmt | compiled SQL statement]. This routine returns 0
! 1801: ** if pStmt is an SQL statement that does not return data (for
! 1802: ** example an UPDATE).
! 1803: */
! 1804: int sqlite3_column_count(sqlite3_stmt *pStmt);
1.1 misha 1805:
1806: /*
1.2 ! misha 1807: ** CAPI3REF: Column Names In A Result Set
! 1808: **
! 1809: ** These routines return the name assigned to a particular column
! 1810: ** in the result set of a SELECT statement. The sqlite3_column_name()
! 1811: ** interface returns a pointer to a UTF8 string and sqlite3_column_name16()
! 1812: ** returns a pointer to a UTF16 string. The first parameter is the
! 1813: ** [sqlite3_stmt | prepared statement] that implements the SELECT statement.
! 1814: ** The second parameter is the column number. The left-most column is
! 1815: ** number 0.
! 1816: **
! 1817: ** The returned string pointer is valid until either the
! 1818: ** [sqlite3_stmt | prepared statement] is destroyed by [sqlite3_finalize()]
! 1819: ** or until the next call sqlite3_column_name() or sqlite3_column_name16()
! 1820: ** on the same column.
! 1821: **
! 1822: ** If sqlite3_malloc() fails during the processing of either routine
! 1823: ** (for example during a conversion from UTF-8 to UTF-16) then a
! 1824: ** NULL pointer is returned.
! 1825: */
! 1826: const char *sqlite3_column_name(sqlite3_stmt*, int N);
! 1827: const void *sqlite3_column_name16(sqlite3_stmt*, int N);
! 1828:
! 1829: /*
! 1830: ** CAPI3REF: Source Of Data In A Query Result
! 1831: **
! 1832: ** These routines provide a means to determine what column of what
! 1833: ** table in which database a result of a SELECT statement comes from.
! 1834: ** The name of the database or table or column can be returned as
! 1835: ** either a UTF8 or UTF16 string. The _database_ routines return
! 1836: ** the database name, the _table_ routines return the table name, and
! 1837: ** the origin_ routines return the column name.
! 1838: ** The returned string is valid until
! 1839: ** the [sqlite3_stmt | prepared statement] is destroyed using
! 1840: ** [sqlite3_finalize()] or until the same information is requested
! 1841: ** again in a different encoding.
! 1842: **
! 1843: ** The names returned are the original un-aliased names of the
! 1844: ** database, table, and column.
! 1845: **
! 1846: ** The first argument to the following calls is a
! 1847: ** [sqlite3_stmt | compiled SQL statement].
! 1848: ** These functions return information about the Nth column returned by
! 1849: ** the statement, where N is the second function argument.
! 1850: **
! 1851: ** If the Nth column returned by the statement is an expression
! 1852: ** or subquery and is not a column value, then all of these functions
! 1853: ** return NULL. Otherwise, they return the
! 1854: ** name of the attached database, table and column that query result
! 1855: ** column was extracted from.
! 1856: **
! 1857: ** As with all other SQLite APIs, those postfixed with "16" return UTF-16
! 1858: ** encoded strings, the other functions return UTF-8.
! 1859: **
! 1860: ** These APIs are only available if the library was compiled with the
! 1861: ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
! 1862: **
! 1863: ** If two or more threads call one or more of these routines against the same
! 1864: ** prepared statement and column at the same time then the results are
! 1865: ** undefined.
! 1866: */
! 1867: const char *sqlite3_column_database_name(sqlite3_stmt*,int);
! 1868: const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
! 1869: const char *sqlite3_column_table_name(sqlite3_stmt*,int);
! 1870: const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
! 1871: const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
! 1872: const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
! 1873:
! 1874: /*
! 1875: ** CAPI3REF: Declared Datatype Of A Query Result
! 1876: **
! 1877: ** The first parameter is a [sqlite3_stmt | compiled SQL statement].
! 1878: ** If this statement is a SELECT statement and the Nth column of the
! 1879: ** returned result set of that SELECT is a table column (not an
! 1880: ** expression or subquery) then the declared type of the table
! 1881: ** column is returned. If the Nth column of the result set is an
! 1882: ** expression or subquery, then a NULL pointer is returned.
! 1883: ** The returned string is always UTF-8 encoded. For example, in
! 1884: ** the database schema:
1.1 misha 1885: **
1886: ** CREATE TABLE t1(c1 VARIANT);
1887: **
1888: ** And the following statement compiled:
1889: **
1.2 ! misha 1890: ** SELECT c1 + 1, c1 FROM t1;
1.1 misha 1891: **
1892: ** Then this routine would return the string "VARIANT" for the second
1893: ** result column (i==1), and a NULL pointer for the first result column
1894: ** (i==0).
1.2 ! misha 1895: **
! 1896: ** SQLite uses dynamic run-time typing. So just because a column
! 1897: ** is declared to contain a particular type does not mean that the
! 1898: ** data stored in that column is of the declared type. SQLite is
! 1899: ** strongly typed, but the typing is dynamic not static. Type
! 1900: ** is associated with individual values, not with the containers
! 1901: ** used to hold those values.
1.1 misha 1902: */
1903: const char *sqlite3_column_decltype(sqlite3_stmt *, int i);
1904: const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
1905:
1906: /*
1.2 ! misha 1907: ** CAPI3REF: Evaluate An SQL Statement
! 1908: **
! 1909: ** After an [sqlite3_stmt | SQL statement] has been prepared with a call
! 1910: ** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of
! 1911: ** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()],
! 1912: ** then this function must be called one or more times to evaluate the
! 1913: ** statement.
! 1914: **
! 1915: ** The details of the behavior of this sqlite3_step() interface depend
! 1916: ** on whether the statement was prepared using the newer "v2" interface
! 1917: ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
! 1918: ** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the
! 1919: ** new "v2" interface is recommended for new applications but the legacy
! 1920: ** interface will continue to be supported.
! 1921: **
! 1922: ** In the lagacy interface, the return value will be either [SQLITE_BUSY],
! 1923: ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
! 1924: ** With the "v2" interface, any of the other [SQLITE_OK | result code]
! 1925: ** or [SQLITE_IOERR_READ | extended result code] might be returned as
! 1926: ** well.
! 1927: **
! 1928: ** [SQLITE_BUSY] means that the database engine was unable to acquire the
! 1929: ** database locks it needs to do its job. If the statement is a COMMIT
! 1930: ** or occurs outside of an explicit transaction, then you can retry the
! 1931: ** statement. If the statement is not a COMMIT and occurs within a
! 1932: ** explicit transaction then you should rollback the transaction before
! 1933: ** continuing.
1.1 misha 1934: **
1.2 ! misha 1935: ** [SQLITE_DONE] means that the statement has finished executing
1.1 misha 1936: ** successfully. sqlite3_step() should not be called again on this virtual
1.2 ! misha 1937: ** machine without first calling [sqlite3_reset()] to reset the virtual
! 1938: ** machine back to its initial state.
1.1 misha 1939: **
1940: ** If the SQL statement being executed returns any data, then
1.2 ! misha 1941: ** [SQLITE_ROW] is returned each time a new row of data is ready
1.1 misha 1942: ** for processing by the caller. The values may be accessed using
1.2 ! misha 1943: ** the [sqlite3_column_int | column access functions].
! 1944: ** sqlite3_step() is called again to retrieve the next row of data.
1.1 misha 1945: **
1.2 ! misha 1946: ** [SQLITE_ERROR] means that a run-time error (such as a constraint
1.1 misha 1947: ** violation) has occurred. sqlite3_step() should not be called again on
1.2 ! misha 1948: ** the VM. More information may be found by calling [sqlite3_errmsg()].
! 1949: ** With the legacy interface, a more specific error code (example:
! 1950: ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
! 1951: ** can be obtained by calling [sqlite3_reset()] on the
! 1952: ** [sqlite3_stmt | prepared statement]. In the "v2" interface,
! 1953: ** the more specific error code is returned directly by sqlite3_step().
! 1954: **
! 1955: ** [SQLITE_MISUSE] means that the this routine was called inappropriately.
! 1956: ** Perhaps it was called on a [sqlite3_stmt | prepared statement] that has
! 1957: ** already been [sqlite3_finalize | finalized] or on one that had
! 1958: ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could
! 1959: ** be the case that the same database connection is being used by two or
! 1960: ** more threads at the same moment in time.
! 1961: **
! 1962: ** <b>Goofy Interface Alert:</b>
! 1963: ** In the legacy interface,
! 1964: ** the sqlite3_step() API always returns a generic error code,
! 1965: ** [SQLITE_ERROR], following any error other than [SQLITE_BUSY]
! 1966: ** and [SQLITE_MISUSE]. You must call [sqlite3_reset()] or
! 1967: ** [sqlite3_finalize()] in order to find one of the specific
! 1968: ** [SQLITE_ERROR | result codes] that better describes the error.
! 1969: ** We admit that this is a goofy design. The problem has been fixed
! 1970: ** with the "v2" interface. If you prepare all of your SQL statements
! 1971: ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
! 1972: ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the
! 1973: ** more specific [SQLITE_ERROR | result codes] are returned directly
! 1974: ** by sqlite3_step(). The use of the "v2" interface is recommended.
1.1 misha 1975: */
1976: int sqlite3_step(sqlite3_stmt*);
1977:
1978: /*
1.2 ! misha 1979: ** CAPI3REF:
! 1980: **
1.1 misha 1981: ** Return the number of values in the current row of the result set.
1982: **
1.2 ! misha 1983: ** After a call to [sqlite3_step()] that returns [SQLITE_ROW], this routine
! 1984: ** will return the same value as the [sqlite3_column_count()] function.
! 1985: ** After [sqlite3_step()] has returned an [SQLITE_DONE], [SQLITE_BUSY], or
! 1986: ** a [SQLITE_ERROR | error code], or before [sqlite3_step()] has been
! 1987: ** called on the [sqlite3_stmt | prepared statement] for the first time,
! 1988: ** this routine returns zero.
1.1 misha 1989: */
1990: int sqlite3_data_count(sqlite3_stmt *pStmt);
1991:
1992: /*
1.2 ! misha 1993: ** CAPI3REF: Fundamental Datatypes
! 1994: **
! 1995: ** Every value in SQLite has one of five fundamental datatypes:
! 1996: **
! 1997: ** <ul>
! 1998: ** <li> 64-bit signed integer
! 1999: ** <li> 64-bit IEEE floating point number
! 2000: ** <li> string
! 2001: ** <li> BLOB
! 2002: ** <li> NULL
! 2003: ** </ul>
! 2004: **
! 2005: ** These constants are codes for each of those types.
! 2006: **
! 2007: ** Note that the SQLITE_TEXT constant was also used in SQLite version 2
! 2008: ** for a completely different meaning. Software that links against both
! 2009: ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT not
! 2010: ** SQLITE_TEXT.
1.1 misha 2011: */
2012: #define SQLITE_INTEGER 1
2013: #define SQLITE_FLOAT 2
2014: #define SQLITE_BLOB 4
2015: #define SQLITE_NULL 5
2016: #ifdef SQLITE_TEXT
2017: # undef SQLITE_TEXT
2018: #else
2019: # define SQLITE_TEXT 3
2020: #endif
2021: #define SQLITE3_TEXT 3
2022:
2023: /*
1.2 ! misha 2024: ** CAPI3REF: Results Values From A Query
! 2025: **
! 2026: ** These routines return information about
! 2027: ** a single column of the current result row of a query. In every
! 2028: ** case the first argument is a pointer to the
! 2029: ** [sqlite3_stmt | SQL statement] that is being
! 2030: ** evaluated (the [sqlite3_stmt*] that was returned from
! 2031: ** [sqlite3_prepare_v2()] or one of its variants) and
1.1 misha 2032: ** the second argument is the index of the column for which information
1.2 ! misha 2033: ** should be returned. The left-most column of the result set
! 2034: ** has an index of 0.
1.1 misha 2035: **
2036: ** If the SQL statement is not currently point to a valid row, or if the
1.2 ! misha 2037: ** the column index is out of range, the result is undefined.
! 2038: ** These routines may only be called when the most recent call to
! 2039: ** [sqlite3_step()] has returned [SQLITE_ROW] and neither
! 2040: ** [sqlite3_reset()] nor [sqlite3_finalize()] has been call subsequently.
! 2041: ** If any of these routines are called after [sqlite3_reset()] or
! 2042: ** [sqlite3_finalize()] or after [sqlite3_step()] has returned
! 2043: ** something other than [SQLITE_ROW], the results are undefined.
! 2044: ** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
! 2045: ** are called from a different thread while any of these routines
! 2046: ** are pending, then the results are undefined.
! 2047: **
! 2048: ** The sqlite3_column_type() routine returns
! 2049: ** [SQLITE_INTEGER | datatype code] for the initial data type
! 2050: ** of the result column. The returned value is one of [SQLITE_INTEGER],
! 2051: ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value
! 2052: ** returned by sqlite3_column_type() is only meaningful if no type
! 2053: ** conversions have occurred as described below. After a type conversion,
! 2054: ** the value returned by sqlite3_column_type() is undefined. Future
! 2055: ** versions of SQLite may change the behavior of sqlite3_column_type()
! 2056: ** following a type conversion.
! 2057: **
! 2058: ** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
! 2059: ** routine returns the number of bytes in that BLOB or string.
! 2060: ** If the result is a UTF-16 string, then sqlite3_column_bytes() converts
! 2061: ** the string to UTF-8 and then returns the number of bytes.
! 2062: ** If the result is a numeric value then sqlite3_column_bytes() uses
! 2063: ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
! 2064: ** the number of bytes in that string.
! 2065: ** The value returned does not include the zero terminator at the end
! 2066: ** of the string. For clarity: the value returned is the number of
! 2067: ** bytes in the string, not the number of characters.
! 2068: **
! 2069: ** Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
! 2070: ** even zero-length strings, are always zero terminated. The return
! 2071: ** value from sqlite3_column_blob() for a zero-length blob is an arbitrary
! 2072: ** pointer, possibly even a NULL pointer.
! 2073: **
! 2074: ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
! 2075: ** but leaves the result in UTF-16 instead of UTF-8.
! 2076: ** The zero terminator is not included in this count.
1.1 misha 2077: **
2078: ** These routines attempt to convert the value where appropriate. For
2079: ** example, if the internal representation is FLOAT and a text result
1.2 ! misha 2080: ** is requested, [sqlite3_snprintf()] is used internally to do the conversion
1.1 misha 2081: ** automatically. The following table details the conversions that
2082: ** are applied:
2083: **
1.2 ! misha 2084: ** <blockquote>
! 2085: ** <table border="1">
! 2086: ** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion
! 2087: **
! 2088: ** <tr><td> NULL <td> INTEGER <td> Result is 0
! 2089: ** <tr><td> NULL <td> FLOAT <td> Result is 0.0
! 2090: ** <tr><td> NULL <td> TEXT <td> Result is NULL pointer
! 2091: ** <tr><td> NULL <td> BLOB <td> Result is NULL pointer
! 2092: ** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float
! 2093: ** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer
! 2094: ** <tr><td> INTEGER <td> BLOB <td> Same as for INTEGER->TEXT
! 2095: ** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer
! 2096: ** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float
! 2097: ** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT
! 2098: ** <tr><td> TEXT <td> INTEGER <td> Use atoi()
! 2099: ** <tr><td> TEXT <td> FLOAT <td> Use atof()
! 2100: ** <tr><td> TEXT <td> BLOB <td> No change
! 2101: ** <tr><td> BLOB <td> INTEGER <td> Convert to TEXT then use atoi()
! 2102: ** <tr><td> BLOB <td> FLOAT <td> Convert to TEXT then use atof()
! 2103: ** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed
! 2104: ** </table>
! 2105: ** </blockquote>
! 2106: **
! 2107: ** The table above makes reference to standard C library functions atoi()
! 2108: ** and atof(). SQLite does not really use these functions. It has its
! 2109: ** on equavalent internal routines. The atoi() and atof() names are
! 2110: ** used in the table for brevity and because they are familiar to most
! 2111: ** C programmers.
! 2112: **
! 2113: ** Note that when type conversions occur, pointers returned by prior
! 2114: ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
! 2115: ** sqlite3_column_text16() may be invalidated.
! 2116: ** Type conversions and pointer invalidations might occur
! 2117: ** in the following cases:
! 2118: **
! 2119: ** <ul>
! 2120: ** <li><p> The initial content is a BLOB and sqlite3_column_text()
! 2121: ** or sqlite3_column_text16() is called. A zero-terminator might
! 2122: ** need to be added to the string.</p></li>
! 2123: **
! 2124: ** <li><p> The initial content is UTF-8 text and sqlite3_column_bytes16() or
! 2125: ** sqlite3_column_text16() is called. The content must be converted
! 2126: ** to UTF-16.</p></li>
! 2127: **
! 2128: ** <li><p> The initial content is UTF-16 text and sqlite3_column_bytes() or
! 2129: ** sqlite3_column_text() is called. The content must be converted
! 2130: ** to UTF-8.</p></li>
! 2131: ** </ul>
! 2132: **
! 2133: ** Conversions between UTF-16be and UTF-16le are always done in place and do
! 2134: ** not invalidate a prior pointer, though of course the content of the buffer
! 2135: ** that the prior pointer points to will have been modified. Other kinds
! 2136: ** of conversion are done in place when it is possible, but sometime it is
! 2137: ** not possible and in those cases prior pointers are invalidated.
! 2138: **
! 2139: ** The safest and easiest to remember policy is to invoke these routines
! 2140: ** in one of the following ways:
! 2141: **
! 2142: ** <ul>
! 2143: ** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
! 2144: ** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
! 2145: ** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
! 2146: ** </ul>
! 2147: **
! 2148: ** In other words, you should call sqlite3_column_text(), sqlite3_column_blob(),
! 2149: ** or sqlite3_column_text16() first to force the result into the desired
! 2150: ** format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to
! 2151: ** find the size of the result. Do not mix call to sqlite3_column_text() or
! 2152: ** sqlite3_column_blob() with calls to sqlite3_column_bytes16(). And do not
! 2153: ** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().
! 2154: **
! 2155: ** The pointers returned are valid until a type conversion occurs as
! 2156: ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
! 2157: ** [sqlite3_finalize()] is called. The memory space used to hold strings
! 2158: ** and blobs is freed automatically. Do <b>not</b> pass the pointers returned
! 2159: ** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
! 2160: ** [sqlite3_free()].
! 2161: **
! 2162: ** If a memory allocation error occurs during the evaluation of any
! 2163: ** of these routines, a default value is returned. The default value
! 2164: ** is either the integer 0, the floating point number 0.0, or a NULL
! 2165: ** pointer. Subsequent calls to [sqlite3_errcode()] will return
! 2166: ** [SQLITE_NOMEM].
1.1 misha 2167: */
2168: const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
2169: int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
2170: int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
2171: double sqlite3_column_double(sqlite3_stmt*, int iCol);
2172: int sqlite3_column_int(sqlite3_stmt*, int iCol);
1.2 ! misha 2173: sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
1.1 misha 2174: const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
2175: const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
2176: int sqlite3_column_type(sqlite3_stmt*, int iCol);
1.2 ! misha 2177: sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
1.1 misha 2178:
2179: /*
1.2 ! misha 2180: ** CAPI3REF: Destroy A Prepared Statement Object
! 2181: **
! 2182: ** The sqlite3_finalize() function is called to delete a
! 2183: ** [sqlite3_stmt | compiled SQL statement]. If the statement was
! 2184: ** executed successfully, or not executed at all, then SQLITE_OK is returned.
! 2185: ** If execution of the statement failed then an
! 2186: ** [SQLITE_ERROR | error code] or [SQLITE_IOERR_READ | extended error code]
! 2187: ** is returned.
1.1 misha 2188: **
2189: ** This routine can be called at any point during the execution of the
1.2 ! misha 2190: ** [sqlite3_stmt | virtual machine]. If the virtual machine has not
! 2191: ** completed execution when this routine is called, that is like
! 2192: ** encountering an error or an interrupt. (See [sqlite3_interrupt()].)
! 2193: ** Incomplete updates may be rolled back and transactions cancelled,
! 2194: ** depending on the circumstances, and the
! 2195: ** [SQLITE_ERROR | result code] returned will be [SQLITE_ABORT].
1.1 misha 2196: */
2197: int sqlite3_finalize(sqlite3_stmt *pStmt);
2198:
2199: /*
1.2 ! misha 2200: ** CAPI3REF: Reset A Prepared Statement Object
! 2201: **
! 2202: ** The sqlite3_reset() function is called to reset a
! 2203: ** [sqlite3_stmt | compiled SQL statement] object.
! 2204: ** back to it's initial state, ready to be re-executed.
1.1 misha 2205: ** Any SQL statement variables that had values bound to them using
1.2 ! misha 2206: ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
! 2207: ** Use [sqlite3_clear_bindings()] to reset the bindings.
1.1 misha 2208: */
2209: int sqlite3_reset(sqlite3_stmt *pStmt);
2210:
2211: /*
1.2 ! misha 2212: ** CAPI3REF: Create Or Redefine SQL Functions
! 2213: **
! 2214: ** The following two functions are used to add SQL functions or aggregates
! 2215: ** or to redefine the behavior of existing SQL functions or aggregates. The
1.1 misha 2216: ** difference only between the two is that the second parameter, the
2217: ** name of the (scalar) function or aggregate, is encoded in UTF-8 for
2218: ** sqlite3_create_function() and UTF-16 for sqlite3_create_function16().
2219: **
1.2 ! misha 2220: ** The first argument is the [sqlite3 | database handle] that holds the
! 2221: ** SQL function or aggregate is to be added or redefined. If a single
! 2222: ** program uses more than one database handle internally, then SQL
! 2223: ** functions or aggregates must be added individually to each database
! 2224: ** handle with which they will be used.
! 2225: **
! 2226: ** The second parameter is the name of the SQL function to be created
! 2227: ** or redefined.
! 2228: ** The length of the name is limited to 255 bytes, exclusive of the
! 2229: ** zero-terminator. Note that the name length limit is in bytes, not
! 2230: ** characters. Any attempt to create a function with a longer name
! 2231: ** will result in an SQLITE_ERROR error.
1.1 misha 2232: **
1.2 ! misha 2233: ** The third parameter is the number of arguments that the SQL function or
! 2234: ** aggregate takes. If this parameter is negative, then the SQL function or
1.1 misha 2235: ** aggregate may take any number of arguments.
2236: **
1.2 ! misha 2237: ** The fourth parameter, eTextRep, specifies what
! 2238: ** [SQLITE_UTF8 | text encoding] this SQL function prefers for
! 2239: ** its parameters. Any SQL function implementation should be able to work
! 2240: ** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be
! 2241: ** more efficient with one encoding than another. It is allowed to
! 2242: ** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
! 2243: ** times with the same function but with different values of eTextRep.
! 2244: ** When multiple implementations of the same function are available, SQLite
! 2245: ** will pick the one that involves the least amount of data conversion.
! 2246: ** If there is only a single implementation which does not care what
! 2247: ** text encoding is used, then the fourth argument should be
! 2248: ** [SQLITE_ANY].
! 2249: **
! 2250: ** The fifth parameter is an arbitrary pointer. The implementation
! 2251: ** of the function can gain access to this pointer using
! 2252: ** [sqlite3_user_data()].
1.1 misha 2253: **
2254: ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are
1.2 ! misha 2255: ** pointers to C-language functions that implement the SQL
! 2256: ** function or aggregate. A scalar SQL function requires an implementation of
1.1 misha 2257: ** the xFunc callback only, NULL pointers should be passed as the xStep
1.2 ! misha 2258: ** and xFinal parameters. An aggregate SQL function requires an implementation
! 2259: ** of xStep and xFinal and NULL should be passed for xFunc. To delete an
! 2260: ** existing SQL function or aggregate, pass NULL for all three function
! 2261: ** callback.
! 2262: **
! 2263: ** It is permitted to register multiple implementations of the same
! 2264: ** functions with the same name but with either differing numbers of
! 2265: ** arguments or differing perferred text encodings. SQLite will use
! 2266: ** the implementation most closely matches the way in which the
! 2267: ** SQL function is used.
1.1 misha 2268: */
2269: int sqlite3_create_function(
2270: sqlite3 *,
2271: const char *zFunctionName,
2272: int nArg,
2273: int eTextRep,
2274: void*,
2275: void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
2276: void (*xStep)(sqlite3_context*,int,sqlite3_value**),
2277: void (*xFinal)(sqlite3_context*)
2278: );
2279: int sqlite3_create_function16(
2280: sqlite3*,
2281: const void *zFunctionName,
2282: int nArg,
2283: int eTextRep,
2284: void*,
2285: void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
2286: void (*xStep)(sqlite3_context*,int,sqlite3_value**),
2287: void (*xFinal)(sqlite3_context*)
2288: );
2289:
2290: /*
1.2 ! misha 2291: ** CAPI3REF: Text Encodings
! 2292: **
! 2293: ** These constant define integer codes that represent the various
! 2294: ** text encodings supported by SQLite.
! 2295: */
! 2296: #define SQLITE_UTF8 1
! 2297: #define SQLITE_UTF16LE 2
! 2298: #define SQLITE_UTF16BE 3
! 2299: #define SQLITE_UTF16 4 /* Use native byte order */
! 2300: #define SQLITE_ANY 5 /* sqlite3_create_function only */
! 2301: #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
! 2302:
! 2303: /*
! 2304: ** CAPI3REF: Obsolete Functions
! 2305: **
! 2306: ** These functions are all now obsolete. In order to maintain
! 2307: ** backwards compatibility with older code, we continue to support
! 2308: ** these functions. However, new development projects should avoid
! 2309: ** the use of these functions. To help encourage people to avoid
! 2310: ** using these functions, we are not going to tell you want they do.
1.1 misha 2311: */
2312: int sqlite3_aggregate_count(sqlite3_context*);
1.2 ! misha 2313: int sqlite3_expired(sqlite3_stmt*);
! 2314: int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
! 2315: int sqlite3_global_recover(void);
! 2316: void sqlite3_thread_cleanup(void);
! 2317:
! 2318: /*
! 2319: ** CAPI3REF: Obtaining SQL Function Parameter Values
! 2320: **
! 2321: ** The C-language implementation of SQL functions and aggregates uses
! 2322: ** this set of interface routines to access the parameter values on
! 2323: ** the function or aggregate.
! 2324: **
! 2325: ** The xFunc (for scalar functions) or xStep (for aggregates) parameters
! 2326: ** to [sqlite3_create_function()] and [sqlite3_create_function16()]
! 2327: ** define callbacks that implement the SQL functions and aggregates.
! 2328: ** The 4th parameter to these callbacks is an array of pointers to
! 2329: ** [sqlite3_value] objects. There is one [sqlite3_value] object for
! 2330: ** each parameter to the SQL function. These routines are used to
! 2331: ** extract values from the [sqlite3_value] objects.
! 2332: **
! 2333: ** These routines work just like the corresponding
! 2334: ** [sqlite3_column_blob | sqlite3_column_* routines] except that
! 2335: ** these routines take a single [sqlite3_value*] pointer instead
! 2336: ** of an [sqlite3_stmt*] pointer and an integer column number.
! 2337: **
! 2338: ** The sqlite3_value_text16() interface extracts a UTF16 string
! 2339: ** in the native byte-order of the host machine. The
! 2340: ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
! 2341: ** extract UTF16 strings as big-endian and little-endian respectively.
! 2342: **
! 2343: ** The sqlite3_value_numeric_type() interface attempts to apply
! 2344: ** numeric affinity to the value. This means that an attempt is
! 2345: ** made to convert the value to an integer or floating point. If
! 2346: ** such a conversion is possible without loss of information (in order
! 2347: ** words if the value is original a string that looks like a number)
! 2348: ** then it is done. Otherwise no conversion occurs. The
! 2349: ** [SQLITE_INTEGER | datatype] after conversion is returned.
! 2350: **
! 2351: ** Please pay particular attention to the fact that the pointer that
! 2352: ** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or
! 2353: ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
! 2354: ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
! 2355: ** or [sqlite3_value_text16()].
! 2356: **
! 2357: ** These routines must be called from the same thread as
! 2358: ** the SQL function that supplied the sqlite3_value* parameters.
! 2359: ** Or, if the sqlite3_value* argument comes from the [sqlite3_column_value()]
! 2360: ** interface, then these routines should be called from the same thread
! 2361: ** that ran [sqlite3_column_value()].
1.1 misha 2362: */
2363: const void *sqlite3_value_blob(sqlite3_value*);
2364: int sqlite3_value_bytes(sqlite3_value*);
2365: int sqlite3_value_bytes16(sqlite3_value*);
2366: double sqlite3_value_double(sqlite3_value*);
2367: int sqlite3_value_int(sqlite3_value*);
1.2 ! misha 2368: sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
1.1 misha 2369: const unsigned char *sqlite3_value_text(sqlite3_value*);
2370: const void *sqlite3_value_text16(sqlite3_value*);
2371: const void *sqlite3_value_text16le(sqlite3_value*);
2372: const void *sqlite3_value_text16be(sqlite3_value*);
2373: int sqlite3_value_type(sqlite3_value*);
1.2 ! misha 2374: int sqlite3_value_numeric_type(sqlite3_value*);
1.1 misha 2375:
2376: /*
1.2 ! misha 2377: ** CAPI3REF: Obtain Aggregate Function Context
! 2378: **
! 2379: ** The implementation of aggregate SQL functions use this routine to allocate
1.1 misha 2380: ** a structure for storing their state. The first time this routine
2381: ** is called for a particular aggregate, a new structure of size nBytes
2382: ** is allocated, zeroed, and returned. On subsequent calls (for the
2383: ** same aggregate instance) the same buffer is returned. The implementation
2384: ** of the aggregate can use the returned buffer to accumulate data.
2385: **
1.2 ! misha 2386: ** The buffer allocated is freed automatically by SQLite whan the aggregate
! 2387: ** query concludes.
! 2388: **
! 2389: ** The first parameter should be a copy of the
! 2390: ** [sqlite3_context | SQL function context] that is the first
! 2391: ** parameter to the callback routine that implements the aggregate
! 2392: ** function.
! 2393: **
! 2394: ** This routine must be called from the same thread in which
! 2395: ** the aggregate SQL function is running.
1.1 misha 2396: */
2397: void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
2398:
2399: /*
1.2 ! misha 2400: ** CAPI3REF: User Data For Functions
! 2401: **
! 2402: ** The pUserData parameter to the [sqlite3_create_function()]
! 2403: ** and [sqlite3_create_function16()] routines
! 2404: ** used to register user functions is available to
! 2405: ** the implementation of the function using this call.
! 2406: **
! 2407: ** This routine must be called from the same thread in which
! 2408: ** the SQL function is running.
1.1 misha 2409: */
2410: void *sqlite3_user_data(sqlite3_context*);
2411:
2412: /*
1.2 ! misha 2413: ** CAPI3REF: Function Auxiliary Data
! 2414: **
! 2415: ** The following two functions may be used by scalar SQL functions to
1.1 misha 2416: ** associate meta-data with argument values. If the same value is passed to
1.2 ! misha 2417: ** multiple invocations of the same SQL function during query execution, under
1.1 misha 2418: ** some circumstances the associated meta-data may be preserved. This may
2419: ** be used, for example, to add a regular-expression matching scalar
2420: ** function. The compiled version of the regular expression is stored as
2421: ** meta-data associated with the SQL value passed as the regular expression
1.2 ! misha 2422: ** pattern. The compiled regular expression can be reused on multiple
! 2423: ** invocations of the same function so that the original pattern string
! 2424: ** does not need to be recompiled on each invocation.
1.1 misha 2425: **
1.2 ! misha 2426: ** The sqlite3_get_auxdata() interface returns a pointer to the meta-data
! 2427: ** associated with the Nth argument value to the current SQL function
1.1 misha 2428: ** call, where N is the second parameter. If no meta-data has been set for
2429: ** that value, then a NULL pointer is returned.
2430: **
1.2 ! misha 2431: ** The sqlite3_set_auxdata() is used to associate meta-data with an SQL
! 2432: ** function argument. The third parameter is a pointer to the meta-data
1.1 misha 2433: ** to be associated with the Nth user function argument value. The fourth
1.2 ! misha 2434: ** parameter specifies a destructor that will be called on the meta-
! 2435: ** data pointer to release it when it is no longer required. If the
! 2436: ** destructor is NULL, it is not invoked.
1.1 misha 2437: **
2438: ** In practice, meta-data is preserved between function calls for
2439: ** expressions that are constant at compile time. This includes literal
2440: ** values and SQL variables.
1.2 ! misha 2441: **
! 2442: ** These routines must be called from the same thread in which
! 2443: ** the SQL function is running.
1.1 misha 2444: */
2445: void *sqlite3_get_auxdata(sqlite3_context*, int);
2446: void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*));
2447:
2448:
2449: /*
1.2 ! misha 2450: ** CAPI3REF: Constants Defining Special Destructor Behavior
! 2451: **
1.1 misha 2452: ** These are special value for the destructor that is passed in as the
1.2 ! misha 2453: ** final argument to routines like [sqlite3_result_blob()]. If the destructor
1.1 misha 2454: ** argument is SQLITE_STATIC, it means that the content pointer is constant
2455: ** and will never change. It does not need to be destroyed. The
2456: ** SQLITE_TRANSIENT value means that the content will likely change in
2457: ** the near future and that SQLite should make its own private copy of
2458: ** the content before returning.
1.2 ! misha 2459: **
! 2460: ** The typedef is necessary to work around problems in certain
! 2461: ** C++ compilers. See ticket #2191.
1.1 misha 2462: */
1.2 ! misha 2463: typedef void (*sqlite3_destructor_type)(void*);
! 2464: #define SQLITE_STATIC ((sqlite3_destructor_type)0)
! 2465: #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1)
! 2466:
! 2467: /*
! 2468: ** CAPI3REF: Setting The Result Of An SQL Function
! 2469: **
! 2470: ** These routines are used by the xFunc or xFinal callbacks that
! 2471: ** implement SQL functions and aggregates. See
! 2472: ** [sqlite3_create_function()] and [sqlite3_create_function16()]
! 2473: ** for additional information.
! 2474: **
! 2475: ** These functions work very much like the
! 2476: ** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used
! 2477: ** to bind values to host parameters in prepared statements.
! 2478: ** Refer to the
! 2479: ** [sqlite3_bind_blob | sqlite3_bind_* documentation] for
! 2480: ** additional information.
! 2481: **
! 2482: ** The sqlite3_result_error() and sqlite3_result_error16() functions
! 2483: ** cause the implemented SQL function to throw an exception. The
! 2484: ** parameter to sqlite3_result_error() or sqlite3_result_error16()
! 2485: ** is the text of an error message.
! 2486: **
! 2487: ** The sqlite3_result_toobig() cause the function implementation
! 2488: ** to throw and error indicating that a string or BLOB is to long
! 2489: ** to represent.
! 2490: **
! 2491: ** These routines must be called from within the same thread as
! 2492: ** the SQL function associated with the [sqlite3_context] pointer.
1.1 misha 2493: */
2494: void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
2495: void sqlite3_result_double(sqlite3_context*, double);
2496: void sqlite3_result_error(sqlite3_context*, const char*, int);
2497: void sqlite3_result_error16(sqlite3_context*, const void*, int);
1.2 ! misha 2498: void sqlite3_result_error_toobig(sqlite3_context*);
! 2499: void sqlite3_result_error_nomem(sqlite3_context*);
1.1 misha 2500: void sqlite3_result_int(sqlite3_context*, int);
1.2 ! misha 2501: void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
1.1 misha 2502: void sqlite3_result_null(sqlite3_context*);
2503: void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
2504: void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
2505: void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
2506: void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
2507: void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
1.2 ! misha 2508: void sqlite3_result_zeroblob(sqlite3_context*, int n);
1.1 misha 2509:
2510: /*
1.2 ! misha 2511: ** CAPI3REF: Define New Collating Sequences
! 2512: **
! 2513: ** These functions are used to add new collation sequences to the
! 2514: ** [sqlite3*] handle specified as the first argument.
1.1 misha 2515: **
2516: ** The name of the new collation sequence is specified as a UTF-8 string
1.2 ! misha 2517: ** for sqlite3_create_collation() and sqlite3_create_collation_v2()
! 2518: ** and a UTF-16 string for sqlite3_create_collation16(). In all cases
! 2519: ** the name is passed as the second function argument.
1.1 misha 2520: **
1.2 ! misha 2521: ** The third argument must be one of the constants [SQLITE_UTF8],
! 2522: ** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied
1.1 misha 2523: ** routine expects to be passed pointers to strings encoded using UTF-8,
2524: ** UTF-16 little-endian or UTF-16 big-endian respectively.
2525: **
2526: ** A pointer to the user supplied routine must be passed as the fifth
2527: ** argument. If it is NULL, this is the same as deleting the collation
2528: ** sequence (so that SQLite cannot call it anymore). Each time the user
2529: ** supplied function is invoked, it is passed a copy of the void* passed as
2530: ** the fourth argument to sqlite3_create_collation() or
2531: ** sqlite3_create_collation16() as its first parameter.
2532: **
2533: ** The remaining arguments to the user-supplied routine are two strings,
2534: ** each represented by a [length, data] pair and encoded in the encoding
2535: ** that was passed as the third argument when the collation sequence was
2536: ** registered. The user routine should return negative, zero or positive if
2537: ** the first string is less than, equal to, or greater than the second
2538: ** string. i.e. (STRING1 - STRING2).
1.2 ! misha 2539: **
! 2540: ** The sqlite3_create_collation_v2() works like sqlite3_create_collation()
! 2541: ** excapt that it takes an extra argument which is a destructor for
! 2542: ** the collation. The destructor is called when the collation is
! 2543: ** destroyed and is passed a copy of the fourth parameter void* pointer
! 2544: ** of the sqlite3_create_collation_v2(). Collations are destroyed when
! 2545: ** they are overridden by later calls to the collation creation functions
! 2546: ** or when the [sqlite3*] database handle is closed using [sqlite3_close()].
! 2547: **
! 2548: ** The sqlite3_create_collation_v2() interface is experimental and
! 2549: ** subject to change in future releases. The other collation creation
! 2550: ** functions are stable.
1.1 misha 2551: */
2552: int sqlite3_create_collation(
2553: sqlite3*,
2554: const char *zName,
2555: int eTextRep,
2556: void*,
2557: int(*xCompare)(void*,int,const void*,int,const void*)
2558: );
1.2 ! misha 2559: int sqlite3_create_collation_v2(
! 2560: sqlite3*,
! 2561: const char *zName,
! 2562: int eTextRep,
! 2563: void*,
! 2564: int(*xCompare)(void*,int,const void*,int,const void*),
! 2565: void(*xDestroy)(void*)
! 2566: );
1.1 misha 2567: int sqlite3_create_collation16(
2568: sqlite3*,
2569: const char *zName,
2570: int eTextRep,
2571: void*,
2572: int(*xCompare)(void*,int,const void*,int,const void*)
2573: );
2574:
2575: /*
1.2 ! misha 2576: ** CAPI3REF: Collation Needed Callbacks
! 2577: **
1.1 misha 2578: ** To avoid having to register all collation sequences before a database
2579: ** can be used, a single callback function may be registered with the
2580: ** database handle to be called whenever an undefined collation sequence is
2581: ** required.
2582: **
2583: ** If the function is registered using the sqlite3_collation_needed() API,
2584: ** then it is passed the names of undefined collation sequences as strings
2585: ** encoded in UTF-8. If sqlite3_collation_needed16() is used, the names
2586: ** are passed as UTF-16 in machine native byte order. A call to either
2587: ** function replaces any existing callback.
2588: **
1.2 ! misha 2589: ** When the callback is invoked, the first argument passed is a copy
1.1 misha 2590: ** of the second argument to sqlite3_collation_needed() or
2591: ** sqlite3_collation_needed16(). The second argument is the database
1.2 ! misha 2592: ** handle. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], or
! 2593: ** [SQLITE_UTF16LE], indicating the most desirable form of the collation
1.1 misha 2594: ** sequence function required. The fourth parameter is the name of the
2595: ** required collation sequence.
2596: **
1.2 ! misha 2597: ** The callback function should register the desired collation using
! 2598: ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
! 2599: ** [sqlite3_create_collation_v2()].
1.1 misha 2600: */
2601: int sqlite3_collation_needed(
2602: sqlite3*,
2603: void*,
2604: void(*)(void*,sqlite3*,int eTextRep,const char*)
2605: );
2606: int sqlite3_collation_needed16(
2607: sqlite3*,
2608: void*,
2609: void(*)(void*,sqlite3*,int eTextRep,const void*)
2610: );
2611:
2612: /*
2613: ** Specify the key for an encrypted database. This routine should be
2614: ** called right after sqlite3_open().
2615: **
2616: ** The code to implement this API is not available in the public release
2617: ** of SQLite.
2618: */
2619: int sqlite3_key(
2620: sqlite3 *db, /* Database to be rekeyed */
2621: const void *pKey, int nKey /* The key */
2622: );
2623:
2624: /*
2625: ** Change the key on an open database. If the current database is not
2626: ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the
2627: ** database is decrypted.
2628: **
2629: ** The code to implement this API is not available in the public release
2630: ** of SQLite.
2631: */
2632: int sqlite3_rekey(
2633: sqlite3 *db, /* Database to be rekeyed */
2634: const void *pKey, int nKey /* The new key */
2635: );
2636:
2637: /*
1.2 ! misha 2638: ** CAPI3REF: Suspend Execution For A Short Time
! 2639: **
! 2640: ** This function causes the current thread to suspend execution
! 2641: ** a number of milliseconds specified in its parameter.
! 2642: **
! 2643: ** If the operating system does not support sleep requests with
! 2644: ** millisecond time resolution, then the time will be rounded up to
! 2645: ** the nearest second. The number of milliseconds of sleep actually
! 2646: ** requested from the operating system is returned.
! 2647: **
! 2648: ** SQLite implements this interface by calling the xSleep()
! 2649: ** method of the default [sqlite3_vfs] object.
! 2650: */
! 2651: int sqlite3_sleep(int);
! 2652:
! 2653: /*
! 2654: ** CAPI3REF: Name Of The Folder Holding Temporary Files
! 2655: **
! 2656: ** If this global variable is made to point to a string which is
! 2657: ** the name of a folder (a.ka. directory), then all temporary files
1.1 misha 2658: ** created by SQLite will be placed in that directory. If this variable
2659: ** is NULL pointer, then SQLite does a search for an appropriate temporary
2660: ** file directory.
2661: **
1.2 ! misha 2662: ** It is not safe to modify this variable once a database connection
! 2663: ** has been opened. It is intended that this variable be set once
! 2664: ** as part of process initialization and before any SQLite interface
! 2665: ** routines have been call and remain unchanged thereafter.
! 2666: */
! 2667: SQLITE_EXTERN char *sqlite3_temp_directory;
! 2668:
! 2669: /*
! 2670: ** CAPI3REF: Test To See If The Database Is In Auto-Commit Mode
! 2671: **
! 2672: ** Test to see whether or not the database connection is in autocommit
! 2673: ** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on
! 2674: ** by default. Autocommit is disabled by a BEGIN statement and reenabled
! 2675: ** by the next COMMIT or ROLLBACK.
! 2676: **
! 2677: ** If certain kinds of errors occur on a statement within a multi-statement
! 2678: ** transactions (errors including [SQLITE_FULL], [SQLITE_IOERR],
! 2679: ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
! 2680: ** transaction might be rolled back automatically. The only way to
! 2681: ** find out if SQLite automatically rolled back the transaction after
! 2682: ** an error is to use this function.
! 2683: **
! 2684: ** If another thread changes the autocommit status of the database
! 2685: ** connection while this routine is running, then the return value
! 2686: ** is undefined.
! 2687: */
! 2688: int sqlite3_get_autocommit(sqlite3*);
! 2689:
! 2690: /*
! 2691: ** CAPI3REF: Find The Database Handle Associated With A Prepared Statement
! 2692: **
! 2693: ** Return the [sqlite3*] database handle to which a
! 2694: ** [sqlite3_stmt | prepared statement] belongs.
! 2695: ** This is the same database handle that was
! 2696: ** the first argument to the [sqlite3_prepare_v2()] or its variants
! 2697: ** that was used to create the statement in the first place.
! 2698: */
! 2699: sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
! 2700:
! 2701:
! 2702: /*
! 2703: ** CAPI3REF: Commit And Rollback Notification Callbacks
! 2704: **
! 2705: ** These routines
! 2706: ** register callback functions to be invoked whenever a transaction
! 2707: ** is committed or rolled back. The pArg argument is passed through
! 2708: ** to the callback. If the callback on a commit hook function
! 2709: ** returns non-zero, then the commit is converted into a rollback.
! 2710: **
! 2711: ** If another function was previously registered, its pArg value is returned.
! 2712: ** Otherwise NULL is returned.
! 2713: **
! 2714: ** Registering a NULL function disables the callback.
! 2715: **
! 2716: ** For the purposes of this API, a transaction is said to have been
! 2717: ** rolled back if an explicit "ROLLBACK" statement is executed, or
! 2718: ** an error or constraint causes an implicit rollback to occur. The
! 2719: ** callback is not invoked if a transaction is automatically rolled
! 2720: ** back because the database connection is closed.
! 2721: **
! 2722: ** These are experimental interfaces and are subject to change.
! 2723: */
! 2724: void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
! 2725: void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
! 2726:
! 2727: /*
! 2728: ** CAPI3REF: Data Change Notification Callbacks
! 2729: **
! 2730: ** Register a callback function with the database connection identified by the
! 2731: ** first argument to be invoked whenever a row is updated, inserted or deleted.
! 2732: ** Any callback set by a previous call to this function for the same
! 2733: ** database connection is overridden.
! 2734: **
! 2735: ** The second argument is a pointer to the function to invoke when a
! 2736: ** row is updated, inserted or deleted. The first argument to the callback is
! 2737: ** a copy of the third argument to sqlite3_update_hook(). The second callback
! 2738: ** argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending
! 2739: ** on the operation that caused the callback to be invoked. The third and
! 2740: ** fourth arguments to the callback contain pointers to the database and
! 2741: ** table name containing the affected row. The final callback parameter is
! 2742: ** the rowid of the row. In the case of an update, this is the rowid after
! 2743: ** the update takes place.
! 2744: **
! 2745: ** The update hook is not invoked when internal system tables are
! 2746: ** modified (i.e. sqlite_master and sqlite_sequence).
! 2747: **
! 2748: ** If another function was previously registered, its pArg value is returned.
! 2749: ** Otherwise NULL is returned.
! 2750: */
! 2751: void *sqlite3_update_hook(
! 2752: sqlite3*,
! 2753: void(*)(void *,int ,char const *,char const *,sqlite3_int64),
! 2754: void*
! 2755: );
! 2756:
! 2757: /*
! 2758: ** CAPI3REF: Enable Or Disable Shared Pager Cache
! 2759: **
! 2760: ** This routine enables or disables the sharing of the database cache
! 2761: ** and schema data structures between connections to the same database.
! 2762: ** Sharing is enabled if the argument is true and disabled if the argument
! 2763: ** is false.
! 2764: **
! 2765: ** Beginning in SQLite version 3.5.0, cache sharing is enabled and disabled
! 2766: ** for an entire process. In prior versions of SQLite, sharing was
! 2767: ** enabled or disabled for each thread separately.
! 2768: **
! 2769: ** The cache sharing mode set by this interface effects all subsequent
! 2770: ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
! 2771: ** Existing database connections continue use the sharing mode that was
! 2772: ** in effect at the time they were opened.
! 2773: **
! 2774: ** Virtual tables cannot be used with a shared cache. When shared
! 2775: ** cache is enabled, the [sqlite3_create_module()] API used to register
! 2776: ** virtual tables will always return an error.
! 2777: **
! 2778: ** This routine returns [SQLITE_OK] if shared cache was
! 2779: ** enabled or disabled successfully. An [SQLITE_ERROR | error code]
! 2780: ** is returned otherwise.
! 2781: **
! 2782: ** Shared cache is disabled by default. But this might change in
! 2783: ** future releases of SQLite. Applications that care about shared
! 2784: ** cache setting should set it explicitly.
! 2785: */
! 2786: int sqlite3_enable_shared_cache(int);
! 2787:
! 2788: /*
! 2789: ** CAPI3REF: Attempt To Free Heap Memory
! 2790: **
! 2791: ** Attempt to free N bytes of heap memory by deallocating non-essential
! 2792: ** memory allocations held by the database library (example: memory
! 2793: ** used to cache database pages to improve performance).
! 2794: */
! 2795: int sqlite3_release_memory(int);
! 2796:
! 2797: /*
! 2798: ** CAPI3REF: Impose A Limit On Heap Size
! 2799: **
! 2800: ** Place a "soft" limit on the amount of heap memory that may be allocated
! 2801: ** by SQLite. If an internal allocation is requested
! 2802: ** that would exceed the specified limit, [sqlite3_release_memory()] is
! 2803: ** invoked one or more times to free up some space before the allocation
! 2804: ** is made.
! 2805: **
! 2806: ** The limit is called "soft", because if [sqlite3_release_memory()] cannot
! 2807: ** free sufficient memory to prevent the limit from being exceeded,
! 2808: ** the memory is allocated anyway and the current operation proceeds.
! 2809: **
! 2810: ** A negative or zero value for N means that there is no soft heap limit and
! 2811: ** [sqlite3_release_memory()] will only be called when memory is exhausted.
! 2812: ** The default value for the soft heap limit is zero.
! 2813: **
! 2814: ** SQLite makes a best effort to honor the soft heap limit. But if it
! 2815: ** is unable to reduce memory usage below the soft limit, execution will
! 2816: ** continue without error or notification. This is why the limit is
! 2817: ** called a "soft" limit. It is advisory only.
! 2818: **
! 2819: ** The soft heap limit is implemented using the [sqlite3_memory_alarm()]
! 2820: ** interface. Only a single memory alarm is available in the default
! 2821: ** implementation. This means that if the application also uses the
! 2822: ** memory alarm interface it will interfere with the operation of the
! 2823: ** soft heap limit and undefined behavior will result.
! 2824: **
! 2825: ** Prior to SQLite version 3.5.0, this routine only constrained the memory
! 2826: ** allocated by a single thread - the same thread in which this routine
! 2827: ** runs. Beginning with SQLite version 3.5.0, the soft heap limit is
! 2828: ** applied to all threads. The value specified for the soft heap limit
! 2829: ** is an upper bound on the total memory allocation for all threads. In
! 2830: ** version 3.5.0 there is no mechanism for limiting the heap usage for
! 2831: ** individual threads.
! 2832: */
! 2833: void sqlite3_soft_heap_limit(int);
! 2834:
! 2835: /*
! 2836: ** CAPI3REF: Extract Metadata About A Column Of A Table
! 2837: **
! 2838: ** This routine
! 2839: ** returns meta-data about a specific column of a specific database
! 2840: ** table accessible using the connection handle passed as the first function
! 2841: ** argument.
! 2842: **
! 2843: ** The column is identified by the second, third and fourth parameters to
! 2844: ** this function. The second parameter is either the name of the database
! 2845: ** (i.e. "main", "temp" or an attached database) containing the specified
! 2846: ** table or NULL. If it is NULL, then all attached databases are searched
! 2847: ** for the table using the same algorithm as the database engine uses to
! 2848: ** resolve unqualified table references.
! 2849: **
! 2850: ** The third and fourth parameters to this function are the table and column
! 2851: ** name of the desired column, respectively. Neither of these parameters
! 2852: ** may be NULL.
! 2853: **
! 2854: ** Meta information is returned by writing to the memory locations passed as
! 2855: ** the 5th and subsequent parameters to this function. Any of these
! 2856: ** arguments may be NULL, in which case the corresponding element of meta
! 2857: ** information is ommitted.
! 2858: **
! 2859: ** <pre>
! 2860: ** Parameter Output Type Description
! 2861: ** -----------------------------------
! 2862: **
! 2863: ** 5th const char* Data type
! 2864: ** 6th const char* Name of the default collation sequence
! 2865: ** 7th int True if the column has a NOT NULL constraint
! 2866: ** 8th int True if the column is part of the PRIMARY KEY
! 2867: ** 9th int True if the column is AUTOINCREMENT
! 2868: ** </pre>
! 2869: **
! 2870: **
! 2871: ** The memory pointed to by the character pointers returned for the
! 2872: ** declaration type and collation sequence is valid only until the next
! 2873: ** call to any sqlite API function.
! 2874: **
! 2875: ** If the specified table is actually a view, then an error is returned.
! 2876: **
! 2877: ** If the specified column is "rowid", "oid" or "_rowid_" and an
! 2878: ** INTEGER PRIMARY KEY column has been explicitly declared, then the output
! 2879: ** parameters are set for the explicitly declared column. If there is no
! 2880: ** explicitly declared IPK column, then the output parameters are set as
! 2881: ** follows:
! 2882: **
! 2883: ** <pre>
! 2884: ** data type: "INTEGER"
! 2885: ** collation sequence: "BINARY"
! 2886: ** not null: 0
! 2887: ** primary key: 1
! 2888: ** auto increment: 0
! 2889: ** </pre>
! 2890: **
! 2891: ** This function may load one or more schemas from database files. If an
! 2892: ** error occurs during this process, or if the requested table or column
! 2893: ** cannot be found, an SQLITE error code is returned and an error message
! 2894: ** left in the database handle (to be retrieved using sqlite3_errmsg()).
! 2895: **
! 2896: ** This API is only available if the library was compiled with the
! 2897: ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
! 2898: */
! 2899: int sqlite3_table_column_metadata(
! 2900: sqlite3 *db, /* Connection handle */
! 2901: const char *zDbName, /* Database name or NULL */
! 2902: const char *zTableName, /* Table name */
! 2903: const char *zColumnName, /* Column name */
! 2904: char const **pzDataType, /* OUTPUT: Declared data type */
! 2905: char const **pzCollSeq, /* OUTPUT: Collation sequence name */
! 2906: int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */
! 2907: int *pPrimaryKey, /* OUTPUT: True if column part of PK */
! 2908: int *pAutoinc /* OUTPUT: True if column is auto-increment */
! 2909: );
! 2910:
! 2911: /*
! 2912: ** CAPI3REF: Load An Extension
! 2913: **
! 2914: ** Attempt to load an SQLite extension library contained in the file
! 2915: ** zFile. The entry point is zProc. zProc may be 0 in which case the
! 2916: ** name of the entry point defaults to "sqlite3_extension_init".
! 2917: **
! 2918: ** Return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
! 2919: **
! 2920: ** If an error occurs and pzErrMsg is not 0, then fill *pzErrMsg with
! 2921: ** error message text. The calling function should free this memory
! 2922: ** by calling [sqlite3_free()].
! 2923: **
! 2924: ** Extension loading must be enabled using [sqlite3_enable_load_extension()]
! 2925: ** prior to calling this API or an error will be returned.
! 2926: */
! 2927: int sqlite3_load_extension(
! 2928: sqlite3 *db, /* Load the extension into this database connection */
! 2929: const char *zFile, /* Name of the shared library containing extension */
! 2930: const char *zProc, /* Entry point. Derived from zFile if 0 */
! 2931: char **pzErrMsg /* Put error message here if not 0 */
! 2932: );
! 2933:
! 2934: /*
! 2935: ** CAPI3REF: Enable Or Disable Extension Loading
! 2936: **
! 2937: ** So as not to open security holes in older applications that are
! 2938: ** unprepared to deal with extension loading, and as a means of disabling
! 2939: ** extension loading while evaluating user-entered SQL, the following
! 2940: ** API is provided to turn the [sqlite3_load_extension()] mechanism on and
! 2941: ** off. It is off by default. See ticket #1863.
! 2942: **
! 2943: ** Call this routine with onoff==1 to turn extension loading on
! 2944: ** and call it with onoff==0 to turn it back off again.
! 2945: */
! 2946: int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
! 2947:
! 2948: /*
! 2949: ** CAPI3REF: Make Arrangements To Automatically Load An Extension
! 2950: **
! 2951: ** Register an extension entry point that is automatically invoked
! 2952: ** whenever a new database connection is opened using
! 2953: ** [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()].
! 2954: **
! 2955: ** This API can be invoked at program startup in order to register
! 2956: ** one or more statically linked extensions that will be available
! 2957: ** to all new database connections.
! 2958: **
! 2959: ** Duplicate extensions are detected so calling this routine multiple
! 2960: ** times with the same extension is harmless.
! 2961: **
! 2962: ** This routine stores a pointer to the extension in an array
! 2963: ** that is obtained from malloc(). If you run a memory leak
! 2964: ** checker on your program and it reports a leak because of this
! 2965: ** array, then invoke [sqlite3_automatic_extension_reset()] prior
! 2966: ** to shutdown to free the memory.
! 2967: **
! 2968: ** Automatic extensions apply across all threads.
! 2969: **
! 2970: ** This interface is experimental and is subject to change or
! 2971: ** removal in future releases of SQLite.
! 2972: */
! 2973: int sqlite3_auto_extension(void *xEntryPoint);
! 2974:
! 2975:
! 2976: /*
! 2977: ** CAPI3REF: Reset Automatic Extension Loading
! 2978: **
! 2979: ** Disable all previously registered automatic extensions. This
! 2980: ** routine undoes the effect of all prior [sqlite3_automatic_extension()]
! 2981: ** calls.
! 2982: **
! 2983: ** This call disabled automatic extensions in all threads.
! 2984: **
! 2985: ** This interface is experimental and is subject to change or
! 2986: ** removal in future releases of SQLite.
! 2987: */
! 2988: void sqlite3_reset_auto_extension(void);
! 2989:
! 2990:
! 2991: /*
! 2992: ****** EXPERIMENTAL - subject to change without notice **************
! 2993: **
! 2994: ** The interface to the virtual-table mechanism is currently considered
! 2995: ** to be experimental. The interface might change in incompatible ways.
! 2996: ** If this is a problem for you, do not use the interface at this time.
! 2997: **
! 2998: ** When the virtual-table mechanism stablizes, we will declare the
! 2999: ** interface fixed, support it indefinitely, and remove this comment.
! 3000: */
! 3001:
! 3002: /*
! 3003: ** Structures used by the virtual table interface
! 3004: */
! 3005: typedef struct sqlite3_vtab sqlite3_vtab;
! 3006: typedef struct sqlite3_index_info sqlite3_index_info;
! 3007: typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
! 3008: typedef struct sqlite3_module sqlite3_module;
! 3009:
! 3010: /*
! 3011: ** A module is a class of virtual tables. Each module is defined
! 3012: ** by an instance of the following structure. This structure consists
! 3013: ** mostly of methods for the module.
! 3014: */
! 3015: struct sqlite3_module {
! 3016: int iVersion;
! 3017: int (*xCreate)(sqlite3*, void *pAux,
! 3018: int argc, const char *const*argv,
! 3019: sqlite3_vtab **ppVTab, char**);
! 3020: int (*xConnect)(sqlite3*, void *pAux,
! 3021: int argc, const char *const*argv,
! 3022: sqlite3_vtab **ppVTab, char**);
! 3023: int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
! 3024: int (*xDisconnect)(sqlite3_vtab *pVTab);
! 3025: int (*xDestroy)(sqlite3_vtab *pVTab);
! 3026: int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
! 3027: int (*xClose)(sqlite3_vtab_cursor*);
! 3028: int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
! 3029: int argc, sqlite3_value **argv);
! 3030: int (*xNext)(sqlite3_vtab_cursor*);
! 3031: int (*xEof)(sqlite3_vtab_cursor*);
! 3032: int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
! 3033: int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
! 3034: int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
! 3035: int (*xBegin)(sqlite3_vtab *pVTab);
! 3036: int (*xSync)(sqlite3_vtab *pVTab);
! 3037: int (*xCommit)(sqlite3_vtab *pVTab);
! 3038: int (*xRollback)(sqlite3_vtab *pVTab);
! 3039: int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
! 3040: void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
! 3041: void **ppArg);
! 3042:
! 3043: int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
! 3044: };
! 3045:
! 3046: /*
! 3047: ** The sqlite3_index_info structure and its substructures is used to
! 3048: ** pass information into and receive the reply from the xBestIndex
! 3049: ** method of an sqlite3_module. The fields under **Inputs** are the
! 3050: ** inputs to xBestIndex and are read-only. xBestIndex inserts its
! 3051: ** results into the **Outputs** fields.
! 3052: **
! 3053: ** The aConstraint[] array records WHERE clause constraints of the
! 3054: ** form:
! 3055: **
! 3056: ** column OP expr
! 3057: **
! 3058: ** Where OP is =, <, <=, >, or >=. The particular operator is stored
! 3059: ** in aConstraint[].op. The index of the column is stored in
! 3060: ** aConstraint[].iColumn. aConstraint[].usable is TRUE if the
! 3061: ** expr on the right-hand side can be evaluated (and thus the constraint
! 3062: ** is usable) and false if it cannot.
! 3063: **
! 3064: ** The optimizer automatically inverts terms of the form "expr OP column"
! 3065: ** and makes other simplifications to the WHERE clause in an attempt to
! 3066: ** get as many WHERE clause terms into the form shown above as possible.
! 3067: ** The aConstraint[] array only reports WHERE clause terms in the correct
! 3068: ** form that refer to the particular virtual table being queried.
! 3069: **
! 3070: ** Information about the ORDER BY clause is stored in aOrderBy[].
! 3071: ** Each term of aOrderBy records a column of the ORDER BY clause.
! 3072: **
! 3073: ** The xBestIndex method must fill aConstraintUsage[] with information
! 3074: ** about what parameters to pass to xFilter. If argvIndex>0 then
! 3075: ** the right-hand side of the corresponding aConstraint[] is evaluated
! 3076: ** and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit
! 3077: ** is true, then the constraint is assumed to be fully handled by the
! 3078: ** virtual table and is not checked again by SQLite.
! 3079: **
! 3080: ** The idxNum and idxPtr values are recorded and passed into xFilter.
! 3081: ** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true.
! 3082: **
! 3083: ** The orderByConsumed means that output from xFilter will occur in
! 3084: ** the correct order to satisfy the ORDER BY clause so that no separate
! 3085: ** sorting step is required.
! 3086: **
! 3087: ** The estimatedCost value is an estimate of the cost of doing the
! 3088: ** particular lookup. A full scan of a table with N entries should have
! 3089: ** a cost of N. A binary search of a table of N entries should have a
! 3090: ** cost of approximately log(N).
! 3091: */
! 3092: struct sqlite3_index_info {
! 3093: /* Inputs */
! 3094: int nConstraint; /* Number of entries in aConstraint */
! 3095: struct sqlite3_index_constraint {
! 3096: int iColumn; /* Column on left-hand side of constraint */
! 3097: unsigned char op; /* Constraint operator */
! 3098: unsigned char usable; /* True if this constraint is usable */
! 3099: int iTermOffset; /* Used internally - xBestIndex should ignore */
! 3100: } *aConstraint; /* Table of WHERE clause constraints */
! 3101: int nOrderBy; /* Number of terms in the ORDER BY clause */
! 3102: struct sqlite3_index_orderby {
! 3103: int iColumn; /* Column number */
! 3104: unsigned char desc; /* True for DESC. False for ASC. */
! 3105: } *aOrderBy; /* The ORDER BY clause */
! 3106:
! 3107: /* Outputs */
! 3108: struct sqlite3_index_constraint_usage {
! 3109: int argvIndex; /* if >0, constraint is part of argv to xFilter */
! 3110: unsigned char omit; /* Do not code a test for this constraint */
! 3111: } *aConstraintUsage;
! 3112: int idxNum; /* Number used to identify the index */
! 3113: char *idxStr; /* String, possibly obtained from sqlite3_malloc */
! 3114: int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
! 3115: int orderByConsumed; /* True if output is already ordered */
! 3116: double estimatedCost; /* Estimated cost of using this index */
! 3117: };
! 3118: #define SQLITE_INDEX_CONSTRAINT_EQ 2
! 3119: #define SQLITE_INDEX_CONSTRAINT_GT 4
! 3120: #define SQLITE_INDEX_CONSTRAINT_LE 8
! 3121: #define SQLITE_INDEX_CONSTRAINT_LT 16
! 3122: #define SQLITE_INDEX_CONSTRAINT_GE 32
! 3123: #define SQLITE_INDEX_CONSTRAINT_MATCH 64
! 3124:
! 3125: /*
! 3126: ** This routine is used to register a new module name with an SQLite
! 3127: ** connection. Module names must be registered before creating new
! 3128: ** virtual tables on the module, or before using preexisting virtual
! 3129: ** tables of the module.
! 3130: */
! 3131: int sqlite3_create_module(
! 3132: sqlite3 *db, /* SQLite connection to register module with */
! 3133: const char *zName, /* Name of the module */
! 3134: const sqlite3_module *, /* Methods for the module */
! 3135: void * /* Client data for xCreate/xConnect */
! 3136: );
! 3137:
! 3138: /*
! 3139: ** This routine is identical to the sqlite3_create_module() method above,
! 3140: ** except that it allows a destructor function to be specified. It is
! 3141: ** even more experimental than the rest of the virtual tables API.
! 3142: */
! 3143: int sqlite3_create_module_v2(
! 3144: sqlite3 *db, /* SQLite connection to register module with */
! 3145: const char *zName, /* Name of the module */
! 3146: const sqlite3_module *, /* Methods for the module */
! 3147: void *, /* Client data for xCreate/xConnect */
! 3148: void(*xDestroy)(void*) /* Module destructor function */
! 3149: );
! 3150:
! 3151: /*
! 3152: ** Every module implementation uses a subclass of the following structure
! 3153: ** to describe a particular instance of the module. Each subclass will
! 3154: ** be tailored to the specific needs of the module implementation. The
! 3155: ** purpose of this superclass is to define certain fields that are common
! 3156: ** to all module implementations.
! 3157: **
! 3158: ** Virtual tables methods can set an error message by assigning a
! 3159: ** string obtained from sqlite3_mprintf() to zErrMsg. The method should
! 3160: ** take care that any prior string is freed by a call to sqlite3_free()
! 3161: ** prior to assigning a new string to zErrMsg. After the error message
! 3162: ** is delivered up to the client application, the string will be automatically
! 3163: ** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note
! 3164: ** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field
! 3165: ** since virtual tables are commonly implemented in loadable extensions which
! 3166: ** do not have access to sqlite3MPrintf() or sqlite3Free().
! 3167: */
! 3168: struct sqlite3_vtab {
! 3169: const sqlite3_module *pModule; /* The module for this virtual table */
! 3170: int nRef; /* Used internally */
! 3171: char *zErrMsg; /* Error message from sqlite3_mprintf() */
! 3172: /* Virtual table implementations will typically add additional fields */
! 3173: };
! 3174:
! 3175: /* Every module implementation uses a subclass of the following structure
! 3176: ** to describe cursors that point into the virtual table and are used
! 3177: ** to loop through the virtual table. Cursors are created using the
! 3178: ** xOpen method of the module. Each module implementation will define
! 3179: ** the content of a cursor structure to suit its own needs.
! 3180: **
! 3181: ** This superclass exists in order to define fields of the cursor that
! 3182: ** are common to all implementations.
! 3183: */
! 3184: struct sqlite3_vtab_cursor {
! 3185: sqlite3_vtab *pVtab; /* Virtual table of this cursor */
! 3186: /* Virtual table implementations will typically add additional fields */
! 3187: };
! 3188:
! 3189: /*
! 3190: ** The xCreate and xConnect methods of a module use the following API
! 3191: ** to declare the format (the names and datatypes of the columns) of
! 3192: ** the virtual tables they implement.
! 3193: */
! 3194: int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable);
! 3195:
! 3196: /*
! 3197: ** Virtual tables can provide alternative implementations of functions
! 3198: ** using the xFindFunction method. But global versions of those functions
! 3199: ** must exist in order to be overloaded.
! 3200: **
! 3201: ** This API makes sure a global version of a function with a particular
! 3202: ** name and number of parameters exists. If no such function exists
! 3203: ** before this API is called, a new function is created. The implementation
! 3204: ** of the new function always causes an exception to be thrown. So
! 3205: ** the new function is not good for anything by itself. Its only
! 3206: ** purpose is to be a place-holder function that can be overloaded
! 3207: ** by virtual tables.
! 3208: **
! 3209: ** This API should be considered part of the virtual table interface,
! 3210: ** which is experimental and subject to change.
! 3211: */
! 3212: int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
! 3213:
! 3214: /*
! 3215: ** The interface to the virtual-table mechanism defined above (back up
! 3216: ** to a comment remarkably similar to this one) is currently considered
! 3217: ** to be experimental. The interface might change in incompatible ways.
! 3218: ** If this is a problem for you, do not use the interface at this time.
! 3219: **
! 3220: ** When the virtual-table mechanism stabilizes, we will declare the
! 3221: ** interface fixed, support it indefinitely, and remove this comment.
! 3222: **
! 3223: ****** EXPERIMENTAL - subject to change without notice **************
! 3224: */
! 3225:
! 3226: /*
! 3227: ** CAPI3REF: A Handle To An Open BLOB
! 3228: **
! 3229: ** An instance of the following opaque structure is used to
! 3230: ** represent an blob-handle. A blob-handle is created by
! 3231: ** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()].
! 3232: ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
! 3233: ** can be used to read or write small subsections of the blob.
! 3234: ** The [sqlite3_blob_bytes()] interface returns the size of the
! 3235: ** blob in bytes.
! 3236: */
! 3237: typedef struct sqlite3_blob sqlite3_blob;
! 3238:
! 3239: /*
! 3240: ** CAPI3REF: Open A BLOB For Incremental I/O
! 3241: **
! 3242: ** Open a handle to the blob located in row iRow,, column zColumn,
! 3243: ** table zTable in database zDb. i.e. the same blob that would
! 3244: ** be selected by:
! 3245: **
! 3246: ** <pre>
! 3247: ** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;
! 3248: ** </pre>
! 3249: **
! 3250: ** If the flags parameter is non-zero, the blob is opened for
! 3251: ** read and write access. If it is zero, the blob is opened for read
! 3252: ** access.
! 3253: **
! 3254: ** On success, [SQLITE_OK] is returned and the new
! 3255: ** [sqlite3_blob | blob handle] is written to *ppBlob.
! 3256: ** Otherwise an error code is returned and
! 3257: ** any value written to *ppBlob should not be used by the caller.
! 3258: ** This function sets the database-handle error code and message
! 3259: ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()].
! 3260: */
! 3261: int sqlite3_blob_open(
! 3262: sqlite3*,
! 3263: const char *zDb,
! 3264: const char *zTable,
! 3265: const char *zColumn,
! 3266: sqlite3_int64 iRow,
! 3267: int flags,
! 3268: sqlite3_blob **ppBlob
! 3269: );
! 3270:
! 3271: /*
! 3272: ** CAPI3REF: Close A BLOB Handle
! 3273: **
! 3274: ** Close an open [sqlite3_blob | blob handle].
! 3275: */
! 3276: int sqlite3_blob_close(sqlite3_blob *);
! 3277:
! 3278: /*
! 3279: ** CAPI3REF: Return The Size Of An Open BLOB
! 3280: **
! 3281: ** Return the size in bytes of the blob accessible via the open
! 3282: ** [sqlite3_blob | blob-handle] passed as an argument.
! 3283: */
! 3284: int sqlite3_blob_bytes(sqlite3_blob *);
! 3285:
! 3286: /*
! 3287: ** CAPI3REF: Read Data From A BLOB Incrementally
! 3288: **
! 3289: ** This function is used to read data from an open
! 3290: ** [sqlite3_blob | blob-handle] into a caller supplied buffer.
! 3291: ** n bytes of data are copied into buffer
! 3292: ** z from the open blob, starting at offset iOffset.
! 3293: **
! 3294: ** On success, SQLITE_OK is returned. Otherwise, an
! 3295: ** [SQLITE_ERROR | SQLite error code] or an
! 3296: ** [SQLITE_IOERR_READ | extended error code] is returned.
1.1 misha 3297: */
1.2 ! misha 3298: int sqlite3_blob_read(sqlite3_blob *, void *z, int n, int iOffset);
! 3299:
! 3300: /*
! 3301: ** CAPI3REF: Write Data Into A BLOB Incrementally
! 3302: **
! 3303: ** This function is used to write data into an open
! 3304: ** [sqlite3_blob | blob-handle] from a user supplied buffer.
! 3305: ** n bytes of data are copied from the buffer
! 3306: ** pointed to by z into the open blob, starting at offset iOffset.
! 3307: **
! 3308: ** If the [sqlite3_blob | blob-handle] passed as the first argument
! 3309: ** was not opened for writing (the flags parameter to [sqlite3_blob_open()]
! 3310: *** was zero), this function returns [SQLITE_READONLY].
! 3311: **
! 3312: ** This function may only modify the contents of the blob, it is
! 3313: ** not possible to increase the size of a blob using this API. If
! 3314: ** offset iOffset is less than n bytes from the end of the blob,
! 3315: ** [SQLITE_ERROR] is returned and no data is written.
! 3316: **
! 3317: ** On success, SQLITE_OK is returned. Otherwise, an
! 3318: ** [SQLITE_ERROR | SQLite error code] or an
! 3319: ** [SQLITE_IOERR_READ | extended error code] is returned.
! 3320: */
! 3321: int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
! 3322:
! 3323: /*
! 3324: ** CAPI3REF: Virtual File System Objects
! 3325: **
! 3326: ** A virtual filesystem (VFS) is an [sqlite3_vfs] object
! 3327: ** that SQLite uses to interact
! 3328: ** with the underlying operating system. Most builds come with a
! 3329: ** single default VFS that is appropriate for the host computer.
! 3330: ** New VFSes can be registered and existing VFSes can be unregistered.
! 3331: ** The following interfaces are provided.
! 3332: **
! 3333: ** The sqlite3_vfs_find() interface returns a pointer to a VFS given its
! 3334: ** name. Names are case sensitive. If there is no match, a NULL
! 3335: ** pointer is returned. If zVfsName is NULL then the default
! 3336: ** VFS is returned.
! 3337: **
! 3338: ** New VFSes are registered with sqlite3_vfs_register(). Each
! 3339: ** new VFS becomes the default VFS if the makeDflt flag is set.
! 3340: ** The same VFS can be registered multiple times without injury.
! 3341: ** To make an existing VFS into the default VFS, register it again
! 3342: ** with the makeDflt flag set. If two different VFSes with the
! 3343: ** same name are registered, the behavior is undefined. If a
! 3344: ** VFS is registered with a name that is NULL or an empty string,
! 3345: ** then the behavior is undefined.
! 3346: **
! 3347: ** Unregister a VFS with the sqlite3_vfs_unregister() interface.
! 3348: ** If the default VFS is unregistered, another VFS is chosen as
! 3349: ** the default. The choice for the new VFS is arbitrary.
! 3350: */
! 3351: sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
! 3352: int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
! 3353: int sqlite3_vfs_unregister(sqlite3_vfs*);
! 3354:
! 3355: /*
! 3356: ** CAPI3REF: Mutexes
! 3357: **
! 3358: ** The SQLite core uses these routines for thread
! 3359: ** synchronization. Though they are intended for internal
! 3360: ** use by SQLite, code that links against SQLite is
! 3361: ** permitted to use any of these routines.
! 3362: **
! 3363: ** The SQLite source code contains multiple implementations
! 3364: ** of these mutex routines. An appropriate implementation
! 3365: ** is selected automatically at compile-time. The following
! 3366: ** implementations are available in the SQLite core:
! 3367: **
! 3368: ** <ul>
! 3369: ** <li> SQLITE_MUTEX_OS2
! 3370: ** <li> SQLITE_MUTEX_PTHREAD
! 3371: ** <li> SQLITE_MUTEX_W32
! 3372: ** <li> SQLITE_MUTEX_NOOP
! 3373: ** </ul>
! 3374: **
! 3375: ** The SQLITE_MUTEX_NOOP implementation is a set of routines
! 3376: ** that does no real locking and is appropriate for use in
! 3377: ** a single-threaded application. The SQLITE_MUTEX_OS2,
! 3378: ** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations
! 3379: ** are appropriate for use on os/2, unix, and windows.
! 3380: **
! 3381: ** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
! 3382: ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
! 3383: ** implementation is included with the library. The
! 3384: ** mutex interface routines defined here become external
! 3385: ** references in the SQLite library for which implementations
! 3386: ** must be provided by the application. This facility allows an
! 3387: ** application that links against SQLite to provide its own mutex
! 3388: ** implementation without having to modify the SQLite core.
! 3389: **
! 3390: ** The sqlite3_mutex_alloc() routine allocates a new
! 3391: ** mutex and returns a pointer to it. If it returns NULL
! 3392: ** that means that a mutex could not be allocated. SQLite
! 3393: ** will unwind its stack and return an error. The argument
! 3394: ** to sqlite3_mutex_alloc() is one of these integer constants:
! 3395: **
! 3396: ** <ul>
! 3397: ** <li> SQLITE_MUTEX_FAST
! 3398: ** <li> SQLITE_MUTEX_RECURSIVE
! 3399: ** <li> SQLITE_MUTEX_STATIC_MASTER
! 3400: ** <li> SQLITE_MUTEX_STATIC_MEM
! 3401: ** <li> SQLITE_MUTEX_STATIC_MEM2
! 3402: ** <li> SQLITE_MUTEX_STATIC_PRNG
! 3403: ** <li> SQLITE_MUTEX_STATIC_LRU
! 3404: ** </ul>
! 3405: **
! 3406: ** The first two constants cause sqlite3_mutex_alloc() to create
! 3407: ** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
! 3408: ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
! 3409: ** The mutex implementation does not need to make a distinction
! 3410: ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
! 3411: ** not want to. But SQLite will only request a recursive mutex in
! 3412: ** cases where it really needs one. If a faster non-recursive mutex
! 3413: ** implementation is available on the host platform, the mutex subsystem
! 3414: ** might return such a mutex in response to SQLITE_MUTEX_FAST.
! 3415: **
! 3416: ** The other allowed parameters to sqlite3_mutex_alloc() each return
! 3417: ** a pointer to a static preexisting mutex. Four static mutexes are
! 3418: ** used by the current version of SQLite. Future versions of SQLite
! 3419: ** may add additional static mutexes. Static mutexes are for internal
! 3420: ** use by SQLite only. Applications that use SQLite mutexes should
! 3421: ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
! 3422: ** SQLITE_MUTEX_RECURSIVE.
! 3423: **
! 3424: ** Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
! 3425: ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
! 3426: ** returns a different mutex on every call. But for the static
! 3427: ** mutex types, the same mutex is returned on every call that has
! 3428: ** the same type number.
! 3429: **
! 3430: ** The sqlite3_mutex_free() routine deallocates a previously
! 3431: ** allocated dynamic mutex. SQLite is careful to deallocate every
! 3432: ** dynamic mutex that it allocates. The dynamic mutexes must not be in
! 3433: ** use when they are deallocated. Attempting to deallocate a static
! 3434: ** mutex results in undefined behavior. SQLite never deallocates
! 3435: ** a static mutex.
! 3436: **
! 3437: ** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
! 3438: ** to enter a mutex. If another thread is already within the mutex,
! 3439: ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
! 3440: ** SQLITE_BUSY. The sqlite3_mutex_try() interface returns SQLITE_OK
! 3441: ** upon successful entry. Mutexes created using SQLITE_MUTEX_RECURSIVE can
! 3442: ** be entered multiple times by the same thread. In such cases the,
! 3443: ** mutex must be exited an equal number of times before another thread
! 3444: ** can enter. If the same thread tries to enter any other kind of mutex
! 3445: ** more than once, the behavior is undefined. SQLite will never exhibit
! 3446: ** such behavior in its own use of mutexes.
! 3447: **
! 3448: ** Some systems (ex: windows95) do not the operation implemented by
! 3449: ** sqlite3_mutex_try(). On those systems, sqlite3_mutex_try() will
! 3450: ** always return SQLITE_BUSY. The SQLite core only ever uses
! 3451: ** sqlite3_mutex_try() as an optimization so this is acceptable behavior.
! 3452: **
! 3453: ** The sqlite3_mutex_leave() routine exits a mutex that was
! 3454: ** previously entered by the same thread. The behavior
! 3455: ** is undefined if the mutex is not currently entered by the
! 3456: ** calling thread or is not currently allocated. SQLite will
! 3457: ** never do either.
! 3458: **
! 3459: ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
! 3460: */
! 3461: sqlite3_mutex *sqlite3_mutex_alloc(int);
! 3462: void sqlite3_mutex_free(sqlite3_mutex*);
! 3463: void sqlite3_mutex_enter(sqlite3_mutex*);
! 3464: int sqlite3_mutex_try(sqlite3_mutex*);
! 3465: void sqlite3_mutex_leave(sqlite3_mutex*);
! 3466:
! 3467: /*
! 3468: ** CAPI3REF: Mutex Verifcation Routines
! 3469: **
! 3470: ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
! 3471: ** are intended for use inside assert() statements. The SQLite core
! 3472: ** never uses these routines except inside an assert() and applications
! 3473: ** are advised to follow the lead of the core. The core only
! 3474: ** provides implementations for these routines when it is compiled
! 3475: ** with the SQLITE_DEBUG flag. External mutex implementations
! 3476: ** are only required to provide these routines if SQLITE_DEBUG is
! 3477: ** defined and if NDEBUG is not defined.
! 3478: **
! 3479: ** These routines should return true if the mutex in their argument
! 3480: ** is held or not held, respectively, by the calling thread.
! 3481: **
! 3482: ** The implementation is not required to provided versions of these
! 3483: ** routines that actually work.
! 3484: ** If the implementation does not provide working
! 3485: ** versions of these routines, it should at least provide stubs
! 3486: ** that always return true so that one does not get spurious
! 3487: ** assertion failures.
! 3488: **
! 3489: ** If the argument to sqlite3_mutex_held() is a NULL pointer then
! 3490: ** the routine should return 1. This seems counter-intuitive since
! 3491: ** clearly the mutex cannot be held if it does not exist. But the
! 3492: ** the reason the mutex does not exist is because the build is not
! 3493: ** using mutexes. And we do not want the assert() containing the
! 3494: ** call to sqlite3_mutex_held() to fail, so a non-zero return is
! 3495: ** the appropriate thing to do. The sqlite3_mutex_notheld()
! 3496: ** interface should also return 1 when given a NULL pointer.
! 3497: */
! 3498: int sqlite3_mutex_held(sqlite3_mutex*);
! 3499: int sqlite3_mutex_notheld(sqlite3_mutex*);
! 3500:
! 3501: /*
! 3502: ** CAPI3REF: Mutex Types
! 3503: **
! 3504: ** The [sqlite3_mutex_alloc()] interface takes a single argument
! 3505: ** which is one of these integer constants.
! 3506: */
! 3507: #define SQLITE_MUTEX_FAST 0
! 3508: #define SQLITE_MUTEX_RECURSIVE 1
! 3509: #define SQLITE_MUTEX_STATIC_MASTER 2
! 3510: #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */
! 3511: #define SQLITE_MUTEX_STATIC_MEM2 4 /* sqlite3_release_memory() */
! 3512: #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */
! 3513: #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
! 3514:
! 3515: /*
! 3516: ** CAPI3REF: Low-Level Control Of Database Files
! 3517: **
! 3518: ** The [sqlite3_file_control()] interface makes a direct call to the
! 3519: ** xFileControl method for the [sqlite3_io_methods] object associated
! 3520: ** with a particular database identified by the second argument. The
! 3521: ** name of the database is the name assigned to the database by the
! 3522: ** <a href="lang_attach.html">ATTACH</a> SQL command that opened the
! 3523: ** database. To control the main database file, use the name "main"
! 3524: ** or a NULL pointer. The third and fourth parameters to this routine
! 3525: ** are passed directly through to the second and third parameters of
! 3526: ** the xFileControl method. The return value of the xFileControl
! 3527: ** method becomes the return value of this routine.
! 3528: **
! 3529: ** If the second parameter (zDbName) does not match the name of any
! 3530: ** open database file, then SQLITE_ERROR is returned. This error
! 3531: ** code is not remembered and will not be recalled by [sqlite3_errcode()]
! 3532: ** or [sqlite3_errmsg()]. The underlying xFileControl method might
! 3533: ** also return SQLITE_ERROR. There is no way to distinguish between
! 3534: ** an incorrect zDbName and an SQLITE_ERROR return from the underlying
! 3535: ** xFileControl method.
! 3536: **
! 3537: ** See also: [SQLITE_FCNTL_LOCKSTATE]
! 3538: */
! 3539: int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
! 3540:
! 3541: /*
! 3542: ** Undo the hack that converts floating point types to integer for
! 3543: ** builds on processors without floating point support.
! 3544: */
! 3545: #ifdef SQLITE_OMIT_FLOATING_POINT
! 3546: # undef double
! 3547: #endif
1.1 misha 3548:
3549: #ifdef __cplusplus
3550: } /* End of the 'extern "C"' block */
3551: #endif
3552: #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