00001 /* 00002 ** 2001 September 15 00003 ** 00004 ** The author disclaims copyright to this source code. In place of 00005 ** a legal notice, here is a blessing: 00006 ** 00007 ** May you do good and not evil. 00008 ** May you find forgiveness for yourself and forgive others. 00009 ** May you share freely, never taking more than you give. 00010 ** 00011 ************************************************************************* 00012 ** This header file defines the interface that the SQLite library 00013 ** presents to client programs. If a C-function, structure, datatype, 00014 ** or constant definition does not appear in this file, then it is 00015 ** not a published API of SQLite, is subject to change without 00016 ** notice, and should not be referenced by programs that use SQLite. 00017 ** 00018 ** Some of the definitions that are in this file are marked as 00019 ** "experimental". Experimental interfaces are normally new 00020 ** features recently added to SQLite. We do not anticipate changes 00021 ** to experimental interfaces but reserve to make minor changes if 00022 ** experience from use "in the wild" suggest such changes are prudent. 00023 ** 00024 ** The official C-language API documentation for SQLite is derived 00025 ** from comments in this file. This file is the authoritative source 00026 ** on how SQLite interfaces are suppose to operate. 00027 ** 00028 ** The name of this file under configuration management is "sqlite.h.in". 00029 ** The makefile makes some minor changes to this file (such as inserting 00030 ** the version number) and changes its name to "sqlite3.h" as 00031 ** part of the build process. 00032 ** 00033 ** @(#) $Id: sqlite.h.in,v 1.256 2007/09/03 20:32:45 drh Exp $ 00034 */ 00035 #ifndef _SQLITE3_H_ 00036 #define _SQLITE3_H_ 00037 #include <stdarg.h> /* Needed for the definition of va_list */ 00038 00039 /* 00040 ** Make sure we can call this stuff from C++. 00041 */ 00042 #ifdef __cplusplus 00043 extern "C" { 00044 #endif 00045 00046 00047 /* 00048 ** Add the ability to override 'extern' 00049 */ 00050 #ifndef SQLITE_EXTERN 00051 # define SQLITE_EXTERN extern 00052 #endif 00053 00054 /* 00055 ** Make sure these symbols where not defined by some previous header 00056 ** file. 00057 */ 00058 #ifdef SQLITE_VERSION 00059 # undef SQLITE_VERSION 00060 #endif 00061 #ifdef SQLITE_VERSION_NUMBER 00062 # undef SQLITE_VERSION_NUMBER 00063 #endif 00064 00065 /* 00066 ** CAPI3REF: Compile-Time Library Version Numbers 00067 ** 00068 ** The version of the SQLite library is contained in the sqlite3.h 00069 ** header file in a #define named SQLITE_VERSION. The SQLITE_VERSION 00070 ** macro resolves to a string constant. 00071 ** 00072 ** The format of the version string is "X.Y.Z", where 00073 ** X is the major version number, Y is the minor version number and Z 00074 ** is the release number. The X.Y.Z might be followed by "alpha" or "beta". 00075 ** For example "3.1.1beta". 00076 ** 00077 ** The X value is always 3 in SQLite. The X value only changes when 00078 ** backwards compatibility is broken and we intend to never break 00079 ** backwards compatibility. The Y value only changes when 00080 ** there are major feature enhancements that are forwards compatible 00081 ** but not backwards compatible. The Z value is incremented with 00082 ** each release but resets back to 0 when Y is incremented. 00083 ** 00084 ** The SQLITE_VERSION_NUMBER is an integer with the value 00085 ** (X*1000000 + Y*1000 + Z). For example, for version "3.1.1beta", 00086 ** SQLITE_VERSION_NUMBER is set to 3001001. To detect if they are using 00087 ** version 3.1.1 or greater at compile time, programs may use the test 00088 ** (SQLITE_VERSION_NUMBER>=3001001). 00089 ** 00090 ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()]. 00091 */ 00092 #define SQLITE_VERSION "3.5.0" 00093 #define SQLITE_VERSION_NUMBER 3005000 00094 00095 /* 00096 ** CAPI3REF: Run-Time Library Version Numbers 00097 ** 00098 ** These routines return values equivalent to the header constants 00099 ** [SQLITE_VERSION] and [SQLITE_VERSION_NUMBER]. The values returned 00100 ** by this routines should only be different from the header values 00101 ** if you compile your program using an sqlite3.h header from a 00102 ** different version of SQLite that the version of the library you 00103 ** link against. 00104 ** 00105 ** The sqlite3_version[] string constant contains the text of the 00106 ** [SQLITE_VERSION] string. The sqlite3_libversion() function returns 00107 ** a poiner to the sqlite3_version[] string constant. The function 00108 ** is provided for DLL users who can only access functions and not 00109 ** constants within the DLL. 00110 */ 00111 SQLITE_EXTERN const char sqlite3_version[]; 00112 const char *sqlite3_libversion(void); 00113 int sqlite3_libversion_number(void); 00114 00115 /* 00116 ** CAPI3REF: Test To See If The Library Is Threadsafe 00117 ** 00118 ** This routine returns TRUE (nonzero) if SQLite was compiled with 00119 ** all of its mutexes enabled and is thus threadsafe. It returns 00120 ** zero if the particular build is for single-threaded operation 00121 ** only. 00122 ** 00123 ** Really all this routine does is return true if SQLite was compiled 00124 ** with the -DSQLITE_THREADSAFE=1 option and false if 00125 ** compiled with -DSQLITE_THREADSAFE=0. If SQLite uses an 00126 ** application-defined mutex subsystem, malloc subsystem, collating 00127 ** sequence, VFS, SQL function, progress callback, commit hook, 00128 ** extension, or other accessories and these add-ons are not 00129 ** threadsafe, then clearly the combination will not be threadsafe 00130 ** either. Hence, this routine never reports that the library 00131 ** is guaranteed to be threadsafe, only when it is guaranteed not 00132 ** to be. 00133 ** 00134 ** This is an experimental API and may go away or change in future 00135 ** releases. 00136 */ 00137 int sqlite3_threadsafe(void); 00138 00139 /* 00140 ** CAPI3REF: Database Connection Handle 00141 ** 00142 ** Each open SQLite database is represented by pointer to an instance of the 00143 ** opaque structure named "sqlite3". It is useful to think of an sqlite3 00144 ** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and 00145 ** [sqlite3_open_v2()] interfaces are its constructors 00146 ** and [sqlite3_close()] is its destructor. There are many other interfaces 00147 ** (such as [sqlite3_prepare_v2()], [sqlite3_create_function()], and 00148 ** [sqlite3_busy_timeout()] to name but three) that are methods on this 00149 ** object. 00150 */ 00151 typedef struct sqlite3 sqlite3; 00152 00153 00154 /* 00155 ** CAPI3REF: 64-Bit Integer Types 00156 ** 00157 ** Some compilers do not support the "long long" datatype. So we have 00158 ** to do compiler-specific typedefs for 64-bit signed and unsigned integers. 00159 ** 00160 ** Many SQLite interface functions require a 64-bit integer arguments. 00161 ** Those interfaces are declared using this typedef. 00162 */ 00163 #ifdef SQLITE_INT64_TYPE 00164 typedef SQLITE_INT64_TYPE sqlite_int64; 00165 typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; 00166 #elif defined(_MSC_VER) || defined(__BORLANDC__) 00167 typedef __int64 sqlite_int64; 00168 typedef unsigned __int64 sqlite_uint64; 00169 #else 00170 typedef long long int sqlite_int64; 00171 typedef unsigned long long int sqlite_uint64; 00172 #endif 00173 typedef sqlite_int64 sqlite3_int64; 00174 typedef sqlite_uint64 sqlite3_uint64; 00175 00176 /* 00177 ** If compiling for a processor that lacks floating point support, 00178 ** substitute integer for floating-point 00179 */ 00180 #ifdef SQLITE_OMIT_FLOATING_POINT 00181 # define double sqlite3_int64 00182 #endif 00183 00184 /* 00185 ** CAPI3REF: Closing A Database Connection 00186 ** 00187 ** Call this function with a pointer to a structure that was previously 00188 ** returned from [sqlite3_open()], [sqlite3_open16()], or 00189 ** [sqlite3_open_v2()] and the corresponding database will by 00190 ** closed. 00191 ** 00192 ** All SQL statements prepared using [sqlite3_prepare_v2()] or 00193 ** [sqlite3_prepare16_v2()] must be destroyed using [sqlite3_finalize()] 00194 ** before this routine is called. Otherwise, SQLITE_BUSY is returned and the 00195 ** database connection remains open. 00196 ** 00197 ** Passing this routine a database connection that has already been 00198 ** closed results in undefined behavior. If other interfaces that 00199 ** reference the same database connection are pending (either in the 00200 ** same thread or in different threads) when this routine is called, 00201 ** then the behavior is undefined and is almost certainly undesirable. 00202 */ 00203 int sqlite3_close(sqlite3 *); 00204 00205 /* 00206 ** The type for a callback function. 00207 ** This is legacy and deprecated. It is included for historical 00208 ** compatibility and is not documented. 00209 */ 00210 typedef int (*sqlite3_callback)(void*,int,char**, char**); 00211 00212 /* 00213 ** CAPI3REF: One-Step Query Execution Interface 00214 ** 00215 ** This interface is used to do a one-time evaluatation of zero 00216 ** or more SQL statements. UTF-8 text of the SQL statements to 00217 ** be evaluted is passed in as the second parameter. The statements 00218 ** are prepared one by one using [sqlite3_prepare()], evaluated 00219 ** using [sqlite3_step()], then destroyed using [sqlite3_finalize()]. 00220 ** 00221 ** If one or more of the SQL statements are queries, then 00222 ** the callback function specified by the 3rd parameter is 00223 ** invoked once for each row of the query result. This callback 00224 ** should normally return 0. If the callback returns a non-zero 00225 ** value then the query is aborted, all subsequent SQL statements 00226 ** are skipped and the sqlite3_exec() function returns the [SQLITE_ABORT]. 00227 ** 00228 ** The 4th parameter to this interface is an arbitrary pointer that is 00229 ** passed through to the callback function as its first parameter. 00230 ** 00231 ** The 2nd parameter to the callback function is the number of 00232 ** columns in the query result. The 3rd parameter to the callback 00233 ** is an array of strings holding the values for each column 00234 ** as extracted using [sqlite3_column_text()]. 00235 ** The 4th parameter to the callback is an array of strings 00236 ** obtained using [sqlite3_column_name()] and holding 00237 ** the names of each column. 00238 ** 00239 ** The callback function may be NULL, even for queries. A NULL 00240 ** callback is not an error. It just means that no callback 00241 ** will be invoked. 00242 ** 00243 ** If an error occurs while parsing or evaluating the SQL (but 00244 ** not while executing the callback) then an appropriate error 00245 ** message is written into memory obtained from [sqlite3_malloc()] and 00246 ** *errmsg is made to point to that message. The calling function 00247 ** is responsible for freeing the memory using [sqlite3_free()]. 00248 ** If errmsg==NULL, then no error message is ever written. 00249 ** 00250 ** The return value is is SQLITE_OK if there are no errors and 00251 ** some other [SQLITE_OK | return code] if there is an error. 00252 ** The particular return value depends on the type of error. 00253 ** 00254 */ 00255 int sqlite3_exec( 00256 sqlite3*, /* An open database */ 00257 const char *sql, /* SQL to be evaluted */ 00258 int (*callback)(void*,int,char**,char**), /* Callback function */ 00259 void *, /* 1st argument to callback */ 00260 char **errmsg /* Error msg written here */ 00261 ); 00262 00263 /* 00264 ** CAPI3REF: Result Codes 00265 ** KEYWORDS: SQLITE_OK 00266 ** 00267 ** Many SQLite functions return an integer result code from the set shown 00268 ** above in order to indicates success or failure. 00269 ** 00270 ** The result codes above are the only ones returned by SQLite in its 00271 ** default configuration. However, the [sqlite3_extended_result_codes()] 00272 ** API can be used to set a database connectoin to return more detailed 00273 ** result codes. 00274 ** 00275 ** See also: [SQLITE_IOERR_READ | extended result codes] 00276 ** 00277 */ 00278 #define SQLITE_OK 0 /* Successful result */ 00279 /* beginning-of-error-codes */ 00280 #define SQLITE_ERROR 1 /* SQL error or missing database */ 00281 #define SQLITE_INTERNAL 2 /* NOT USED. Internal logic error in SQLite */ 00282 #define SQLITE_PERM 3 /* Access permission denied */ 00283 #define SQLITE_ABORT 4 /* Callback routine requested an abort */ 00284 #define SQLITE_BUSY 5 /* The database file is locked */ 00285 #define SQLITE_LOCKED 6 /* A table in the database is locked */ 00286 #define SQLITE_NOMEM 7 /* A malloc() failed */ 00287 #define SQLITE_READONLY 8 /* Attempt to write a readonly database */ 00288 #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/ 00289 #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ 00290 #define SQLITE_CORRUPT 11 /* The database disk image is malformed */ 00291 #define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */ 00292 #define SQLITE_FULL 13 /* Insertion failed because database is full */ 00293 #define SQLITE_CANTOPEN 14 /* Unable to open the database file */ 00294 #define SQLITE_PROTOCOL 15 /* NOT USED. Database lock protocol error */ 00295 #define SQLITE_EMPTY 16 /* Database is empty */ 00296 #define SQLITE_SCHEMA 17 /* The database schema changed */ 00297 #define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */ 00298 #define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */ 00299 #define SQLITE_MISMATCH 20 /* Data type mismatch */ 00300 #define SQLITE_MISUSE 21 /* Library used incorrectly */ 00301 #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ 00302 #define SQLITE_AUTH 23 /* Authorization denied */ 00303 #define SQLITE_FORMAT 24 /* Auxiliary database format error */ 00304 #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */ 00305 #define SQLITE_NOTADB 26 /* File opened that is not a database file */ 00306 #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ 00307 #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ 00308 /* end-of-error-codes */ 00309 00310 /* 00311 ** CAPI3REF: Extended Result Codes 00312 ** 00313 ** In its default configuration, SQLite API routines return one of 26 integer 00314 ** result codes described at result-codes. However, experience has shown that 00315 ** many of these result codes are too course-grained. They do not provide as 00316 ** much information about problems as users might like. In an effort to 00317 ** address this, newer versions of SQLite (version 3.3.8 and later) include 00318 ** support for additional result codes that provide more detailed information 00319 ** about errors. The extended result codes are enabled (or disabled) for 00320 ** each database 00321 ** connection using the [sqlite3_extended_result_codes()] API. 00322 ** 00323 ** Some of the available extended result codes are listed above. 00324 ** We expect the number of extended result codes will be expand 00325 ** over time. Software that uses extended result codes should expect 00326 ** to see new result codes in future releases of SQLite. 00327 ** 00328 ** The symbolic name for an extended result code always contains a related 00329 ** primary result code as a prefix. Primary result codes contain a single 00330 ** "_" character. Extended result codes contain two or more "_" characters. 00331 ** The numeric value of an extended result code can be converted to its 00332 ** corresponding primary result code by masking off the lower 8 bytes. 00333 ** 00334 ** The SQLITE_OK result code will never be extended. It will always 00335 ** be exactly zero. 00336 */ 00337 #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) 00338 #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) 00339 #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) 00340 #define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) 00341 #define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) 00342 #define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) 00343 #define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) 00344 #define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) 00345 #define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) 00346 #define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) 00347 #define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8)) 00348 00349 /* 00350 ** CAPI3REF: Flags For File Open Operations 00351 ** 00352 ** Combination of the following bit values are used as the 00353 ** third argument to the [sqlite3_open_v2()] interface and 00354 ** as fourth argument to the xOpen method of the 00355 ** [sqlite3_vfs] object. 00356 ** 00357 */ 00358 #define SQLITE_OPEN_READONLY 0x00000001 00359 #define SQLITE_OPEN_READWRITE 0x00000002 00360 #define SQLITE_OPEN_CREATE 0x00000004 00361 #define SQLITE_OPEN_DELETEONCLOSE 0x00000008 00362 #define SQLITE_OPEN_EXCLUSIVE 0x00000010 00363 #define SQLITE_OPEN_MAIN_DB 0x00000100 00364 #define SQLITE_OPEN_TEMP_DB 0x00000200 00365 #define SQLITE_OPEN_TRANSIENT_DB 0x00000400 00366 #define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 00367 #define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 00368 #define SQLITE_OPEN_SUBJOURNAL 0x00002000 00369 #define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 00370 00371 /* 00372 ** CAPI3REF: Device Characteristics 00373 ** 00374 ** The xDeviceCapabilities method of the [sqlite3_io_methods] 00375 ** object returns an integer which is a vector of the following 00376 ** bit values expressing I/O characteristics of the mass storage 00377 ** device that holds the file that the [sqlite3_io_methods] 00378 ** refers to. 00379 ** 00380 ** The SQLITE_IOCAP_ATOMIC property means that all writes of 00381 ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values 00382 ** mean that writes of blocks that are nnn bytes in size and 00383 ** are aligned to an address which is an integer multiple of 00384 ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means 00385 ** that when data is appended to a file, the data is appended 00386 ** first then the size of the file is extended, never the other 00387 ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that 00388 ** information is written to disk in the same order as calls 00389 ** to xWrite(). 00390 */ 00391 #define SQLITE_IOCAP_ATOMIC 0x00000001 00392 #define SQLITE_IOCAP_ATOMIC512 0x00000002 00393 #define SQLITE_IOCAP_ATOMIC1K 0x00000004 00394 #define SQLITE_IOCAP_ATOMIC2K 0x00000008 00395 #define SQLITE_IOCAP_ATOMIC4K 0x00000010 00396 #define SQLITE_IOCAP_ATOMIC8K 0x00000020 00397 #define SQLITE_IOCAP_ATOMIC16K 0x00000040 00398 #define SQLITE_IOCAP_ATOMIC32K 0x00000080 00399 #define SQLITE_IOCAP_ATOMIC64K 0x00000100 00400 #define SQLITE_IOCAP_SAFE_APPEND 0x00000200 00401 #define SQLITE_IOCAP_SEQUENTIAL 0x00000400 00402 00403 /* 00404 ** CAPI3REF: File Locking Levels 00405 ** 00406 ** SQLite uses one of the following integer values as the second 00407 ** argument to calls it makes to the xLock() and xUnlock() methods 00408 ** of an [sqlite3_io_methods] object. 00409 */ 00410 #define SQLITE_LOCK_NONE 0 00411 #define SQLITE_LOCK_SHARED 1 00412 #define SQLITE_LOCK_RESERVED 2 00413 #define SQLITE_LOCK_PENDING 3 00414 #define SQLITE_LOCK_EXCLUSIVE 4 00415 00416 /* 00417 ** CAPI3REF: Synchronization Type Flags 00418 ** 00419 ** When SQLite invokes the xSync() method of an [sqlite3_io_methods] 00420 ** object it uses a combination of the following integer values as 00421 ** the second argument. 00422 ** 00423 ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the 00424 ** sync operation only needs to flush data to mass storage. Inode 00425 ** information need not be flushed. The SQLITE_SYNC_NORMAL means 00426 ** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means 00427 ** to use Mac OS-X style fullsync instead of fsync(). 00428 */ 00429 #define SQLITE_SYNC_NORMAL 0x00002 00430 #define SQLITE_SYNC_FULL 0x00003 00431 #define SQLITE_SYNC_DATAONLY 0x00010 00432 00433 00434 /* 00435 ** CAPI3REF: OS Interface Open File Handle 00436 ** 00437 ** An [sqlite3_file] object represents an open file in the OS 00438 ** interface layer. Individual OS interface implementations will 00439 ** want to subclass this object by appending additional fields 00440 ** for their own use. The pMethods entry is a pointer to an 00441 ** [sqlite3_io_methods] object that defines methods for performing 00442 ** I/O operations on the open file. 00443 */ 00444 typedef struct sqlite3_file sqlite3_file; 00445 struct sqlite3_file { 00446 const struct sqlite3_io_methods *pMethods; /* Methods for an open file */ 00447 }; 00448 00449 /* 00450 ** CAPI3REF: OS Interface File Virtual Methods Object 00451 ** 00452 ** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to 00453 ** an instance of the this object. This object defines the 00454 ** methods used to perform various operations against the open file. 00455 ** 00456 ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or 00457 ** [SQLITE_SYNC_FULL]. The first choice is the normal fsync(). 00458 * The second choice is an 00459 ** OS-X style fullsync. The SQLITE_SYNC_DATA flag may be ORed in to 00460 ** indicate that only the data of the file and not its inode needs to be 00461 ** synced. 00462 ** 00463 ** The integer values to xLock() and xUnlock() are one of 00464 ** <ul> 00465 ** <li> [SQLITE_LOCK_NONE], 00466 ** <li> [SQLITE_LOCK_READ], 00467 ** <li> [SQLITE_LOCK_RESERVED], 00468 ** <li> [SQLITE_LOCK_PENDING], or 00469 ** <li> [SQLITE_LOCK_EXCLUSIVE]. 00470 ** </ul> 00471 ** xLock() increases the lock. xUnlock() decreases the lock. 00472 ** The xCheckReservedLock() method looks 00473 ** to see if any database connection, either in this 00474 ** process or in some other process, is holding an RESERVED, 00475 ** PENDING, or EXCLUSIVE lock on the file. It returns true 00476 ** if such a lock exists and false if not. 00477 ** 00478 ** The xFileControl() method is a generic interface that allows custom 00479 ** VFS implementations to directly control an open file using the 00480 ** [sqlite3_file_control()] interface. The second "op" argument 00481 ** is an integer opcode. The third 00482 ** argument is a generic pointer which is intended to be a pointer 00483 ** to a structure that may contain arguments or space in which to 00484 ** write return values. Potential uses for xFileControl() might be 00485 ** functions to enable blocking locks with timeouts, to change the 00486 ** locking strategy (for example to use dot-file locks), to inquire 00487 ** about the status of a lock, or to break stale locks. The SQLite 00488 ** core reserves opcodes less than 100 for its own use. 00489 ** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available. 00490 ** Applications that define a custom xFileControl method should use opcodes 00491 ** greater than 100 to avoid conflicts. 00492 ** 00493 ** The xSectorSize() method returns the sector size of the 00494 ** device that underlies the file. The sector size is the 00495 ** minimum write that can be performed without disturbing 00496 ** other bytes in the file. The xDeviceCharacteristics() 00497 ** method returns a bit vector describing behaviors of the 00498 ** underlying device: 00499 ** 00500 ** <ul> 00501 ** <li> [SQLITE_IOCAP_ATOMIC] 00502 ** <li> [SQLITE_IOCAP_ATOMIC512] 00503 ** <li> [SQLITE_IOCAP_ATOMIC1K] 00504 ** <li> [SQLITE_IOCAP_ATOMIC2K] 00505 ** <li> [SQLITE_IOCAP_ATOMIC4K] 00506 ** <li> [SQLITE_IOCAP_ATOMIC8K] 00507 ** <li> [SQLITE_IOCAP_ATOMIC16K] 00508 ** <li> [SQLITE_IOCAP_ATOMIC32K] 00509 ** <li> [SQLITE_IOCAP_ATOMIC64K] 00510 ** <li> [SQLITE_IOCAP_SAFE_APPEND] 00511 ** <li> [SQLITE_IOCAP_SEQUENTIAL] 00512 ** </ul> 00513 ** 00514 ** The SQLITE_IOCAP_ATOMIC property means that all writes of 00515 ** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values 00516 ** mean that writes of blocks that are nnn bytes in size and 00517 ** are aligned to an address which is an integer multiple of 00518 ** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means 00519 ** that when data is appended to a file, the data is appended 00520 ** first then the size of the file is extended, never the other 00521 ** way around. The SQLITE_IOCAP_SEQUENTIAL property means that 00522 ** information is written to disk in the same order as calls 00523 ** to xWrite(). 00524 */ 00525 typedef struct sqlite3_io_methods sqlite3_io_methods; 00526 struct sqlite3_io_methods { 00527 int iVersion; 00528 int (*xClose)(sqlite3_file*); 00529 int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite_int64 iOfst); 00530 int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite_int64 iOfst); 00531 int (*xTruncate)(sqlite3_file*, sqlite_int64 size); 00532 int (*xSync)(sqlite3_file*, int flags); 00533 int (*xFileSize)(sqlite3_file*, sqlite_int64 *pSize); 00534 int (*xLock)(sqlite3_file*, int); 00535 int (*xUnlock)(sqlite3_file*, int); 00536 int (*xCheckReservedLock)(sqlite3_file*); 00537 int (*xFileControl)(sqlite3_file*, int op, void *pArg); 00538 int (*xSectorSize)(sqlite3_file*); 00539 int (*xDeviceCharacteristics)(sqlite3_file*); 00540 /* Additional methods may be added in future releases */ 00541 }; 00542 00543 /* 00544 ** CAPI3REF: Standard File Control Opcodes 00545 ** 00546 ** These integer constants are opcodes for the xFileControl method 00547 ** of the [sqlite3_io_methods] object and to the [sqlite3_file_control()] 00548 ** interface. 00549 ** 00550 ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This 00551 ** opcode cases the xFileControl method to write the current state of 00552 ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED], 00553 ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE]) 00554 ** into an integer that the pArg argument points to. This capability 00555 ** is used during testing and only needs to be supported when SQLITE_TEST 00556 ** is defined. 00557 */ 00558 #define SQLITE_FCNTL_LOCKSTATE 1 00559 00560 /* 00561 ** CAPI3REF: Mutex Handle 00562 ** 00563 ** The mutex module within SQLite defines [sqlite3_mutex] to be an 00564 ** abstract type for a mutex object. The SQLite core never looks 00565 ** at the internal representation of an [sqlite3_mutex]. It only 00566 ** deals with pointers to the [sqlite3_mutex] object. 00567 ** 00568 ** Mutexes are created using [sqlite3_mutex_alloc()]. 00569 */ 00570 typedef struct sqlite3_mutex sqlite3_mutex; 00571 00572 /* 00573 ** CAPI3REF: OS Interface Object 00574 ** 00575 ** An instance of this object defines the interface between the 00576 ** SQLite core and the underlying operating system. The "vfs" 00577 ** in the name of the object stands for "virtual file system". 00578 ** 00579 ** The iVersion field is initially 1 but may be larger for future 00580 ** versions of SQLite. Additional fields may be appended to this 00581 ** object when the iVersion value is increased. 00582 ** 00583 ** The szOsFile field is the size of the subclassed [sqlite3_file] 00584 ** structure used by this VFS. mxPathname is the maximum length of 00585 ** a pathname in this VFS. 00586 ** 00587 ** Registered vfs modules are kept on a linked list formed by 00588 ** the pNext pointer. The [sqlite3_register_vfs()] 00589 ** and [sqlite3_unregister_vfs()] interfaces manage this list 00590 ** in a thread-safe way. The [sqlite3_find_vfs()] interface 00591 ** searches the list. 00592 ** 00593 ** The pNext field is the only fields in the sqlite3_vfs 00594 ** structure that SQLite will ever modify. SQLite will only access 00595 ** or modify this field while holding a particular static mutex. 00596 ** The application should never modify anything within the sqlite3_vfs 00597 ** object once the object has been registered. 00598 ** 00599 ** The zName field holds the name of the VFS module. The name must 00600 ** be unique across all VFS modules. 00601 ** 00602 ** SQLite will guarantee that the zFilename string passed to 00603 ** xOpen() is a full pathname as generated by xFullPathname() and 00604 ** that the string will be valid and unchanged until xClose() is 00605 ** called. So the [sqlite3_file] can store a pointer to the 00606 ** filename if it needs to remember the filename for some reason. 00607 ** 00608 ** The flags argument to xOpen() is a copy of the flags argument 00609 ** to [sqlite3_open_v2()]. If [sqlite3_open()] or [sqlite3_open16()] 00610 ** is used, then flags is [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. 00611 ** If xOpen() opens a file read-only then it sets *pOutFlags to 00612 ** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be 00613 ** set. 00614 ** 00615 ** SQLite will also add one of the following flags to the xOpen() 00616 ** call, depending on the object being opened: 00617 ** 00618 ** <ul> 00619 ** <li> [SQLITE_OPEN_MAIN_DB] 00620 ** <li> [SQLITE_OPEN_MAIN_JOURNAL] 00621 ** <li> [SQLITE_OPEN_TEMP_DB] 00622 ** <li> [SQLITE_OPEN_TEMP_JOURNAL] 00623 ** <li> [SQLITE_OPEN_TRANSIENT_DB] 00624 ** <li> [SQLITE_OPEN_SUBJOURNAL] 00625 ** <li> [SQLITE_OPEN_MASTER_JOURNAL] 00626 ** </ul> 00627 ** 00628 ** The file I/O implementation can use the object type flags to 00629 ** changes the way it deals with files. For example, an application 00630 ** that does not care about crash recovery or rollback, might make 00631 ** the open of a journal file a no-op. Writes to this journal are 00632 ** also a no-op. Any attempt to read the journal return SQLITE_IOERR. 00633 ** Or the implementation might recognize the a database file will 00634 ** be doing page-aligned sector reads and writes in a random order 00635 ** and set up its I/O subsystem accordingly. 00636 ** 00637 ** SQLite might also add one of the following flags to the xOpen 00638 ** method: 00639 ** 00640 ** <ul> 00641 ** <li> [SQLITE_OPEN_DELETEONCLOSE] 00642 ** <li> [SQLITE_OPEN_EXCLUSIVE] 00643 ** </ul> 00644 ** 00645 ** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be 00646 ** deleted when it is closed. This will always be set for TEMP 00647 ** databases and journals and for subjournals. The 00648 ** [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened 00649 ** for exclusive access. This flag is set for all files except 00650 ** for the main database file. 00651 ** 00652 ** Space to hold the [sqlite3_file] structure passed as the third 00653 ** argument to xOpen is allocated by caller (the SQLite core). 00654 ** szOsFile bytes are allocated for this object. The xOpen method 00655 ** fills in the allocated space. 00656 ** 00657 ** The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] 00658 ** to test for the existance of a file, 00659 ** or [SQLITE_ACCESS_READWRITE] to test to see 00660 ** if a file is readable and writable, or [SQLITE_ACCESS_READ] 00661 ** to test to see if a file is at least readable. The file can be a 00662 ** directory. 00663 ** 00664 ** SQLite will always allocate at least mxPathname+1 byte for 00665 ** the output buffers for xGetTempName and xFullPathname. 00666 ** 00667 ** The xRandomness(), xSleep(), and xCurrentTime() interfaces 00668 ** are not strictly a part of the filesystem, but they are 00669 ** included in the VFS structure for completeness. 00670 ** The xRandomness() function attempts to return nBytes bytes 00671 ** of good-quality randomness into zOut. The return value is 00672 ** the actual number of bytes of randomness obtained. The 00673 ** xSleep() method cause the calling thread to sleep for at 00674 ** least the number of microseconds given. The xCurrentTime() 00675 ** method returns a Julian Day Number for the current date and 00676 ** time. 00677 */ 00678 typedef struct sqlite3_vfs sqlite3_vfs; 00679 struct sqlite3_vfs { 00680 int iVersion; /* Structure version number */ 00681 int szOsFile; /* Size of subclassed sqlite3_file */ 00682 int mxPathname; /* Maximum file pathname length */ 00683 sqlite3_vfs *pNext; /* Next registered VFS */ 00684 const char *zName; /* Name of this virtual file system */ 00685 void *pAppData; /* Pointer to application-specific data */ 00686 int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*, 00687 int flags, int *pOutFlags); 00688 int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir); 00689 int (*xAccess)(sqlite3_vfs*, const char *zName, int flags); 00690 int (*xGetTempName)(sqlite3_vfs*, char *zOut); 00691 int (*xFullPathname)(sqlite3_vfs*, const char *zName, char *zOut); 00692 void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename); 00693 void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg); 00694 void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol); 00695 void (*xDlClose)(sqlite3_vfs*, void*); 00696 int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut); 00697 int (*xSleep)(sqlite3_vfs*, int microseconds); 00698 int (*xCurrentTime)(sqlite3_vfs*, double*); 00699 /* New fields may be appended in figure versions. The iVersion 00700 ** value will increment whenever this happens. */ 00701 }; 00702 00703 /* 00704 ** CAPI3REF: Flags for the xAccess VFS method 00705 ** 00706 ** These integer constants can be used as the third parameter to 00707 ** the xAccess method of an [sqlite3_vfs] object. They determine 00708 ** the kind of what kind of permissions the xAccess method is 00709 ** looking for. With SQLITE_ACCESS_EXISTS, the xAccess method 00710 ** simply checks to see if the file exists. With SQLITE_ACCESS_READWRITE, 00711 ** the xAccess method checks to see if the file is both readable 00712 ** and writable. With SQLITE_ACCESS_READ the xAccess method 00713 ** checks to see if the file is readable. 00714 */ 00715 #define SQLITE_ACCESS_EXISTS 0 00716 #define SQLITE_ACCESS_READWRITE 1 00717 #define SQLITE_ACCESS_READ 2 00718 00719 /* 00720 ** CAPI3REF: Enable Or Disable Extended Result Codes 00721 ** 00722 ** This routine enables or disables the 00723 ** [SQLITE_IOERR_READ | extended result codes] feature. 00724 ** By default, SQLite API routines return one of only 26 integer 00725 ** [SQLITE_OK | result codes]. When extended result codes 00726 ** are enabled by this routine, the repetoire of result codes can be 00727 ** much larger and can (hopefully) provide more detailed information 00728 ** about the cause of an error. 00729 ** 00730 ** The second argument is a boolean value that turns extended result 00731 ** codes on and off. Extended result codes are off by default for 00732 ** backwards compatibility with older versions of SQLite. 00733 */ 00734 int sqlite3_extended_result_codes(sqlite3*, int onoff); 00735 00736 /* 00737 ** CAPI3REF: Last Insert Rowid 00738 ** 00739 ** Each entry in an SQLite table has a unique 64-bit signed integer key 00740 ** called the "rowid". The rowid is always available as an undeclared 00741 ** column named ROWID, OID, or _ROWID_. If the table has a column of 00742 ** type INTEGER PRIMARY KEY then that column is another an alias for the 00743 ** rowid. 00744 ** 00745 ** This routine returns the rowid of the most recent INSERT into 00746 ** the database from the database connection given in the first 00747 ** argument. If no inserts have ever occurred on this database 00748 ** connection, zero is returned. 00749 ** 00750 ** If an INSERT occurs within a trigger, then the rowid of the 00751 ** inserted row is returned by this routine as long as the trigger 00752 ** is running. But once the trigger terminates, the value returned 00753 ** by this routine reverts to the last value inserted before the 00754 ** trigger fired. 00755 ** 00756 ** If another thread does a new insert on the same database connection 00757 ** while this routine is running and thus changes the last insert rowid, 00758 ** then the return value of this routine is undefined. 00759 */ 00760 sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*); 00761 00762 /* 00763 ** CAPI3REF: Count The Number Of Rows Modified 00764 ** 00765 ** This function returns the number of database rows that were changed 00766 ** (or inserted or deleted) by the most recent SQL statement. Only 00767 ** changes that are directly specified by the INSERT, UPDATE, or 00768 ** DELETE statement are counted. Auxiliary changes caused by 00769 ** triggers are not counted. Use the [sqlite3_total_changes()] function 00770 ** to find the total number of changes including changes caused by triggers. 00771 ** 00772 ** Within the body of a trigger, the sqlite3_changes() interface can be 00773 ** called to find the number of 00774 ** changes in the most recently completed INSERT, UPDATE, or DELETE 00775 ** statement within the body of the trigger. 00776 ** 00777 ** All changes are counted, even if they were later undone by a 00778 ** ROLLBACK or ABORT. Except, changes associated with creating and 00779 ** dropping tables are not counted. 00780 ** 00781 ** If a callback invokes [sqlite3_exec()] or [sqlite3_step()] recursively, 00782 ** then the changes in the inner, recursive call are counted together 00783 ** with the changes in the outer call. 00784 ** 00785 ** SQLite implements the command "DELETE FROM table" without a WHERE clause 00786 ** by dropping and recreating the table. (This is much faster than going 00787 ** through and deleting individual elements from the table.) Because of 00788 ** this optimization, the change count for "DELETE FROM table" will be 00789 ** zero regardless of the number of elements that were originally in the 00790 ** table. To get an accurate count of the number of rows deleted, use 00791 ** "DELETE FROM table WHERE 1" instead. 00792 ** 00793 ** If another thread makes changes on the same database connection 00794 ** while this routine is running then the return value of this routine 00795 ** is undefined. 00796 */ 00797 int sqlite3_changes(sqlite3*); 00798 00799 /* 00800 ** CAPI3REF: Total Number Of Rows Modified 00801 *** 00802 ** This function returns the number of database rows that have been 00803 ** modified by INSERT, UPDATE or DELETE statements since the database handle 00804 ** was opened. This includes UPDATE, INSERT and DELETE statements executed 00805 ** as part of trigger programs. All changes are counted as soon as the 00806 ** statement that makes them is completed (when the statement handle is 00807 ** passed to [sqlite3_reset()] or [sqlite3_finalise()]). 00808 ** 00809 ** See also the [sqlite3_change()] interface. 00810 ** 00811 ** SQLite implements the command "DELETE FROM table" without a WHERE clause 00812 ** by dropping and recreating the table. (This is much faster than going 00813 ** through and deleting individual elements form the table.) Because of 00814 ** this optimization, the change count for "DELETE FROM table" will be 00815 ** zero regardless of the number of elements that were originally in the 00816 ** table. To get an accurate count of the number of rows deleted, use 00817 ** "DELETE FROM table WHERE 1" instead. 00818 ** 00819 ** If another thread makes changes on the same database connection 00820 ** while this routine is running then the return value of this routine 00821 ** is undefined. 00822 */ 00823 int sqlite3_total_changes(sqlite3*); 00824 00825 /* 00826 ** CAPI3REF: Interrupt A Long-Running Query 00827 ** 00828 ** This function causes any pending database operation to abort and 00829 ** return at its earliest opportunity. This routine is typically 00830 ** called in response to a user action such as pressing "Cancel" 00831 ** or Ctrl-C where the user wants a long query operation to halt 00832 ** immediately. 00833 ** 00834 ** It is safe to call this routine from a thread different from the 00835 ** thread that is currently running the database operation. But it 00836 ** is not safe to call this routine with a database connection that 00837 ** is closed or might close before sqlite3_interrupt() returns. 00838 ** 00839 ** The SQL operation that is interrupted will return [SQLITE_INTERRUPT]. 00840 ** If an interrupted operation was an update that is inside an 00841 ** explicit transaction, then the entire transaction will be rolled 00842 ** back automatically. 00843 */ 00844 void sqlite3_interrupt(sqlite3*); 00845 00846 /* 00847 ** CAPI3REF: Determine If An SQL Statement Is Complete 00848 ** 00849 ** These functions return true if the given input string comprises 00850 ** one or more complete SQL statements. For the sqlite3_complete() call, 00851 ** the parameter must be a nul-terminated UTF-8 string. For 00852 ** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string 00853 ** is required. 00854 ** 00855 ** These routines are useful for command-line input to determine if the 00856 ** currently entered text forms one or more complete SQL statements or 00857 ** if additional input is needed before sending the statements into 00858 ** SQLite for parsing. The algorithm is simple. If the 00859 ** last token other than spaces and comments is a semicolon, then return 00860 ** true. Actually, the algorithm is a little more complicated than that 00861 ** in order to deal with triggers, but the basic idea is the same: the 00862 ** statement is not complete unless it ends in a semicolon. 00863 */ 00864 int sqlite3_complete(const char *sql); 00865 int sqlite3_complete16(const void *sql); 00866 00867 /* 00868 ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors 00869 ** 00870 ** This routine identifies a callback function that might be invoked 00871 ** whenever an attempt is made to open a database table 00872 ** that another thread or process has locked. 00873 ** If the busy callback is NULL, then [SQLITE_BUSY] 00874 ** (or sometimes [SQLITE_IOERR_BLOCKED]) 00875 ** is returned immediately upon encountering the lock. 00876 ** If the busy callback is not NULL, then the 00877 ** callback will be invoked with two arguments. The 00878 ** first argument to the handler is a copy of the void* pointer which 00879 ** is the third argument to this routine. The second argument to 00880 ** the handler is the number of times that the busy handler has 00881 ** been invoked for this locking event. If the 00882 ** busy callback returns 0, then no additional attempts are made to 00883 ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned. 00884 ** If the callback returns non-zero, then another attempt is made to open the 00885 ** database for reading and the cycle repeats. 00886 ** 00887 ** The presence of a busy handler does not guarantee that 00888 ** it will be invoked when there is lock contention. 00889 ** If SQLite determines that invoking the busy handler could result in 00890 ** a deadlock, it will return [SQLITE_BUSY] instead. 00891 ** Consider a scenario where one process is holding a read lock that 00892 ** it is trying to promote to a reserved lock and 00893 ** a second process is holding a reserved lock that it is trying 00894 ** to promote to an exclusive lock. The first process cannot proceed 00895 ** because it is blocked by the second and the second process cannot 00896 ** proceed because it is blocked by the first. If both processes 00897 ** invoke the busy handlers, neither will make any progress. Therefore, 00898 ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this 00899 ** will induce the first process to release its read lock and allow 00900 ** the second process to proceed. 00901 ** 00902 ** The default busy callback is NULL. 00903 ** 00904 ** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED] when 00905 ** SQLite is in the middle of a large transaction where all the 00906 ** changes will not fit into the in-memory cache. SQLite will 00907 ** already hold a RESERVED lock on the database file, but it needs 00908 ** to promote this lock to EXCLUSIVE so that it can spill cache 00909 ** pages into the database file without harm to concurrent 00910 ** readers. If it is unable to promote the lock, then the in-memory 00911 ** cache will be left in an inconsistent state and so the error 00912 ** code is promoted from the relatively benign [SQLITE_BUSY] to 00913 ** the more severe [SQLITE_IOERR_BLOCKED]. This error code promotion 00914 ** forces an automatic rollback of the changes. See the 00915 ** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError"> 00916 ** CorruptionFollowingBusyError</a> wiki page for a discussion of why 00917 ** this is important. 00918 ** 00919 ** Sqlite is re-entrant, so the busy handler may start a new query. 00920 ** (It is not clear why anyone would every want to do this, but it 00921 ** is allowed, in theory.) But the busy handler may not close the 00922 ** database. Closing the database from a busy handler will delete 00923 ** data structures out from under the executing query and will 00924 ** probably result in a segmentation fault or other runtime error. 00925 ** 00926 ** There can only be a single busy handler defined for each database 00927 ** connection. Setting a new busy handler clears any previous one. 00928 ** Note that calling [sqlite3_busy_timeout()] will also set or clear 00929 ** the busy handler. 00930 ** 00931 ** When operating in [sqlite3_enable_shared_cache | shared cache mode], 00932 ** only a single busy handler can be defined for each database file. 00933 ** So if two database connections share a single cache, then changing 00934 ** the busy handler on one connection will also change the busy 00935 ** handler in the other connection. The busy handler is invoked 00936 ** in the thread that was running when the SQLITE_BUSY was hit. 00937 */ 00938 int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); 00939 00940 /* 00941 ** CAPI3REF: Set A Busy Timeout 00942 ** 00943 ** This routine sets a busy handler that sleeps for a while when a 00944 ** table is locked. The handler will sleep multiple times until 00945 ** at least "ms" milliseconds of sleeping have been done. After 00946 ** "ms" milliseconds of sleeping, the handler returns 0 which 00947 ** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]. 00948 ** 00949 ** Calling this routine with an argument less than or equal to zero 00950 ** turns off all busy handlers. 00951 ** 00952 ** There can only be a single busy handler for a particular database 00953 ** connection. If another busy handler was defined 00954 ** (using [sqlite3_busy_handler()]) prior to calling 00955 ** this routine, that other busy handler is cleared. 00956 */ 00957 int sqlite3_busy_timeout(sqlite3*, int ms); 00958 00959 /* 00960 ** CAPI3REF: Convenience Routines For Running Queries 00961 ** 00962 ** This next routine is a convenience wrapper around [sqlite3_exec()]. 00963 ** Instead of invoking a user-supplied callback for each row of the 00964 ** result, this routine remembers each row of the result in memory 00965 ** obtained from [sqlite3_malloc()], then returns all of the result after the 00966 ** query has finished. 00967 ** 00968 ** As an example, suppose the query result where this table: 00969 ** 00970 ** <blockquote><pre> 00971 ** Name | Age 00972 ** ----------------------- 00973 ** Alice | 43 00974 ** Bob | 28 00975 ** Cindy | 21 00976 ** </pre></blockquote> 00977 ** 00978 ** If the 3rd argument were &azResult then after the function returns 00979 ** azResult will contain the following data: 00980 ** 00981 ** <blockquote><pre> 00982 ** azResult[0] = "Name"; 00983 ** azResult[1] = "Age"; 00984 ** azResult[2] = "Alice"; 00985 ** azResult[3] = "43"; 00986 ** azResult[4] = "Bob"; 00987 ** azResult[5] = "28"; 00988 ** azResult[6] = "Cindy"; 00989 ** azResult[7] = "21"; 00990 ** </pre></blockquote> 00991 ** 00992 ** Notice that there is an extra row of data containing the column 00993 ** headers. But the *nrow return value is still 3. *ncolumn is 00994 ** set to 2. In general, the number of values inserted into azResult 00995 ** will be ((*nrow) + 1)*(*ncolumn). 00996 ** 00997 ** After the calling function has finished using the result, it should 00998 ** pass the result data pointer to sqlite3_free_table() in order to 00999 ** release the memory that was malloc-ed. Because of the way the 01000 ** [sqlite3_malloc()] happens, the calling function must not try to call 01001 ** [sqlite3_free()] directly. Only [sqlite3_free_table()] is able to release 01002 ** the memory properly and safely. 01003 ** 01004 ** The return value of this routine is the same as from [sqlite3_exec()]. 01005 */ 01006 int sqlite3_get_table( 01007 sqlite3*, /* An open database */ 01008 const char *sql, /* SQL to be executed */ 01009 char ***resultp, /* Result written to a char *[] that this points to */ 01010 int *nrow, /* Number of result rows written here */ 01011 int *ncolumn, /* Number of result columns written here */ 01012 char **errmsg /* Error msg written here */ 01013 ); 01014 void sqlite3_free_table(char **result); 01015 01016 /* 01017 ** CAPI3REF: Formatted String Printing Functions 01018 ** 01019 ** These routines are workalikes of the "printf()" family of functions 01020 ** from the standard C library. 01021 ** 01022 ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their 01023 ** results into memory obtained from [sqlite3_malloc()]. 01024 ** The strings returned by these two routines should be 01025 ** released by [sqlite3_free()]. Both routines return a 01026 ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough 01027 ** memory to hold the resulting string. 01028 ** 01029 ** In sqlite3_snprintf() routine is similar to "snprintf()" from 01030 ** the standard C library. The result is written into the 01031 ** buffer supplied as the second parameter whose size is given by 01032 ** the first parameter. Note that the order of the 01033 ** first two parameters is reversed from snprintf(). This is an 01034 ** historical accident that cannot be fixed without breaking 01035 ** backwards compatibility. Note also that sqlite3_snprintf() 01036 ** returns a pointer to its buffer instead of the number of 01037 ** characters actually written into the buffer. We admit that 01038 ** the number of characters written would be a more useful return 01039 ** value but we cannot change the implementation of sqlite3_snprintf() 01040 ** now without breaking compatibility. 01041 ** 01042 ** As long as the buffer size is greater than zero, sqlite3_snprintf() 01043 ** guarantees that the buffer is always zero-terminated. The first 01044 ** parameter "n" is the total size of the buffer, including space for 01045 ** the zero terminator. So the longest string that can be completely 01046 ** written will be n-1 characters. 01047 ** 01048 ** These routines all implement some additional formatting 01049 ** options that are useful for constructing SQL statements. 01050 ** All of the usual printf formatting options apply. In addition, there 01051 ** is are "%q", "%Q", and "%z" options. 01052 ** 01053 ** The %q option works like %s in that it substitutes a null-terminated 01054 ** string from the argument list. But %q also doubles every '\'' character. 01055 ** %q is designed for use inside a string literal. By doubling each '\'' 01056 ** character it escapes that character and allows it to be inserted into 01057 ** the string. 01058 ** 01059 ** For example, so some string variable contains text as follows: 01060 ** 01061 ** <blockquote><pre> 01062 ** char *zText = "It's a happy day!"; 01063 ** </pre></blockquote> 01064 ** 01065 ** One can use this text in an SQL statement as follows: 01066 ** 01067 ** <blockquote><pre> 01068 ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText); 01069 ** sqlite3_exec(db, zSQL, 0, 0, 0); 01070 ** sqlite3_free(zSQL); 01071 ** </pre></blockquote> 01072 ** 01073 ** Because the %q format string is used, the '\'' character in zText 01074 ** is escaped and the SQL generated is as follows: 01075 ** 01076 ** <blockquote><pre> 01077 ** INSERT INTO table1 VALUES('It''s a happy day!') 01078 ** </pre></blockquote> 01079 ** 01080 ** This is correct. Had we used %s instead of %q, the generated SQL 01081 ** would have looked like this: 01082 ** 01083 ** <blockquote><pre> 01084 ** INSERT INTO table1 VALUES('It's a happy day!'); 01085 ** </pre></blockquote> 01086 ** 01087 ** This second example is an SQL syntax error. As a general rule you 01088 ** should always use %q instead of %s when inserting text into a string 01089 ** literal. 01090 ** 01091 ** The %Q option works like %q except it also adds single quotes around 01092 ** the outside of the total string. Or if the parameter in the argument 01093 ** list is a NULL pointer, %Q substitutes the text "NULL" (without single 01094 ** quotes) in place of the %Q option. So, for example, one could say: 01095 ** 01096 ** <blockquote><pre> 01097 ** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText); 01098 ** sqlite3_exec(db, zSQL, 0, 0, 0); 01099 ** sqlite3_free(zSQL); 01100 ** </pre></blockquote> 01101 ** 01102 ** The code above will render a correct SQL statement in the zSQL 01103 ** variable even if the zText variable is a NULL pointer. 01104 ** 01105 ** The "%z" formatting option works exactly like "%s" with the 01106 ** addition that after the string has been read and copied into 01107 ** the result, [sqlite3_free()] is called on the input string. 01108 */ 01109 char *sqlite3_mprintf(const char*,...); 01110 char *sqlite3_vmprintf(const char*, va_list); 01111 char *sqlite3_snprintf(int,char*,const char*, ...); 01112 01113 /* 01114 ** CAPI3REF: Memory Allocation Subsystem 01115 ** 01116 ** The SQLite core uses these three routines for all of its own 01117 ** internal memory allocation needs. The default implementation 01118 ** of the memory allocation subsystem uses the malloc(), realloc() 01119 ** and free() provided by the standard C library. However, if 01120 ** SQLite is compiled with the following C preprocessor macro 01121 ** 01122 ** <blockquote> SQLITE_OMIT_MEMORY_ALLOCATION </blockquote> 01123 ** 01124 ** then no implementation is provided for these routines by 01125 ** SQLite. The application that links against SQLite is 01126 ** expected to provide its own implementation. If the application 01127 ** does provide its own implementation for these routines, then 01128 ** it must also provide an implementation for 01129 ** [sqlite3_memory_alarm()]. 01130 ** 01131 ** <b>Exception:</b> The windows OS interface layer calls 01132 ** the system malloc() and free() directly when converting 01133 ** filenames between the UTF-8 encoding used by SQLite 01134 ** and whatever filename encoding is used by the particular windows 01135 ** installation. Memory allocation errors are detected, but 01136 ** they are reported back as [SQLITE_CANTOPEN] or 01137 ** [SQLITE_IOERR] rather than [SQLITE_NOMEM]. 01138 */ 01139 void *sqlite3_malloc(int); 01140 void *sqlite3_realloc(void*, int); 01141 void sqlite3_free(void*); 01142 01143 /* 01144 ** CAPI3REF: Memory Allocator Statistics 01145 ** 01146 ** In addition to the basic three allocation routines 01147 ** [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()], 01148 ** the memory allocation subsystem included with the SQLite 01149 ** sources provides the interfaces shown below. 01150 ** 01151 ** The first of these two routines returns the amount of memory 01152 ** currently outstanding (malloced but not freed). The second 01153 ** returns the largest instantaneous amount of outstanding 01154 ** memory. The highwater mark is reset if the argument is 01155 ** true. The SQLite core does not use either of these routines 01156 ** and so they do not have to be implemented by the application 01157 ** if SQLITE_OMIT_MEMORY_ALLOCATION is defined. These routines 01158 ** are provided by the default memory subsystem for diagnostic 01159 ** purposes. 01160 */ 01161 sqlite3_int64 sqlite3_memory_used(void); 01162 sqlite3_int64 sqlite3_memory_highwater(int resetFlag); 01163 01164 /* 01165 ** CAPI3REF: Memory Allocation Alarms 01166 ** 01167 ** The [sqlite3_memory_alarm] routine is used to register 01168 ** a callback on memory allocation events. 01169 ** 01170 ** This routine registers or clears a callbacks that fires when 01171 ** the amount of memory allocated exceeds iThreshold. Only 01172 ** a single callback can be registered at a time. Each call 01173 ** to [sqlite3_memory_alarm()] overwrites the previous callback. 01174 ** The callback is disabled by setting xCallback to a NULL 01175 ** pointer. 01176 ** 01177 ** The parameters to the callback are the pArg value, the 01178 ** amount of memory currently in use, and the size of the 01179 ** allocation that provoked the callback. The callback will 01180 ** presumably invoke [sqlite3_free()] to free up memory space. 01181 ** The callback may invoke [sqlite3_malloc()] or [sqlite3_realloc()] 01182 ** but if it does, no additional callbacks will be invoked by 01183 ** the recursive calls. 01184 ** 01185 ** The [sqlite3_soft_heap_limit()] interface works by registering 01186 ** a memory alarm at the soft heap limit and invoking 01187 ** [sqlite3_release_memory()] in the alarm callback. Application 01188 ** programs should not attempt to use the [sqlite3_memory_alarm()] 01189 ** interface because doing so will interfere with the 01190 ** [sqlite3_soft_heap_limit()] module. This interface is exposed 01191 ** only so that applications can provide their own 01192 ** alternative implementation when the SQLite core is 01193 ** compiled with SQLITE_OMIT_MEMORY_ALLOCATION. 01194 */ 01195 int sqlite3_memory_alarm( 01196 void(*xCallback)(void *pArg, sqlite3_int64 used, int N), 01197 void *pArg, 01198 sqlite3_int64 iThreshold 01199 ); 01200 01201 01202 /* 01203 ** CAPI3REF: Compile-Time Authorization Callbacks 01204 *** 01205 ** This routine registers a authorizer callback with the SQLite library. 01206 ** The authorizer callback is invoked as SQL statements are being compiled 01207 ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()], 01208 ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various 01209 ** points during the compilation process, as logic is being created 01210 ** to perform various actions, the authorizer callback is invoked to 01211 ** see if those actions are allowed. The authorizer callback should 01212 ** return SQLITE_OK to allow the action, [SQLITE_IGNORE] to disallow the 01213 ** specific action but allow the SQL statement to continue to be 01214 ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be 01215 ** rejected with an error. 01216 ** 01217 ** Depending on the action, the [SQLITE_IGNORE] and [SQLITE_DENY] return 01218 ** codes might mean something different or they might mean the same 01219 ** thing. If the action is, for example, to perform a delete opertion, 01220 ** then [SQLITE_IGNORE] and [SQLITE_DENY] both cause the statement compilation 01221 ** to fail with an error. But if the action is to read a specific column 01222 ** from a specific table, then [SQLITE_DENY] will cause the entire 01223 ** statement to fail but [SQLITE_IGNORE] will cause a NULL value to be 01224 ** read instead of the actual column value. 01225 ** 01226 ** The first parameter to the authorizer callback is a copy of 01227 ** the third parameter to the sqlite3_set_authorizer() interface. 01228 ** The second parameter to the callback is an integer 01229 ** [SQLITE_COPY | action code] that specifies the particular action 01230 ** to be authorized. The available action codes are 01231 ** [SQLITE_COPY | documented separately]. The third through sixth 01232 ** parameters to the callback are strings that contain additional 01233 ** details about the action to be authorized. 01234 ** 01235 ** An authorizer is used when preparing SQL statements from an untrusted 01236 ** source, to ensure that the SQL statements do not try to access data 01237 ** that they are not allowed to see, or that they do not try to 01238 ** execute malicious statements that damage the database. For 01239 ** example, an application may allow a user to enter arbitrary 01240 ** SQL queries for evaluation by a database. But the application does 01241 ** not want the user to be able to make arbitrary changes to the 01242 ** database. An authorizer could then be put in place while the 01243 ** user-entered SQL is being prepared that disallows everything 01244 ** except SELECT statements. 01245 ** 01246 ** Only a single authorizer can be in place on a database connection 01247 ** at a time. Each call to sqlite3_set_authorizer overrides the 01248 ** previous call. A NULL authorizer means that no authorization 01249 ** callback is invoked. The default authorizer is NULL. 01250 ** 01251 ** Note that the authorizer callback is invoked only during 01252 ** [sqlite3_prepare()] or its variants. Authorization is not 01253 ** performed during statement evaluation in [sqlite3_step()]. 01254 */ 01255 int sqlite3_set_authorizer( 01256 sqlite3*, 01257 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), 01258 void *pUserData 01259 ); 01260 01261 /* 01262 ** CAPI3REF: Authorizer Return Codes 01263 ** 01264 ** The [sqlite3_set_authorizer | authorizer callback function] must 01265 ** return either [SQLITE_OK] or one of these two constants in order 01266 ** to signal SQLite whether or not the action is permitted. See the 01267 ** [sqlite3_set_authorizer | authorizer documentation] for additional 01268 ** information. 01269 */ 01270 #define SQLITE_DENY 1 /* Abort the SQL statement with an error */ 01271 #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ 01272 01273 /* 01274 ** CAPI3REF: Authorizer Action Codes 01275 ** 01276 ** The [sqlite3_set_authorizer()] interface registers a callback function 01277 ** that is invoked to authorizer certain SQL statement actions. The 01278 ** second parameter to the callback is an integer code that specifies 01279 ** what action is being authorized. These are the integer action codes that 01280 ** the authorizer callback may be passed. 01281 ** 01282 ** These action code values signify what kind of operation is to be 01283 ** authorized. The 3rd and 4th parameters to the authorization callback 01284 ** function will be parameters or NULL depending on which of these 01285 ** codes is used as the second parameter. The 5th parameter to the 01286 ** authorizer callback is the name of the database ("main", "temp", 01287 ** etc.) if applicable. The 6th parameter to the authorizer callback 01288 ** is the name of the inner-most trigger or view that is responsible for 01289 ** the access attempt or NULL if this access attempt is directly from 01290 ** top-level SQL code. 01291 */ 01292 /******************************************* 3rd ************ 4th ***********/ 01293 #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ 01294 #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */ 01295 #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */ 01296 #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */ 01297 #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */ 01298 #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */ 01299 #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */ 01300 #define SQLITE_CREATE_VIEW 8 /* View Name NULL */ 01301 #define SQLITE_DELETE 9 /* Table Name NULL */ 01302 #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */ 01303 #define SQLITE_DROP_TABLE 11 /* Table Name NULL */ 01304 #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */ 01305 #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */ 01306 #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */ 01307 #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */ 01308 #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */ 01309 #define SQLITE_DROP_VIEW 17 /* View Name NULL */ 01310 #define SQLITE_INSERT 18 /* Table Name NULL */ 01311 #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */ 01312 #define SQLITE_READ 20 /* Table Name Column Name */ 01313 #define SQLITE_SELECT 21 /* NULL NULL */ 01314 #define SQLITE_TRANSACTION 22 /* NULL NULL */ 01315 #define SQLITE_UPDATE 23 /* Table Name Column Name */ 01316 #define SQLITE_ATTACH 24 /* Filename NULL */ 01317 #define SQLITE_DETACH 25 /* Database Name NULL */ 01318 #define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */ 01319 #define SQLITE_REINDEX 27 /* Index Name NULL */ 01320 #define SQLITE_ANALYZE 28 /* Table Name NULL */ 01321 #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ 01322 #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ 01323 #define SQLITE_FUNCTION 31 /* Function Name NULL */ 01324 #define SQLITE_COPY 0 /* No longer used */ 01325 01326 /* 01327 ** CAPI3REF: Tracing And Profiling Functions 01328 ** 01329 ** These routines register callback functions that can be used for 01330 ** tracing and profiling the execution of SQL statements. 01331 ** The callback function registered by sqlite3_trace() is invoked 01332 ** at the first [sqlite3_step()] for the evaluation of an SQL statement. 01333 ** The callback function registered by sqlite3_profile() is invoked 01334 ** as each SQL statement finishes and includes 01335 ** information on how long that statement ran. 01336 ** 01337 ** The sqlite3_profile() API is currently considered experimental and 01338 ** is subject to change. 01339 */ 01340 void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); 01341 void *sqlite3_profile(sqlite3*, 01342 void(*xProfile)(void*,const char*,sqlite3_uint64), void*); 01343 01344 /* 01345 ** CAPI3REF: Query Progress Callbacks 01346 ** 01347 ** This routine configures a callback function - the progress callback - that 01348 ** is invoked periodically during long running calls to [sqlite3_exec()], 01349 ** [sqlite3_step()] and [sqlite3_get_table()]. An example use for this 01350 ** interface is to keep a GUI updated during a large query. 01351 ** 01352 ** The progress callback is invoked once for every N virtual machine opcodes, 01353 ** where N is the second argument to this function. The progress callback 01354 ** itself is identified by the third argument to this function. The fourth 01355 ** argument to this function is a void pointer passed to the progress callback 01356 ** function each time it is invoked. 01357 ** 01358 ** If a call to [sqlite3_exec()], [sqlite3_step()], or [sqlite3_get_table()] 01359 ** results in fewer than N opcodes being executed, then the progress 01360 ** callback is never invoked. 01361 ** 01362 ** Only a single progress callback function may be registered for each 01363 ** open database connection. Every call to sqlite3_progress_handler() 01364 ** overwrites the results of the previous call. 01365 ** To remove the progress callback altogether, pass NULL as the third 01366 ** argument to this function. 01367 ** 01368 ** If the progress callback returns a result other than 0, then the current 01369 ** query is immediately terminated and any database changes rolled back. 01370 ** The containing [sqlite3_exec()], [sqlite3_step()], or 01371 ** [sqlite3_get_table()] call returns SQLITE_INTERRUPT. This feature 01372 ** can be used, for example, to implement the "Cancel" button on a 01373 ** progress dialog box in a GUI. 01374 */ 01375 void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); 01376 01377 /* 01378 ** CAPI3REF: Opening A New Database Connection 01379 ** 01380 ** Open the sqlite database file "filename". The "filename" is UTF-8 01381 ** encoded for [sqlite3_open()] and [sqlite3_open_v2()] and UTF-16 encoded 01382 ** in the native byte order for [sqlite3_open16()]. 01383 ** An [sqlite3*] handle is returned in *ppDb, even 01384 ** if an error occurs. If the database is opened (or created) successfully, 01385 ** then [SQLITE_OK] is returned. Otherwise an error code is returned. The 01386 ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain 01387 ** an English language description of the error. 01388 ** 01389 ** The default encoding for the database will be UTF-8 if 01390 ** [sqlite3_open()] or [sqlite3_open_v2()] is called and 01391 ** UTF-16 if [sqlite3_open16()] is used. 01392 ** 01393 ** Whether or not an error occurs when it is opened, resources associated 01394 ** with the [sqlite3*] handle should be released by passing it to 01395 ** [sqlite3_close()] when it is no longer required. 01396 ** 01397 ** The [sqlite3_open_v2()] interface works like [sqlite3_open()] except that 01398 ** provides two additional parameters for additional control over the 01399 ** new database connection. The flags parameter can be one of: 01400 ** 01401 ** <ol> 01402 ** <li> [SQLITE_OPEN_READONLY] 01403 ** <li> [SQLITE_OPEN_READWRITE] 01404 ** <li> [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE] 01405 ** </ol> 01406 ** 01407 ** The first value opens the database read-only. If the database does 01408 ** not previously exist, an error is returned. The second option opens 01409 ** the database for reading and writing if possible, or reading only if 01410 ** if the file is write protected. In either case the database must already 01411 ** exist or an error is returned. The third option opens the database 01412 ** for reading and writing and creates it if it does not already exist. 01413 ** The third options is behavior that is always used for [sqlite3_open()] 01414 ** and [sqlite3_open16()]. 01415 ** 01416 ** If the filename is ":memory:", then an private 01417 ** in-memory database is created for the connection. This in-memory 01418 ** database will vanish when the database connection is closed. Future 01419 ** version of SQLite might make use of additional special filenames 01420 ** that begin with the ":" character. It is recommended that 01421 ** when a database filename really does begin with 01422 ** ":" that you prefix the filename with a pathname like "./" to 01423 ** avoid ambiguity. 01424 ** 01425 ** If the filename is an empty string, then a private temporary 01426 ** on-disk database will be created. This private database will be 01427 ** automatically deleted as soon as the database connection is closed. 01428 ** 01429 ** The fourth parameter to sqlite3_open_v2() is the name of the 01430 ** [sqlite3_vfs] object that defines the operating system 01431 ** interface that the new database connection should use. If the 01432 ** fourth parameter is a NULL pointer then the default [sqlite3_vfs] 01433 ** object is used. 01434 ** 01435 ** <b>Note to windows users:</b> The encoding used for the filename argument 01436 ** of [sqlite3_open()] and [sqlite3_open_v2()] must be UTF-8, not whatever 01437 ** codepage is currently defined. Filenames containing international 01438 ** characters must be converted to UTF-8 prior to passing them into 01439 ** [sqlite3_open()] or [sqlite3_open_v2()]. 01440 */ 01441 int sqlite3_open( 01442 const char *filename, /* Database filename (UTF-8) */ 01443 sqlite3 **ppDb /* OUT: SQLite db handle */ 01444 ); 01445 int sqlite3_open16( 01446 const void *filename, /* Database filename (UTF-16) */ 01447 sqlite3 **ppDb /* OUT: SQLite db handle */ 01448 ); 01449 int sqlite3_open_v2( 01450 const char *filename, /* Database filename (UTF-8) */ 01451 sqlite3 **ppDb, /* OUT: SQLite db handle */ 01452 int flags, /* Flags */ 01453 const char *zVfs /* Name of VFS module to use */ 01454 ); 01455 01456 /* 01457 ** CAPI3REF: Error Codes And Messages 01458 ** 01459 ** The sqlite3_errcode() interface returns the numeric 01460 ** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code] 01461 ** for the most recent failed sqlite3_* API call associated 01462 ** with [sqlite3] handle 'db'. If a prior API call failed but the 01463 ** most recent API call succeeded, the return value from sqlite3_errcode() 01464 ** is undefined. 01465 ** 01466 ** The sqlite3_errmsg() and sqlite3_errmsg16() return English-langauge 01467 ** text that describes the error, as either UTF8 or UTF16 respectively. 01468 ** Memory to hold the error message string is managed internally. The 01469 ** string may be overwritten or deallocated by subsequent calls to SQLite 01470 ** interface functions. 01471 ** 01472 ** Calls to many sqlite3_* functions set the error code and string returned 01473 ** by [sqlite3_errcode()], [sqlite3_errmsg()], and [sqlite3_errmsg16()] 01474 ** (overwriting the previous values). Note that calls to [sqlite3_errcode()], 01475 ** [sqlite3_errmsg()], and [sqlite3_errmsg16()] themselves do not affect the 01476 ** results of future invocations. Calls to API routines that do not return 01477 ** an error code (example: [sqlite3_data_count()]) do not 01478 ** change the error code returned by this routine. Interfaces that are 01479 ** not associated with a specific database connection (examples: 01480 ** [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()] do not change 01481 ** the return code. 01482 ** 01483 ** Assuming no other intervening sqlite3_* API calls are made, the error 01484 ** code returned by this function is associated with the same error as 01485 ** the strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()]. 01486 */ 01487 int sqlite3_errcode(sqlite3 *db); 01488 const char *sqlite3_errmsg(sqlite3*); 01489 const void *sqlite3_errmsg16(sqlite3*); 01490 01491 /* 01492 ** CAPI3REF: SQL Statement Object 01493 ** 01494 ** Instance of this object represent single SQL statements. This 01495 ** is variously known as a "prepared statement" or a 01496 ** "compiled SQL statement" or simply as a "statement". 01497 ** 01498 ** The life of a statement object goes something like this: 01499 ** 01500 ** <ol> 01501 ** <li> Create the object using [sqlite3_prepare_v2()] or a related 01502 ** function. 01503 ** <li> Bind values to host parameters using 01504 ** [sqlite3_bind_blob | sqlite3_bind_* interfaces]. 01505 ** <li> Run the SQL by calling [sqlite3_step()] one or more times. 01506 ** <li> Reset the statement using [sqlite3_reset()] then go back 01507 ** to step 2. Do this zero or more times. 01508 ** <li> Destroy the object using [sqlite3_finalize()]. 01509 ** </ol> 01510 ** 01511 ** Refer to documentation on individual methods above for additional 01512 ** information. 01513 */ 01514 typedef struct sqlite3_stmt sqlite3_stmt; 01515 01516 /* 01517 ** CAPI3REF: Compiling An SQL Statement 01518 ** 01519 ** To execute an SQL query, it must first be compiled into a byte-code 01520 ** program using one of these routines. 01521 ** 01522 ** The first argument "db" is an [sqlite3 | SQLite database handle] 01523 ** obtained from a prior call to [sqlite3_open()], [sqlite3_open_v2()] 01524 ** or [sqlite3_open16()]. 01525 ** The second argument "zSql" is the statement to be compiled, encoded 01526 ** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() 01527 ** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2() 01528 ** use UTF-16. 01529 ** 01530 ** If the nByte argument is less 01531 ** than zero, then zSql is read up to the first zero terminator. If 01532 ** nByte is non-negative, then it is the maximum number of 01533 ** bytes read from zSql. When nByte is non-negative, the 01534 ** zSql string ends at either the first '\000' character or 01535 ** until the nByte-th byte, whichever comes first. 01536 ** 01537 ** *pzTail is made to point to the first byte past the end of the first 01538 ** SQL statement in zSql. This routine only compiles the first statement 01539 ** in zSql, so *pzTail is left pointing to what remains uncompiled. 01540 ** 01541 ** *ppStmt is left pointing to a compiled 01542 ** [sqlite3_stmt | SQL statement structure] that can be 01543 ** executed using [sqlite3_step()]. Or if there is an error, *ppStmt may be 01544 ** set to NULL. If the input text contained no SQL (if the input is and 01545 ** empty string or a comment) then *ppStmt is set to NULL. The calling 01546 ** procedure is responsible for deleting the compiled SQL statement 01547 ** using [sqlite3_finalize()] after it has finished with it. 01548 ** 01549 ** On success, [SQLITE_OK] is returned. Otherwise an 01550 ** [SQLITE_ERROR | error code] is returned. 01551 ** 01552 ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are 01553 ** recommended for all new programs. The two older interfaces are retained 01554 ** for backwards compatibility, but their use is discouraged. 01555 ** In the "v2" interfaces, the prepared statement 01556 ** that is returned (the [sqlite3_stmt] object) contains a copy of the 01557 ** original SQL text. This causes the [sqlite3_step()] interface to 01558 ** behave a differently in two ways: 01559 ** 01560 ** <ol> 01561 ** <li> 01562 ** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it 01563 ** always used to do, [sqlite3_step()] will automatically recompile the SQL 01564 ** statement and try to run it again. If the schema has changed in a way 01565 ** that makes the statement no longer valid, [sqlite3_step()] will still 01566 ** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is 01567 ** now a fatal error. Calling [sqlite3_prepare_v2()] again will not make the 01568 ** error go away. Note: use [sqlite3_errmsg()] to find the text of the parsing 01569 ** error that results in an [SQLITE_SCHEMA] return. 01570 ** </li> 01571 ** 01572 ** <li> 01573 ** When an error occurs, 01574 ** [sqlite3_step()] will return one of the detailed 01575 ** [SQLITE_ERROR | result codes] or 01576 ** [SQLITE_IOERR_READ | extended result codes] such as directly. 01577 ** The legacy behavior was that [sqlite3_step()] would only return a generic 01578 ** [SQLITE_ERROR] result code and you would have to make a second call to 01579 ** [sqlite3_reset()] in order to find the underlying cause of the problem. 01580 ** With the "v2" prepare interfaces, the underlying reason for the error is 01581 ** returned immediately. 01582 ** </li> 01583 ** </ol> 01584 */ 01585 int sqlite3_prepare( 01586 sqlite3 *db, /* Database handle */ 01587 const char *zSql, /* SQL statement, UTF-8 encoded */ 01588 int nByte, /* Maximum length of zSql in bytes. */ 01589 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 01590 const char **pzTail /* OUT: Pointer to unused portion of zSql */ 01591 ); 01592 int sqlite3_prepare_v2( 01593 sqlite3 *db, /* Database handle */ 01594 const char *zSql, /* SQL statement, UTF-8 encoded */ 01595 int nByte, /* Maximum length of zSql in bytes. */ 01596 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 01597 const char **pzTail /* OUT: Pointer to unused portion of zSql */ 01598 ); 01599 int sqlite3_prepare16( 01600 sqlite3 *db, /* Database handle */ 01601 const void *zSql, /* SQL statement, UTF-16 encoded */ 01602 int nByte, /* Maximum length of zSql in bytes. */ 01603 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 01604 const void **pzTail /* OUT: Pointer to unused portion of zSql */ 01605 ); 01606 int sqlite3_prepare16_v2( 01607 sqlite3 *db, /* Database handle */ 01608 const void *zSql, /* SQL statement, UTF-16 encoded */ 01609 int nByte, /* Maximum length of zSql in bytes. */ 01610 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 01611 const void **pzTail /* OUT: Pointer to unused portion of zSql */ 01612 ); 01613 01614 /* 01615 ** CAPI3REF: Dynamically Typed Value Object 01616 ** 01617 ** SQLite uses dynamic typing for the values it stores. Values can 01618 ** be integers, floating point values, strings, BLOBs, or NULL. When 01619 ** passing around values internally, each value is represented as 01620 ** an instance of the sqlite3_value object. 01621 */ 01622 typedef struct Mem sqlite3_value; 01623 01624 /* 01625 ** CAPI3REF: SQL Function Context Object 01626 ** 01627 ** The context in which an SQL function executes is stored in an 01628 ** sqlite3_context object. A pointer to such an object is the 01629 ** first parameter to user-defined SQL functions. 01630 */ 01631 typedef struct sqlite3_context sqlite3_context; 01632 01633 /* 01634 ** CAPI3REF: Binding Values To Prepared Statements 01635 ** 01636 ** In the SQL strings input to [sqlite3_prepare_v2()] and its variants, 01637 ** one or more literals can be replace by a parameter in one of these 01638 ** forms: 01639 ** 01640 ** <ul> 01641 ** <li> ? 01642 ** <li> ?NNN 01643 ** <li> :AAA 01644 ** <li> @AAA 01645 ** <li> $VVV 01646 ** </ul> 01647 ** 01648 ** In the parameter forms shown above NNN is an integer literal, 01649 ** AAA is an alphanumeric identifier and VVV is a variable name according 01650 ** to the syntax rules of the TCL programming language. 01651 ** The values of these parameters (also called "host parameter names") 01652 ** can be set using the sqlite3_bind_*() routines defined here. 01653 ** 01654 ** The first argument to the sqlite3_bind_*() routines always is a pointer 01655 ** to the [sqlite3_stmt] object returned from [sqlite3_prepare_v2()] or 01656 ** its variants. The second 01657 ** argument is the index of the parameter to be set. The first parameter has 01658 ** an index of 1. When the same named parameter is used more than once, second 01659 ** and subsequent 01660 ** occurrences have the same index as the first occurrence. The index for 01661 ** named parameters can be looked up using the 01662 ** [sqlite3_bind_parameter_name()] API if desired. The index for "?NNN" 01663 ** parametes is the value of NNN. 01664 ** The NNN value must be between 1 and the compile-time 01665 ** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999). 01666 ** See <a href="limits.html">limits.html</a> for additional information. 01667 ** 01668 ** The third argument is the value to bind to the parameter. 01669 ** 01670 ** In those 01671 ** routines that have a fourth argument, its value is the number of bytes 01672 ** in the parameter. To be clear: the value is the number of bytes in the 01673 ** string, not the number of characters. The number 01674 ** of bytes does not include the zero-terminator at the end of strings. 01675 ** If the fourth parameter is negative, the length of the string is 01676 ** number of bytes up to the first zero terminator. 01677 ** 01678 ** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and 01679 ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or 01680 ** text after SQLite has finished with it. If the fifth argument is the 01681 ** special value [SQLITE_STATIC], then the library assumes that the information 01682 ** is in static, unmanaged space and does not need to be freed. If the 01683 ** fifth argument has the value [SQLITE_TRANSIENT], then SQLite makes its 01684 ** own private copy of the data immediately, before the sqlite3_bind_*() 01685 ** routine returns. 01686 ** 01687 ** The sqlite3_bind_zeroblob() routine binds a BLOB of length n that 01688 ** is filled with zeros. A zeroblob uses a fixed amount of memory 01689 ** (just an integer to hold it size) while it is being processed. 01690 ** Zeroblobs are intended to serve as place-holders for BLOBs whose 01691 ** content is later written using 01692 ** [sqlite3_blob_open | increment BLOB I/O] routines. 01693 ** 01694 ** The sqlite3_bind_*() routines must be called after 01695 ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and 01696 ** before [sqlite3_step()]. 01697 ** Bindings are not cleared by the [sqlite3_reset()] routine. 01698 ** Unbound parameters are interpreted as NULL. 01699 ** 01700 ** These routines return [SQLITE_OK] on success or an error code if 01701 ** anything goes wrong. [SQLITE_RANGE] is returned if the parameter 01702 ** index is out of range. [SQLITE_NOMEM] is returned if malloc fails. 01703 ** [SQLITE_MISUSE] is returned if these routines are called on a virtual 01704 ** machine that is the wrong state or which has already been finalized. 01705 */ 01706 int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); 01707 int sqlite3_bind_double(sqlite3_stmt*, int, double); 01708 int sqlite3_bind_int(sqlite3_stmt*, int, int); 01709 int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); 01710 int sqlite3_bind_null(sqlite3_stmt*, int); 01711 int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); 01712 int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); 01713 int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); 01714 int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); 01715 01716 /* 01717 ** CAPI3REF: Number Of Host Parameters 01718 ** 01719 ** Return the largest host parameter index in the precompiled statement given 01720 ** as the argument. When the host parameters are of the forms like ":AAA" 01721 ** or "?", then they are assigned sequential increasing numbers beginning 01722 ** with one, so the value returned is the number of parameters. However 01723 ** if the same host parameter name is used multiple times, each occurrance 01724 ** is given the same number, so the value returned in that case is the number 01725 ** of unique host parameter names. If host parameters of the form "?NNN" 01726 ** are used (where NNN is an integer) then there might be gaps in the 01727 ** numbering and the value returned by this interface is the index of the 01728 ** host parameter with the largest index value. 01729 ** 01730 ** The prepared statement must not be [sqlite3_finalize | finalized] 01731 ** prior to this routine returnning. Otherwise the results are undefined 01732 ** and probably undesirable. 01733 */ 01734 int sqlite3_bind_parameter_count(sqlite3_stmt*); 01735 01736 /* 01737 ** CAPI3REF: Name Of A Host Parameter 01738 ** 01739 ** This routine returns a pointer to the name of the n-th parameter in a 01740 ** [sqlite3_stmt | prepared statement]. 01741 ** Host parameters of the form ":AAA" or "@AAA" or "$VVV" have a name 01742 ** which is the string ":AAA" or "@AAA" or "$VVV". 01743 ** In other words, the initial ":" or "$" or "@" 01744 ** is included as part of the name. 01745 ** Parameters of the form "?" or "?NNN" have no name. 01746 ** 01747 ** The first bound parameter has an index of 1, not 0. 01748 ** 01749 ** If the value n is out of range or if the n-th parameter is nameless, 01750 ** then NULL is returned. The returned string is always in the 01751 ** UTF-8 encoding even if the named parameter was originally specified 01752 ** as UTF-16 in [sqlite3_prepare16()] or [sqlite3_prepare16_v2()]. 01753 */ 01754 const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); 01755 01756 /* 01757 ** CAPI3REF: Index Of A Parameter With A Given Name 01758 ** 01759 ** This routine returns the index of a host parameter with the given name. 01760 ** The name must match exactly. If no parameter with the given name is 01761 ** found, return 0. Parameter names must be UTF8. 01762 */ 01763 int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); 01764 01765 /* 01766 ** CAPI3REF: Reset All Bindings On A Prepared Statement 01767 ** 01768 ** Contrary to the intuition of many, [sqlite3_reset()] does not 01769 ** reset the [sqlite3_bind_blob | bindings] on a 01770 ** [sqlite3_stmt | prepared statement]. Use this routine to 01771 ** reset all host parameters to NULL. 01772 */ 01773 int sqlite3_clear_bindings(sqlite3_stmt*); 01774 01775 /* 01776 ** CAPI3REF: Number Of Columns In A Result Set 01777 ** 01778 ** Return the number of columns in the result set returned by the 01779 ** [sqlite3_stmt | compiled SQL statement]. This routine returns 0 01780 ** if pStmt is an SQL statement that does not return data (for 01781 ** example an UPDATE). 01782 */ 01783 int sqlite3_column_count(sqlite3_stmt *pStmt); 01784 01785 /* 01786 ** CAPI3REF: Column Names In A Result Set 01787 ** 01788 ** These routines return the name assigned to a particular column 01789 ** in the result set of a SELECT statement. The sqlite3_column_name() 01790 ** interface returns a pointer to a UTF8 string and sqlite3_column_name16() 01791 ** returns a pointer to a UTF16 string. The first parameter is the 01792 ** [sqlite3_stmt | prepared statement] that implements the SELECT statement. 01793 ** The second parameter is the column number. The left-most column is 01794 ** number 0. 01795 ** 01796 ** The returned string pointer is valid until either the 01797 ** [sqlite3_stmt | prepared statement] is destroyed by [sqlite3_finalize()] 01798 ** or until the next call sqlite3_column_name() or sqlite3_column_name16() 01799 ** on the same column. 01800 ** 01801 ** If sqlite3_malloc() fails during the processing of either routine 01802 ** (for example during a conversion from UTF-8 to UTF-16) then a 01803 ** NULL pointer is returned. 01804 */ 01805 const char *sqlite3_column_name(sqlite3_stmt*, int N); 01806 const void *sqlite3_column_name16(sqlite3_stmt*, int N); 01807 01808 /* 01809 ** CAPI3REF: Source Of Data In A Query Result 01810 ** 01811 ** These routines provide a means to determine what column of what 01812 ** table in which database a result of a SELECT statement comes from. 01813 ** The name of the database or table or column can be returned as 01814 ** either a UTF8 or UTF16 string. The _database_ routines return 01815 ** the database name, the _table_ routines return the table name, and 01816 ** the origin_ routines return the column name. 01817 ** The returned string is valid until 01818 ** the [sqlite3_stmt | prepared statement] is destroyed using 01819 ** [sqlite3_finalize()] or until the same information is requested 01820 ** again in a different encoding. 01821 ** 01822 ** The names returned are the original un-aliased names of the 01823 ** database, table, and column. 01824 ** 01825 ** The first argument to the following calls is a 01826 ** [sqlite3_stmt | compiled SQL statement]. 01827 ** These functions return information about the Nth column returned by 01828 ** the statement, where N is the second function argument. 01829 ** 01830 ** If the Nth column returned by the statement is an expression 01831 ** or subquery and is not a column value, then all of these functions 01832 ** return NULL. Otherwise, they return the 01833 ** name of the attached database, table and column that query result 01834 ** column was extracted from. 01835 ** 01836 ** As with all other SQLite APIs, those postfixed with "16" return UTF-16 01837 ** encoded strings, the other functions return UTF-8. 01838 ** 01839 ** These APIs are only available if the library was compiled with the 01840 ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. 01841 ** 01842 ** If two or more threads call one or more of these routines against the same 01843 ** prepared statement and column at the same time then the results are 01844 ** undefined. 01845 */ 01846 const char *sqlite3_column_database_name(sqlite3_stmt*,int); 01847 const void *sqlite3_column_database_name16(sqlite3_stmt*,int); 01848 const char *sqlite3_column_table_name(sqlite3_stmt*,int); 01849 const void *sqlite3_column_table_name16(sqlite3_stmt*,int); 01850 const char *sqlite3_column_origin_name(sqlite3_stmt*,int); 01851 const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); 01852 01853 /* 01854 ** CAPI3REF: Declared Datatype Of A Query Result 01855 ** 01856 ** The first parameter is a [sqlite3_stmt | compiled SQL statement]. 01857 ** If this statement is a SELECT statement and the Nth column of the 01858 ** returned result set of that SELECT is a table column (not an 01859 ** expression or subquery) then the declared type of the table 01860 ** column is returned. If the Nth column of the result set is an 01861 ** expression or subquery, then a NULL pointer is returned. 01862 ** The returned string is always UTF-8 encoded. For example, in 01863 ** the database schema: 01864 ** 01865 ** CREATE TABLE t1(c1 VARIANT); 01866 ** 01867 ** And the following statement compiled: 01868 ** 01869 ** SELECT c1 + 1, c1 FROM t1; 01870 ** 01871 ** Then this routine would return the string "VARIANT" for the second 01872 ** result column (i==1), and a NULL pointer for the first result column 01873 ** (i==0). 01874 ** 01875 ** SQLite uses dynamic run-time typing. So just because a column 01876 ** is declared to contain a particular type does not mean that the 01877 ** data stored in that column is of the declared type. SQLite is 01878 ** strongly typed, but the typing is dynamic not static. Type 01879 ** is associated with individual values, not with the containers 01880 ** used to hold those values. 01881 */ 01882 const char *sqlite3_column_decltype(sqlite3_stmt *, int i); 01883 const void *sqlite3_column_decltype16(sqlite3_stmt*,int); 01884 01885 /* 01886 ** CAPI3REF: Evaluate An SQL Statement 01887 ** 01888 ** After an [sqlite3_stmt | SQL statement] has been prepared with a call 01889 ** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of 01890 ** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], 01891 ** then this function must be called one or more times to evaluate the 01892 ** statement. 01893 ** 01894 ** The details of the behavior of this sqlite3_step() interface depend 01895 ** on whether the statement was prepared using the newer "v2" interface 01896 ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy 01897 ** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the 01898 ** new "v2" interface is recommended for new applications but the legacy 01899 ** interface will continue to be supported. 01900 ** 01901 ** In the lagacy interface, the return value will be either [SQLITE_BUSY], 01902 ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE]. 01903 ** With the "v2" interface, any of the other [SQLITE_OK | result code] 01904 ** or [SQLITE_IOERR_READ | extended result code] might be returned as 01905 ** well. 01906 ** 01907 ** [SQLITE_BUSY] means that the database engine was unable to acquire the 01908 ** database locks it needs to do its job. If the statement is a COMMIT 01909 ** or occurs outside of an explicit transaction, then you can retry the 01910 ** statement. If the statement is not a COMMIT and occurs within a 01911 ** explicit transaction then you should rollback the transaction before 01912 ** continuing. 01913 ** 01914 ** [SQLITE_DONE] means that the statement has finished executing 01915 ** successfully. sqlite3_step() should not be called again on this virtual 01916 ** machine without first calling [sqlite3_reset()] to reset the virtual 01917 ** machine back to its initial state. 01918 ** 01919 ** If the SQL statement being executed returns any data, then 01920 ** [SQLITE_ROW] is returned each time a new row of data is ready 01921 ** for processing by the caller. The values may be accessed using 01922 ** the [sqlite3_column_int | column access functions]. 01923 ** sqlite3_step() is called again to retrieve the next row of data. 01924 ** 01925 ** [SQLITE_ERROR] means that a run-time error (such as a constraint 01926 ** violation) has occurred. sqlite3_step() should not be called again on 01927 ** the VM. More information may be found by calling [sqlite3_errmsg()]. 01928 ** With the legacy interface, a more specific error code (example: 01929 ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth) 01930 ** can be obtained by calling [sqlite3_reset()] on the 01931 ** [sqlite3_stmt | prepared statement]. In the "v2" interface, 01932 ** the more specific error code is returned directly by sqlite3_step(). 01933 ** 01934 ** [SQLITE_MISUSE] means that the this routine was called inappropriately. 01935 ** Perhaps it was called on a [sqlite3_stmt | prepared statement] that has 01936 ** already been [sqlite3_finalize | finalized] or on one that had 01937 ** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could 01938 ** be the case that the same database connection is being used by two or 01939 ** more threads at the same moment in time. 01940 ** 01941 ** <b>Goofy Interface Alert:</b> 01942 ** In the legacy interface, 01943 ** the sqlite3_step() API always returns a generic error code, 01944 ** [SQLITE_ERROR], following any error other than [SQLITE_BUSY] 01945 ** and [SQLITE_MISUSE]. You must call [sqlite3_reset()] or 01946 ** [sqlite3_finalize()] in order to find one of the specific 01947 ** [SQLITE_ERROR | result codes] that better describes the error. 01948 ** We admit that this is a goofy design. The problem has been fixed 01949 ** with the "v2" interface. If you prepare all of your SQL statements 01950 ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead 01951 ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the 01952 ** more specific [SQLITE_ERROR | result codes] are returned directly 01953 ** by sqlite3_step(). The use of the "v2" interface is recommended. 01954 */ 01955 int sqlite3_step(sqlite3_stmt*); 01956 01957 /* 01958 ** CAPI3REF: 01959 ** 01960 ** Return the number of values in the current row of the result set. 01961 ** 01962 ** After a call to [sqlite3_step()] that returns [SQLITE_ROW], this routine 01963 ** will return the same value as the [sqlite3_column_count()] function. 01964 ** After [sqlite3_step()] has returned an [SQLITE_DONE], [SQLITE_BUSY], or 01965 ** a [SQLITE_ERROR | error code], or before [sqlite3_step()] has been 01966 ** called on the [sqlite3_stmt | prepared statement] for the first time, 01967 ** this routine returns zero. 01968 */ 01969 int sqlite3_data_count(sqlite3_stmt *pStmt); 01970 01971 /* 01972 ** CAPI3REF: Fundamental Datatypes 01973 ** 01974 ** Every value in SQLite has one of five fundamental datatypes: 01975 ** 01976 ** <ul> 01977 ** <li> 64-bit signed integer 01978 ** <li> 64-bit IEEE floating point number 01979 ** <li> string 01980 ** <li> BLOB 01981 ** <li> NULL 01982 ** </ul> 01983 ** 01984 ** These constants are codes for each of those types. 01985 ** 01986 ** Note that the SQLITE_TEXT constant was also used in SQLite version 2 01987 ** for a completely different meaning. Software that links against both 01988 ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT not 01989 ** SQLITE_TEXT. 01990 */ 01991 #define SQLITE_INTEGER 1 01992 #define SQLITE_FLOAT 2 01993 #define SQLITE_BLOB 4 01994 #define SQLITE_NULL 5 01995 #ifdef SQLITE_TEXT 01996 # undef SQLITE_TEXT 01997 #else 01998 # define SQLITE_TEXT 3 01999 #endif 02000 #define SQLITE3_TEXT 3 02001 02002 /* 02003 ** CAPI3REF: Results Values From A Query 02004 ** 02005 ** These routines return information about 02006 ** a single column of the current result row of a query. In every 02007 ** case the first argument is a pointer to the 02008 ** [sqlite3_stmt | SQL statement] that is being 02009 ** evaluated (the [sqlite3_stmt*] that was returned from 02010 ** [sqlite3_prepare_v2()] or one of its variants) and 02011 ** the second argument is the index of the column for which information 02012 ** should be returned. The left-most column of the result set 02013 ** has an index of 0. 02014 ** 02015 ** If the SQL statement is not currently point to a valid row, or if the 02016 ** the column index is out of range, the result is undefined. 02017 ** These routines may only be called when the most recent call to 02018 ** [sqlite3_step()] has returned [SQLITE_ROW] and neither 02019 ** [sqlite3_reset()] nor [sqlite3_finalize()] has been call subsequently. 02020 ** If any of these routines are called after [sqlite3_reset()] or 02021 ** [sqlite3_finalize()] or after [sqlite3_step()] has returned 02022 ** something other than [SQLITE_ROW], the results are undefined. 02023 ** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()] 02024 ** are called from a different thread while any of these routines 02025 ** are pending, then the results are undefined. 02026 ** 02027 ** The sqlite3_column_type() routine returns 02028 ** [SQLITE_INTEGER | datatype code] for the initial data type 02029 ** of the result column. The returned value is one of [SQLITE_INTEGER], 02030 ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value 02031 ** returned by sqlite3_column_type() is only meaningful if no type 02032 ** conversions have occurred as described below. After a type conversion, 02033 ** the value returned by sqlite3_column_type() is undefined. Future 02034 ** versions of SQLite may change the behavior of sqlite3_column_type() 02035 ** following a type conversion. 02036 ** 02037 ** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() 02038 ** routine returns the number of bytes in that BLOB or string. 02039 ** If the result is a UTF-16 string, then sqlite3_column_bytes() converts 02040 ** the string to UTF-8 and then returns the number of bytes. 02041 ** If the result is a numeric value then sqlite3_column_bytes() uses 02042 ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns 02043 ** the number of bytes in that string. 02044 ** The value returned does not include the zero terminator at the end 02045 ** of the string. For clarity: the value returned is the number of 02046 ** bytes in the string, not the number of characters. 02047 ** 02048 ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes() 02049 ** but leaves the result in UTF-16 instead of UTF-8. 02050 ** The zero terminator is not included in this count. 02051 ** 02052 ** These routines attempt to convert the value where appropriate. For 02053 ** example, if the internal representation is FLOAT and a text result 02054 ** is requested, [sqlite3_snprintf()] is used internally to do the conversion 02055 ** automatically. The following table details the conversions that 02056 ** are applied: 02057 ** 02058 ** <blockquote> 02059 ** <table border="1"> 02060 ** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion 02061 ** 02062 ** <tr><td> NULL <td> INTEGER <td> Result is 0 02063 ** <tr><td> NULL <td> FLOAT <td> Result is 0.0 02064 ** <tr><td> NULL <td> TEXT <td> Result is NULL pointer 02065 ** <tr><td> NULL <td> BLOB <td> Result is NULL pointer 02066 ** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float 02067 ** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer 02068 ** <tr><td> INTEGER <td> BLOB <td> Same as for INTEGER->TEXT 02069 ** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer 02070 ** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float 02071 ** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT 02072 ** <tr><td> TEXT <td> INTEGER <td> Use atoi() 02073 ** <tr><td> TEXT <td> FLOAT <td> Use atof() 02074 ** <tr><td> TEXT <td> BLOB <td> No change 02075 ** <tr><td> BLOB <td> INTEGER <td> Convert to TEXT then use atoi() 02076 ** <tr><td> BLOB <td> FLOAT <td> Convert to TEXT then use atof() 02077 ** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed 02078 ** </table> 02079 ** </blockquote> 02080 ** 02081 ** The table above makes reference to standard C library functions atoi() 02082 ** and atof(). SQLite does not really use these functions. It has its 02083 ** on equavalent internal routines. The atoi() and atof() names are 02084 ** used in the table for brevity and because they are familiar to most 02085 ** C programmers. 02086 ** 02087 ** Note that when type conversions occur, pointers returned by prior 02088 ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or 02089 ** sqlite3_column_text16() may be invalidated. 02090 ** Type conversions and pointer invalidations might occur 02091 ** in the following cases: 02092 ** 02093 ** <ul> 02094 ** <li><p> The initial content is a BLOB and sqlite3_column_text() 02095 ** or sqlite3_column_text16() is called. A zero-terminator might 02096 ** need to be added to the string.</p></li> 02097 ** 02098 ** <li><p> The initial content is UTF-8 text and sqlite3_column_bytes16() or 02099 ** sqlite3_column_text16() is called. The content must be converted 02100 ** to UTF-16.</p></li> 02101 ** 02102 ** <li><p> The initial content is UTF-16 text and sqlite3_column_bytes() or 02103 ** sqlite3_column_text() is called. The content must be converted 02104 ** to UTF-8.</p></li> 02105 ** </ul> 02106 ** 02107 ** Conversions between UTF-16be and UTF-16le are always done in place and do 02108 ** not invalidate a prior pointer, though of course the content of the buffer 02109 ** that the prior pointer points to will have been modified. Other kinds 02110 ** of conversion are done in place when it is possible, but sometime it is 02111 ** not possible and in those cases prior pointers are invalidated. 02112 ** 02113 ** The safest and easiest to remember policy is to invoke these routines 02114 ** in one of the following ways: 02115 ** 02116 ** <ul> 02117 ** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li> 02118 ** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li> 02119 ** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li> 02120 ** </ul> 02121 ** 02122 ** In other words, you should call sqlite3_column_text(), sqlite3_column_blob(), 02123 ** or sqlite3_column_text16() first to force the result into the desired 02124 ** format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to 02125 ** find the size of the result. Do not mix call to sqlite3_column_text() or 02126 ** sqlite3_column_blob() with calls to sqlite3_column_bytes16(). And do not 02127 ** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes(). 02128 ** 02129 ** The pointers returned are valid until a type conversion occurs as 02130 ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or 02131 ** [sqlite3_finalize()] is called. The memory space used to hold strings 02132 ** and blobs is freed automatically. Do <b>not</b> pass the pointers returned 02133 ** [sqlite3_column_blob()], [sqlite_column_text()], etc. into 02134 ** [sqlite3_free()]. 02135 ** 02136 ** If a memory allocation error occurs during the evaluation of any 02137 ** of these routines, a default value is returned. The default value 02138 ** is either the integer 0, the floating point number 0.0, or a NULL 02139 ** pointer. Subsequent calls to [sqlite3_errcode()] will return 02140 ** [SQLITE_NOMEM]. 02141 */ 02142 const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); 02143 int sqlite3_column_bytes(sqlite3_stmt*, int iCol); 02144 int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); 02145 double sqlite3_column_double(sqlite3_stmt*, int iCol); 02146 int sqlite3_column_int(sqlite3_stmt*, int iCol); 02147 sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); 02148 const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); 02149 const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); 02150 int sqlite3_column_type(sqlite3_stmt*, int iCol); 02151 sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); 02152 02153 /* 02154 ** CAPI3REF: Destroy A Prepared Statement Object 02155 ** 02156 ** The sqlite3_finalize() function is called to delete a 02157 ** [sqlite3_stmt | compiled SQL statement]. If the statement was 02158 ** executed successfully, or not executed at all, then SQLITE_OK is returned. 02159 ** If execution of the statement failed then an 02160 ** [SQLITE_ERROR | error code] or [SQLITE_IOERR_READ | extended error code] 02161 ** is returned. 02162 ** 02163 ** This routine can be called at any point during the execution of the 02164 ** [sqlite3_stmt | virtual machine]. If the virtual machine has not 02165 ** completed execution when this routine is called, that is like 02166 ** encountering an error or an interrupt. (See [sqlite3_interrupt()].) 02167 ** Incomplete updates may be rolled back and transactions cancelled, 02168 ** depending on the circumstances, and the 02169 ** [SQLITE_ERROR | result code] returned will be [SQLITE_ABORT]. 02170 */ 02171 int sqlite3_finalize(sqlite3_stmt *pStmt); 02172 02173 /* 02174 ** CAPI3REF: Reset A Prepared Statement Object 02175 ** 02176 ** The sqlite3_reset() function is called to reset a 02177 ** [sqlite3_stmt | compiled SQL statement] object. 02178 ** back to it's initial state, ready to be re-executed. 02179 ** Any SQL statement variables that had values bound to them using 02180 ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values. 02181 ** Use [sqlite3_clear_bindings()] to reset the bindings. 02182 */ 02183 int sqlite3_reset(sqlite3_stmt *pStmt); 02184 02185 /* 02186 ** CAPI3REF: Create Or Redefine SQL Functions 02187 ** 02188 ** The following two functions are used to add SQL functions or aggregates 02189 ** or to redefine the behavior of existing SQL functions or aggregates. The 02190 ** difference only between the two is that the second parameter, the 02191 ** name of the (scalar) function or aggregate, is encoded in UTF-8 for 02192 ** sqlite3_create_function() and UTF-16 for sqlite3_create_function16(). 02193 ** 02194 ** The first argument is the [sqlite3 | database handle] that holds the 02195 ** SQL function or aggregate is to be added or redefined. If a single 02196 ** program uses more than one database handle internally, then SQL 02197 ** functions or aggregates must be added individually to each database 02198 ** handle with which they will be used. 02199 ** 02200 ** The second parameter is the name of the SQL function to be created 02201 ** or redefined. 02202 ** The length of the name is limited to 255 bytes, exclusive of the 02203 ** zero-terminator. Note that the name length limit is in bytes, not 02204 ** characters. Any attempt to create a function with a longer name 02205 ** will result in an SQLITE_ERROR error. 02206 ** 02207 ** The third parameter is the number of arguments that the SQL function or 02208 ** aggregate takes. If this parameter is negative, then the SQL function or 02209 ** aggregate may take any number of arguments. 02210 ** 02211 ** The fourth parameter, eTextRep, specifies what 02212 ** [SQLITE_UTF8 | text encoding] this SQL function prefers for 02213 ** its parameters. Any SQL function implementation should be able to work 02214 ** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be 02215 ** more efficient with one encoding than another. It is allowed to 02216 ** invoke sqlite3_create_function() or sqlite3_create_function16() multiple 02217 ** times with the same function but with different values of eTextRep. 02218 ** When multiple implementations of the same function are available, SQLite 02219 ** will pick the one that involves the least amount of data conversion. 02220 ** If there is only a single implementation which does not care what 02221 ** text encoding is used, then the fourth argument should be 02222 ** [SQLITE_ANY]. 02223 ** 02224 ** The fifth parameter is an arbitrary pointer. The implementation 02225 ** of the function can gain access to this pointer using 02226 ** [sqlite3_user_data()]. 02227 ** 02228 ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are 02229 ** pointers to C-language functions that implement the SQL 02230 ** function or aggregate. A scalar SQL function requires an implementation of 02231 ** the xFunc callback only, NULL pointers should be passed as the xStep 02232 ** and xFinal parameters. An aggregate SQL function requires an implementation 02233 ** of xStep and xFinal and NULL should be passed for xFunc. To delete an 02234 ** existing SQL function or aggregate, pass NULL for all three function 02235 ** callback. 02236 ** 02237 ** It is permitted to register multiple implementations of the same 02238 ** functions with the same name but with either differing numbers of 02239 ** arguments or differing perferred text encodings. SQLite will use 02240 ** the implementation most closely matches the way in which the 02241 ** SQL function is used. 02242 */ 02243 int sqlite3_create_function( 02244 sqlite3 *, 02245 const char *zFunctionName, 02246 int nArg, 02247 int eTextRep, 02248 void*, 02249 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 02250 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 02251 void (*xFinal)(sqlite3_context*) 02252 ); 02253 int sqlite3_create_function16( 02254 sqlite3*, 02255 const void *zFunctionName, 02256 int nArg, 02257 int eTextRep, 02258 void*, 02259 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 02260 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 02261 void (*xFinal)(sqlite3_context*) 02262 ); 02263 02264 /* 02265 ** CAPI3REF: Text Encodings 02266 ** 02267 ** These constant define integer codes that represent the various 02268 ** text encodings supported by SQLite. 02269 */ 02270 #define SQLITE_UTF8 1 02271 #define SQLITE_UTF16LE 2 02272 #define SQLITE_UTF16BE 3 02273 #define SQLITE_UTF16 4 /* Use native byte order */ 02274 #define SQLITE_ANY 5 /* sqlite3_create_function only */ 02275 #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ 02276 02277 /* 02278 ** CAPI3REF: Obsolete Functions 02279 ** 02280 ** These functions are all now obsolete. In order to maintain 02281 ** backwards compatibility with older code, we continue to support 02282 ** these functions. However, new development projects should avoid 02283 ** the use of these functions. To help encourage people to avoid 02284 ** using these functions, we are not going to tell you want they do. 02285 */ 02286 int sqlite3_aggregate_count(sqlite3_context*); 02287 int sqlite3_expired(sqlite3_stmt*); 02288 int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); 02289 int sqlite3_global_recover(void); 02290 void sqlite3_thread_cleanup(void); 02291 02292 /* 02293 ** CAPI3REF: Obtaining SQL Function Parameter Values 02294 ** 02295 ** The C-language implementation of SQL functions and aggregates uses 02296 ** this set of interface routines to access the parameter values on 02297 ** the function or aggregate. 02298 ** 02299 ** The xFunc (for scalar functions) or xStep (for aggregates) parameters 02300 ** to [sqlite3_create_function()] and [sqlite3_create_function16()] 02301 ** define callbacks that implement the SQL functions and aggregates. 02302 ** The 4th parameter to these callbacks is an array of pointers to 02303 ** [sqlite3_value] objects. There is one [sqlite3_value] object for 02304 ** each parameter to the SQL function. These routines are used to 02305 ** extract values from the [sqlite3_value] objects. 02306 ** 02307 ** These routines work just like the corresponding 02308 ** [sqlite3_column_blob | sqlite3_column_* routines] except that 02309 ** these routines take a single [sqlite3_value*] pointer instead 02310 ** of an [sqlite3_stmt*] pointer and an integer column number. 02311 ** 02312 ** The sqlite3_value_text16() interface extracts a UTF16 string 02313 ** in the native byte-order of the host machine. The 02314 ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces 02315 ** extract UTF16 strings as big-endian and little-endian respectively. 02316 ** 02317 ** The sqlite3_value_numeric_type() interface attempts to apply 02318 ** numeric affinity to the value. This means that an attempt is 02319 ** made to convert the value to an integer or floating point. If 02320 ** such a conversion is possible without loss of information (in order 02321 ** words if the value is original a string that looks like a number) 02322 ** then it is done. Otherwise no conversion occurs. The 02323 ** [SQLITE_INTEGER | datatype] after conversion is returned. 02324 ** 02325 ** Please pay particular attention to the fact that the pointer that 02326 ** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or 02327 ** [sqlite3_value_text16()] can be invalidated by a subsequent call to 02328 ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()], 02329 ** or [sqlite3_value_text16()]. 02330 ** 02331 ** These routines must be called from the same thread as 02332 ** the SQL function that supplied the sqlite3_value* parameters. 02333 ** Or, if the sqlite3_value* argument comes from the [sqlite3_column_value()] 02334 ** interface, then these routines should be called from the same thread 02335 ** that ran [sqlite3_column_value()]. 02336 */ 02337 const void *sqlite3_value_blob(sqlite3_value*); 02338 int sqlite3_value_bytes(sqlite3_value*); 02339 int sqlite3_value_bytes16(sqlite3_value*); 02340 double sqlite3_value_double(sqlite3_value*); 02341 int sqlite3_value_int(sqlite3_value*); 02342 sqlite3_int64 sqlite3_value_int64(sqlite3_value*); 02343 const unsigned char *sqlite3_value_text(sqlite3_value*); 02344 const void *sqlite3_value_text16(sqlite3_value*); 02345 const void *sqlite3_value_text16le(sqlite3_value*); 02346 const void *sqlite3_value_text16be(sqlite3_value*); 02347 int sqlite3_value_type(sqlite3_value*); 02348 int sqlite3_value_numeric_type(sqlite3_value*); 02349 02350 /* 02351 ** CAPI3REF: Obtain Aggregate Function Context 02352 ** 02353 ** The implementation of aggregate SQL functions use this routine to allocate 02354 ** a structure for storing their state. The first time this routine 02355 ** is called for a particular aggregate, a new structure of size nBytes 02356 ** is allocated, zeroed, and returned. On subsequent calls (for the 02357 ** same aggregate instance) the same buffer is returned. The implementation 02358 ** of the aggregate can use the returned buffer to accumulate data. 02359 ** 02360 ** The buffer allocated is freed automatically by SQLite whan the aggregate 02361 ** query concludes. 02362 ** 02363 ** The first parameter should be a copy of the 02364 ** [sqlite3_context | SQL function context] that is the first 02365 ** parameter to the callback routine that implements the aggregate 02366 ** function. 02367 ** 02368 ** This routine must be called from the same thread in which 02369 ** the aggregate SQL function is running. 02370 */ 02371 void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); 02372 02373 /* 02374 ** CAPI3REF: User Data For Functions 02375 ** 02376 ** The pUserData parameter to the [sqlite3_create_function()] 02377 ** and [sqlite3_create_function16()] routines 02378 ** used to register user functions is available to 02379 ** the implementation of the function using this call. 02380 ** 02381 ** This routine must be called from the same thread in which 02382 ** the SQL function is running. 02383 */ 02384 void *sqlite3_user_data(sqlite3_context*); 02385 02386 /* 02387 ** CAPI3REF: Function Auxiliary Data 02388 ** 02389 ** The following two functions may be used by scalar SQL functions to 02390 ** associate meta-data with argument values. If the same value is passed to 02391 ** multiple invocations of the same SQL function during query execution, under 02392 ** some circumstances the associated meta-data may be preserved. This may 02393 ** be used, for example, to add a regular-expression matching scalar 02394 ** function. The compiled version of the regular expression is stored as 02395 ** meta-data associated with the SQL value passed as the regular expression 02396 ** pattern. The compiled regular expression can be reused on multiple 02397 ** invocations of the same function so that the original pattern string 02398 ** does not need to be recompiled on each invocation. 02399 ** 02400 ** The sqlite3_get_auxdata() interface returns a pointer to the meta-data 02401 ** associated with the Nth argument value to the current SQL function 02402 ** call, where N is the second parameter. If no meta-data has been set for 02403 ** that value, then a NULL pointer is returned. 02404 ** 02405 ** The sqlite3_set_auxdata() is used to associate meta-data with an SQL 02406 ** function argument. The third parameter is a pointer to the meta-data 02407 ** to be associated with the Nth user function argument value. The fourth 02408 ** parameter specifies a destructor that will be called on the meta- 02409 ** data pointer to release it when it is no longer required. If the 02410 ** destructor is NULL, it is not invoked. 02411 ** 02412 ** In practice, meta-data is preserved between function calls for 02413 ** expressions that are constant at compile time. This includes literal 02414 ** values and SQL variables. 02415 ** 02416 ** These routines must be called from the same thread in which 02417 ** the SQL function is running. 02418 */ 02419 void *sqlite3_get_auxdata(sqlite3_context*, int); 02420 void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*)); 02421 02422 02423 /* 02424 ** CAPI3REF: Constants Defining Special Destructor Behavior 02425 ** 02426 ** These are special value for the destructor that is passed in as the 02427 ** final argument to routines like [sqlite3_result_blob()]. If the destructor 02428 ** argument is SQLITE_STATIC, it means that the content pointer is constant 02429 ** and will never change. It does not need to be destroyed. The 02430 ** SQLITE_TRANSIENT value means that the content will likely change in 02431 ** the near future and that SQLite should make its own private copy of 02432 ** the content before returning. 02433 ** 02434 ** The typedef is necessary to work around problems in certain 02435 ** C++ compilers. See ticket #2191. 02436 */ 02437 typedef void (*sqlite3_destructor_type)(void*); 02438 #define SQLITE_STATIC ((sqlite3_destructor_type)0) 02439 #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) 02440 02441 /* 02442 ** CAPI3REF: Setting The Result Of An SQL Function 02443 ** 02444 ** These routines are used by the xFunc or xFinal callbacks that 02445 ** implement SQL functions and aggregates. See 02446 ** [sqlite3_create_function()] and [sqlite3_create_function16()] 02447 ** for additional information. 02448 ** 02449 ** These functions work very much like the 02450 ** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used 02451 ** to bind values to host parameters in prepared statements. 02452 ** Refer to the 02453 ** [sqlite3_bind_blob | sqlite3_bind_* documentation] for 02454 ** additional information. 02455 ** 02456 ** The sqlite3_result_error() and sqlite3_result_error16() functions 02457 ** cause the implemented SQL function to throw an exception. The 02458 ** parameter to sqlite3_result_error() or sqlite3_result_error16() 02459 ** is the text of an error message. 02460 ** 02461 ** The sqlite3_result_toobig() cause the function implementation 02462 ** to throw and error indicating that a string or BLOB is to long 02463 ** to represent. 02464 ** 02465 ** These routines must be called from within the same thread as 02466 ** the SQL function associated with the [sqlite3_context] pointer. 02467 */ 02468 void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); 02469 void sqlite3_result_double(sqlite3_context*, double); 02470 void sqlite3_result_error(sqlite3_context*, const char*, int); 02471 void sqlite3_result_error16(sqlite3_context*, const void*, int); 02472 void sqlite3_result_error_toobig(sqlite3_context*); 02473 void sqlite3_result_error_nomem(sqlite3_context*); 02474 void sqlite3_result_int(sqlite3_context*, int); 02475 void sqlite3_result_int64(sqlite3_context*, sqlite3_int64); 02476 void sqlite3_result_null(sqlite3_context*); 02477 void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); 02478 void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); 02479 void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); 02480 void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); 02481 void sqlite3_result_value(sqlite3_context*, sqlite3_value*); 02482 void sqlite3_result_zeroblob(sqlite3_context*, int n); 02483 02484 /* 02485 ** CAPI3REF: Define New Collating Sequences 02486 ** 02487 ** These functions are used to add new collation sequences to the 02488 ** [sqlite3*] handle specified as the first argument. 02489 ** 02490 ** The name of the new collation sequence is specified as a UTF-8 string 02491 ** for sqlite3_create_collation() and sqlite3_create_collation_v2() 02492 ** and a UTF-16 string for sqlite3_create_collation16(). In all cases 02493 ** the name is passed as the second function argument. 02494 ** 02495 ** The third argument must be one of the constants [SQLITE_UTF8], 02496 ** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied 02497 ** routine expects to be passed pointers to strings encoded using UTF-8, 02498 ** UTF-16 little-endian or UTF-16 big-endian respectively. 02499 ** 02500 ** A pointer to the user supplied routine must be passed as the fifth 02501 ** argument. If it is NULL, this is the same as deleting the collation 02502 ** sequence (so that SQLite cannot call it anymore). Each time the user 02503 ** supplied function is invoked, it is passed a copy of the void* passed as 02504 ** the fourth argument to sqlite3_create_collation() or 02505 ** sqlite3_create_collation16() as its first parameter. 02506 ** 02507 ** The remaining arguments to the user-supplied routine are two strings, 02508 ** each represented by a [length, data] pair and encoded in the encoding 02509 ** that was passed as the third argument when the collation sequence was 02510 ** registered. The user routine should return negative, zero or positive if 02511 ** the first string is less than, equal to, or greater than the second 02512 ** string. i.e. (STRING1 - STRING2). 02513 ** 02514 ** The sqlite3_create_collation_v2() works like sqlite3_create_collation() 02515 ** excapt that it takes an extra argument which is a destructor for 02516 ** the collation. The destructor is called when the collation is 02517 ** destroyed and is passed a copy of the fourth parameter void* pointer 02518 ** of the sqlite3_create_collation_v2(). Collations are destroyed when 02519 ** they are overridden by later calls to the collation creation functions 02520 ** or when the [sqlite3*] database handle is closed using [sqlite3_close()]. 02521 ** 02522 ** The sqlite3_create_collation_v2() interface is experimental and 02523 ** subject to change in future releases. The other collation creation 02524 ** functions are stable. 02525 */ 02526 int sqlite3_create_collation( 02527 sqlite3*, 02528 const char *zName, 02529 int eTextRep, 02530 void*, 02531 int(*xCompare)(void*,int,const void*,int,const void*) 02532 ); 02533 int sqlite3_create_collation_v2( 02534 sqlite3*, 02535 const char *zName, 02536 int eTextRep, 02537 void*, 02538 int(*xCompare)(void*,int,const void*,int,const void*), 02539 void(*xDestroy)(void*) 02540 ); 02541 int sqlite3_create_collation16( 02542 sqlite3*, 02543 const char *zName, 02544 int eTextRep, 02545 void*, 02546 int(*xCompare)(void*,int,const void*,int,const void*) 02547 ); 02548 02549 /* 02550 ** CAPI3REF: Collation Needed Callbacks 02551 ** 02552 ** To avoid having to register all collation sequences before a database 02553 ** can be used, a single callback function may be registered with the 02554 ** database handle to be called whenever an undefined collation sequence is 02555 ** required. 02556 ** 02557 ** If the function is registered using the sqlite3_collation_needed() API, 02558 ** then it is passed the names of undefined collation sequences as strings 02559 ** encoded in UTF-8. If sqlite3_collation_needed16() is used, the names 02560 ** are passed as UTF-16 in machine native byte order. A call to either 02561 ** function replaces any existing callback. 02562 ** 02563 ** When the callback is invoked, the first argument passed is a copy 02564 ** of the second argument to sqlite3_collation_needed() or 02565 ** sqlite3_collation_needed16(). The second argument is the database 02566 ** handle. The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE], or 02567 ** [SQLITE_UTF16LE], indicating the most desirable form of the collation 02568 ** sequence function required. The fourth parameter is the name of the 02569 ** required collation sequence. 02570 ** 02571 ** The callback function should register the desired collation using 02572 ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or 02573 ** [sqlite3_create_collation_v2()]. 02574 */ 02575 int sqlite3_collation_needed( 02576 sqlite3*, 02577 void*, 02578 void(*)(void*,sqlite3*,int eTextRep,const char*) 02579 ); 02580 int sqlite3_collation_needed16( 02581 sqlite3*, 02582 void*, 02583 void(*)(void*,sqlite3*,int eTextRep,const void*) 02584 ); 02585 02586 /* 02587 ** Specify the key for an encrypted database. This routine should be 02588 ** called right after sqlite3_open(). 02589 ** 02590 ** The code to implement this API is not available in the public release 02591 ** of SQLite. 02592 */ 02593 int sqlite3_key( 02594 sqlite3 *db, /* Database to be rekeyed */ 02595 const void *pKey, int nKey /* The key */ 02596 ); 02597 02598 /* 02599 ** Change the key on an open database. If the current database is not 02600 ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the 02601 ** database is decrypted. 02602 ** 02603 ** The code to implement this API is not available in the public release 02604 ** of SQLite. 02605 */ 02606 int sqlite3_rekey( 02607 sqlite3 *db, /* Database to be rekeyed */ 02608 const void *pKey, int nKey /* The new key */ 02609 ); 02610 02611 /* 02612 ** CAPI3REF: Suspend Execution For A Short Time 02613 ** 02614 ** This function causes the current thread to suspend execution 02615 ** a number of milliseconds specified in its parameter. 02616 ** 02617 ** If the operating system does not support sleep requests with 02618 ** millisecond time resolution, then the time will be rounded up to 02619 ** the nearest second. The number of milliseconds of sleep actually 02620 ** requested from the operating system is returned. 02621 ** 02622 ** SQLite implements this interface by calling the xSleep() 02623 ** method of the default [sqlite3_vfs] object. 02624 */ 02625 int sqlite3_sleep(int); 02626 02627 /* 02628 ** CAPI3REF: Name Of The Folder Holding Temporary Files 02629 ** 02630 ** If this global variable is made to point to a string which is 02631 ** the name of a folder (a.ka. directory), then all temporary files 02632 ** created by SQLite will be placed in that directory. If this variable 02633 ** is NULL pointer, then SQLite does a search for an appropriate temporary 02634 ** file directory. 02635 ** 02636 ** It is not safe to modify this variable once a database connection 02637 ** has been opened. It is intended that this variable be set once 02638 ** as part of process initialization and before any SQLite interface 02639 ** routines have been call and remain unchanged thereafter. 02640 */ 02641 SQLITE_EXTERN char *sqlite3_temp_directory; 02642 02643 /* 02644 ** CAPI3REF: Test To See If The Database Is In Auto-Commit Mode 02645 ** 02646 ** Test to see whether or not the database connection is in autocommit 02647 ** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on 02648 ** by default. Autocommit is disabled by a BEGIN statement and reenabled 02649 ** by the next COMMIT or ROLLBACK. 02650 ** 02651 ** If another thread changes the autocommit status of the database 02652 ** connection while this routine is running, then the return value 02653 ** is undefined. 02654 */ 02655 int sqlite3_get_autocommit(sqlite3*); 02656 02657 /* 02658 ** CAPI3REF: Find The Database Handle Associated With A Prepared Statement 02659 ** 02660 ** Return the [sqlite3*] database handle to which a 02661 ** [sqlite3_stmt | prepared statement] belongs. 02662 ** This is the same database handle that was 02663 ** the first argument to the [sqlite3_prepare_v2()] or its variants 02664 ** that was used to create the statement in the first place. 02665 */ 02666 sqlite3 *sqlite3_db_handle(sqlite3_stmt*); 02667 02668 02669 /* 02670 ** CAPI3REF: Commit And Rollback Notification Callbacks 02671 ** 02672 ** These routines 02673 ** register callback functions to be invoked whenever a transaction 02674 ** is committed or rolled back. The pArg argument is passed through 02675 ** to the callback. If the callback on a commit hook function 02676 ** returns non-zero, then the commit is converted into a rollback. 02677 ** 02678 ** If another function was previously registered, its pArg value is returned. 02679 ** Otherwise NULL is returned. 02680 ** 02681 ** Registering a NULL function disables the callback. 02682 ** 02683 ** For the purposes of this API, a transaction is said to have been 02684 ** rolled back if an explicit "ROLLBACK" statement is executed, or 02685 ** an error or constraint causes an implicit rollback to occur. The 02686 ** callback is not invoked if a transaction is automatically rolled 02687 ** back because the database connection is closed. 02688 ** 02689 ** These are experimental interfaces and are subject to change. 02690 */ 02691 void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); 02692 void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); 02693 02694 /* 02695 ** CAPI3REF: Data Change Notification Callbacks 02696 ** 02697 ** Register a callback function with the database connection identified by the 02698 ** first argument to be invoked whenever a row is updated, inserted or deleted. 02699 ** Any callback set by a previous call to this function for the same 02700 ** database connection is overridden. 02701 ** 02702 ** The second argument is a pointer to the function to invoke when a 02703 ** row is updated, inserted or deleted. The first argument to the callback is 02704 ** a copy of the third argument to sqlite3_update_hook(). The second callback 02705 ** argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending 02706 ** on the operation that caused the callback to be invoked. The third and 02707 ** fourth arguments to the callback contain pointers to the database and 02708 ** table name containing the affected row. The final callback parameter is 02709 ** the rowid of the row. In the case of an update, this is the rowid after 02710 ** the update takes place. 02711 ** 02712 ** The update hook is not invoked when internal system tables are 02713 ** modified (i.e. sqlite_master and sqlite_sequence). 02714 ** 02715 ** If another function was previously registered, its pArg value is returned. 02716 ** Otherwise NULL is returned. 02717 */ 02718 void *sqlite3_update_hook( 02719 sqlite3*, 02720 void(*)(void *,int ,char const *,char const *,sqlite3_int64), 02721 void* 02722 ); 02723 02724 /* 02725 ** CAPI3REF: Enable Or Disable Shared Pager Cache 02726 ** 02727 ** This routine enables or disables the sharing of the database cache 02728 ** and schema data structures between connections to the same database. 02729 ** Sharing is enabled if the argument is true and disabled if the argument 02730 ** is false. 02731 ** 02732 ** Beginning in SQLite version 3.5.0, cache sharing is enabled and disabled 02733 ** for an entire process. In prior versions of SQLite, sharing was 02734 ** enabled or disabled for each thread separately. 02735 ** 02736 ** The cache sharing mode set by this interface effects all subsequent 02737 ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()]. 02738 ** Existing database connections continue use the sharing mode that was 02739 ** in effect at the time they were opened. 02740 ** 02741 ** Virtual tables cannot be used with a shared cache. When shared 02742 ** cache is enabled, the [sqlite3_create_module()] API used to register 02743 ** virtual tables will always return an error. 02744 ** 02745 ** This routine returns [SQLITE_OK] if shared cache was 02746 ** enabled or disabled successfully. An [SQLITE_ERROR | error code] 02747 ** is returned otherwise. 02748 ** 02749 ** Shared cache is disabled by default. But this might change in 02750 ** future releases of SQLite. Applications that care about shared 02751 ** cache setting should set it explicitly. 02752 */ 02753 int sqlite3_enable_shared_cache(int); 02754 02755 /* 02756 ** CAPI3REF: Attempt To Free Heap Memory 02757 ** 02758 ** Attempt to free N bytes of heap memory by deallocating non-essential 02759 ** memory allocations held by the database library (example: memory 02760 ** used to cache database pages to improve performance). 02761 */ 02762 int sqlite3_release_memory(int); 02763 02764 /* 02765 ** CAPI3REF: Impose A Limit On Heap Size 02766 ** 02767 ** Place a "soft" limit on the amount of heap memory that may be allocated 02768 ** by SQLite. If an internal allocation is requested 02769 ** that would exceed the specified limit, [sqlite3_release_memory()] is 02770 ** invoked one or more times to free up some space before the allocation 02771 ** is made. 02772 ** 02773 ** The limit is called "soft", because if [sqlite3_release_memory()] cannot 02774 ** free sufficient memory to prevent the limit from being exceeded, 02775 ** the memory is allocated anyway and the current operation proceeds. 02776 ** 02777 ** A negative or zero value for N means that there is no soft heap limit and 02778 ** [sqlite3_release_memory()] will only be called when memory is exhausted. 02779 ** The default value for the soft heap limit is zero. 02780 ** 02781 ** SQLite makes a best effort to honor the soft heap limit. But if it 02782 ** is unable to reduce memory usage below the soft limit, execution will 02783 ** continue without error or notification. This is why the limit is 02784 ** called a "soft" limit. It is advisory only. 02785 ** 02786 ** The soft heap limit is implemented using the [sqlite3_memory_alarm()] 02787 ** interface. Only a single memory alarm is available in the default 02788 ** implementation. This means that if the application also uses the 02789 ** memory alarm interface it will interfere with the operation of the 02790 ** soft heap limit and undefined behavior will result. 02791 ** 02792 ** Prior to SQLite version 3.5.0, this routine only constrained the memory 02793 ** allocated by a single thread - the same thread in which this routine 02794 ** runs. Beginning with SQLite version 3.5.0, the soft heap limit is 02795 ** applied to all threads. The value specified for the soft heap limit 02796 ** is an upper bound on the total memory allocation for all threads. In 02797 ** version 3.5.0 there is no mechanism for limiting the heap usage for 02798 ** individual threads. 02799 */ 02800 void sqlite3_soft_heap_limit(int); 02801 02802 /* 02803 ** CAPI3REF: Extract Metadata About A Column Of A Table 02804 ** 02805 ** This routine 02806 ** returns meta-data about a specific column of a specific database 02807 ** table accessible using the connection handle passed as the first function 02808 ** argument. 02809 ** 02810 ** The column is identified by the second, third and fourth parameters to 02811 ** this function. The second parameter is either the name of the database 02812 ** (i.e. "main", "temp" or an attached database) containing the specified 02813 ** table or NULL. If it is NULL, then all attached databases are searched 02814 ** for the table using the same algorithm as the database engine uses to 02815 ** resolve unqualified table references. 02816 ** 02817 ** The third and fourth parameters to this function are the table and column 02818 ** name of the desired column, respectively. Neither of these parameters 02819 ** may be NULL. 02820 ** 02821 ** Meta information is returned by writing to the memory locations passed as 02822 ** the 5th and subsequent parameters to this function. Any of these 02823 ** arguments may be NULL, in which case the corresponding element of meta 02824 ** information is ommitted. 02825 ** 02826 ** <pre> 02827 ** Parameter Output Type Description 02828 ** ----------------------------------- 02829 ** 02830 ** 5th const char* Data type 02831 ** 6th const char* Name of the default collation sequence 02832 ** 7th int True if the column has a NOT NULL constraint 02833 ** 8th int True if the column is part of the PRIMARY KEY 02834 ** 9th int True if the column is AUTOINCREMENT 02835 ** </pre> 02836 ** 02837 ** 02838 ** The memory pointed to by the character pointers returned for the 02839 ** declaration type and collation sequence is valid only until the next 02840 ** call to any sqlite API function. 02841 ** 02842 ** If the specified table is actually a view, then an error is returned. 02843 ** 02844 ** If the specified column is "rowid", "oid" or "_rowid_" and an 02845 ** INTEGER PRIMARY KEY column has been explicitly declared, then the output 02846 ** parameters are set for the explicitly declared column. If there is no 02847 ** explicitly declared IPK column, then the output parameters are set as 02848 ** follows: 02849 ** 02850 ** <pre> 02851 ** data type: "INTEGER" 02852 ** collation sequence: "BINARY" 02853 ** not null: 0 02854 ** primary key: 1 02855 ** auto increment: 0 02856 ** </pre> 02857 ** 02858 ** This function may load one or more schemas from database files. If an 02859 ** error occurs during this process, or if the requested table or column 02860 ** cannot be found, an SQLITE error code is returned and an error message 02861 ** left in the database handle (to be retrieved using sqlite3_errmsg()). 02862 ** 02863 ** This API is only available if the library was compiled with the 02864 ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. 02865 */ 02866 int sqlite3_table_column_metadata( 02867 sqlite3 *db, /* Connection handle */ 02868 const char *zDbName, /* Database name or NULL */ 02869 const char *zTableName, /* Table name */ 02870 const char *zColumnName, /* Column name */ 02871 char const **pzDataType, /* OUTPUT: Declared data type */ 02872 char const **pzCollSeq, /* OUTPUT: Collation sequence name */ 02873 int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ 02874 int *pPrimaryKey, /* OUTPUT: True if column part of PK */ 02875 int *pAutoinc /* OUTPUT: True if colums is auto-increment */ 02876 ); 02877 02878 /* 02879 ** CAPI3REF: Load An Extension 02880 ** 02881 ** Attempt to load an SQLite extension library contained in the file 02882 ** zFile. The entry point is zProc. zProc may be 0 in which case the 02883 ** name of the entry point defaults to "sqlite3_extension_init". 02884 ** 02885 ** Return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. 02886 ** 02887 ** If an error occurs and pzErrMsg is not 0, then fill *pzErrMsg with 02888 ** error message text. The calling function should free this memory 02889 ** by calling [sqlite3_free()]. 02890 ** 02891 ** Extension loading must be enabled using [sqlite3_enable_load_extension()] 02892 ** prior to calling this API or an error will be returned. 02893 */ 02894 int sqlite3_load_extension( 02895 sqlite3 *db, /* Load the extension into this database connection */ 02896 const char *zFile, /* Name of the shared library containing extension */ 02897 const char *zProc, /* Entry point. Derived from zFile if 0 */ 02898 char **pzErrMsg /* Put error message here if not 0 */ 02899 ); 02900 02901 /* 02902 ** CAPI3REF: Enable Or Disable Extension Loading 02903 ** 02904 ** So as not to open security holes in older applications that are 02905 ** unprepared to deal with extension loading, and as a means of disabling 02906 ** extension loading while evaluating user-entered SQL, the following 02907 ** API is provided to turn the [sqlite3_load_extension()] mechanism on and 02908 ** off. It is off by default. See ticket #1863. 02909 ** 02910 ** Call this routine with onoff==1 to turn extension loading on 02911 ** and call it with onoff==0 to turn it back off again. 02912 */ 02913 int sqlite3_enable_load_extension(sqlite3 *db, int onoff); 02914 02915 /* 02916 ** CAPI3REF: Make Arrangements To Automatically Load An Extension 02917 ** 02918 ** Register an extension entry point that is automatically invoked 02919 ** whenever a new database connection is opened using 02920 ** [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()]. 02921 ** 02922 ** This API can be invoked at program startup in order to register 02923 ** one or more statically linked extensions that will be available 02924 ** to all new database connections. 02925 ** 02926 ** Duplicate extensions are detected so calling this routine multiple 02927 ** times with the same extension is harmless. 02928 ** 02929 ** This routine stores a pointer to the extension in an array 02930 ** that is obtained from malloc(). If you run a memory leak 02931 ** checker on your program and it reports a leak because of this 02932 ** array, then invoke [sqlite3_automatic_extension_reset()] prior 02933 ** to shutdown to free the memory. 02934 ** 02935 ** Automatic extensions apply across all threads. 02936 ** 02937 ** This interface is experimental and is subject to change or 02938 ** removal in future releases of SQLite. 02939 */ 02940 int sqlite3_auto_extension(void *xEntryPoint); 02941 02942 02943 /* 02944 ** CAPI3REF: Reset Automatic Extension Loading 02945 ** 02946 ** Disable all previously registered automatic extensions. This 02947 ** routine undoes the effect of all prior [sqlite3_automatic_extension()] 02948 ** calls. 02949 ** 02950 ** This call disabled automatic extensions in all threads. 02951 ** 02952 ** This interface is experimental and is subject to change or 02953 ** removal in future releases of SQLite. 02954 */ 02955 void sqlite3_reset_auto_extension(void); 02956 02957 02958 /* 02959 ****** EXPERIMENTAL - subject to change without notice ************** 02960 ** 02961 ** The interface to the virtual-table mechanism is currently considered 02962 ** to be experimental. The interface might change in incompatible ways. 02963 ** If this is a problem for you, do not use the interface at this time. 02964 ** 02965 ** When the virtual-table mechanism stablizes, we will declare the 02966 ** interface fixed, support it indefinitely, and remove this comment. 02967 */ 02968 02969 /* 02970 ** Structures used by the virtual table interface 02971 */ 02972 typedef struct sqlite3_vtab sqlite3_vtab; 02973 typedef struct sqlite3_index_info sqlite3_index_info; 02974 typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor; 02975 typedef struct sqlite3_module sqlite3_module; 02976 02977 /* 02978 ** A module is a class of virtual tables. Each module is defined 02979 ** by an instance of the following structure. This structure consists 02980 ** mostly of methods for the module. 02981 */ 02982 struct sqlite3_module { 02983 int iVersion; 02984 int (*xCreate)(sqlite3*, void *pAux, 02985 int argc, const char *const*argv, 02986 sqlite3_vtab **ppVTab, char**); 02987 int (*xConnect)(sqlite3*, void *pAux, 02988 int argc, const char *const*argv, 02989 sqlite3_vtab **ppVTab, char**); 02990 int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*); 02991 int (*xDisconnect)(sqlite3_vtab *pVTab); 02992 int (*xDestroy)(sqlite3_vtab *pVTab); 02993 int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor); 02994 int (*xClose)(sqlite3_vtab_cursor*); 02995 int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr, 02996 int argc, sqlite3_value **argv); 02997 int (*xNext)(sqlite3_vtab_cursor*); 02998 int (*xEof)(sqlite3_vtab_cursor*); 02999 int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int); 03000 int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid); 03001 int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *); 03002 int (*xBegin)(sqlite3_vtab *pVTab); 03003 int (*xSync)(sqlite3_vtab *pVTab); 03004 int (*xCommit)(sqlite3_vtab *pVTab); 03005 int (*xRollback)(sqlite3_vtab *pVTab); 03006 int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, 03007 void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), 03008 void **ppArg); 03009 03010 int (*xRename)(sqlite3_vtab *pVtab, const char *zNew); 03011 }; 03012 03013 /* 03014 ** The sqlite3_index_info structure and its substructures is used to 03015 ** pass information into and receive the reply from the xBestIndex 03016 ** method of an sqlite3_module. The fields under **Inputs** are the 03017 ** inputs to xBestIndex and are read-only. xBestIndex inserts its 03018 ** results into the **Outputs** fields. 03019 ** 03020 ** The aConstraint[] array records WHERE clause constraints of the 03021 ** form: 03022 ** 03023 ** column OP expr 03024 ** 03025 ** Where OP is =, <, <=, >, or >=. The particular operator is stored 03026 ** in aConstraint[].op. The index of the column is stored in 03027 ** aConstraint[].iColumn. aConstraint[].usable is TRUE if the 03028 ** expr on the right-hand side can be evaluated (and thus the constraint 03029 ** is usable) and false if it cannot. 03030 ** 03031 ** The optimizer automatically inverts terms of the form "expr OP column" 03032 ** and makes other simplificatinos to the WHERE clause in an attempt to 03033 ** get as many WHERE clause terms into the form shown above as possible. 03034 ** The aConstraint[] array only reports WHERE clause terms in the correct 03035 ** form that refer to the particular virtual table being queried. 03036 ** 03037 ** Information about the ORDER BY clause is stored in aOrderBy[]. 03038 ** Each term of aOrderBy records a column of the ORDER BY clause. 03039 ** 03040 ** The xBestIndex method must fill aConstraintUsage[] with information 03041 ** about what parameters to pass to xFilter. If argvIndex>0 then 03042 ** the right-hand side of the corresponding aConstraint[] is evaluated 03043 ** and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit 03044 ** is true, then the constraint is assumed to be fully handled by the 03045 ** virtual table and is not checked again by SQLite. 03046 ** 03047 ** The idxNum and idxPtr values are recorded and passed into xFilter. 03048 ** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true. 03049 ** 03050 ** The orderByConsumed means that output from xFilter will occur in 03051 ** the correct order to satisfy the ORDER BY clause so that no separate 03052 ** sorting step is required. 03053 ** 03054 ** The estimatedCost value is an estimate of the cost of doing the 03055 ** particular lookup. A full scan of a table with N entries should have 03056 ** a cost of N. A binary search of a table of N entries should have a 03057 ** cost of approximately log(N). 03058 */ 03059 struct sqlite3_index_info { 03060 /* Inputs */ 03061 const int nConstraint; /* Number of entries in aConstraint */ 03062 const struct sqlite3_index_constraint { 03063 int iColumn; /* Column on left-hand side of constraint */ 03064 unsigned char op; /* Constraint operator */ 03065 unsigned char usable; /* True if this constraint is usable */ 03066 int iTermOffset; /* Used internally - xBestIndex should ignore */ 03067 } *const aConstraint; /* Table of WHERE clause constraints */ 03068 const int nOrderBy; /* Number of terms in the ORDER BY clause */ 03069 const struct sqlite3_index_orderby { 03070 int iColumn; /* Column number */ 03071 unsigned char desc; /* True for DESC. False for ASC. */ 03072 } *const aOrderBy; /* The ORDER BY clause */ 03073 03074 /* Outputs */ 03075 struct sqlite3_index_constraint_usage { 03076 int argvIndex; /* if >0, constraint is part of argv to xFilter */ 03077 unsigned char omit; /* Do not code a test for this constraint */ 03078 } *const aConstraintUsage; 03079 int idxNum; /* Number used to identify the index */ 03080 char *idxStr; /* String, possibly obtained from sqlite3_malloc */ 03081 int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */ 03082 int orderByConsumed; /* True if output is already ordered */ 03083 double estimatedCost; /* Estimated cost of using this index */ 03084 }; 03085 #define SQLITE_INDEX_CONSTRAINT_EQ 2 03086 #define SQLITE_INDEX_CONSTRAINT_GT 4 03087 #define SQLITE_INDEX_CONSTRAINT_LE 8 03088 #define SQLITE_INDEX_CONSTRAINT_LT 16 03089 #define SQLITE_INDEX_CONSTRAINT_GE 32 03090 #define SQLITE_INDEX_CONSTRAINT_MATCH 64 03091 03092 /* 03093 ** This routine is used to register a new module name with an SQLite 03094 ** connection. Module names must be registered before creating new 03095 ** virtual tables on the module, or before using preexisting virtual 03096 ** tables of the module. 03097 */ 03098 int sqlite3_create_module( 03099 sqlite3 *db, /* SQLite connection to register module with */ 03100 const char *zName, /* Name of the module */ 03101 const sqlite3_module *, /* Methods for the module */ 03102 void * /* Client data for xCreate/xConnect */ 03103 ); 03104 03105 /* 03106 ** This routine is identical to the sqlite3_create_module() method above, 03107 ** except that it allows a destructor function to be specified. It is 03108 ** even more experimental than the rest of the virtual tables API. 03109 */ 03110 int sqlite3_create_module_v2( 03111 sqlite3 *db, /* SQLite connection to register module with */ 03112 const char *zName, /* Name of the module */ 03113 const sqlite3_module *, /* Methods for the module */ 03114 void *, /* Client data for xCreate/xConnect */ 03115 void(*xDestroy)(void*) /* Module destructor function */ 03116 ); 03117 03118 /* 03119 ** Every module implementation uses a subclass of the following structure 03120 ** to describe a particular instance of the module. Each subclass will 03121 ** be taylored to the specific needs of the module implementation. The 03122 ** purpose of this superclass is to define certain fields that are common 03123 ** to all module implementations. 03124 ** 03125 ** Virtual tables methods can set an error message by assigning a 03126 ** string obtained from sqlite3_mprintf() to zErrMsg. The method should 03127 ** take care that any prior string is freed by a call to sqlite3_free() 03128 ** prior to assigning a new string to zErrMsg. After the error message 03129 ** is delivered up to the client application, the string will be automatically 03130 ** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note 03131 ** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field 03132 ** since virtual tables are commonly implemented in loadable extensions which 03133 ** do not have access to sqlite3MPrintf() or sqlite3Free(). 03134 */ 03135 struct sqlite3_vtab { 03136 const sqlite3_module *pModule; /* The module for this virtual table */ 03137 int nRef; /* Used internally */ 03138 char *zErrMsg; /* Error message from sqlite3_mprintf() */ 03139 /* Virtual table implementations will typically add additional fields */ 03140 }; 03141 03142 /* Every module implementation uses a subclass of the following structure 03143 ** to describe cursors that point into the virtual table and are used 03144 ** to loop through the virtual table. Cursors are created using the 03145 ** xOpen method of the module. Each module implementation will define 03146 ** the content of a cursor structure to suit its own needs. 03147 ** 03148 ** This superclass exists in order to define fields of the cursor that 03149 ** are common to all implementations. 03150 */ 03151 struct sqlite3_vtab_cursor { 03152 sqlite3_vtab *pVtab; /* Virtual table of this cursor */ 03153 /* Virtual table implementations will typically add additional fields */ 03154 }; 03155 03156 /* 03157 ** The xCreate and xConnect methods of a module use the following API 03158 ** to declare the format (the names and datatypes of the columns) of 03159 ** the virtual tables they implement. 03160 */ 03161 int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); 03162 03163 /* 03164 ** Virtual tables can provide alternative implementations of functions 03165 ** using the xFindFunction method. But global versions of those functions 03166 ** must exist in order to be overloaded. 03167 ** 03168 ** This API makes sure a global version of a function with a particular 03169 ** name and number of parameters exists. If no such function exists 03170 ** before this API is called, a new function is created. The implementation 03171 ** of the new function always causes an exception to be thrown. So 03172 ** the new function is not good for anything by itself. Its only 03173 ** purpose is to be a place-holder function that can be overloaded 03174 ** by virtual tables. 03175 ** 03176 ** This API should be considered part of the virtual table interface, 03177 ** which is experimental and subject to change. 03178 */ 03179 int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); 03180 03181 /* 03182 ** The interface to the virtual-table mechanism defined above (back up 03183 ** to a comment remarkably similar to this one) is currently considered 03184 ** to be experimental. The interface might change in incompatible ways. 03185 ** If this is a problem for you, do not use the interface at this time. 03186 ** 03187 ** When the virtual-table mechanism stablizes, we will declare the 03188 ** interface fixed, support it indefinitely, and remove this comment. 03189 ** 03190 ****** EXPERIMENTAL - subject to change without notice ************** 03191 */ 03192 03193 /* 03194 ** CAPI3REF: A Handle To An Open BLOB 03195 ** 03196 ** An instance of the following opaque structure is used to 03197 ** represent an blob-handle. A blob-handle is created by 03198 ** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()]. 03199 ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces 03200 ** can be used to read or write small subsections of the blob. 03201 ** The [sqltie3_blob_size()] interface returns the size of the 03202 ** blob in bytes. 03203 */ 03204 typedef struct sqlite3_blob sqlite3_blob; 03205 03206 /* 03207 ** CAPI3REF: Open A BLOB For Incremental I/O 03208 ** 03209 ** Open a handle to the blob located in row iRow,, column zColumn, 03210 ** table zTable in database zDb. i.e. the same blob that would 03211 ** be selected by: 03212 ** 03213 ** <pre> 03214 ** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow; 03215 ** </pre> 03216 ** 03217 ** If the flags parameter is non-zero, the blob is opened for 03218 ** read and write access. If it is zero, the blob is opened for read 03219 ** access. 03220 ** 03221 ** On success, [SQLITE_OK] is returned and the new 03222 ** [sqlite3_blob | blob handle] is written to *ppBlob. 03223 ** Otherwise an error code is returned and 03224 ** any value written to *ppBlob should not be used by the caller. 03225 ** This function sets the database-handle error code and message 03226 ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()]. 03227 */ 03228 int sqlite3_blob_open( 03229 sqlite3*, 03230 const char *zDb, 03231 const char *zTable, 03232 const char *zColumn, 03233 sqlite3_int64 iRow, 03234 int flags, 03235 sqlite3_blob **ppBlob 03236 ); 03237 03238 /* 03239 ** CAPI3REF: Close A BLOB Handle 03240 ** 03241 ** Close an open [sqlite3_blob | blob handle]. 03242 */ 03243 int sqlite3_blob_close(sqlite3_blob *); 03244 03245 /* 03246 ** CAPI3REF: Return The Size Of An Open BLOB 03247 ** 03248 ** Return the size in bytes of the blob accessible via the open 03249 ** [sqlite3_blob | blob-handle] passed as an argument. 03250 */ 03251 int sqlite3_blob_bytes(sqlite3_blob *); 03252 03253 /* 03254 ** CAPI3REF: Read Data From A BLOB Incrementally 03255 ** 03256 ** This function is used to read data from an open 03257 ** [sqlite3_blob | blob-handle] into a caller supplied buffer. 03258 ** n bytes of data are copied into buffer 03259 ** z from the open blob, starting at offset iOffset. 03260 ** 03261 ** On success, SQLITE_OK is returned. Otherwise, an 03262 ** [SQLITE_ERROR | SQLite error code] or an 03263 ** [SQLITE_IOERR_READ | extended error code] is returned. 03264 */ 03265 int sqlite3_blob_read(sqlite3_blob *, void *z, int n, int iOffset); 03266 03267 /* 03268 ** CAPI3REF: Write Data Into A BLOB Incrementally 03269 ** 03270 ** This function is used to write data into an open 03271 ** [sqlite3_blob | blob-handle] from a user supplied buffer. 03272 ** n bytes of data are copied from the buffer 03273 ** pointed to by z into the open blob, starting at offset iOffset. 03274 ** 03275 ** If the [sqlite3_blob | blob-handle] passed as the first argument 03276 ** was not opened for writing (the flags parameter to [sqlite3_blob_open()] 03277 *** was zero), this function returns [SQLITE_READONLY]. 03278 ** 03279 ** This function may only modify the contents of the blob, it is 03280 ** not possible to increase the size of a blob using this API. If 03281 ** offset iOffset is less than n bytes from the end of the blob, 03282 ** [SQLITE_ERROR] is returned and no data is written. 03283 ** 03284 ** On success, SQLITE_OK is returned. Otherwise, an 03285 ** [SQLITE_ERROR | SQLite error code] or an 03286 ** [SQLITE_IOERR_READ | extended error code] is returned. 03287 */ 03288 int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); 03289 03290 /* 03291 ** CAPI3REF: Virtual File System Objects 03292 ** 03293 ** A virtual filesystem (VFS) is an [sqlite3_vfs] object 03294 ** that SQLite uses to interact 03295 ** with the underlying operating system. Most builds come with a 03296 ** single default VFS that is appropriate for the host computer. 03297 ** New VFSes can be registered and existing VFSes can be unregistered. 03298 ** The following interfaces are provided. 03299 ** 03300 ** The sqlite3_vfs_find() interface returns a pointer to a VFS given its 03301 ** name. Names are case sensitive. If there is no match, a NULL 03302 ** pointer is returned. If zVfsName is NULL then the default 03303 ** VFS is returned. 03304 ** 03305 ** New VFSes are registered with sqlite3_vfs_register(). Each 03306 ** new VFS becomes the default VFS if the makeDflt flag is set. 03307 ** The same VFS can be registered multiple times without injury. 03308 ** To make an existing VFS into the default VFS, register it again 03309 ** with the makeDflt flag set. If two different VFSes with the 03310 ** same name are registered, the behavior is undefined. If a 03311 ** VFS is registered with a name that is NULL or an empty string, 03312 ** then the behavior is undefined. 03313 ** 03314 ** Unregister a VFS with the sqlite3_vfs_unregister() interface. 03315 ** If the default VFS is unregistered, another VFS is chosen as 03316 ** the default. The choice for the new VFS is arbitrary. 03317 */ 03318 sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); 03319 int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); 03320 int sqlite3_vfs_unregister(sqlite3_vfs*); 03321 03322 /* 03323 ** CAPI3REF: Mutexes 03324 ** 03325 ** The SQLite core uses these routines for thread 03326 ** synchronization. Though they are intended for internal 03327 ** use by SQLite, code that links against SQLite is 03328 ** permitted to use any of these routines. 03329 ** 03330 ** The SQLite source code contains multiple implementations 03331 ** of these mutex routines. An appropriate implementation 03332 ** is selected automatically at compile-time. The following 03333 ** implementations are available in the SQLite core: 03334 ** 03335 ** <ul> 03336 ** <li> SQLITE_MUTEX_OS2 03337 ** <li> SQLITE_MUTEX_PTHREAD 03338 ** <li> SQLITE_MUTEX_W32 03339 ** <li> SQLITE_MUTEX_NOOP 03340 ** </ul> 03341 ** 03342 ** The SQLITE_MUTEX_NOOP implementation is a set of routines 03343 ** that does no real locking and is appropriate for use in 03344 ** a single-threaded application. The SQLITE_MUTEX_OS2, 03345 ** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations 03346 ** are appropriate for use on os/2, unix, and windows. 03347 ** 03348 ** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor 03349 ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex 03350 ** implementation is included with the library. The 03351 ** mutex interface routines defined here become external 03352 ** references in the SQLite library for which implementations 03353 ** must be provided by the application. This facility allows an 03354 ** application that links against SQLite to provide its own mutex 03355 ** implementation without having to modify the SQLite core. 03356 ** 03357 ** The sqlite3_mutex_alloc() routine allocates a new 03358 ** mutex and returns a pointer to it. If it returns NULL 03359 ** that means that a mutex could not be allocated. SQLite 03360 ** will unwind its stack and return an error. The argument 03361 ** to sqlite3_mutex_alloc() is one of these integer constants: 03362 ** 03363 ** <ul> 03364 ** <li> SQLITE_MUTEX_FAST 03365 ** <li> SQLITE_MUTEX_RECURSIVE 03366 ** <li> SQLITE_MUTEX_STATIC_MASTER 03367 ** <li> SQLITE_MUTEX_STATIC_MEM 03368 ** <li> SQLITE_MUTEX_STATIC_MEM2 03369 ** <li> SQLITE_MUTEX_STATIC_PRNG 03370 ** <li> SQLITE_MUTEX_STATIC_LRU 03371 ** </ul> 03372 ** 03373 ** The first two constants cause sqlite3_mutex_alloc() to create 03374 ** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE 03375 ** is used but not necessarily so when SQLITE_MUTEX_FAST is used. 03376 ** The mutex implementation does not need to make a distinction 03377 ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does 03378 ** not want to. But SQLite will only request a recursive mutex in 03379 ** cases where it really needs one. If a faster non-recursive mutex 03380 ** implementation is available on the host platform, the mutex subsystem 03381 ** might return such a mutex in response to SQLITE_MUTEX_FAST. 03382 ** 03383 ** The other allowed parameters to sqlite3_mutex_alloc() each return 03384 ** a pointer to a static preexisting mutex. Four static mutexes are 03385 ** used by the current version of SQLite. Future versions of SQLite 03386 ** may add additional static mutexes. Static mutexes are for internal 03387 ** use by SQLite only. Applications that use SQLite mutexes should 03388 ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or 03389 ** SQLITE_MUTEX_RECURSIVE. 03390 ** 03391 ** Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST 03392 ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() 03393 ** returns a different mutex on every call. But for the static 03394 ** mutex types, the same mutex is returned on every call that has 03395 ** the same type number. 03396 ** 03397 ** The sqlite3_mutex_free() routine deallocates a previously 03398 ** allocated dynamic mutex. SQLite is careful to deallocate every 03399 ** dynamic mutex that it allocates. The dynamic mutexes must not be in 03400 ** use when they are deallocated. Attempting to deallocate a static 03401 ** mutex results in undefined behavior. SQLite never deallocates 03402 ** a static mutex. 03403 ** 03404 ** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt 03405 ** to enter a mutex. If another thread is already within the mutex, 03406 ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return 03407 ** SQLITE_BUSY. The sqlite3_mutex_try() interface returns SQLITE_OK 03408 ** upon successful entry. Mutexes created using SQLITE_MUTEX_RECURSIVE can 03409 ** be entered multiple times by the same thread. In such cases the, 03410 ** mutex must be exited an equal number of times before another thread 03411 ** can enter. If the same thread tries to enter any other kind of mutex 03412 ** more than once, the behavior is undefined. SQLite will never exhibit 03413 ** such behavior in its own use of mutexes. 03414 ** 03415 ** The sqlite3_mutex_leave() routine exits a mutex that was 03416 ** previously entered by the same thread. The behavior 03417 ** is undefined if the mutex is not currently entered by the 03418 ** calling thread or is not currently allocated. SQLite will 03419 ** never do either. 03420 ** 03421 ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()]. 03422 */ 03423 sqlite3_mutex *sqlite3_mutex_alloc(int); 03424 void sqlite3_mutex_free(sqlite3_mutex*); 03425 void sqlite3_mutex_enter(sqlite3_mutex*); 03426 int sqlite3_mutex_try(sqlite3_mutex*); 03427 void sqlite3_mutex_leave(sqlite3_mutex*); 03428 03429 /* 03430 ** CAPI3REF: Mutex Verifcation Routines 03431 ** 03432 ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines 03433 ** are intended for use inside assert() statements. The SQLite core 03434 ** never uses these routines except inside an assert() and applications 03435 ** are advised to follow the lead of the core. The core only 03436 ** provides implementations for these routines when it is compiled 03437 ** with the SQLITE_DEBUG flag. External mutex implementations 03438 ** are only required to provide these routines if SQLITE_DEBUG is 03439 ** defined and if NDEBUG is not defined. 03440 ** 03441 ** These routines should return true if the mutex in their argument 03442 ** is held or not held, respectively, by the calling thread. 03443 ** 03444 ** The implementation is not required to provided versions of these 03445 ** routines that actually work. 03446 ** If the implementation does not provide working 03447 ** versions of these routines, it should at least provide stubs 03448 ** that always return true so that one does not get spurious 03449 ** assertion failures. 03450 ** 03451 ** If the argument to sqlite3_mutex_held() is a NULL pointer then 03452 ** the routine should return 1. This seems counter-intuitive since 03453 ** clearly the mutex cannot be held if it does not exist. But the 03454 ** the reason the mutex does not exist is because the build is not 03455 ** using mutexes. And we do not want the assert() containing the 03456 ** call to sqlite3_mutex_held() to fail, so a non-zero return is 03457 ** the appropriate thing to do. The sqlite3_mutex_notheld() 03458 ** interface should also return 1 when given a NULL pointer. 03459 */ 03460 int sqlite3_mutex_held(sqlite3_mutex*); 03461 int sqlite3_mutex_notheld(sqlite3_mutex*); 03462 03463 /* 03464 ** CAPI3REF: Mutex Types 03465 ** 03466 ** The [sqlite3_mutex_alloc()] interface takes a single argument 03467 ** which is one of these integer constants. 03468 */ 03469 #define SQLITE_MUTEX_FAST 0 03470 #define SQLITE_MUTEX_RECURSIVE 1 03471 #define SQLITE_MUTEX_STATIC_MASTER 2 03472 #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */ 03473 #define SQLITE_MUTEX_STATIC_MEM2 4 /* sqlite3_release_memory() */ 03474 #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */ 03475 #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */ 03476 03477 /* 03478 ** CAPI3REF: Low-Level Control Of Database Files 03479 ** 03480 ** The [sqlite3_file_control()] interface makes a direct call to the 03481 ** xFileControl method for the [sqlite3_io_methods] object associated 03482 ** with a particular database identified by the second argument. The 03483 ** name of the database is the name assigned to the database by the 03484 ** <a href="lang_attach.html">ATTACH</a> SQL command that opened the 03485 ** database. To control the main database file, use the name "main" 03486 ** or a NULL pointer. The third and fourth parameters to this routine 03487 ** are passed directly through to the second and third parameters of 03488 ** the xFileControl method. The return value of the xFileControl 03489 ** method becomes the return value of this routine. 03490 ** 03491 ** If the second parameter (zDbName) does not match the name of any 03492 ** open database file, then SQLITE_ERROR is returned. This error 03493 ** code is not remembered and will not be recalled by [sqlite3_errcode()] 03494 ** or [sqlite3_errmsg()]. The underlying xFileControl method might 03495 ** also return SQLITE_ERROR. There is no way to distinguish between 03496 ** an incorrect zDbName and an SQLITE_ERROR return from the underlying 03497 ** xFileControl method. 03498 ** 03499 ** See also: [SQLITE_FCNTL_LOCKSTATE] 03500 */ 03501 int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*); 03502 03503 /* 03504 ** Undo the hack that converts floating point types to integer for 03505 ** builds on processors without floating point support. 03506 */ 03507 #ifdef SQLITE_OMIT_FLOATING_POINT 03508 # undef double 03509 #endif 03510 03511 #ifdef __cplusplus 03512 } /* End of the 'extern "C"' block */ 03513 #endif 03514 #endif