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. 00014 ** 00015 ** @(#) $Id: sqlite.h.in,v 1.201 2007/03/30 20:43:42 drh Exp $ 00016 */ 00017 #ifndef _SQLITE3_H_ 00018 #define _SQLITE3_H_ 00019 #include <stdarg.h> /* Needed for the definition of va_list */ 00020 00021 /* 00022 ** Make sure we can call this stuff from C++. 00023 */ 00024 #ifdef __cplusplus 00025 extern "C" { 00026 #endif 00027 00028 /* 00029 ** The version of the SQLite library. 00030 */ 00031 #ifdef SQLITE_VERSION 00032 # undef SQLITE_VERSION 00033 #endif 00034 #define SQLITE_VERSION "3.3.17" 00035 00036 /* 00037 ** The format of the version string is "X.Y.Z<trailing string>", where 00038 ** X is the major version number, Y is the minor version number and Z 00039 ** is the release number. The trailing string is often "alpha" or "beta". 00040 ** For example "3.1.1beta". 00041 ** 00042 ** The SQLITE_VERSION_NUMBER is an integer with the value 00043 ** (X*100000 + Y*1000 + Z). For example, for version "3.1.1beta", 00044 ** SQLITE_VERSION_NUMBER is set to 3001001. To detect if they are using 00045 ** version 3.1.1 or greater at compile time, programs may use the test 00046 ** (SQLITE_VERSION_NUMBER>=3001001). 00047 */ 00048 #ifdef SQLITE_VERSION_NUMBER 00049 # undef SQLITE_VERSION_NUMBER 00050 #endif 00051 #define SQLITE_VERSION_NUMBER 3003017 00052 00053 /* 00054 ** The version string is also compiled into the library so that a program 00055 ** can check to make sure that the lib*.a file and the *.h file are from 00056 ** the same version. The sqlite3_libversion() function returns a pointer 00057 ** to the sqlite3_version variable - useful in DLLs which cannot access 00058 ** global variables. 00059 */ 00060 extern const char sqlite3_version[]; 00061 const char *sqlite3_libversion(void); 00062 00063 /* 00064 ** Return the value of the SQLITE_VERSION_NUMBER macro when the 00065 ** library was compiled. 00066 */ 00067 int sqlite3_libversion_number(void); 00068 00069 /* 00070 ** Each open sqlite database is represented by an instance of the 00071 ** following opaque structure. 00072 */ 00073 typedef struct sqlite3 sqlite3; 00074 00075 00076 /* 00077 ** Some compilers do not support the "long long" datatype. So we have 00078 ** to do a typedef that for 64-bit integers that depends on what compiler 00079 ** is being used. 00080 */ 00081 #ifdef SQLITE_INT64_TYPE 00082 typedef SQLITE_INT64_TYPE sqlite_int64; 00083 typedef unsigned SQLITE_INT64_TYPE sqlite_uint64; 00084 #elif defined(_MSC_VER) || defined(__BORLANDC__) 00085 typedef __int64 sqlite_int64; 00086 typedef unsigned __int64 sqlite_uint64; 00087 #else 00088 typedef long long int sqlite_int64; 00089 typedef unsigned long long int sqlite_uint64; 00090 #endif 00091 00092 /* 00093 ** If compiling for a processor that lacks floating point support, 00094 ** substitute integer for floating-point 00095 */ 00096 #ifdef SQLITE_OMIT_FLOATING_POINT 00097 # define double sqlite_int64 00098 #endif 00099 00100 /* 00101 ** A function to close the database. 00102 ** 00103 ** Call this function with a pointer to a structure that was previously 00104 ** returned from sqlite3_open() and the corresponding database will by closed. 00105 ** 00106 ** All SQL statements prepared using sqlite3_prepare() or 00107 ** sqlite3_prepare16() must be deallocated using sqlite3_finalize() before 00108 ** this routine is called. Otherwise, SQLITE_BUSY is returned and the 00109 ** database connection remains open. 00110 */ 00111 int sqlite3_close(sqlite3 *); 00112 00113 /* 00114 ** The type for a callback function. 00115 */ 00116 typedef int (*sqlite3_callback)(void*,int,char**, char**); 00117 00118 /* 00119 ** A function to executes one or more statements of SQL. 00120 ** 00121 ** If one or more of the SQL statements are queries, then 00122 ** the callback function specified by the 3rd parameter is 00123 ** invoked once for each row of the query result. This callback 00124 ** should normally return 0. If the callback returns a non-zero 00125 ** value then the query is aborted, all subsequent SQL statements 00126 ** are skipped and the sqlite3_exec() function returns the SQLITE_ABORT. 00127 ** 00128 ** The 1st parameter is an arbitrary pointer that is passed 00129 ** to the callback function as its first parameter. 00130 ** 00131 ** The 2nd parameter to the callback function is the number of 00132 ** columns in the query result. The 3rd parameter to the callback 00133 ** is an array of strings holding the values for each column. 00134 ** The 4th parameter to the callback is an array of strings holding 00135 ** the names of each column. 00136 ** 00137 ** The callback function may be NULL, even for queries. A NULL 00138 ** callback is not an error. It just means that no callback 00139 ** will be invoked. 00140 ** 00141 ** If an error occurs while parsing or evaluating the SQL (but 00142 ** not while executing the callback) then an appropriate error 00143 ** message is written into memory obtained from malloc() and 00144 ** *errmsg is made to point to that message. The calling function 00145 ** is responsible for freeing the memory that holds the error 00146 ** message. Use sqlite3_free() for this. If errmsg==NULL, 00147 ** then no error message is ever written. 00148 ** 00149 ** The return value is is SQLITE_OK if there are no errors and 00150 ** some other return code if there is an error. The particular 00151 ** return value depends on the type of error. 00152 ** 00153 ** If the query could not be executed because a database file is 00154 ** locked or busy, then this function returns SQLITE_BUSY. (This 00155 ** behavior can be modified somewhat using the sqlite3_busy_handler() 00156 ** and sqlite3_busy_timeout() functions below.) 00157 */ 00158 int sqlite3_exec( 00159 sqlite3*, /* An open database */ 00160 const char *sql, /* SQL to be executed */ 00161 sqlite3_callback, /* Callback function */ 00162 void *, /* 1st argument to callback function */ 00163 char **errmsg /* Error msg written here */ 00164 ); 00165 00166 /* 00167 ** Return values for sqlite3_exec() and sqlite3_step() 00168 */ 00169 #define SQLITE_OK 0 /* Successful result */ 00170 /* beginning-of-error-codes */ 00171 #define SQLITE_ERROR 1 /* SQL error or missing database */ 00172 #define SQLITE_INTERNAL 2 /* NOT USED. Internal logic error in SQLite */ 00173 #define SQLITE_PERM 3 /* Access permission denied */ 00174 #define SQLITE_ABORT 4 /* Callback routine requested an abort */ 00175 #define SQLITE_BUSY 5 /* The database file is locked */ 00176 #define SQLITE_LOCKED 6 /* A table in the database is locked */ 00177 #define SQLITE_NOMEM 7 /* A malloc() failed */ 00178 #define SQLITE_READONLY 8 /* Attempt to write a readonly database */ 00179 #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/ 00180 #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ 00181 #define SQLITE_CORRUPT 11 /* The database disk image is malformed */ 00182 #define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */ 00183 #define SQLITE_FULL 13 /* Insertion failed because database is full */ 00184 #define SQLITE_CANTOPEN 14 /* Unable to open the database file */ 00185 #define SQLITE_PROTOCOL 15 /* NOT USED. Database lock protocol error */ 00186 #define SQLITE_EMPTY 16 /* Database is empty */ 00187 #define SQLITE_SCHEMA 17 /* The database schema changed */ 00188 #define SQLITE_TOOBIG 18 /* NOT USED. Too much data for one row */ 00189 #define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */ 00190 #define SQLITE_MISMATCH 20 /* Data type mismatch */ 00191 #define SQLITE_MISUSE 21 /* Library used incorrectly */ 00192 #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ 00193 #define SQLITE_AUTH 23 /* Authorization denied */ 00194 #define SQLITE_FORMAT 24 /* Auxiliary database format error */ 00195 #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */ 00196 #define SQLITE_NOTADB 26 /* File opened that is not a database file */ 00197 #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ 00198 #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ 00199 /* end-of-error-codes */ 00200 00201 /* 00202 ** Using the sqlite3_extended_result_codes() API, you can cause 00203 ** SQLite to return result codes with additional information in 00204 ** their upper bits. The lower 8 bits will be the same as the 00205 ** primary result codes above. But the upper bits might contain 00206 ** more specific error information. 00207 ** 00208 ** To extract the primary result code from an extended result code, 00209 ** simply mask off the lower 8 bits. 00210 ** 00211 ** primary = extended & 0xff; 00212 ** 00213 ** New result error codes may be added from time to time. Software 00214 ** that uses the extended result codes should plan accordingly and be 00215 ** sure to always handle new unknown codes gracefully. 00216 ** 00217 ** The SQLITE_OK result code will never be extended. It will always 00218 ** be exactly zero. 00219 ** 00220 ** The extended result codes always have the primary result code 00221 ** as a prefix. Primary result codes only contain a single "_" 00222 ** character. Extended result codes contain two or more "_" characters. 00223 */ 00224 #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8)) 00225 #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8)) 00226 #define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8)) 00227 #define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8)) 00228 #define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8)) 00229 #define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8)) 00230 #define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8)) 00231 #define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8)) 00232 #define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8)) 00233 #define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8)) 00234 00235 /* 00236 ** Enable or disable the extended result codes. 00237 */ 00238 int sqlite3_extended_result_codes(sqlite3*, int onoff); 00239 00240 /* 00241 ** Each entry in an SQLite table has a unique integer key. (The key is 00242 ** the value of the INTEGER PRIMARY KEY column if there is such a column, 00243 ** otherwise the key is generated automatically. The unique key is always 00244 ** available as the ROWID, OID, or _ROWID_ column.) The following routine 00245 ** returns the integer key of the most recent insert in the database. 00246 */ 00247 sqlite_int64 sqlite3_last_insert_rowid(sqlite3*); 00248 00249 /* 00250 ** This function returns the number of database rows that were changed 00251 ** (or inserted or deleted) by the most recent SQL statement. Only 00252 ** changes that are directly specified by the INSERT, UPDATE, or 00253 ** DELETE statement are counted. Auxiliary changes caused by 00254 ** triggers are not counted. Within the body of a trigger, however, 00255 ** the sqlite3_changes() API can be called to find the number of 00256 ** changes in the most recently completed INSERT, UPDATE, or DELETE 00257 ** statement within the body of the trigger. 00258 ** 00259 ** All changes are counted, even if they were later undone by a 00260 ** ROLLBACK or ABORT. Except, changes associated with creating and 00261 ** dropping tables are not counted. 00262 ** 00263 ** If a callback invokes sqlite3_exec() or sqlite3_step() recursively, 00264 ** then the changes in the inner, recursive call are counted together 00265 ** with the changes in the outer call. 00266 ** 00267 ** SQLite implements the command "DELETE FROM table" without a WHERE clause 00268 ** by dropping and recreating the table. (This is much faster than going 00269 ** through and deleting individual elements form the table.) Because of 00270 ** this optimization, the change count for "DELETE FROM table" will be 00271 ** zero regardless of the number of elements that were originally in the 00272 ** table. To get an accurate count of the number of rows deleted, use 00273 ** "DELETE FROM table WHERE 1" instead. 00274 */ 00275 int sqlite3_changes(sqlite3*); 00276 00277 /* 00278 ** This function returns the number of database rows that have been 00279 ** modified by INSERT, UPDATE or DELETE statements since the database handle 00280 ** was opened. This includes UPDATE, INSERT and DELETE statements executed 00281 ** as part of trigger programs. All changes are counted as soon as the 00282 ** statement that makes them is completed (when the statement handle is 00283 ** passed to sqlite3_reset() or sqlite_finalise()). 00284 ** 00285 ** SQLite implements the command "DELETE FROM table" without a WHERE clause 00286 ** by dropping and recreating the table. (This is much faster than going 00287 ** through and deleting individual elements form the table.) Because of 00288 ** this optimization, the change count for "DELETE FROM table" will be 00289 ** zero regardless of the number of elements that were originally in the 00290 ** table. To get an accurate count of the number of rows deleted, use 00291 ** "DELETE FROM table WHERE 1" instead. 00292 */ 00293 int sqlite3_total_changes(sqlite3*); 00294 00295 /* This function causes any pending database operation to abort and 00296 ** return at its earliest opportunity. This routine is typically 00297 ** called in response to a user action such as pressing "Cancel" 00298 ** or Ctrl-C where the user wants a long query operation to halt 00299 ** immediately. 00300 ** 00301 ** It is safe to call this routine from a different thread that the 00302 ** thread that is currently running the database operation. 00303 */ 00304 void sqlite3_interrupt(sqlite3*); 00305 00306 00307 /* These functions return true if the given input string comprises 00308 ** one or more complete SQL statements. For the sqlite3_complete() call, 00309 ** the parameter must be a nul-terminated UTF-8 string. For 00310 ** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string 00311 ** is required. 00312 ** 00313 ** This routine is useful for command-line input to see of the user has 00314 ** entered a complete statement of SQL or if the current statement needs 00315 ** to be continued on the next line. The algorithm is simple. If the 00316 ** last token other than spaces and comments is a semicolon, then return 00317 ** true. Actually, the algorithm is a little more complicated than that 00318 ** in order to deal with triggers, but the basic idea is the same: the 00319 ** statement is not complete unless it ends in a semicolon. 00320 */ 00321 int sqlite3_complete(const char *sql); 00322 int sqlite3_complete16(const void *sql); 00323 00324 /* 00325 ** This routine identifies a callback function that is invoked 00326 ** whenever an attempt is made to open a database table that is 00327 ** currently locked by another process or thread. If the busy callback 00328 ** is NULL, then sqlite3_exec() returns SQLITE_BUSY immediately if 00329 ** it finds a locked table. If the busy callback is not NULL, then 00330 ** sqlite3_exec() invokes the callback with two arguments. The 00331 ** first argument to the handler is a copy of the void* pointer which 00332 ** is the third argument to this routine. The second argument to 00333 ** the handler is the number of times that the busy handler has 00334 ** been invoked for this locking event. If the 00335 ** busy callback returns 0, then sqlite3_exec() immediately returns 00336 ** SQLITE_BUSY. If the callback returns non-zero, then sqlite3_exec() 00337 ** tries to open the table again and the cycle repeats. 00338 ** 00339 ** The presence of a busy handler does not guarantee that 00340 ** it will be invoked when there is lock contention. 00341 ** If SQLite determines that invoking the busy handler could result in 00342 ** a deadlock, it will return SQLITE_BUSY instead. 00343 ** Consider a scenario where one process is holding a read lock that 00344 ** it is trying to promote to a reserved lock and 00345 ** a second process is holding a reserved lock that it is trying 00346 ** to promote to an exclusive lock. The first process cannot proceed 00347 ** because it is blocked by the second and the second process cannot 00348 ** proceed because it is blocked by the first. If both processes 00349 ** invoke the busy handlers, neither will make any progress. Therefore, 00350 ** SQLite returns SQLITE_BUSY for the first process, hoping that this 00351 ** will induce the first process to release its read lock and allow 00352 ** the second process to proceed. 00353 ** 00354 ** The default busy callback is NULL. 00355 ** 00356 ** Sqlite is re-entrant, so the busy handler may start a new query. 00357 ** (It is not clear why anyone would every want to do this, but it 00358 ** is allowed, in theory.) But the busy handler may not close the 00359 ** database. Closing the database from a busy handler will delete 00360 ** data structures out from under the executing query and will 00361 ** probably result in a coredump. 00362 */ 00363 int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); 00364 00365 /* 00366 ** This routine sets a busy handler that sleeps for a while when a 00367 ** table is locked. The handler will sleep multiple times until 00368 ** at least "ms" milleseconds of sleeping have been done. After 00369 ** "ms" milleseconds of sleeping, the handler returns 0 which 00370 ** causes sqlite3_exec() to return SQLITE_BUSY. 00371 ** 00372 ** Calling this routine with an argument less than or equal to zero 00373 ** turns off all busy handlers. 00374 */ 00375 int sqlite3_busy_timeout(sqlite3*, int ms); 00376 00377 /* 00378 ** This next routine is really just a wrapper around sqlite3_exec(). 00379 ** Instead of invoking a user-supplied callback for each row of the 00380 ** result, this routine remembers each row of the result in memory 00381 ** obtained from malloc(), then returns all of the result after the 00382 ** query has finished. 00383 ** 00384 ** As an example, suppose the query result where this table: 00385 ** 00386 ** Name | Age 00387 ** ----------------------- 00388 ** Alice | 43 00389 ** Bob | 28 00390 ** Cindy | 21 00391 ** 00392 ** If the 3rd argument were &azResult then after the function returns 00393 ** azResult will contain the following data: 00394 ** 00395 ** azResult[0] = "Name"; 00396 ** azResult[1] = "Age"; 00397 ** azResult[2] = "Alice"; 00398 ** azResult[3] = "43"; 00399 ** azResult[4] = "Bob"; 00400 ** azResult[5] = "28"; 00401 ** azResult[6] = "Cindy"; 00402 ** azResult[7] = "21"; 00403 ** 00404 ** Notice that there is an extra row of data containing the column 00405 ** headers. But the *nrow return value is still 3. *ncolumn is 00406 ** set to 2. In general, the number of values inserted into azResult 00407 ** will be ((*nrow) + 1)*(*ncolumn). 00408 ** 00409 ** After the calling function has finished using the result, it should 00410 ** pass the result data pointer to sqlite3_free_table() in order to 00411 ** release the memory that was malloc-ed. Because of the way the 00412 ** malloc() happens, the calling function must not try to call 00413 ** free() directly. Only sqlite3_free_table() is able to release 00414 ** the memory properly and safely. 00415 ** 00416 ** The return value of this routine is the same as from sqlite3_exec(). 00417 */ 00418 int sqlite3_get_table( 00419 sqlite3*, /* An open database */ 00420 const char *sql, /* SQL to be executed */ 00421 char ***resultp, /* Result written to a char *[] that this points to */ 00422 int *nrow, /* Number of result rows written here */ 00423 int *ncolumn, /* Number of result columns written here */ 00424 char **errmsg /* Error msg written here */ 00425 ); 00426 00427 /* 00428 ** Call this routine to free the memory that sqlite3_get_table() allocated. 00429 */ 00430 void sqlite3_free_table(char **result); 00431 00432 /* 00433 ** The following routines are variants of the "sprintf()" from the 00434 ** standard C library. The resulting string is written into memory 00435 ** obtained from malloc() so that there is never a possiblity of buffer 00436 ** overflow. These routines also implement some additional formatting 00437 ** options that are useful for constructing SQL statements. 00438 ** 00439 ** The strings returned by these routines should be freed by calling 00440 ** sqlite3_free(). 00441 ** 00442 ** All of the usual printf formatting options apply. In addition, there 00443 ** is a "%q" option. %q works like %s in that it substitutes a null-terminated 00444 ** string from the argument list. But %q also doubles every '\'' character. 00445 ** %q is designed for use inside a string literal. By doubling each '\'' 00446 ** character it escapes that character and allows it to be inserted into 00447 ** the string. 00448 ** 00449 ** For example, so some string variable contains text as follows: 00450 ** 00451 ** char *zText = "It's a happy day!"; 00452 ** 00453 ** We can use this text in an SQL statement as follows: 00454 ** 00455 ** char *z = sqlite3_mprintf("INSERT INTO TABLES('%q')", zText); 00456 ** sqlite3_exec(db, z, callback1, 0, 0); 00457 ** sqlite3_free(z); 00458 ** 00459 ** Because the %q format string is used, the '\'' character in zText 00460 ** is escaped and the SQL generated is as follows: 00461 ** 00462 ** INSERT INTO table1 VALUES('It''s a happy day!') 00463 ** 00464 ** This is correct. Had we used %s instead of %q, the generated SQL 00465 ** would have looked like this: 00466 ** 00467 ** INSERT INTO table1 VALUES('It's a happy day!'); 00468 ** 00469 ** This second example is an SQL syntax error. As a general rule you 00470 ** should always use %q instead of %s when inserting text into a string 00471 ** literal. 00472 */ 00473 char *sqlite3_mprintf(const char*,...); 00474 char *sqlite3_vmprintf(const char*, va_list); 00475 char *sqlite3_snprintf(int,char*,const char*, ...); 00476 00477 /* 00478 ** SQLite uses its own memory allocator. On many installations, this 00479 ** memory allocator is identical to the standard malloc()/realloc()/free() 00480 ** and can be used interchangable. On others, the implementations are 00481 ** different. For maximum portability, it is best not to mix calls 00482 ** to the standard malloc/realloc/free with the sqlite versions. 00483 */ 00484 void *sqlite3_malloc(int); 00485 void *sqlite3_realloc(void*, int); 00486 void sqlite3_free(void*); 00487 00488 #ifndef SQLITE_OMIT_AUTHORIZATION 00489 /* 00490 ** This routine registers a callback with the SQLite library. The 00491 ** callback is invoked (at compile-time, not at run-time) for each 00492 ** attempt to access a column of a table in the database. The callback 00493 ** returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire 00494 ** SQL statement should be aborted with an error and SQLITE_IGNORE 00495 ** if the column should be treated as a NULL value. 00496 */ 00497 int sqlite3_set_authorizer( 00498 sqlite3*, 00499 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), 00500 void *pUserData 00501 ); 00502 #endif 00503 00504 /* 00505 ** The second parameter to the access authorization function above will 00506 ** be one of the values below. These values signify what kind of operation 00507 ** is to be authorized. The 3rd and 4th parameters to the authorization 00508 ** function will be parameters or NULL depending on which of the following 00509 ** codes is used as the second parameter. The 5th parameter is the name 00510 ** of the database ("main", "temp", etc.) if applicable. The 6th parameter 00511 ** is the name of the inner-most trigger or view that is responsible for 00512 ** the access attempt or NULL if this access attempt is directly from 00513 ** input SQL code. 00514 ** 00515 ** Arg-3 Arg-4 00516 */ 00517 #define SQLITE_COPY 0 /* Table Name File Name */ 00518 #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ 00519 #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */ 00520 #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */ 00521 #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */ 00522 #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */ 00523 #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */ 00524 #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */ 00525 #define SQLITE_CREATE_VIEW 8 /* View Name NULL */ 00526 #define SQLITE_DELETE 9 /* Table Name NULL */ 00527 #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */ 00528 #define SQLITE_DROP_TABLE 11 /* Table Name NULL */ 00529 #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */ 00530 #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */ 00531 #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */ 00532 #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */ 00533 #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */ 00534 #define SQLITE_DROP_VIEW 17 /* View Name NULL */ 00535 #define SQLITE_INSERT 18 /* Table Name NULL */ 00536 #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */ 00537 #define SQLITE_READ 20 /* Table Name Column Name */ 00538 #define SQLITE_SELECT 21 /* NULL NULL */ 00539 #define SQLITE_TRANSACTION 22 /* NULL NULL */ 00540 #define SQLITE_UPDATE 23 /* Table Name Column Name */ 00541 #define SQLITE_ATTACH 24 /* Filename NULL */ 00542 #define SQLITE_DETACH 25 /* Database Name NULL */ 00543 #define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */ 00544 #define SQLITE_REINDEX 27 /* Index Name NULL */ 00545 #define SQLITE_ANALYZE 28 /* Table Name NULL */ 00546 #define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */ 00547 #define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */ 00548 #define SQLITE_FUNCTION 31 /* Function Name NULL */ 00549 00550 /* 00551 ** The return value of the authorization function should be one of the 00552 ** following constants: 00553 */ 00554 /* #define SQLITE_OK 0 // Allow access (This is actually defined above) */ 00555 #define SQLITE_DENY 1 /* Abort the SQL statement with an error */ 00556 #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ 00557 00558 /* 00559 ** Register a function for tracing SQL command evaluation. The function 00560 ** registered by sqlite3_trace() is invoked at the first sqlite3_step() 00561 ** for the evaluation of an SQL statement. The function registered by 00562 ** sqlite3_profile() runs at the end of each SQL statement and includes 00563 ** information on how long that statement ran. 00564 ** 00565 ** The sqlite3_profile() API is currently considered experimental and 00566 ** is subject to change. 00567 */ 00568 void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); 00569 void *sqlite3_profile(sqlite3*, 00570 void(*xProfile)(void*,const char*,sqlite_uint64), void*); 00571 00572 /* 00573 ** This routine configures a callback function - the progress callback - that 00574 ** is invoked periodically during long running calls to sqlite3_exec(), 00575 ** sqlite3_step() and sqlite3_get_table(). An example use for this API is to 00576 ** keep a GUI updated during a large query. 00577 ** 00578 ** The progress callback is invoked once for every N virtual machine opcodes, 00579 ** where N is the second argument to this function. The progress callback 00580 ** itself is identified by the third argument to this function. The fourth 00581 ** argument to this function is a void pointer passed to the progress callback 00582 ** function each time it is invoked. 00583 ** 00584 ** If a call to sqlite3_exec(), sqlite3_step() or sqlite3_get_table() results 00585 ** in less than N opcodes being executed, then the progress callback is not 00586 ** invoked. 00587 ** 00588 ** To remove the progress callback altogether, pass NULL as the third 00589 ** argument to this function. 00590 ** 00591 ** If the progress callback returns a result other than 0, then the current 00592 ** query is immediately terminated and any database changes rolled back. If the 00593 ** query was part of a larger transaction, then the transaction is not rolled 00594 ** back and remains active. The sqlite3_exec() call returns SQLITE_ABORT. 00595 ** 00596 ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ****** 00597 */ 00598 void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); 00599 00600 /* 00601 ** Register a callback function to be invoked whenever a new transaction 00602 ** is committed. The pArg argument is passed through to the callback. 00603 ** callback. If the callback function returns non-zero, then the commit 00604 ** is converted into a rollback. 00605 ** 00606 ** If another function was previously registered, its pArg value is returned. 00607 ** Otherwise NULL is returned. 00608 ** 00609 ** Registering a NULL function disables the callback. 00610 ** 00611 ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ****** 00612 */ 00613 void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); 00614 00615 /* 00616 ** Open the sqlite database file "filename". The "filename" is UTF-8 00617 ** encoded for sqlite3_open() and UTF-16 encoded in the native byte order 00618 ** for sqlite3_open16(). An sqlite3* handle is returned in *ppDb, even 00619 ** if an error occurs. If the database is opened (or created) successfully, 00620 ** then SQLITE_OK is returned. Otherwise an error code is returned. The 00621 ** sqlite3_errmsg() or sqlite3_errmsg16() routines can be used to obtain 00622 ** an English language description of the error. 00623 ** 00624 ** If the database file does not exist, then a new database is created. 00625 ** The encoding for the database is UTF-8 if sqlite3_open() is called and 00626 ** UTF-16 if sqlite3_open16 is used. 00627 ** 00628 ** Whether or not an error occurs when it is opened, resources associated 00629 ** with the sqlite3* handle should be released by passing it to 00630 ** sqlite3_close() when it is no longer required. 00631 */ 00632 int sqlite3_open( 00633 const char *filename, /* Database filename (UTF-8) */ 00634 sqlite3 **ppDb /* OUT: SQLite db handle */ 00635 ); 00636 int sqlite3_open16( 00637 const void *filename, /* Database filename (UTF-16) */ 00638 sqlite3 **ppDb /* OUT: SQLite db handle */ 00639 ); 00640 00641 /* 00642 ** Return the error code for the most recent sqlite3_* API call associated 00643 ** with sqlite3 handle 'db'. SQLITE_OK is returned if the most recent 00644 ** API call was successful. 00645 ** 00646 ** Calls to many sqlite3_* functions set the error code and string returned 00647 ** by sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16() 00648 ** (overwriting the previous values). Note that calls to sqlite3_errcode(), 00649 ** sqlite3_errmsg() and sqlite3_errmsg16() themselves do not affect the 00650 ** results of future invocations. 00651 ** 00652 ** Assuming no other intervening sqlite3_* API calls are made, the error 00653 ** code returned by this function is associated with the same error as 00654 ** the strings returned by sqlite3_errmsg() and sqlite3_errmsg16(). 00655 */ 00656 int sqlite3_errcode(sqlite3 *db); 00657 00658 /* 00659 ** Return a pointer to a UTF-8 encoded string describing in english the 00660 ** error condition for the most recent sqlite3_* API call. The returned 00661 ** string is always terminated by an 0x00 byte. 00662 ** 00663 ** The string "not an error" is returned when the most recent API call was 00664 ** successful. 00665 */ 00666 const char *sqlite3_errmsg(sqlite3*); 00667 00668 /* 00669 ** Return a pointer to a UTF-16 native byte order encoded string describing 00670 ** in english the error condition for the most recent sqlite3_* API call. 00671 ** The returned string is always terminated by a pair of 0x00 bytes. 00672 ** 00673 ** The string "not an error" is returned when the most recent API call was 00674 ** successful. 00675 */ 00676 const void *sqlite3_errmsg16(sqlite3*); 00677 00678 /* 00679 ** An instance of the following opaque structure is used to represent 00680 ** a compiled SQL statment. 00681 */ 00682 typedef struct sqlite3_stmt sqlite3_stmt; 00683 00684 /* 00685 ** To execute an SQL query, it must first be compiled into a byte-code 00686 ** program using one of the following routines. The only difference between 00687 ** them is that the second argument, specifying the SQL statement to 00688 ** compile, is assumed to be encoded in UTF-8 for the sqlite3_prepare() 00689 ** function and UTF-16 for sqlite3_prepare16(). 00690 ** 00691 ** The first parameter "db" is an SQLite database handle. The second 00692 ** parameter "zSql" is the statement to be compiled, encoded as either 00693 ** UTF-8 or UTF-16 (see above). If the next parameter, "nBytes", is less 00694 ** than zero, then zSql is read up to the first nul terminator. If 00695 ** "nBytes" is not less than zero, then it is the length of the string zSql 00696 ** in bytes (not characters). 00697 ** 00698 ** *pzTail is made to point to the first byte past the end of the first 00699 ** SQL statement in zSql. This routine only compiles the first statement 00700 ** in zSql, so *pzTail is left pointing to what remains uncompiled. 00701 ** 00702 ** *ppStmt is left pointing to a compiled SQL statement that can be 00703 ** executed using sqlite3_step(). Or if there is an error, *ppStmt may be 00704 ** set to NULL. If the input text contained no SQL (if the input is and 00705 ** empty string or a comment) then *ppStmt is set to NULL. 00706 ** 00707 ** On success, SQLITE_OK is returned. Otherwise an error code is returned. 00708 */ 00709 int sqlite3_prepare( 00710 sqlite3 *db, /* Database handle */ 00711 const char *zSql, /* SQL statement, UTF-8 encoded */ 00712 int nBytes, /* Length of zSql in bytes. */ 00713 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 00714 const char **pzTail /* OUT: Pointer to unused portion of zSql */ 00715 ); 00716 int sqlite3_prepare16( 00717 sqlite3 *db, /* Database handle */ 00718 const void *zSql, /* SQL statement, UTF-16 encoded */ 00719 int nBytes, /* Length of zSql in bytes. */ 00720 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 00721 const void **pzTail /* OUT: Pointer to unused portion of zSql */ 00722 ); 00723 00724 /* 00725 ** Newer versions of the prepare API work just like the legacy versions 00726 ** but with one exception: The a copy of the SQL text is saved in the 00727 ** sqlite3_stmt structure that is returned. If this copy exists, it 00728 ** modifieds the behavior of sqlite3_step() slightly. First, sqlite3_step() 00729 ** will no longer return an SQLITE_SCHEMA error but will instead automatically 00730 ** rerun the compiler to rebuild the prepared statement. Secondly, 00731 ** sqlite3_step() now turns a full result code - the result code that 00732 ** use used to have to call sqlite3_reset() to get. 00733 */ 00734 int sqlite3_prepare_v2( 00735 sqlite3 *db, /* Database handle */ 00736 const char *zSql, /* SQL statement, UTF-8 encoded */ 00737 int nBytes, /* Length of zSql in bytes. */ 00738 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 00739 const char **pzTail /* OUT: Pointer to unused portion of zSql */ 00740 ); 00741 int sqlite3_prepare16_v2( 00742 sqlite3 *db, /* Database handle */ 00743 const void *zSql, /* SQL statement, UTF-16 encoded */ 00744 int nBytes, /* Length of zSql in bytes. */ 00745 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 00746 const void **pzTail /* OUT: Pointer to unused portion of zSql */ 00747 ); 00748 00749 /* 00750 ** Pointers to the following two opaque structures are used to communicate 00751 ** with the implementations of user-defined functions. 00752 */ 00753 typedef struct sqlite3_context sqlite3_context; 00754 typedef struct Mem sqlite3_value; 00755 00756 /* 00757 ** In the SQL strings input to sqlite3_prepare() and sqlite3_prepare16(), 00758 ** one or more literals can be replace by parameters "?" or "?NNN" or 00759 ** ":AAA" or "@AAA" or "$VVV" where NNN is a integer, AAA is an identifer, 00760 ** and VVV is a variable name according to the syntax rules of the 00761 ** TCL programming language. The value of these parameters (also called 00762 ** "host parameter names") can be set using the routines listed below. 00763 ** 00764 ** In every case, the first argument is a pointer to the sqlite3_stmt 00765 ** structure returned from sqlite3_prepare(). The second argument is the 00766 ** index of the host parameter name. The first host parameter as an index 00767 ** of 1. For named host parameters (":AAA" or "$VVV") you can use 00768 ** sqlite3_bind_parameter_index() to get the correct index value given 00769 ** the parameter name. If the same named parameter occurs more than 00770 ** once, it is assigned the same index each time. 00771 ** 00772 ** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and 00773 ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or 00774 ** text after SQLite has finished with it. If the fifth argument is the 00775 ** special value SQLITE_STATIC, then the library assumes that the information 00776 ** is in static, unmanaged space and does not need to be freed. If the 00777 ** fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its 00778 ** own private copy of the data before the sqlite3_bind_* routine returns. 00779 ** 00780 ** The sqlite3_bind_* routine must be called before sqlite3_step() and after 00781 ** an sqlite3_prepare() or sqlite3_reset(). Bindings persist across 00782 ** multiple calls to sqlite3_reset() and sqlite3_step(). Unbound parameters 00783 ** are interpreted as NULL. 00784 */ 00785 int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); 00786 int sqlite3_bind_double(sqlite3_stmt*, int, double); 00787 int sqlite3_bind_int(sqlite3_stmt*, int, int); 00788 int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite_int64); 00789 int sqlite3_bind_null(sqlite3_stmt*, int); 00790 int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); 00791 int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); 00792 int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); 00793 00794 /* 00795 ** Return the number of host parameters in a compiled SQL statement. This 00796 ** routine was added to support DBD::SQLite. 00797 */ 00798 int sqlite3_bind_parameter_count(sqlite3_stmt*); 00799 00800 /* 00801 ** Return the name of the i-th name parameter. Ordinary parameters "?" are 00802 ** nameless and a NULL is returned. For parameters of the form :AAA or 00803 ** $VVV the complete text of the parameter name is returned, including 00804 ** the initial ":" or "$". NULL is returned if the index is out of range. 00805 */ 00806 const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); 00807 00808 /* 00809 ** Return the index of a parameter with the given name. The name 00810 ** must match exactly. If no parameter with the given name is found, 00811 ** return 0. 00812 */ 00813 int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); 00814 00815 /* 00816 ** Set all the parameters in the compiled SQL statement to NULL. 00817 */ 00818 int sqlite3_clear_bindings(sqlite3_stmt*); 00819 00820 /* 00821 ** Return the number of columns in the result set returned by the compiled 00822 ** SQL statement. This routine returns 0 if pStmt is an SQL statement 00823 ** that does not return data (for example an UPDATE). 00824 */ 00825 int sqlite3_column_count(sqlite3_stmt *pStmt); 00826 00827 /* 00828 ** The first parameter is a compiled SQL statement. This function returns 00829 ** the column heading for the Nth column of that statement, where N is the 00830 ** second function parameter. The string returned is UTF-8 for 00831 ** sqlite3_column_name() and UTF-16 for sqlite3_column_name16(). 00832 */ 00833 const char *sqlite3_column_name(sqlite3_stmt*,int); 00834 const void *sqlite3_column_name16(sqlite3_stmt*,int); 00835 00836 /* 00837 ** The first argument to the following calls is a compiled SQL statement. 00838 ** These functions return information about the Nth column returned by 00839 ** the statement, where N is the second function argument. 00840 ** 00841 ** If the Nth column returned by the statement is not a column value, 00842 ** then all of the functions return NULL. Otherwise, the return the 00843 ** name of the attached database, table and column that the expression 00844 ** extracts a value from. 00845 ** 00846 ** As with all other SQLite APIs, those postfixed with "16" return UTF-16 00847 ** encoded strings, the other functions return UTF-8. The memory containing 00848 ** the returned strings is valid until the statement handle is finalized(). 00849 ** 00850 ** These APIs are only available if the library was compiled with the 00851 ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. 00852 */ 00853 const char *sqlite3_column_database_name(sqlite3_stmt*,int); 00854 const void *sqlite3_column_database_name16(sqlite3_stmt*,int); 00855 const char *sqlite3_column_table_name(sqlite3_stmt*,int); 00856 const void *sqlite3_column_table_name16(sqlite3_stmt*,int); 00857 const char *sqlite3_column_origin_name(sqlite3_stmt*,int); 00858 const void *sqlite3_column_origin_name16(sqlite3_stmt*,int); 00859 00860 /* 00861 ** The first parameter is a compiled SQL statement. If this statement 00862 ** is a SELECT statement, the Nth column of the returned result set 00863 ** of the SELECT is a table column then the declared type of the table 00864 ** column is returned. If the Nth column of the result set is not at table 00865 ** column, then a NULL pointer is returned. The returned string is always 00866 ** UTF-8 encoded. For example, in the database schema: 00867 ** 00868 ** CREATE TABLE t1(c1 VARIANT); 00869 ** 00870 ** And the following statement compiled: 00871 ** 00872 ** SELECT c1 + 1, c1 FROM t1; 00873 ** 00874 ** Then this routine would return the string "VARIANT" for the second 00875 ** result column (i==1), and a NULL pointer for the first result column 00876 ** (i==0). 00877 */ 00878 const char *sqlite3_column_decltype(sqlite3_stmt *, int i); 00879 00880 /* 00881 ** The first parameter is a compiled SQL statement. If this statement 00882 ** is a SELECT statement, the Nth column of the returned result set 00883 ** of the SELECT is a table column then the declared type of the table 00884 ** column is returned. If the Nth column of the result set is not at table 00885 ** column, then a NULL pointer is returned. The returned string is always 00886 ** UTF-16 encoded. For example, in the database schema: 00887 ** 00888 ** CREATE TABLE t1(c1 INTEGER); 00889 ** 00890 ** And the following statement compiled: 00891 ** 00892 ** SELECT c1 + 1, c1 FROM t1; 00893 ** 00894 ** Then this routine would return the string "INTEGER" for the second 00895 ** result column (i==1), and a NULL pointer for the first result column 00896 ** (i==0). 00897 */ 00898 const void *sqlite3_column_decltype16(sqlite3_stmt*,int); 00899 00900 /* 00901 ** After an SQL query has been compiled with a call to either 00902 ** sqlite3_prepare() or sqlite3_prepare16(), then this function must be 00903 ** called one or more times to execute the statement. 00904 ** 00905 ** The return value will be either SQLITE_BUSY, SQLITE_DONE, 00906 ** SQLITE_ROW, SQLITE_ERROR, or SQLITE_MISUSE. 00907 ** 00908 ** SQLITE_BUSY means that the database engine attempted to open 00909 ** a locked database and there is no busy callback registered. 00910 ** Call sqlite3_step() again to retry the open. 00911 ** 00912 ** SQLITE_DONE means that the statement has finished executing 00913 ** successfully. sqlite3_step() should not be called again on this virtual 00914 ** machine. 00915 ** 00916 ** If the SQL statement being executed returns any data, then 00917 ** SQLITE_ROW is returned each time a new row of data is ready 00918 ** for processing by the caller. The values may be accessed using 00919 ** the sqlite3_column_*() functions described below. sqlite3_step() 00920 ** is called again to retrieve the next row of data. 00921 ** 00922 ** SQLITE_ERROR means that a run-time error (such as a constraint 00923 ** violation) has occurred. sqlite3_step() should not be called again on 00924 ** the VM. More information may be found by calling sqlite3_errmsg(). 00925 ** 00926 ** SQLITE_MISUSE means that the this routine was called inappropriately. 00927 ** Perhaps it was called on a virtual machine that had already been 00928 ** finalized or on one that had previously returned SQLITE_ERROR or 00929 ** SQLITE_DONE. Or it could be the case the the same database connection 00930 ** is being used simulataneously by two or more threads. 00931 */ 00932 int sqlite3_step(sqlite3_stmt*); 00933 00934 /* 00935 ** Return the number of values in the current row of the result set. 00936 ** 00937 ** After a call to sqlite3_step() that returns SQLITE_ROW, this routine 00938 ** will return the same value as the sqlite3_column_count() function. 00939 ** After sqlite3_step() has returned an SQLITE_DONE, SQLITE_BUSY or 00940 ** error code, or before sqlite3_step() has been called on a 00941 ** compiled SQL statement, this routine returns zero. 00942 */ 00943 int sqlite3_data_count(sqlite3_stmt *pStmt); 00944 00945 /* 00946 ** Values are stored in the database in one of the following fundamental 00947 ** types. 00948 */ 00949 #define SQLITE_INTEGER 1 00950 #define SQLITE_FLOAT 2 00951 /* #define SQLITE_TEXT 3 // See below */ 00952 #define SQLITE_BLOB 4 00953 #define SQLITE_NULL 5 00954 00955 /* 00956 ** SQLite version 2 defines SQLITE_TEXT differently. To allow both 00957 ** version 2 and version 3 to be included, undefine them both if a 00958 ** conflict is seen. Define SQLITE3_TEXT to be the version 3 value. 00959 */ 00960 #ifdef SQLITE_TEXT 00961 # undef SQLITE_TEXT 00962 #else 00963 # define SQLITE_TEXT 3 00964 #endif 00965 #define SQLITE3_TEXT 3 00966 00967 /* 00968 ** The next group of routines returns information about the information 00969 ** in a single column of the current result row of a query. In every 00970 ** case the first parameter is a pointer to the SQL statement that is being 00971 ** executed (the sqlite_stmt* that was returned from sqlite3_prepare()) and 00972 ** the second argument is the index of the column for which information 00973 ** should be returned. iCol is zero-indexed. The left-most column as an 00974 ** index of 0. 00975 ** 00976 ** If the SQL statement is not currently point to a valid row, or if the 00977 ** the colulmn index is out of range, the result is undefined. 00978 ** 00979 ** These routines attempt to convert the value where appropriate. For 00980 ** example, if the internal representation is FLOAT and a text result 00981 ** is requested, sprintf() is used internally to do the conversion 00982 ** automatically. The following table details the conversions that 00983 ** are applied: 00984 ** 00985 ** Internal Type Requested Type Conversion 00986 ** ------------- -------------- -------------------------- 00987 ** NULL INTEGER Result is 0 00988 ** NULL FLOAT Result is 0.0 00989 ** NULL TEXT Result is an empty string 00990 ** NULL BLOB Result is a zero-length BLOB 00991 ** INTEGER FLOAT Convert from integer to float 00992 ** INTEGER TEXT ASCII rendering of the integer 00993 ** INTEGER BLOB Same as for INTEGER->TEXT 00994 ** FLOAT INTEGER Convert from float to integer 00995 ** FLOAT TEXT ASCII rendering of the float 00996 ** FLOAT BLOB Same as FLOAT->TEXT 00997 ** TEXT INTEGER Use atoi() 00998 ** TEXT FLOAT Use atof() 00999 ** TEXT BLOB No change 01000 ** BLOB INTEGER Convert to TEXT then use atoi() 01001 ** BLOB FLOAT Convert to TEXT then use atof() 01002 ** BLOB TEXT Add a \000 terminator if needed 01003 ** 01004 ** The following access routines are provided: 01005 ** 01006 ** _type() Return the datatype of the result. This is one of 01007 ** SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB, 01008 ** or SQLITE_NULL. 01009 ** _blob() Return the value of a BLOB. 01010 ** _bytes() Return the number of bytes in a BLOB value or the number 01011 ** of bytes in a TEXT value represented as UTF-8. The \000 01012 ** terminator is included in the byte count for TEXT values. 01013 ** _bytes16() Return the number of bytes in a BLOB value or the number 01014 ** of bytes in a TEXT value represented as UTF-16. The \u0000 01015 ** terminator is included in the byte count for TEXT values. 01016 ** _double() Return a FLOAT value. 01017 ** _int() Return an INTEGER value in the host computer's native 01018 ** integer representation. This might be either a 32- or 64-bit 01019 ** integer depending on the host. 01020 ** _int64() Return an INTEGER value as a 64-bit signed integer. 01021 ** _text() Return the value as UTF-8 text. 01022 ** _text16() Return the value as UTF-16 text. 01023 */ 01024 const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); 01025 int sqlite3_column_bytes(sqlite3_stmt*, int iCol); 01026 int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); 01027 double sqlite3_column_double(sqlite3_stmt*, int iCol); 01028 int sqlite3_column_int(sqlite3_stmt*, int iCol); 01029 sqlite_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); 01030 const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); 01031 const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); 01032 int sqlite3_column_type(sqlite3_stmt*, int iCol); 01033 int sqlite3_column_numeric_type(sqlite3_stmt*, int iCol); 01034 sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); 01035 01036 /* 01037 ** The sqlite3_finalize() function is called to delete a compiled 01038 ** SQL statement obtained by a previous call to sqlite3_prepare() 01039 ** or sqlite3_prepare16(). If the statement was executed successfully, or 01040 ** not executed at all, then SQLITE_OK is returned. If execution of the 01041 ** statement failed then an error code is returned. 01042 ** 01043 ** This routine can be called at any point during the execution of the 01044 ** virtual machine. If the virtual machine has not completed execution 01045 ** when this routine is called, that is like encountering an error or 01046 ** an interrupt. (See sqlite3_interrupt().) Incomplete updates may be 01047 ** rolled back and transactions cancelled, depending on the circumstances, 01048 ** and the result code returned will be SQLITE_ABORT. 01049 */ 01050 int sqlite3_finalize(sqlite3_stmt *pStmt); 01051 01052 /* 01053 ** The sqlite3_reset() function is called to reset a compiled SQL 01054 ** statement obtained by a previous call to sqlite3_prepare() or 01055 ** sqlite3_prepare16() back to it's initial state, ready to be re-executed. 01056 ** Any SQL statement variables that had values bound to them using 01057 ** the sqlite3_bind_*() API retain their values. 01058 */ 01059 int sqlite3_reset(sqlite3_stmt *pStmt); 01060 01061 /* 01062 ** The following two functions are used to add user functions or aggregates 01063 ** implemented in C to the SQL langauge interpreted by SQLite. The 01064 ** difference only between the two is that the second parameter, the 01065 ** name of the (scalar) function or aggregate, is encoded in UTF-8 for 01066 ** sqlite3_create_function() and UTF-16 for sqlite3_create_function16(). 01067 ** 01068 ** The first argument is the database handle that the new function or 01069 ** aggregate is to be added to. If a single program uses more than one 01070 ** database handle internally, then user functions or aggregates must 01071 ** be added individually to each database handle with which they will be 01072 ** used. 01073 ** 01074 ** The third parameter is the number of arguments that the function or 01075 ** aggregate takes. If this parameter is negative, then the function or 01076 ** aggregate may take any number of arguments. 01077 ** 01078 ** The fourth parameter is one of SQLITE_UTF* values defined below, 01079 ** indicating the encoding that the function is most likely to handle 01080 ** values in. This does not change the behaviour of the programming 01081 ** interface. However, if two versions of the same function are registered 01082 ** with different encoding values, SQLite invokes the version likely to 01083 ** minimize conversions between text encodings. 01084 ** 01085 ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are 01086 ** pointers to user implemented C functions that implement the user 01087 ** function or aggregate. A scalar function requires an implementation of 01088 ** the xFunc callback only, NULL pointers should be passed as the xStep 01089 ** and xFinal parameters. An aggregate function requires an implementation 01090 ** of xStep and xFinal, but NULL should be passed for xFunc. To delete an 01091 ** existing user function or aggregate, pass NULL for all three function 01092 ** callback. Specifying an inconstent set of callback values, such as an 01093 ** xFunc and an xFinal, or an xStep but no xFinal, SQLITE_ERROR is 01094 ** returned. 01095 */ 01096 int sqlite3_create_function( 01097 sqlite3 *, 01098 const char *zFunctionName, 01099 int nArg, 01100 int eTextRep, 01101 void*, 01102 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 01103 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 01104 void (*xFinal)(sqlite3_context*) 01105 ); 01106 int sqlite3_create_function16( 01107 sqlite3*, 01108 const void *zFunctionName, 01109 int nArg, 01110 int eTextRep, 01111 void*, 01112 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 01113 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 01114 void (*xFinal)(sqlite3_context*) 01115 ); 01116 01117 /* 01118 ** This function is deprecated. Do not use it. It continues to exist 01119 ** so as not to break legacy code. But new code should avoid using it. 01120 */ 01121 int sqlite3_aggregate_count(sqlite3_context*); 01122 01123 /* 01124 ** The next group of routines returns information about parameters to 01125 ** a user-defined function. Function implementations use these routines 01126 ** to access their parameters. These routines are the same as the 01127 ** sqlite3_column_* routines except that these routines take a single 01128 ** sqlite3_value* pointer instead of an sqlite3_stmt* and an integer 01129 ** column number. 01130 */ 01131 const void *sqlite3_value_blob(sqlite3_value*); 01132 int sqlite3_value_bytes(sqlite3_value*); 01133 int sqlite3_value_bytes16(sqlite3_value*); 01134 double sqlite3_value_double(sqlite3_value*); 01135 int sqlite3_value_int(sqlite3_value*); 01136 sqlite_int64 sqlite3_value_int64(sqlite3_value*); 01137 const unsigned char *sqlite3_value_text(sqlite3_value*); 01138 const void *sqlite3_value_text16(sqlite3_value*); 01139 const void *sqlite3_value_text16le(sqlite3_value*); 01140 const void *sqlite3_value_text16be(sqlite3_value*); 01141 int sqlite3_value_type(sqlite3_value*); 01142 int sqlite3_value_numeric_type(sqlite3_value*); 01143 01144 /* 01145 ** Aggregate functions use the following routine to allocate 01146 ** a structure for storing their state. The first time this routine 01147 ** is called for a particular aggregate, a new structure of size nBytes 01148 ** is allocated, zeroed, and returned. On subsequent calls (for the 01149 ** same aggregate instance) the same buffer is returned. The implementation 01150 ** of the aggregate can use the returned buffer to accumulate data. 01151 ** 01152 ** The buffer allocated is freed automatically by SQLite. 01153 */ 01154 void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); 01155 01156 /* 01157 ** The pUserData parameter to the sqlite3_create_function() 01158 ** routine used to register user functions is available to 01159 ** the implementation of the function using this call. 01160 */ 01161 void *sqlite3_user_data(sqlite3_context*); 01162 01163 /* 01164 ** The following two functions may be used by scalar user functions to 01165 ** associate meta-data with argument values. If the same value is passed to 01166 ** multiple invocations of the user-function during query execution, under 01167 ** some circumstances the associated meta-data may be preserved. This may 01168 ** be used, for example, to add a regular-expression matching scalar 01169 ** function. The compiled version of the regular expression is stored as 01170 ** meta-data associated with the SQL value passed as the regular expression 01171 ** pattern. 01172 ** 01173 ** Calling sqlite3_get_auxdata() returns a pointer to the meta data 01174 ** associated with the Nth argument value to the current user function 01175 ** call, where N is the second parameter. If no meta-data has been set for 01176 ** that value, then a NULL pointer is returned. 01177 ** 01178 ** The sqlite3_set_auxdata() is used to associate meta data with a user 01179 ** function argument. The third parameter is a pointer to the meta data 01180 ** to be associated with the Nth user function argument value. The fourth 01181 ** parameter specifies a 'delete function' that will be called on the meta 01182 ** data pointer to release it when it is no longer required. If the delete 01183 ** function pointer is NULL, it is not invoked. 01184 ** 01185 ** In practice, meta-data is preserved between function calls for 01186 ** expressions that are constant at compile time. This includes literal 01187 ** values and SQL variables. 01188 */ 01189 void *sqlite3_get_auxdata(sqlite3_context*, int); 01190 void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*)); 01191 01192 01193 /* 01194 ** These are special value for the destructor that is passed in as the 01195 ** final argument to routines like sqlite3_result_blob(). If the destructor 01196 ** argument is SQLITE_STATIC, it means that the content pointer is constant 01197 ** and will never change. It does not need to be destroyed. The 01198 ** SQLITE_TRANSIENT value means that the content will likely change in 01199 ** the near future and that SQLite should make its own private copy of 01200 ** the content before returning. 01201 ** 01202 ** The typedef is necessary to work around problems in certain 01203 ** C++ compilers. See ticket #2191. 01204 */ 01205 typedef void (*sqlite3_destructor_type)(void*); 01206 #define SQLITE_STATIC ((sqlite3_destructor_type)0) 01207 #define SQLITE_TRANSIENT ((sqlite3_destructor_type)-1) 01208 01209 /* 01210 ** User-defined functions invoke the following routines in order to 01211 ** set their return value. 01212 */ 01213 void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); 01214 void sqlite3_result_double(sqlite3_context*, double); 01215 void sqlite3_result_error(sqlite3_context*, const char*, int); 01216 void sqlite3_result_error16(sqlite3_context*, const void*, int); 01217 void sqlite3_result_int(sqlite3_context*, int); 01218 void sqlite3_result_int64(sqlite3_context*, sqlite_int64); 01219 void sqlite3_result_null(sqlite3_context*); 01220 void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); 01221 void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); 01222 void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); 01223 void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); 01224 void sqlite3_result_value(sqlite3_context*, sqlite3_value*); 01225 01226 /* 01227 ** These are the allowed values for the eTextRep argument to 01228 ** sqlite3_create_collation and sqlite3_create_function. 01229 */ 01230 #define SQLITE_UTF8 1 01231 #define SQLITE_UTF16LE 2 01232 #define SQLITE_UTF16BE 3 01233 #define SQLITE_UTF16 4 /* Use native byte order */ 01234 #define SQLITE_ANY 5 /* sqlite3_create_function only */ 01235 #define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */ 01236 01237 /* 01238 ** These two functions are used to add new collation sequences to the 01239 ** sqlite3 handle specified as the first argument. 01240 ** 01241 ** The name of the new collation sequence is specified as a UTF-8 string 01242 ** for sqlite3_create_collation() and a UTF-16 string for 01243 ** sqlite3_create_collation16(). In both cases the name is passed as the 01244 ** second function argument. 01245 ** 01246 ** The third argument must be one of the constants SQLITE_UTF8, 01247 ** SQLITE_UTF16LE or SQLITE_UTF16BE, indicating that the user-supplied 01248 ** routine expects to be passed pointers to strings encoded using UTF-8, 01249 ** UTF-16 little-endian or UTF-16 big-endian respectively. 01250 ** 01251 ** A pointer to the user supplied routine must be passed as the fifth 01252 ** argument. If it is NULL, this is the same as deleting the collation 01253 ** sequence (so that SQLite cannot call it anymore). Each time the user 01254 ** supplied function is invoked, it is passed a copy of the void* passed as 01255 ** the fourth argument to sqlite3_create_collation() or 01256 ** sqlite3_create_collation16() as its first parameter. 01257 ** 01258 ** The remaining arguments to the user-supplied routine are two strings, 01259 ** each represented by a [length, data] pair and encoded in the encoding 01260 ** that was passed as the third argument when the collation sequence was 01261 ** registered. The user routine should return negative, zero or positive if 01262 ** the first string is less than, equal to, or greater than the second 01263 ** string. i.e. (STRING1 - STRING2). 01264 */ 01265 int sqlite3_create_collation( 01266 sqlite3*, 01267 const char *zName, 01268 int eTextRep, 01269 void*, 01270 int(*xCompare)(void*,int,const void*,int,const void*) 01271 ); 01272 int sqlite3_create_collation16( 01273 sqlite3*, 01274 const char *zName, 01275 int eTextRep, 01276 void*, 01277 int(*xCompare)(void*,int,const void*,int,const void*) 01278 ); 01279 01280 /* 01281 ** To avoid having to register all collation sequences before a database 01282 ** can be used, a single callback function may be registered with the 01283 ** database handle to be called whenever an undefined collation sequence is 01284 ** required. 01285 ** 01286 ** If the function is registered using the sqlite3_collation_needed() API, 01287 ** then it is passed the names of undefined collation sequences as strings 01288 ** encoded in UTF-8. If sqlite3_collation_needed16() is used, the names 01289 ** are passed as UTF-16 in machine native byte order. A call to either 01290 ** function replaces any existing callback. 01291 ** 01292 ** When the user-function is invoked, the first argument passed is a copy 01293 ** of the second argument to sqlite3_collation_needed() or 01294 ** sqlite3_collation_needed16(). The second argument is the database 01295 ** handle. The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE or 01296 ** SQLITE_UTF16LE, indicating the most desirable form of the collation 01297 ** sequence function required. The fourth parameter is the name of the 01298 ** required collation sequence. 01299 ** 01300 ** The collation sequence is returned to SQLite by a collation-needed 01301 ** callback using the sqlite3_create_collation() or 01302 ** sqlite3_create_collation16() APIs, described above. 01303 */ 01304 int sqlite3_collation_needed( 01305 sqlite3*, 01306 void*, 01307 void(*)(void*,sqlite3*,int eTextRep,const char*) 01308 ); 01309 int sqlite3_collation_needed16( 01310 sqlite3*, 01311 void*, 01312 void(*)(void*,sqlite3*,int eTextRep,const void*) 01313 ); 01314 01315 /* 01316 ** Specify the key for an encrypted database. This routine should be 01317 ** called right after sqlite3_open(). 01318 ** 01319 ** The code to implement this API is not available in the public release 01320 ** of SQLite. 01321 */ 01322 int sqlite3_key( 01323 sqlite3 *db, /* Database to be rekeyed */ 01324 const void *pKey, int nKey /* The key */ 01325 ); 01326 01327 /* 01328 ** Change the key on an open database. If the current database is not 01329 ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the 01330 ** database is decrypted. 01331 ** 01332 ** The code to implement this API is not available in the public release 01333 ** of SQLite. 01334 */ 01335 int sqlite3_rekey( 01336 sqlite3 *db, /* Database to be rekeyed */ 01337 const void *pKey, int nKey /* The new key */ 01338 ); 01339 01340 /* 01341 ** Sleep for a little while. The second parameter is the number of 01342 ** miliseconds to sleep for. 01343 ** 01344 ** If the operating system does not support sleep requests with 01345 ** milisecond time resolution, then the time will be rounded up to 01346 ** the nearest second. The number of miliseconds of sleep actually 01347 ** requested from the operating system is returned. 01348 */ 01349 int sqlite3_sleep(int); 01350 01351 /* 01352 ** Return TRUE (non-zero) if the statement supplied as an argument needs 01353 ** to be recompiled. A statement needs to be recompiled whenever the 01354 ** execution environment changes in a way that would alter the program 01355 ** that sqlite3_prepare() generates. For example, if new functions or 01356 ** collating sequences are registered or if an authorizer function is 01357 ** added or changed. 01358 ** 01359 */ 01360 int sqlite3_expired(sqlite3_stmt*); 01361 01362 /* 01363 ** Move all bindings from the first prepared statement over to the second. 01364 ** This routine is useful, for example, if the first prepared statement 01365 ** fails with an SQLITE_SCHEMA error. The same SQL can be prepared into 01366 ** the second prepared statement then all of the bindings transfered over 01367 ** to the second statement before the first statement is finalized. 01368 */ 01369 int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); 01370 01371 /* 01372 ** If the following global variable is made to point to a 01373 ** string which is the name of a directory, then all temporary files 01374 ** created by SQLite will be placed in that directory. If this variable 01375 ** is NULL pointer, then SQLite does a search for an appropriate temporary 01376 ** file directory. 01377 ** 01378 ** Once sqlite3_open() has been called, changing this variable will invalidate 01379 ** the current temporary database, if any. 01380 */ 01381 extern char *sqlite3_temp_directory; 01382 01383 /* 01384 ** This function is called to recover from a malloc() failure that occured 01385 ** within the SQLite library. Normally, after a single malloc() fails the 01386 ** library refuses to function (all major calls return SQLITE_NOMEM). 01387 ** This function restores the library state so that it can be used again. 01388 ** 01389 ** All existing statements (sqlite3_stmt pointers) must be finalized or 01390 ** reset before this call is made. Otherwise, SQLITE_BUSY is returned. 01391 ** If any in-memory databases are in use, either as a main or TEMP 01392 ** database, SQLITE_ERROR is returned. In either of these cases, the 01393 ** library is not reset and remains unusable. 01394 ** 01395 ** This function is *not* threadsafe. Calling this from within a threaded 01396 ** application when threads other than the caller have used SQLite is 01397 ** dangerous and will almost certainly result in malfunctions. 01398 ** 01399 ** This functionality can be omitted from a build by defining the 01400 ** SQLITE_OMIT_GLOBALRECOVER at compile time. 01401 */ 01402 int sqlite3_global_recover(void); 01403 01404 /* 01405 ** Test to see whether or not the database connection is in autocommit 01406 ** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on 01407 ** by default. Autocommit is disabled by a BEGIN statement and reenabled 01408 ** by the next COMMIT or ROLLBACK. 01409 */ 01410 int sqlite3_get_autocommit(sqlite3*); 01411 01412 /* 01413 ** Return the sqlite3* database handle to which the prepared statement given 01414 ** in the argument belongs. This is the same database handle that was 01415 ** the first argument to the sqlite3_prepare() that was used to create 01416 ** the statement in the first place. 01417 */ 01418 sqlite3 *sqlite3_db_handle(sqlite3_stmt*); 01419 01420 /* 01421 ** Register a callback function with the database connection identified by the 01422 ** first argument to be invoked whenever a row is updated, inserted or deleted. 01423 ** Any callback set by a previous call to this function for the same 01424 ** database connection is overridden. 01425 ** 01426 ** The second argument is a pointer to the function to invoke when a 01427 ** row is updated, inserted or deleted. The first argument to the callback is 01428 ** a copy of the third argument to sqlite3_update_hook. The second callback 01429 ** argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending 01430 ** on the operation that caused the callback to be invoked. The third and 01431 ** fourth arguments to the callback contain pointers to the database and 01432 ** table name containing the affected row. The final callback parameter is 01433 ** the rowid of the row. In the case of an update, this is the rowid after 01434 ** the update takes place. 01435 ** 01436 ** The update hook is not invoked when internal system tables are 01437 ** modified (i.e. sqlite_master and sqlite_sequence). 01438 ** 01439 ** If another function was previously registered, its pArg value is returned. 01440 ** Otherwise NULL is returned. 01441 */ 01442 void *sqlite3_update_hook( 01443 sqlite3*, 01444 void(*)(void *,int ,char const *,char const *,sqlite_int64), 01445 void* 01446 ); 01447 01448 /* 01449 ** Register a callback to be invoked whenever a transaction is rolled 01450 ** back. 01451 ** 01452 ** The new callback function overrides any existing rollback-hook 01453 ** callback. If there was an existing callback, then it's pArg value 01454 ** (the third argument to sqlite3_rollback_hook() when it was registered) 01455 ** is returned. Otherwise, NULL is returned. 01456 ** 01457 ** For the purposes of this API, a transaction is said to have been 01458 ** rolled back if an explicit "ROLLBACK" statement is executed, or 01459 ** an error or constraint causes an implicit rollback to occur. The 01460 ** callback is not invoked if a transaction is automatically rolled 01461 ** back because the database connection is closed. 01462 */ 01463 void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); 01464 01465 /* 01466 ** This function is only available if the library is compiled without 01467 ** the SQLITE_OMIT_SHARED_CACHE macro defined. It is used to enable or 01468 ** disable (if the argument is true or false, respectively) the 01469 ** "shared pager" feature. 01470 */ 01471 int sqlite3_enable_shared_cache(int); 01472 01473 /* 01474 ** Attempt to free N bytes of heap memory by deallocating non-essential 01475 ** memory allocations held by the database library (example: memory 01476 ** used to cache database pages to improve performance). 01477 ** 01478 ** This function is not a part of standard builds. It is only created 01479 ** if SQLite is compiled with the SQLITE_ENABLE_MEMORY_MANAGEMENT macro. 01480 */ 01481 int sqlite3_release_memory(int); 01482 01483 /* 01484 ** Place a "soft" limit on the amount of heap memory that may be allocated by 01485 ** SQLite within the current thread. If an internal allocation is requested 01486 ** that would exceed the specified limit, sqlite3_release_memory() is invoked 01487 ** one or more times to free up some space before the allocation is made. 01488 ** 01489 ** The limit is called "soft", because if sqlite3_release_memory() cannot free 01490 ** sufficient memory to prevent the limit from being exceeded, the memory is 01491 ** allocated anyway and the current operation proceeds. 01492 ** 01493 ** This function is only available if the library was compiled with the 01494 ** SQLITE_ENABLE_MEMORY_MANAGEMENT option set. 01495 ** memory-management has been enabled. 01496 */ 01497 void sqlite3_soft_heap_limit(int); 01498 01499 /* 01500 ** This routine makes sure that all thread-local storage has been 01501 ** deallocated for the current thread. 01502 ** 01503 ** This routine is not technically necessary. All thread-local storage 01504 ** will be automatically deallocated once memory-management and 01505 ** shared-cache are disabled and the soft heap limit has been set 01506 ** to zero. This routine is provided as a convenience for users who 01507 ** want to make absolutely sure they have not forgotten something 01508 ** prior to killing off a thread. 01509 */ 01510 void sqlite3_thread_cleanup(void); 01511 01512 /* 01513 ** Return meta information about a specific column of a specific database 01514 ** table accessible using the connection handle passed as the first function 01515 ** argument. 01516 ** 01517 ** The column is identified by the second, third and fourth parameters to 01518 ** this function. The second parameter is either the name of the database 01519 ** (i.e. "main", "temp" or an attached database) containing the specified 01520 ** table or NULL. If it is NULL, then all attached databases are searched 01521 ** for the table using the same algorithm as the database engine uses to 01522 ** resolve unqualified table references. 01523 ** 01524 ** The third and fourth parameters to this function are the table and column 01525 ** name of the desired column, respectively. Neither of these parameters 01526 ** may be NULL. 01527 ** 01528 ** Meta information is returned by writing to the memory locations passed as 01529 ** the 5th and subsequent parameters to this function. Any of these 01530 ** arguments may be NULL, in which case the corresponding element of meta 01531 ** information is ommitted. 01532 ** 01533 ** Parameter Output Type Description 01534 ** ----------------------------------- 01535 ** 01536 ** 5th const char* Data type 01537 ** 6th const char* Name of the default collation sequence 01538 ** 7th int True if the column has a NOT NULL constraint 01539 ** 8th int True if the column is part of the PRIMARY KEY 01540 ** 9th int True if the column is AUTOINCREMENT 01541 ** 01542 ** 01543 ** The memory pointed to by the character pointers returned for the 01544 ** declaration type and collation sequence is valid only until the next 01545 ** call to any sqlite API function. 01546 ** 01547 ** If the specified table is actually a view, then an error is returned. 01548 ** 01549 ** If the specified column is "rowid", "oid" or "_rowid_" and an 01550 ** INTEGER PRIMARY KEY column has been explicitly declared, then the output 01551 ** parameters are set for the explicitly declared column. If there is no 01552 ** explicitly declared IPK column, then the output parameters are set as 01553 ** follows: 01554 ** 01555 ** data type: "INTEGER" 01556 ** collation sequence: "BINARY" 01557 ** not null: 0 01558 ** primary key: 1 01559 ** auto increment: 0 01560 ** 01561 ** This function may load one or more schemas from database files. If an 01562 ** error occurs during this process, or if the requested table or column 01563 ** cannot be found, an SQLITE error code is returned and an error message 01564 ** left in the database handle (to be retrieved using sqlite3_errmsg()). 01565 ** 01566 ** This API is only available if the library was compiled with the 01567 ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. 01568 */ 01569 int sqlite3_table_column_metadata( 01570 sqlite3 *db, /* Connection handle */ 01571 const char *zDbName, /* Database name or NULL */ 01572 const char *zTableName, /* Table name */ 01573 const char *zColumnName, /* Column name */ 01574 char const **pzDataType, /* OUTPUT: Declared data type */ 01575 char const **pzCollSeq, /* OUTPUT: Collation sequence name */ 01576 int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */ 01577 int *pPrimaryKey, /* OUTPUT: True if column part of PK */ 01578 int *pAutoinc /* OUTPUT: True if colums is auto-increment */ 01579 ); 01580 01581 /* 01582 ****** EXPERIMENTAL - subject to change without notice ************** 01583 ** 01584 ** Attempt to load an SQLite extension library contained in the file 01585 ** zFile. The entry point is zProc. zProc may be 0 in which case the 01586 ** name of the entry point defaults to "sqlite3_extension_init". 01587 ** 01588 ** Return SQLITE_OK on success and SQLITE_ERROR if something goes wrong. 01589 ** 01590 ** If an error occurs and pzErrMsg is not 0, then fill *pzErrMsg with 01591 ** error message text. The calling function should free this memory 01592 ** by calling sqlite3_free(). 01593 ** 01594 ** Extension loading must be enabled using sqlite3_enable_load_extension() 01595 ** prior to calling this API or an error will be returned. 01596 ** 01597 ****** EXPERIMENTAL - subject to change without notice ************** 01598 */ 01599 int sqlite3_load_extension( 01600 sqlite3 *db, /* Load the extension into this database connection */ 01601 const char *zFile, /* Name of the shared library containing extension */ 01602 const char *zProc, /* Entry point. Derived from zFile if 0 */ 01603 char **pzErrMsg /* Put error message here if not 0 */ 01604 ); 01605 01606 /* 01607 ** So as not to open security holes in older applications that are 01608 ** unprepared to deal with extension load, and as a means of disabling 01609 ** extension loading while executing user-entered SQL, the following 01610 ** API is provided to turn the extension loading mechanism on and 01611 ** off. It is off by default. See ticket #1863. 01612 ** 01613 ** Call this routine with onoff==1 to turn extension loading on 01614 ** and call it with onoff==0 to turn it back off again. 01615 */ 01616 int sqlite3_enable_load_extension(sqlite3 *db, int onoff); 01617 01618 /* 01619 ****** EXPERIMENTAL - subject to change without notice ************** 01620 ** 01621 ** Register an extension entry point that is automatically invoked 01622 ** whenever a new database connection is opened. 01623 ** 01624 ** This API can be invoked at program startup in order to register 01625 ** one or more statically linked extensions that will be available 01626 ** to all new database connections. 01627 ** 01628 ** Duplicate extensions are detected so calling this routine multiple 01629 ** times with the same extension is harmless. 01630 ** 01631 ** This routine stores a pointer to the extension in an array 01632 ** that is obtained from malloc(). If you run a memory leak 01633 ** checker on your program and it reports a leak because of this 01634 ** array, then invoke sqlite3_automatic_extension_reset() prior 01635 ** to shutdown to free the memory. 01636 ** 01637 ** Automatic extensions apply across all threads. 01638 */ 01639 int sqlite3_auto_extension(void *xEntryPoint); 01640 01641 01642 /* 01643 ****** EXPERIMENTAL - subject to change without notice ************** 01644 ** 01645 ** Disable all previously registered automatic extensions. This 01646 ** routine undoes the effect of all prior sqlite3_automatic_extension() 01647 ** calls. 01648 ** 01649 ** This call disabled automatic extensions in all threads. 01650 */ 01651 void sqlite3_reset_auto_extension(void); 01652 01653 01654 /* 01655 ****** EXPERIMENTAL - subject to change without notice ************** 01656 ** 01657 ** The interface to the virtual-table mechanism is currently considered 01658 ** to be experimental. The interface might change in incompatible ways. 01659 ** If this is a problem for you, do not use the interface at this time. 01660 ** 01661 ** When the virtual-table mechanism stablizes, we will declare the 01662 ** interface fixed, support it indefinitely, and remove this comment. 01663 */ 01664 01665 /* 01666 ** Structures used by the virtual table interface 01667 */ 01668 typedef struct sqlite3_vtab sqlite3_vtab; 01669 typedef struct sqlite3_index_info sqlite3_index_info; 01670 typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor; 01671 typedef struct sqlite3_module sqlite3_module; 01672 01673 /* 01674 ** A module is a class of virtual tables. Each module is defined 01675 ** by an instance of the following structure. This structure consists 01676 ** mostly of methods for the module. 01677 */ 01678 struct sqlite3_module { 01679 int iVersion; 01680 int (*xCreate)(sqlite3*, void *pAux, 01681 int argc, const char *const*argv, 01682 sqlite3_vtab **ppVTab, char**); 01683 int (*xConnect)(sqlite3*, void *pAux, 01684 int argc, const char *const*argv, 01685 sqlite3_vtab **ppVTab, char**); 01686 int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*); 01687 int (*xDisconnect)(sqlite3_vtab *pVTab); 01688 int (*xDestroy)(sqlite3_vtab *pVTab); 01689 int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor); 01690 int (*xClose)(sqlite3_vtab_cursor*); 01691 int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr, 01692 int argc, sqlite3_value **argv); 01693 int (*xNext)(sqlite3_vtab_cursor*); 01694 int (*xEof)(sqlite3_vtab_cursor*); 01695 int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int); 01696 int (*xRowid)(sqlite3_vtab_cursor*, sqlite_int64 *pRowid); 01697 int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite_int64 *); 01698 int (*xBegin)(sqlite3_vtab *pVTab); 01699 int (*xSync)(sqlite3_vtab *pVTab); 01700 int (*xCommit)(sqlite3_vtab *pVTab); 01701 int (*xRollback)(sqlite3_vtab *pVTab); 01702 int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName, 01703 void (**pxFunc)(sqlite3_context*,int,sqlite3_value**), 01704 void **ppArg); 01705 }; 01706 01707 /* 01708 ** The sqlite3_index_info structure and its substructures is used to 01709 ** pass information into and receive the reply from the xBestIndex 01710 ** method of an sqlite3_module. The fields under **Inputs** are the 01711 ** inputs to xBestIndex and are read-only. xBestIndex inserts its 01712 ** results into the **Outputs** fields. 01713 ** 01714 ** The aConstraint[] array records WHERE clause constraints of the 01715 ** form: 01716 ** 01717 ** column OP expr 01718 ** 01719 ** Where OP is =, <, <=, >, or >=. The particular operator is stored 01720 ** in aConstraint[].op. The index of the column is stored in 01721 ** aConstraint[].iColumn. aConstraint[].usable is TRUE if the 01722 ** expr on the right-hand side can be evaluated (and thus the constraint 01723 ** is usable) and false if it cannot. 01724 ** 01725 ** The optimizer automatically inverts terms of the form "expr OP column" 01726 ** and makes other simplificatinos to the WHERE clause in an attempt to 01727 ** get as many WHERE clause terms into the form shown above as possible. 01728 ** The aConstraint[] array only reports WHERE clause terms in the correct 01729 ** form that refer to the particular virtual table being queried. 01730 ** 01731 ** Information about the ORDER BY clause is stored in aOrderBy[]. 01732 ** Each term of aOrderBy records a column of the ORDER BY clause. 01733 ** 01734 ** The xBestIndex method must fill aConstraintUsage[] with information 01735 ** about what parameters to pass to xFilter. If argvIndex>0 then 01736 ** the right-hand side of the corresponding aConstraint[] is evaluated 01737 ** and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit 01738 ** is true, then the constraint is assumed to be fully handled by the 01739 ** virtual table and is not checked again by SQLite. 01740 ** 01741 ** The idxNum and idxPtr values are recorded and passed into xFilter. 01742 ** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true. 01743 ** 01744 ** The orderByConsumed means that output from xFilter will occur in 01745 ** the correct order to satisfy the ORDER BY clause so that no separate 01746 ** sorting step is required. 01747 ** 01748 ** The estimatedCost value is an estimate of the cost of doing the 01749 ** particular lookup. A full scan of a table with N entries should have 01750 ** a cost of N. A binary search of a table of N entries should have a 01751 ** cost of approximately log(N). 01752 */ 01753 struct sqlite3_index_info { 01754 /* Inputs */ 01755 const int nConstraint; /* Number of entries in aConstraint */ 01756 const struct sqlite3_index_constraint { 01757 int iColumn; /* Column on left-hand side of constraint */ 01758 unsigned char op; /* Constraint operator */ 01759 unsigned char usable; /* True if this constraint is usable */ 01760 int iTermOffset; /* Used internally - xBestIndex should ignore */ 01761 } *const aConstraint; /* Table of WHERE clause constraints */ 01762 const int nOrderBy; /* Number of terms in the ORDER BY clause */ 01763 const struct sqlite3_index_orderby { 01764 int iColumn; /* Column number */ 01765 unsigned char desc; /* True for DESC. False for ASC. */ 01766 } *const aOrderBy; /* The ORDER BY clause */ 01767 01768 /* Outputs */ 01769 struct sqlite3_index_constraint_usage { 01770 int argvIndex; /* if >0, constraint is part of argv to xFilter */ 01771 unsigned char omit; /* Do not code a test for this constraint */ 01772 } *const aConstraintUsage; 01773 int idxNum; /* Number used to identify the index */ 01774 char *idxStr; /* String, possibly obtained from sqlite3_malloc */ 01775 int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */ 01776 int orderByConsumed; /* True if output is already ordered */ 01777 double estimatedCost; /* Estimated cost of using this index */ 01778 }; 01779 #define SQLITE_INDEX_CONSTRAINT_EQ 2 01780 #define SQLITE_INDEX_CONSTRAINT_GT 4 01781 #define SQLITE_INDEX_CONSTRAINT_LE 8 01782 #define SQLITE_INDEX_CONSTRAINT_LT 16 01783 #define SQLITE_INDEX_CONSTRAINT_GE 32 01784 #define SQLITE_INDEX_CONSTRAINT_MATCH 64 01785 01786 /* 01787 ** This routine is used to register a new module name with an SQLite 01788 ** connection. Module names must be registered before creating new 01789 ** virtual tables on the module, or before using preexisting virtual 01790 ** tables of the module. 01791 */ 01792 int sqlite3_create_module( 01793 sqlite3 *db, /* SQLite connection to register module with */ 01794 const char *zName, /* Name of the module */ 01795 const sqlite3_module *, /* Methods for the module */ 01796 void * /* Client data for xCreate/xConnect */ 01797 ); 01798 01799 /* 01800 ** Every module implementation uses a subclass of the following structure 01801 ** to describe a particular instance of the module. Each subclass will 01802 ** be taylored to the specific needs of the module implementation. The 01803 ** purpose of this superclass is to define certain fields that are common 01804 ** to all module implementations. 01805 ** 01806 ** Virtual tables methods can set an error message by assigning a 01807 ** string obtained from sqlite3_mprintf() to zErrMsg. The method should 01808 ** take care that any prior string is freed by a call to sqlite3_free() 01809 ** prior to assigning a new string to zErrMsg. After the error message 01810 ** is delivered up to the client application, the string will be automatically 01811 ** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note 01812 ** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field 01813 ** since virtual tables are commonly implemented in loadable extensions which 01814 ** do not have access to sqlite3MPrintf() or sqlite3Free(). 01815 */ 01816 struct sqlite3_vtab { 01817 const sqlite3_module *pModule; /* The module for this virtual table */ 01818 int nRef; /* Used internally */ 01819 char *zErrMsg; /* Error message from sqlite3_mprintf() */ 01820 /* Virtual table implementations will typically add additional fields */ 01821 }; 01822 01823 /* Every module implementation uses a subclass of the following structure 01824 ** to describe cursors that point into the virtual table and are used 01825 ** to loop through the virtual table. Cursors are created using the 01826 ** xOpen method of the module. Each module implementation will define 01827 ** the content of a cursor structure to suit its own needs. 01828 ** 01829 ** This superclass exists in order to define fields of the cursor that 01830 ** are common to all implementations. 01831 */ 01832 struct sqlite3_vtab_cursor { 01833 sqlite3_vtab *pVtab; /* Virtual table of this cursor */ 01834 /* Virtual table implementations will typically add additional fields */ 01835 }; 01836 01837 /* 01838 ** The xCreate and xConnect methods of a module use the following API 01839 ** to declare the format (the names and datatypes of the columns) of 01840 ** the virtual tables they implement. 01841 */ 01842 int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable); 01843 01844 /* 01845 ** Virtual tables can provide alternative implementations of functions 01846 ** using the xFindFunction method. But global versions of those functions 01847 ** must exist in order to be overloaded. 01848 ** 01849 ** This API makes sure a global version of a function with a particular 01850 ** name and number of parameters exists. If no such function exists 01851 ** before this API is called, a new function is created. The implementation 01852 ** of the new function always causes an exception to be thrown. So 01853 ** the new function is not good for anything by itself. Its only 01854 ** purpose is to be a place-holder function that can be overloaded 01855 ** by virtual tables. 01856 ** 01857 ** This API should be considered part of the virtual table interface, 01858 ** which is experimental and subject to change. 01859 */ 01860 int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg); 01861 01862 /* 01863 ** The interface to the virtual-table mechanism defined above (back up 01864 ** to a comment remarkably similar to this one) is currently considered 01865 ** to be experimental. The interface might change in incompatible ways. 01866 ** If this is a problem for you, do not use the interface at this time. 01867 ** 01868 ** When the virtual-table mechanism stablizes, we will declare the 01869 ** interface fixed, support it indefinitely, and remove this comment. 01870 ** 01871 ****** EXPERIMENTAL - subject to change without notice ************** 01872 */ 01873 01874 /* 01875 ** Undo the hack that converts floating point types to integer for 01876 ** builds on processors without floating point support. 01877 */ 01878 #ifdef SQLITE_OMIT_FLOATING_POINT 01879 # undef double 01880 #endif 01881 01882 #ifdef __cplusplus 01883 } /* End of the 'extern "C"' block */ 01884 #endif 01885 #endif