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.156 2006/01/12 02:50:10 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.1" 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 3003001 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 #if defined(_MSC_VER) || defined(__BORLANDC__) 00082 typedef __int64 sqlite_int64; 00083 typedef unsigned __int64 sqlite_uint64; 00084 #else 00085 typedef long long int sqlite_int64; 00086 typedef unsigned long long int sqlite_uint64; 00087 #endif 00088 00089 /* 00090 ** If compiling for a processor that lacks floating point support, 00091 ** substitute integer for floating-point 00092 */ 00093 #ifdef SQLITE_OMIT_FLOATING_POINT 00094 # define double sqlite_int64 00095 #endif 00096 00097 /* 00098 ** A function to close the database. 00099 ** 00100 ** Call this function with a pointer to a structure that was previously 00101 ** returned from sqlite3_open() and the corresponding database will by closed. 00102 ** 00103 ** All SQL statements prepared using sqlite3_prepare() or 00104 ** sqlite3_prepare16() must be deallocated using sqlite3_finalize() before 00105 ** this routine is called. Otherwise, SQLITE_BUSY is returned and the 00106 ** database connection remains open. 00107 */ 00108 int sqlite3_close(sqlite3 *); 00109 00110 /* 00111 ** The type for a callback function. 00112 */ 00113 typedef int (*sqlite3_callback)(void*,int,char**, char**); 00114 00115 /* 00116 ** A function to executes one or more statements of SQL. 00117 ** 00118 ** If one or more of the SQL statements are queries, then 00119 ** the callback function specified by the 3rd parameter is 00120 ** invoked once for each row of the query result. This callback 00121 ** should normally return 0. If the callback returns a non-zero 00122 ** value then the query is aborted, all subsequent SQL statements 00123 ** are skipped and the sqlite3_exec() function returns the SQLITE_ABORT. 00124 ** 00125 ** The 4th parameter is an arbitrary pointer that is passed 00126 ** to the callback function as its first parameter. 00127 ** 00128 ** The 2nd parameter to the callback function is the number of 00129 ** columns in the query result. The 3rd parameter to the callback 00130 ** is an array of strings holding the values for each column. 00131 ** The 4th parameter to the callback is an array of strings holding 00132 ** the names of each column. 00133 ** 00134 ** The callback function may be NULL, even for queries. A NULL 00135 ** callback is not an error. It just means that no callback 00136 ** will be invoked. 00137 ** 00138 ** If an error occurs while parsing or evaluating the SQL (but 00139 ** not while executing the callback) then an appropriate error 00140 ** message is written into memory obtained from malloc() and 00141 ** *errmsg is made to point to that message. The calling function 00142 ** is responsible for freeing the memory that holds the error 00143 ** message. Use sqlite3_free() for this. If errmsg==NULL, 00144 ** then no error message is ever written. 00145 ** 00146 ** The return value is is SQLITE_OK if there are no errors and 00147 ** some other return code if there is an error. The particular 00148 ** return value depends on the type of error. 00149 ** 00150 ** If the query could not be executed because a database file is 00151 ** locked or busy, then this function returns SQLITE_BUSY. (This 00152 ** behavior can be modified somewhat using the sqlite3_busy_handler() 00153 ** and sqlite3_busy_timeout() functions below.) 00154 */ 00155 int sqlite3_exec( 00156 sqlite3*, /* An open database */ 00157 const char *sql, /* SQL to be executed */ 00158 sqlite3_callback, /* Callback function */ 00159 void *, /* 1st argument to callback function */ 00160 char **errmsg /* Error msg written here */ 00161 ); 00162 00163 /* 00164 ** Return values for sqlite3_exec() and sqlite3_step() 00165 */ 00166 #define SQLITE_OK 0 /* Successful result */ 00167 #define SQLITE_ERROR 1 /* SQL error or missing database */ 00168 #define SQLITE_INTERNAL 2 /* NOT USED. Internal logic error in SQLite */ 00169 #define SQLITE_PERM 3 /* Access permission denied */ 00170 #define SQLITE_ABORT 4 /* Callback routine requested an abort */ 00171 #define SQLITE_BUSY 5 /* The database file is locked */ 00172 #define SQLITE_LOCKED 6 /* A table in the database is locked */ 00173 #define SQLITE_NOMEM 7 /* A malloc() failed */ 00174 #define SQLITE_READONLY 8 /* Attempt to write a readonly database */ 00175 #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/ 00176 #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ 00177 #define SQLITE_CORRUPT 11 /* The database disk image is malformed */ 00178 #define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */ 00179 #define SQLITE_FULL 13 /* Insertion failed because database is full */ 00180 #define SQLITE_CANTOPEN 14 /* Unable to open the database file */ 00181 #define SQLITE_PROTOCOL 15 /* Database lock protocol error */ 00182 #define SQLITE_EMPTY 16 /* Database is empty */ 00183 #define SQLITE_SCHEMA 17 /* The database schema changed */ 00184 #define SQLITE_TOOBIG 18 /* NOT USED. Too much data for one row */ 00185 #define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */ 00186 #define SQLITE_MISMATCH 20 /* Data type mismatch */ 00187 #define SQLITE_MISUSE 21 /* Library used incorrectly */ 00188 #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ 00189 #define SQLITE_AUTH 23 /* Authorization denied */ 00190 #define SQLITE_FORMAT 24 /* Auxiliary database format error */ 00191 #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */ 00192 #define SQLITE_NOTADB 26 /* File opened that is not a database file */ 00193 #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ 00194 #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ 00195 /* end-of-return-codes */ 00196 00197 /* 00198 ** Each entry in an SQLite table has a unique integer key. (The key is 00199 ** the value of the INTEGER PRIMARY KEY column if there is such a column, 00200 ** otherwise the key is generated at random. The unique key is always 00201 ** available as the ROWID, OID, or _ROWID_ column.) The following routine 00202 ** returns the integer key of the most recent insert in the database. 00203 ** 00204 ** This function is similar to the mysql_insert_id() function from MySQL. 00205 */ 00206 sqlite_int64 sqlite3_last_insert_rowid(sqlite3*); 00207 00208 /* 00209 ** This function returns the number of database rows that were changed 00210 ** (or inserted or deleted) by the most recent called sqlite3_exec(). 00211 ** 00212 ** All changes are counted, even if they were later undone by a 00213 ** ROLLBACK or ABORT. Except, changes associated with creating and 00214 ** dropping tables are not counted. 00215 ** 00216 ** If a callback invokes sqlite3_exec() recursively, then the changes 00217 ** in the inner, recursive call are counted together with the changes 00218 ** in the outer call. 00219 ** 00220 ** SQLite implements the command "DELETE FROM table" without a WHERE clause 00221 ** by dropping and recreating the table. (This is much faster than going 00222 ** through and deleting individual elements form the table.) Because of 00223 ** this optimization, the change count for "DELETE FROM table" will be 00224 ** zero regardless of the number of elements that were originally in the 00225 ** table. To get an accurate count of the number of rows deleted, use 00226 ** "DELETE FROM table WHERE 1" instead. 00227 */ 00228 int sqlite3_changes(sqlite3*); 00229 00230 /* 00231 ** This function returns the number of database rows that have been 00232 ** modified by INSERT, UPDATE or DELETE statements since the database handle 00233 ** was opened. This includes UPDATE, INSERT and DELETE statements executed 00234 ** as part of trigger programs. All changes are counted as soon as the 00235 ** statement that makes them is completed (when the statement handle is 00236 ** passed to sqlite3_reset() or sqlite_finalise()). 00237 ** 00238 ** SQLite implements the command "DELETE FROM table" without a WHERE clause 00239 ** by dropping and recreating the table. (This is much faster than going 00240 ** through and deleting individual elements form the table.) Because of 00241 ** this optimization, the change count for "DELETE FROM table" will be 00242 ** zero regardless of the number of elements that were originally in the 00243 ** table. To get an accurate count of the number of rows deleted, use 00244 ** "DELETE FROM table WHERE 1" instead. 00245 */ 00246 int sqlite3_total_changes(sqlite3*); 00247 00248 /* This function causes any pending database operation to abort and 00249 ** return at its earliest opportunity. This routine is typically 00250 ** called in response to a user action such as pressing "Cancel" 00251 ** or Ctrl-C where the user wants a long query operation to halt 00252 ** immediately. 00253 */ 00254 void sqlite3_interrupt(sqlite3*); 00255 00256 00257 /* These functions return true if the given input string comprises 00258 ** one or more complete SQL statements. For the sqlite3_complete() call, 00259 ** the parameter must be a nul-terminated UTF-8 string. For 00260 ** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string 00261 ** is required. 00262 ** 00263 ** The algorithm is simple. If the last token other than spaces 00264 ** and comments is a semicolon, then return true. otherwise return 00265 ** false. 00266 */ 00267 int sqlite3_complete(const char *sql); 00268 int sqlite3_complete16(const void *sql); 00269 00270 /* 00271 ** This routine identifies a callback function that is invoked 00272 ** whenever an attempt is made to open a database table that is 00273 ** currently locked by another process or thread. If the busy callback 00274 ** is NULL, then sqlite3_exec() returns SQLITE_BUSY immediately if 00275 ** it finds a locked table. If the busy callback is not NULL, then 00276 ** sqlite3_exec() invokes the callback with three arguments. The 00277 ** second argument is the name of the locked table and the third 00278 ** argument is the number of times the table has been busy. If the 00279 ** busy callback returns 0, then sqlite3_exec() immediately returns 00280 ** SQLITE_BUSY. If the callback returns non-zero, then sqlite3_exec() 00281 ** tries to open the table again and the cycle repeats. 00282 ** 00283 ** The default busy callback is NULL. 00284 ** 00285 ** Sqlite is re-entrant, so the busy handler may start a new query. 00286 ** (It is not clear why anyone would every want to do this, but it 00287 ** is allowed, in theory.) But the busy handler may not close the 00288 ** database. Closing the database from a busy handler will delete 00289 ** data structures out from under the executing query and will 00290 ** probably result in a coredump. 00291 */ 00292 int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); 00293 00294 /* 00295 ** This routine sets a busy handler that sleeps for a while when a 00296 ** table is locked. The handler will sleep multiple times until 00297 ** at least "ms" milleseconds of sleeping have been done. After 00298 ** "ms" milleseconds of sleeping, the handler returns 0 which 00299 ** causes sqlite3_exec() to return SQLITE_BUSY. 00300 ** 00301 ** Calling this routine with an argument less than or equal to zero 00302 ** turns off all busy handlers. 00303 */ 00304 int sqlite3_busy_timeout(sqlite3*, int ms); 00305 00306 /* 00307 ** This next routine is really just a wrapper around sqlite3_exec(). 00308 ** Instead of invoking a user-supplied callback for each row of the 00309 ** result, this routine remembers each row of the result in memory 00310 ** obtained from malloc(), then returns all of the result after the 00311 ** query has finished. 00312 ** 00313 ** As an example, suppose the query result where this table: 00314 ** 00315 ** Name | Age 00316 ** ----------------------- 00317 ** Alice | 43 00318 ** Bob | 28 00319 ** Cindy | 21 00320 ** 00321 ** If the 3rd argument were &azResult then after the function returns 00322 ** azResult will contain the following data: 00323 ** 00324 ** azResult[0] = "Name"; 00325 ** azResult[1] = "Age"; 00326 ** azResult[2] = "Alice"; 00327 ** azResult[3] = "43"; 00328 ** azResult[4] = "Bob"; 00329 ** azResult[5] = "28"; 00330 ** azResult[6] = "Cindy"; 00331 ** azResult[7] = "21"; 00332 ** 00333 ** Notice that there is an extra row of data containing the column 00334 ** headers. But the *nrow return value is still 3. *ncolumn is 00335 ** set to 2. In general, the number of values inserted into azResult 00336 ** will be ((*nrow) + 1)*(*ncolumn). 00337 ** 00338 ** After the calling function has finished using the result, it should 00339 ** pass the result data pointer to sqlite3_free_table() in order to 00340 ** release the memory that was malloc-ed. Because of the way the 00341 ** malloc() happens, the calling function must not try to call 00342 ** free() directly. Only sqlite3_free_table() is able to release 00343 ** the memory properly and safely. 00344 ** 00345 ** The return value of this routine is the same as from sqlite3_exec(). 00346 */ 00347 int sqlite3_get_table( 00348 sqlite3*, /* An open database */ 00349 const char *sql, /* SQL to be executed */ 00350 char ***resultp, /* Result written to a char *[] that this points to */ 00351 int *nrow, /* Number of result rows written here */ 00352 int *ncolumn, /* Number of result columns written here */ 00353 char **errmsg /* Error msg written here */ 00354 ); 00355 00356 /* 00357 ** Call this routine to free the memory that sqlite3_get_table() allocated. 00358 */ 00359 void sqlite3_free_table(char **result); 00360 00361 /* 00362 ** The following routines are variants of the "sprintf()" from the 00363 ** standard C library. The resulting string is written into memory 00364 ** obtained from malloc() so that there is never a possiblity of buffer 00365 ** overflow. These routines also implement some additional formatting 00366 ** options that are useful for constructing SQL statements. 00367 ** 00368 ** The strings returned by these routines should be freed by calling 00369 ** sqlite3_free(). 00370 ** 00371 ** All of the usual printf formatting options apply. In addition, there 00372 ** is a "%q" option. %q works like %s in that it substitutes a null-terminated 00373 ** string from the argument list. But %q also doubles every '\'' character. 00374 ** %q is designed for use inside a string literal. By doubling each '\'' 00375 ** character it escapes that character and allows it to be inserted into 00376 ** the string. 00377 ** 00378 ** For example, so some string variable contains text as follows: 00379 ** 00380 ** char *zText = "It's a happy day!"; 00381 ** 00382 ** We can use this text in an SQL statement as follows: 00383 ** 00384 ** char *z = sqlite3_mprintf("INSERT INTO TABLES('%q')", zText); 00385 ** sqlite3_exec(db, z, callback1, 0, 0); 00386 ** sqlite3_free(z); 00387 ** 00388 ** Because the %q format string is used, the '\'' character in zText 00389 ** is escaped and the SQL generated is as follows: 00390 ** 00391 ** INSERT INTO table1 VALUES('It''s a happy day!') 00392 ** 00393 ** This is correct. Had we used %s instead of %q, the generated SQL 00394 ** would have looked like this: 00395 ** 00396 ** INSERT INTO table1 VALUES('It's a happy day!'); 00397 ** 00398 ** This second example is an SQL syntax error. As a general rule you 00399 ** should always use %q instead of %s when inserting text into a string 00400 ** literal. 00401 */ 00402 char *sqlite3_mprintf(const char*,...); 00403 char *sqlite3_vmprintf(const char*, va_list); 00404 void sqlite3_free(char *z); 00405 char *sqlite3_snprintf(int,char*,const char*, ...); 00406 00407 #ifndef SQLITE_OMIT_AUTHORIZATION 00408 /* 00409 ** This routine registers a callback with the SQLite library. The 00410 ** callback is invoked (at compile-time, not at run-time) for each 00411 ** attempt to access a column of a table in the database. The callback 00412 ** returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire 00413 ** SQL statement should be aborted with an error and SQLITE_IGNORE 00414 ** if the column should be treated as a NULL value. 00415 */ 00416 int sqlite3_set_authorizer( 00417 sqlite3*, 00418 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), 00419 void *pUserData 00420 ); 00421 #endif 00422 00423 /* 00424 ** The second parameter to the access authorization function above will 00425 ** be one of the values below. These values signify what kind of operation 00426 ** is to be authorized. The 3rd and 4th parameters to the authorization 00427 ** function will be parameters or NULL depending on which of the following 00428 ** codes is used as the second parameter. The 5th parameter is the name 00429 ** of the database ("main", "temp", etc.) if applicable. The 6th parameter 00430 ** is the name of the inner-most trigger or view that is responsible for 00431 ** the access attempt or NULL if this access attempt is directly from 00432 ** input SQL code. 00433 ** 00434 ** Arg-3 Arg-4 00435 */ 00436 #define SQLITE_COPY 0 /* Table Name File Name */ 00437 #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ 00438 #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */ 00439 #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */ 00440 #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */ 00441 #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */ 00442 #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */ 00443 #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */ 00444 #define SQLITE_CREATE_VIEW 8 /* View Name NULL */ 00445 #define SQLITE_DELETE 9 /* Table Name NULL */ 00446 #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */ 00447 #define SQLITE_DROP_TABLE 11 /* Table Name NULL */ 00448 #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */ 00449 #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */ 00450 #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */ 00451 #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */ 00452 #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */ 00453 #define SQLITE_DROP_VIEW 17 /* View Name NULL */ 00454 #define SQLITE_INSERT 18 /* Table Name NULL */ 00455 #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */ 00456 #define SQLITE_READ 20 /* Table Name Column Name */ 00457 #define SQLITE_SELECT 21 /* NULL NULL */ 00458 #define SQLITE_TRANSACTION 22 /* NULL NULL */ 00459 #define SQLITE_UPDATE 23 /* Table Name Column Name */ 00460 #define SQLITE_ATTACH 24 /* Filename NULL */ 00461 #define SQLITE_DETACH 25 /* Database Name NULL */ 00462 #define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */ 00463 #define SQLITE_REINDEX 27 /* Index Name NULL */ 00464 #define SQLITE_ANALYZE 28 /* Table Name NULL */ 00465 00466 00467 /* 00468 ** The return value of the authorization function should be one of the 00469 ** following constants: 00470 */ 00471 /* #define SQLITE_OK 0 // Allow access (This is actually defined above) */ 00472 #define SQLITE_DENY 1 /* Abort the SQL statement with an error */ 00473 #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ 00474 00475 /* 00476 ** Register a function for tracing SQL command evaluation. The function 00477 ** registered by sqlite3_trace() is invoked at the first sqlite3_step() 00478 ** for the evaluation of an SQL statement. The function registered by 00479 ** sqlite3_profile() runs at the end of each SQL statement and includes 00480 ** information on how long that statement ran. 00481 ** 00482 ** The sqlite3_profile() API is currently considered experimental and 00483 ** is subject to change. 00484 */ 00485 void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*); 00486 void *sqlite3_profile(sqlite3*, 00487 void(*xProfile)(void*,const char*,sqlite_uint64), void*); 00488 00489 /* 00490 ** This routine configures a callback function - the progress callback - that 00491 ** is invoked periodically during long running calls to sqlite3_exec(), 00492 ** sqlite3_step() and sqlite3_get_table(). An example use for this API is to 00493 ** keep a GUI updated during a large query. 00494 ** 00495 ** The progress callback is invoked once for every N virtual machine opcodes, 00496 ** where N is the second argument to this function. The progress callback 00497 ** itself is identified by the third argument to this function. The fourth 00498 ** argument to this function is a void pointer passed to the progress callback 00499 ** function each time it is invoked. 00500 ** 00501 ** If a call to sqlite3_exec(), sqlite3_step() or sqlite3_get_table() results 00502 ** in less than N opcodes being executed, then the progress callback is not 00503 ** invoked. 00504 ** 00505 ** To remove the progress callback altogether, pass NULL as the third 00506 ** argument to this function. 00507 ** 00508 ** If the progress callback returns a result other than 0, then the current 00509 ** query is immediately terminated and any database changes rolled back. If the 00510 ** query was part of a larger transaction, then the transaction is not rolled 00511 ** back and remains active. The sqlite3_exec() call returns SQLITE_ABORT. 00512 ** 00513 ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ****** 00514 */ 00515 void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); 00516 00517 /* 00518 ** Register a callback function to be invoked whenever a new transaction 00519 ** is committed. The pArg argument is passed through to the callback. 00520 ** callback. If the callback function returns non-zero, then the commit 00521 ** is converted into a rollback. 00522 ** 00523 ** If another function was previously registered, its pArg value is returned. 00524 ** Otherwise NULL is returned. 00525 ** 00526 ** Registering a NULL function disables the callback. 00527 ** 00528 ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ****** 00529 */ 00530 void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*); 00531 00532 /* 00533 ** Open the sqlite database file "filename". The "filename" is UTF-8 00534 ** encoded for sqlite3_open() and UTF-16 encoded in the native byte order 00535 ** for sqlite3_open16(). An sqlite3* handle is returned in *ppDb, even 00536 ** if an error occurs. If the database is opened (or created) successfully, 00537 ** then SQLITE_OK is returned. Otherwise an error code is returned. The 00538 ** sqlite3_errmsg() or sqlite3_errmsg16() routines can be used to obtain 00539 ** an English language description of the error. 00540 ** 00541 ** If the database file does not exist, then a new database is created. 00542 ** The encoding for the database is UTF-8 if sqlite3_open() is called and 00543 ** UTF-16 if sqlite3_open16 is used. 00544 ** 00545 ** Whether or not an error occurs when it is opened, resources associated 00546 ** with the sqlite3* handle should be released by passing it to 00547 ** sqlite3_close() when it is no longer required. 00548 */ 00549 int sqlite3_open( 00550 const char *filename, /* Database filename (UTF-8) */ 00551 sqlite3 **ppDb /* OUT: SQLite db handle */ 00552 ); 00553 int sqlite3_open16( 00554 const void *filename, /* Database filename (UTF-16) */ 00555 sqlite3 **ppDb /* OUT: SQLite db handle */ 00556 ); 00557 00558 /* 00559 ** Return the error code for the most recent sqlite3_* API call associated 00560 ** with sqlite3 handle 'db'. SQLITE_OK is returned if the most recent 00561 ** API call was successful. 00562 ** 00563 ** Calls to many sqlite3_* functions set the error code and string returned 00564 ** by sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16() 00565 ** (overwriting the previous values). Note that calls to sqlite3_errcode(), 00566 ** sqlite3_errmsg() and sqlite3_errmsg16() themselves do not affect the 00567 ** results of future invocations. 00568 ** 00569 ** Assuming no other intervening sqlite3_* API calls are made, the error 00570 ** code returned by this function is associated with the same error as 00571 ** the strings returned by sqlite3_errmsg() and sqlite3_errmsg16(). 00572 */ 00573 int sqlite3_errcode(sqlite3 *db); 00574 00575 /* 00576 ** Return a pointer to a UTF-8 encoded string describing in english the 00577 ** error condition for the most recent sqlite3_* API call. The returned 00578 ** string is always terminated by an 0x00 byte. 00579 ** 00580 ** The string "not an error" is returned when the most recent API call was 00581 ** successful. 00582 */ 00583 const char *sqlite3_errmsg(sqlite3*); 00584 00585 /* 00586 ** Return a pointer to a UTF-16 native byte order encoded string describing 00587 ** in english the error condition for the most recent sqlite3_* API call. 00588 ** The returned string is always terminated by a pair of 0x00 bytes. 00589 ** 00590 ** The string "not an error" is returned when the most recent API call was 00591 ** successful. 00592 */ 00593 const void *sqlite3_errmsg16(sqlite3*); 00594 00595 /* 00596 ** An instance of the following opaque structure is used to represent 00597 ** a compiled SQL statment. 00598 */ 00599 typedef struct sqlite3_stmt sqlite3_stmt; 00600 00601 /* 00602 ** To execute an SQL query, it must first be compiled into a byte-code 00603 ** program using one of the following routines. The only difference between 00604 ** them is that the second argument, specifying the SQL statement to 00605 ** compile, is assumed to be encoded in UTF-8 for the sqlite3_prepare() 00606 ** function and UTF-16 for sqlite3_prepare16(). 00607 ** 00608 ** The first parameter "db" is an SQLite database handle. The second 00609 ** parameter "zSql" is the statement to be compiled, encoded as either 00610 ** UTF-8 or UTF-16 (see above). If the next parameter, "nBytes", is less 00611 ** than zero, then zSql is read up to the first nul terminator. If 00612 ** "nBytes" is not less than zero, then it is the length of the string zSql 00613 ** in bytes (not characters). 00614 ** 00615 ** *pzTail is made to point to the first byte past the end of the first 00616 ** SQL statement in zSql. This routine only compiles the first statement 00617 ** in zSql, so *pzTail is left pointing to what remains uncompiled. 00618 ** 00619 ** *ppStmt is left pointing to a compiled SQL statement that can be 00620 ** executed using sqlite3_step(). Or if there is an error, *ppStmt may be 00621 ** set to NULL. If the input text contained no SQL (if the input is and 00622 ** empty string or a comment) then *ppStmt is set to NULL. 00623 ** 00624 ** On success, SQLITE_OK is returned. Otherwise an error code is returned. 00625 */ 00626 int sqlite3_prepare( 00627 sqlite3 *db, /* Database handle */ 00628 const char *zSql, /* SQL statement, UTF-8 encoded */ 00629 int nBytes, /* Length of zSql in bytes. */ 00630 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 00631 const char **pzTail /* OUT: Pointer to unused portion of zSql */ 00632 ); 00633 int sqlite3_prepare16( 00634 sqlite3 *db, /* Database handle */ 00635 const void *zSql, /* SQL statement, UTF-16 encoded */ 00636 int nBytes, /* Length of zSql in bytes. */ 00637 sqlite3_stmt **ppStmt, /* OUT: Statement handle */ 00638 const void **pzTail /* OUT: Pointer to unused portion of zSql */ 00639 ); 00640 00641 /* 00642 ** Pointers to the following two opaque structures are used to communicate 00643 ** with the implementations of user-defined functions. 00644 */ 00645 typedef struct sqlite3_context sqlite3_context; 00646 typedef struct Mem sqlite3_value; 00647 00648 /* 00649 ** In the SQL strings input to sqlite3_prepare() and sqlite3_prepare16(), 00650 ** one or more literals can be replace by parameters "?" or ":AAA" or 00651 ** "$VVV" where AAA is an identifer and VVV is a variable name according 00652 ** to the syntax rules of the TCL programming language. 00653 ** The value of these parameters (also called "host parameter names") can 00654 ** be set using the routines listed below. 00655 ** 00656 ** In every case, the first parameter is a pointer to the sqlite3_stmt 00657 ** structure returned from sqlite3_prepare(). The second parameter is the 00658 ** index of the parameter. The first parameter as an index of 1. For 00659 ** named parameters (":AAA" or "$VVV") you can use 00660 ** sqlite3_bind_parameter_index() to get the correct index value given 00661 ** the parameters name. If the same named parameter occurs more than 00662 ** once, it is assigned the same index each time. 00663 ** 00664 ** The fifth parameter to sqlite3_bind_blob(), sqlite3_bind_text(), and 00665 ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or 00666 ** text after SQLite has finished with it. If the fifth argument is the 00667 ** special value SQLITE_STATIC, then the library assumes that the information 00668 ** is in static, unmanaged space and does not need to be freed. If the 00669 ** fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its 00670 ** own private copy of the data. 00671 ** 00672 ** The sqlite3_bind_* routine must be called before sqlite3_step() after 00673 ** an sqlite3_prepare() or sqlite3_reset(). Unbound parameterss are 00674 ** interpreted as NULL. 00675 */ 00676 int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); 00677 int sqlite3_bind_double(sqlite3_stmt*, int, double); 00678 int sqlite3_bind_int(sqlite3_stmt*, int, int); 00679 int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite_int64); 00680 int sqlite3_bind_null(sqlite3_stmt*, int); 00681 int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); 00682 int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); 00683 int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); 00684 00685 /* 00686 ** Return the number of parameters in a compiled SQL statement. This 00687 ** routine was added to support DBD::SQLite. 00688 */ 00689 int sqlite3_bind_parameter_count(sqlite3_stmt*); 00690 00691 /* 00692 ** Return the name of the i-th parameter. Ordinary parameters "?" are 00693 ** nameless and a NULL is returned. For parameters of the form :AAA or 00694 ** $VVV the complete text of the parameter name is returned, including 00695 ** the initial ":" or "$". NULL is returned if the index is out of range. 00696 */ 00697 const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); 00698 00699 /* 00700 ** Return the index of a parameter with the given name. The name 00701 ** must match exactly. If no parameter with the given name is found, 00702 ** return 0. 00703 */ 00704 int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); 00705 00706 /* 00707 ** Set all the parameters in the compiled SQL statement to NULL. 00708 */ 00709 int sqlite3_clear_bindings(sqlite3_stmt*); 00710 00711 /* 00712 ** Return the number of columns in the result set returned by the compiled 00713 ** SQL statement. This routine returns 0 if pStmt is an SQL statement 00714 ** that does not return data (for example an UPDATE). 00715 */ 00716 int sqlite3_column_count(sqlite3_stmt *pStmt); 00717 00718 /* 00719 ** The first parameter is a compiled SQL statement. This function returns 00720 ** the column heading for the Nth column of that statement, where N is the 00721 ** second function parameter. The string returned is UTF-8 for 00722 ** sqlite3_column_name() and UTF-16 for sqlite3_column_name16(). 00723 */ 00724 const char *sqlite3_column_name(sqlite3_stmt*,int); 00725 const void *sqlite3_column_name16(sqlite3_stmt*,int); 00726 00727 /* 00728 ** The first parameter is a compiled SQL statement. If this statement 00729 ** is a SELECT statement, the Nth column of the returned result set 00730 ** of the SELECT is a table column then the declared type of the table 00731 ** column is returned. If the Nth column of the result set is not at table 00732 ** column, then a NULL pointer is returned. The returned string is always 00733 ** UTF-8 encoded. For example, in the database schema: 00734 ** 00735 ** CREATE TABLE t1(c1 VARIANT); 00736 ** 00737 ** And the following statement compiled: 00738 ** 00739 ** SELECT c1 + 1, 0 FROM t1; 00740 ** 00741 ** Then this routine would return the string "VARIANT" for the second 00742 ** result column (i==1), and a NULL pointer for the first result column 00743 ** (i==0). 00744 */ 00745 const char *sqlite3_column_decltype(sqlite3_stmt *, int i); 00746 00747 /* 00748 ** The first parameter is a compiled SQL statement. If this statement 00749 ** is a SELECT statement, the Nth column of the returned result set 00750 ** of the SELECT is a table column then the declared type of the table 00751 ** column is returned. If the Nth column of the result set is not at table 00752 ** column, then a NULL pointer is returned. The returned string is always 00753 ** UTF-16 encoded. For example, in the database schema: 00754 ** 00755 ** CREATE TABLE t1(c1 INTEGER); 00756 ** 00757 ** And the following statement compiled: 00758 ** 00759 ** SELECT c1 + 1, 0 FROM t1; 00760 ** 00761 ** Then this routine would return the string "INTEGER" for the second 00762 ** result column (i==1), and a NULL pointer for the first result column 00763 ** (i==0). 00764 */ 00765 const void *sqlite3_column_decltype16(sqlite3_stmt*,int); 00766 00767 /* 00768 ** After an SQL query has been compiled with a call to either 00769 ** sqlite3_prepare() or sqlite3_prepare16(), then this function must be 00770 ** called one or more times to execute the statement. 00771 ** 00772 ** The return value will be either SQLITE_BUSY, SQLITE_DONE, 00773 ** SQLITE_ROW, SQLITE_ERROR, or SQLITE_MISUSE. 00774 ** 00775 ** SQLITE_BUSY means that the database engine attempted to open 00776 ** a locked database and there is no busy callback registered. 00777 ** Call sqlite3_step() again to retry the open. 00778 ** 00779 ** SQLITE_DONE means that the statement has finished executing 00780 ** successfully. sqlite3_step() should not be called again on this virtual 00781 ** machine. 00782 ** 00783 ** If the SQL statement being executed returns any data, then 00784 ** SQLITE_ROW is returned each time a new row of data is ready 00785 ** for processing by the caller. The values may be accessed using 00786 ** the sqlite3_column_*() functions described below. sqlite3_step() 00787 ** is called again to retrieve the next row of data. 00788 ** 00789 ** SQLITE_ERROR means that a run-time error (such as a constraint 00790 ** violation) has occurred. sqlite3_step() should not be called again on 00791 ** the VM. More information may be found by calling sqlite3_errmsg(). 00792 ** 00793 ** SQLITE_MISUSE means that the this routine was called inappropriately. 00794 ** Perhaps it was called on a virtual machine that had already been 00795 ** finalized or on one that had previously returned SQLITE_ERROR or 00796 ** SQLITE_DONE. Or it could be the case the the same database connection 00797 ** is being used simulataneously by two or more threads. 00798 */ 00799 int sqlite3_step(sqlite3_stmt*); 00800 00801 /* 00802 ** Return the number of values in the current row of the result set. 00803 ** 00804 ** After a call to sqlite3_step() that returns SQLITE_ROW, this routine 00805 ** will return the same value as the sqlite3_column_count() function. 00806 ** After sqlite3_step() has returned an SQLITE_DONE, SQLITE_BUSY or 00807 ** error code, or before sqlite3_step() has been called on a 00808 ** compiled SQL statement, this routine returns zero. 00809 */ 00810 int sqlite3_data_count(sqlite3_stmt *pStmt); 00811 00812 /* 00813 ** Values are stored in the database in one of the following fundamental 00814 ** types. 00815 */ 00816 #define SQLITE_INTEGER 1 00817 #define SQLITE_FLOAT 2 00818 /* #define SQLITE_TEXT 3 // See below */ 00819 #define SQLITE_BLOB 4 00820 #define SQLITE_NULL 5 00821 00822 /* 00823 ** SQLite version 2 defines SQLITE_TEXT differently. To allow both 00824 ** version 2 and version 3 to be included, undefine them both if a 00825 ** conflict is seen. Define SQLITE3_TEXT to be the version 3 value. 00826 */ 00827 #ifdef SQLITE_TEXT 00828 # undef SQLITE_TEXT 00829 #else 00830 # define SQLITE_TEXT 3 00831 #endif 00832 #define SQLITE3_TEXT 3 00833 00834 /* 00835 ** The next group of routines returns information about the information 00836 ** in a single column of the current result row of a query. In every 00837 ** case the first parameter is a pointer to the SQL statement that is being 00838 ** executed (the sqlite_stmt* that was returned from sqlite3_prepare()) and 00839 ** the second argument is the index of the column for which information 00840 ** should be returned. iCol is zero-indexed. The left-most column as an 00841 ** index of 0. 00842 ** 00843 ** If the SQL statement is not currently point to a valid row, or if the 00844 ** the colulmn index is out of range, the result is undefined. 00845 ** 00846 ** These routines attempt to convert the value where appropriate. For 00847 ** example, if the internal representation is FLOAT and a text result 00848 ** is requested, sprintf() is used internally to do the conversion 00849 ** automatically. The following table details the conversions that 00850 ** are applied: 00851 ** 00852 ** Internal Type Requested Type Conversion 00853 ** ------------- -------------- -------------------------- 00854 ** NULL INTEGER Result is 0 00855 ** NULL FLOAT Result is 0.0 00856 ** NULL TEXT Result is an empty string 00857 ** NULL BLOB Result is a zero-length BLOB 00858 ** INTEGER FLOAT Convert from integer to float 00859 ** INTEGER TEXT ASCII rendering of the integer 00860 ** INTEGER BLOB Same as for INTEGER->TEXT 00861 ** FLOAT INTEGER Convert from float to integer 00862 ** FLOAT TEXT ASCII rendering of the float 00863 ** FLOAT BLOB Same as FLOAT->TEXT 00864 ** TEXT INTEGER Use atoi() 00865 ** TEXT FLOAT Use atof() 00866 ** TEXT BLOB No change 00867 ** BLOB INTEGER Convert to TEXT then use atoi() 00868 ** BLOB FLOAT Convert to TEXT then use atof() 00869 ** BLOB TEXT Add a \000 terminator if needed 00870 ** 00871 ** The following access routines are provided: 00872 ** 00873 ** _type() Return the datatype of the result. This is one of 00874 ** SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB, 00875 ** or SQLITE_NULL. 00876 ** _blob() Return the value of a BLOB. 00877 ** _bytes() Return the number of bytes in a BLOB value or the number 00878 ** of bytes in a TEXT value represented as UTF-8. The \000 00879 ** terminator is included in the byte count for TEXT values. 00880 ** _bytes16() Return the number of bytes in a BLOB value or the number 00881 ** of bytes in a TEXT value represented as UTF-16. The \u0000 00882 ** terminator is included in the byte count for TEXT values. 00883 ** _double() Return a FLOAT value. 00884 ** _int() Return an INTEGER value in the host computer's native 00885 ** integer representation. This might be either a 32- or 64-bit 00886 ** integer depending on the host. 00887 ** _int64() Return an INTEGER value as a 64-bit signed integer. 00888 ** _text() Return the value as UTF-8 text. 00889 ** _text16() Return the value as UTF-16 text. 00890 */ 00891 const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); 00892 int sqlite3_column_bytes(sqlite3_stmt*, int iCol); 00893 int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); 00894 double sqlite3_column_double(sqlite3_stmt*, int iCol); 00895 int sqlite3_column_int(sqlite3_stmt*, int iCol); 00896 sqlite_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); 00897 const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); 00898 const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); 00899 int sqlite3_column_type(sqlite3_stmt*, int iCol); 00900 00901 /* 00902 ** The sqlite3_finalize() function is called to delete a compiled 00903 ** SQL statement obtained by a previous call to sqlite3_prepare() 00904 ** or sqlite3_prepare16(). If the statement was executed successfully, or 00905 ** not executed at all, then SQLITE_OK is returned. If execution of the 00906 ** statement failed then an error code is returned. 00907 ** 00908 ** This routine can be called at any point during the execution of the 00909 ** virtual machine. If the virtual machine has not completed execution 00910 ** when this routine is called, that is like encountering an error or 00911 ** an interrupt. (See sqlite3_interrupt().) Incomplete updates may be 00912 ** rolled back and transactions cancelled, depending on the circumstances, 00913 ** and the result code returned will be SQLITE_ABORT. 00914 */ 00915 int sqlite3_finalize(sqlite3_stmt *pStmt); 00916 00917 /* 00918 ** The sqlite3_reset() function is called to reset a compiled SQL 00919 ** statement obtained by a previous call to sqlite3_prepare() or 00920 ** sqlite3_prepare16() back to it's initial state, ready to be re-executed. 00921 ** Any SQL statement variables that had values bound to them using 00922 ** the sqlite3_bind_*() API retain their values. 00923 */ 00924 int sqlite3_reset(sqlite3_stmt *pStmt); 00925 00926 /* 00927 ** The following two functions are used to add user functions or aggregates 00928 ** implemented in C to the SQL langauge interpreted by SQLite. The 00929 ** difference only between the two is that the second parameter, the 00930 ** name of the (scalar) function or aggregate, is encoded in UTF-8 for 00931 ** sqlite3_create_function() and UTF-16 for sqlite3_create_function16(). 00932 ** 00933 ** The first argument is the database handle that the new function or 00934 ** aggregate is to be added to. If a single program uses more than one 00935 ** database handle internally, then user functions or aggregates must 00936 ** be added individually to each database handle with which they will be 00937 ** used. 00938 ** 00939 ** The third parameter is the number of arguments that the function or 00940 ** aggregate takes. If this parameter is negative, then the function or 00941 ** aggregate may take any number of arguments. 00942 ** 00943 ** The fourth parameter is one of SQLITE_UTF* values defined below, 00944 ** indicating the encoding that the function is most likely to handle 00945 ** values in. This does not change the behaviour of the programming 00946 ** interface. However, if two versions of the same function are registered 00947 ** with different encoding values, SQLite invokes the version likely to 00948 ** minimize conversions between text encodings. 00949 ** 00950 ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are 00951 ** pointers to user implemented C functions that implement the user 00952 ** function or aggregate. A scalar function requires an implementation of 00953 ** the xFunc callback only, NULL pointers should be passed as the xStep 00954 ** and xFinal parameters. An aggregate function requires an implementation 00955 ** of xStep and xFinal, but NULL should be passed for xFunc. To delete an 00956 ** existing user function or aggregate, pass NULL for all three function 00957 ** callback. Specifying an inconstent set of callback values, such as an 00958 ** xFunc and an xFinal, or an xStep but no xFinal, SQLITE_ERROR is 00959 ** returned. 00960 */ 00961 int sqlite3_create_function( 00962 sqlite3 *, 00963 const char *zFunctionName, 00964 int nArg, 00965 int eTextRep, 00966 void*, 00967 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 00968 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 00969 void (*xFinal)(sqlite3_context*) 00970 ); 00971 int sqlite3_create_function16( 00972 sqlite3*, 00973 const void *zFunctionName, 00974 int nArg, 00975 int eTextRep, 00976 void*, 00977 void (*xFunc)(sqlite3_context*,int,sqlite3_value**), 00978 void (*xStep)(sqlite3_context*,int,sqlite3_value**), 00979 void (*xFinal)(sqlite3_context*) 00980 ); 00981 00982 /* 00983 ** The next routine returns the number of calls to xStep for a particular 00984 ** aggregate function instance. The current call to xStep counts so this 00985 ** routine always returns at least 1. 00986 */ 00987 int sqlite3_aggregate_count(sqlite3_context*); 00988 00989 /* 00990 ** The next group of routines returns information about parameters to 00991 ** a user-defined function. Function implementations use these routines 00992 ** to access their parameters. These routines are the same as the 00993 ** sqlite3_column_* routines except that these routines take a single 00994 ** sqlite3_value* pointer instead of an sqlite3_stmt* and an integer 00995 ** column number. 00996 */ 00997 const void *sqlite3_value_blob(sqlite3_value*); 00998 int sqlite3_value_bytes(sqlite3_value*); 00999 int sqlite3_value_bytes16(sqlite3_value*); 01000 double sqlite3_value_double(sqlite3_value*); 01001 int sqlite3_value_int(sqlite3_value*); 01002 sqlite_int64 sqlite3_value_int64(sqlite3_value*); 01003 const unsigned char *sqlite3_value_text(sqlite3_value*); 01004 const void *sqlite3_value_text16(sqlite3_value*); 01005 const void *sqlite3_value_text16le(sqlite3_value*); 01006 const void *sqlite3_value_text16be(sqlite3_value*); 01007 int sqlite3_value_type(sqlite3_value*); 01008 01009 /* 01010 ** Aggregate functions use the following routine to allocate 01011 ** a structure for storing their state. The first time this routine 01012 ** is called for a particular aggregate, a new structure of size nBytes 01013 ** is allocated, zeroed, and returned. On subsequent calls (for the 01014 ** same aggregate instance) the same buffer is returned. The implementation 01015 ** of the aggregate can use the returned buffer to accumulate data. 01016 ** 01017 ** The buffer allocated is freed automatically by SQLite. 01018 */ 01019 void *sqlite3_aggregate_context(sqlite3_context*, int nBytes); 01020 01021 /* 01022 ** The pUserData parameter to the sqlite3_create_function() 01023 ** routine used to register user functions is available to 01024 ** the implementation of the function using this call. 01025 */ 01026 void *sqlite3_user_data(sqlite3_context*); 01027 01028 /* 01029 ** The following two functions may be used by scalar user functions to 01030 ** associate meta-data with argument values. If the same value is passed to 01031 ** multiple invocations of the user-function during query execution, under 01032 ** some circumstances the associated meta-data may be preserved. This may 01033 ** be used, for example, to add a regular-expression matching scalar 01034 ** function. The compiled version of the regular expression is stored as 01035 ** meta-data associated with the SQL value passed as the regular expression 01036 ** pattern. 01037 ** 01038 ** Calling sqlite3_get_auxdata() returns a pointer to the meta data 01039 ** associated with the Nth argument value to the current user function 01040 ** call, where N is the second parameter. If no meta-data has been set for 01041 ** that value, then a NULL pointer is returned. 01042 ** 01043 ** The sqlite3_set_auxdata() is used to associate meta data with a user 01044 ** function argument. The third parameter is a pointer to the meta data 01045 ** to be associated with the Nth user function argument value. The fourth 01046 ** parameter specifies a 'delete function' that will be called on the meta 01047 ** data pointer to release it when it is no longer required. If the delete 01048 ** function pointer is NULL, it is not invoked. 01049 ** 01050 ** In practice, meta-data is preserved between function calls for 01051 ** expressions that are constant at compile time. This includes literal 01052 ** values and SQL variables. 01053 */ 01054 void *sqlite3_get_auxdata(sqlite3_context*, int); 01055 void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*)); 01056 01057 01058 /* 01059 ** These are special value for the destructor that is passed in as the 01060 ** final argument to routines like sqlite3_result_blob(). If the destructor 01061 ** argument is SQLITE_STATIC, it means that the content pointer is constant 01062 ** and will never change. It does not need to be destroyed. The 01063 ** SQLITE_TRANSIENT value means that the content will likely change in 01064 ** the near future and that SQLite should make its own private copy of 01065 ** the content before returning. 01066 */ 01067 #define SQLITE_STATIC ((void(*)(void *))0) 01068 #define SQLITE_TRANSIENT ((void(*)(void *))-1) 01069 01070 /* 01071 ** User-defined functions invoke the following routines in order to 01072 ** set their return value. 01073 */ 01074 void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); 01075 void sqlite3_result_double(sqlite3_context*, double); 01076 void sqlite3_result_error(sqlite3_context*, const char*, int); 01077 void sqlite3_result_error16(sqlite3_context*, const void*, int); 01078 void sqlite3_result_int(sqlite3_context*, int); 01079 void sqlite3_result_int64(sqlite3_context*, sqlite_int64); 01080 void sqlite3_result_null(sqlite3_context*); 01081 void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); 01082 void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); 01083 void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); 01084 void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); 01085 void sqlite3_result_value(sqlite3_context*, sqlite3_value*); 01086 01087 /* 01088 ** These are the allowed values for the eTextRep argument to 01089 ** sqlite3_create_collation and sqlite3_create_function. 01090 */ 01091 #define SQLITE_UTF8 1 01092 #define SQLITE_UTF16LE 2 01093 #define SQLITE_UTF16BE 3 01094 #define SQLITE_UTF16 4 /* Use native byte order */ 01095 #define SQLITE_ANY 5 /* sqlite3_create_function only */ 01096 01097 /* 01098 ** These two functions are used to add new collation sequences to the 01099 ** sqlite3 handle specified as the first argument. 01100 ** 01101 ** The name of the new collation sequence is specified as a UTF-8 string 01102 ** for sqlite3_create_collation() and a UTF-16 string for 01103 ** sqlite3_create_collation16(). In both cases the name is passed as the 01104 ** second function argument. 01105 ** 01106 ** The third argument must be one of the constants SQLITE_UTF8, 01107 ** SQLITE_UTF16LE or SQLITE_UTF16BE, indicating that the user-supplied 01108 ** routine expects to be passed pointers to strings encoded using UTF-8, 01109 ** UTF-16 little-endian or UTF-16 big-endian respectively. 01110 ** 01111 ** A pointer to the user supplied routine must be passed as the fifth 01112 ** argument. If it is NULL, this is the same as deleting the collation 01113 ** sequence (so that SQLite cannot call it anymore). Each time the user 01114 ** supplied function is invoked, it is passed a copy of the void* passed as 01115 ** the fourth argument to sqlite3_create_collation() or 01116 ** sqlite3_create_collation16() as its first parameter. 01117 ** 01118 ** The remaining arguments to the user-supplied routine are two strings, 01119 ** each represented by a [length, data] pair and encoded in the encoding 01120 ** that was passed as the third argument when the collation sequence was 01121 ** registered. The user routine should return negative, zero or positive if 01122 ** the first string is less than, equal to, or greater than the second 01123 ** string. i.e. (STRING1 - STRING2). 01124 */ 01125 int sqlite3_create_collation( 01126 sqlite3*, 01127 const char *zName, 01128 int eTextRep, 01129 void*, 01130 int(*xCompare)(void*,int,const void*,int,const void*) 01131 ); 01132 int sqlite3_create_collation16( 01133 sqlite3*, 01134 const char *zName, 01135 int eTextRep, 01136 void*, 01137 int(*xCompare)(void*,int,const void*,int,const void*) 01138 ); 01139 01140 /* 01141 ** To avoid having to register all collation sequences before a database 01142 ** can be used, a single callback function may be registered with the 01143 ** database handle to be called whenever an undefined collation sequence is 01144 ** required. 01145 ** 01146 ** If the function is registered using the sqlite3_collation_needed() API, 01147 ** then it is passed the names of undefined collation sequences as strings 01148 ** encoded in UTF-8. If sqlite3_collation_needed16() is used, the names 01149 ** are passed as UTF-16 in machine native byte order. A call to either 01150 ** function replaces any existing callback. 01151 ** 01152 ** When the user-function is invoked, the first argument passed is a copy 01153 ** of the second argument to sqlite3_collation_needed() or 01154 ** sqlite3_collation_needed16(). The second argument is the database 01155 ** handle. The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE or 01156 ** SQLITE_UTF16LE, indicating the most desirable form of the collation 01157 ** sequence function required. The fourth parameter is the name of the 01158 ** required collation sequence. 01159 ** 01160 ** The collation sequence is returned to SQLite by a collation-needed 01161 ** callback using the sqlite3_create_collation() or 01162 ** sqlite3_create_collation16() APIs, described above. 01163 */ 01164 int sqlite3_collation_needed( 01165 sqlite3*, 01166 void*, 01167 void(*)(void*,sqlite3*,int eTextRep,const char*) 01168 ); 01169 int sqlite3_collation_needed16( 01170 sqlite3*, 01171 void*, 01172 void(*)(void*,sqlite3*,int eTextRep,const void*) 01173 ); 01174 01175 /* 01176 ** Specify the key for an encrypted database. This routine should be 01177 ** called right after sqlite3_open(). 01178 ** 01179 ** The code to implement this API is not available in the public release 01180 ** of SQLite. 01181 */ 01182 int sqlite3_key( 01183 sqlite3 *db, /* Database to be rekeyed */ 01184 const void *pKey, int nKey /* The key */ 01185 ); 01186 01187 /* 01188 ** Change the key on an open database. If the current database is not 01189 ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the 01190 ** database is decrypted. 01191 ** 01192 ** The code to implement this API is not available in the public release 01193 ** of SQLite. 01194 */ 01195 int sqlite3_rekey( 01196 sqlite3 *db, /* Database to be rekeyed */ 01197 const void *pKey, int nKey /* The new key */ 01198 ); 01199 01200 /* 01201 ** Sleep for a little while. The second parameter is the number of 01202 ** miliseconds to sleep for. 01203 ** 01204 ** If the operating system does not support sleep requests with 01205 ** milisecond time resolution, then the time will be rounded up to 01206 ** the nearest second. The number of miliseconds of sleep actually 01207 ** requested from the operating system is returned. 01208 */ 01209 int sqlite3_sleep(int); 01210 01211 /* 01212 ** Return TRUE (non-zero) if the statement supplied as an argument needs 01213 ** to be recompiled. A statement needs to be recompiled whenever the 01214 ** execution environment changes in a way that would alter the program 01215 ** that sqlite3_prepare() generates. For example, if new functions or 01216 ** collating sequences are registered or if an authorizer function is 01217 ** added or changed. 01218 ** 01219 */ 01220 int sqlite3_expired(sqlite3_stmt*); 01221 01222 /* 01223 ** Move all bindings from the first prepared statement over to the second. 01224 ** This routine is useful, for example, if the first prepared statement 01225 ** fails with an SQLITE_SCHEMA error. The same SQL can be prepared into 01226 ** the second prepared statement then all of the bindings transfered over 01227 ** to the second statement before the first statement is finalized. 01228 */ 01229 int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*); 01230 01231 /* 01232 ** If the following global variable is made to point to a 01233 ** string which is the name of a directory, then all temporary files 01234 ** created by SQLite will be placed in that directory. If this variable 01235 ** is NULL pointer, then SQLite does a search for an appropriate temporary 01236 ** file directory. 01237 ** 01238 ** Once sqlite3_open() has been called, changing this variable will invalidate 01239 ** the current temporary database, if any. 01240 */ 01241 extern char *sqlite3_temp_directory; 01242 01243 /* 01244 ** This function is called to recover from a malloc() failure that occured 01245 ** within the SQLite library. Normally, after a single malloc() fails the 01246 ** library refuses to function (all major calls return SQLITE_NOMEM). 01247 ** This function restores the library state so that it can be used again. 01248 ** 01249 ** All existing statements (sqlite3_stmt pointers) must be finalized or 01250 ** reset before this call is made. Otherwise, SQLITE_BUSY is returned. 01251 ** If any in-memory databases are in use, either as a main or TEMP 01252 ** database, SQLITE_ERROR is returned. In either of these cases, the 01253 ** library is not reset and remains unusable. 01254 ** 01255 ** This function is *not* threadsafe. Calling this from within a threaded 01256 ** application when threads other than the caller have used SQLite is 01257 ** dangerous and will almost certainly result in malfunctions. 01258 ** 01259 ** This functionality can be omitted from a build by defining the 01260 ** SQLITE_OMIT_GLOBALRECOVER at compile time. 01261 */ 01262 int sqlite3_global_recover(void); 01263 01264 /* 01265 ** Test to see whether or not the database connection is in autocommit 01266 ** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on 01267 ** by default. Autocommit is disabled by a BEGIN statement and reenabled 01268 ** by the next COMMIT or ROLLBACK. 01269 */ 01270 int sqlite3_get_autocommit(sqlite3*); 01271 01272 /* 01273 ** Return the sqlite3* database handle to which the prepared statement given 01274 ** in the argument belongs. This is the same database handle that was 01275 ** the first argument to the sqlite3_prepare() that was used to create 01276 ** the statement in the first place. 01277 */ 01278 sqlite3 *sqlite3_db_handle(sqlite3_stmt*); 01279 01280 /* 01281 ** Register a callback function with the database connection identified by the 01282 ** first argument to be invoked whenever a row is updated, inserted or deleted. 01283 ** Any callback set by a previous call to this function for the same 01284 ** database connection is overridden. 01285 ** 01286 ** The second argument is a pointer to the function to invoke when a 01287 ** row is updated, inserted or deleted. The first argument to the callback is 01288 ** a copy of the third argument to sqlite3_update_hook. The second callback 01289 ** argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending 01290 ** on the operation that caused the callback to be invoked. The third and 01291 ** fourth arguments to the callback contain pointers to the database and 01292 ** table name containing the affected row. The final callback parameter is 01293 ** the rowid of the row. In the case of an update, this is the rowid after 01294 ** the update takes place. 01295 ** 01296 ** The update hook is not invoked when internal system tables are 01297 ** modified (i.e. sqlite_master and sqlite_sequence). 01298 ** 01299 ** If another function was previously registered, its pArg value is returned. 01300 ** Otherwise NULL is returned. 01301 */ 01302 void *sqlite3_update_hook( 01303 sqlite3*, 01304 void(*)(void *,int ,char const *,char const *,sqlite_int64), 01305 void* 01306 ); 01307 01308 /* 01309 ** Register a callback to be invoked whenever a transaction is rolled 01310 ** back. 01311 ** 01312 ** The new callback function overrides any existing rollback-hook 01313 ** callback. If there was an existing callback, then it's pArg value 01314 ** (the third argument to sqlite3_rollback_hook() when it was registered) 01315 ** is returned. Otherwise, NULL is returned. 01316 ** 01317 ** For the purposes of this API, a transaction is said to have been 01318 ** rolled back if an explicit "ROLLBACK" statement is executed, or 01319 ** an error or constraint causes an implicit rollback to occur. The 01320 ** callback is not invoked if a transaction is automatically rolled 01321 ** back because the database connection is closed. 01322 */ 01323 void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); 01324 01325 /* 01326 ** This function is only available if the library is compiled without 01327 ** the SQLITE_OMIT_SHARED_CACHE macro defined. It is used to enable or 01328 ** disable (if the argument is true or false, respectively) the 01329 ** "shared pager" feature. 01330 */ 01331 int sqlite3_enable_shared_cache(int); 01332 01333 /* 01334 ** Attempt to free N bytes of heap memory by deallocating non-essential 01335 ** memory allocations held by the database library (example: memory 01336 ** used to cache database pages to improve performance). 01337 ** 01338 ** This function is not a part of standard builds. It is only created 01339 ** if SQLite is compiled with the SQLITE_ENABLE_MEMORY_MANAGEMENT macro. 01340 */ 01341 int sqlite3_release_memory(int); 01342 01343 /* 01344 ** Place a "soft" limit on the amount of heap memory that may be allocated by 01345 ** SQLite within the current thread. If an internal allocation is requested 01346 ** that would exceed the specified limit, sqlite3_release_memory() is invoked 01347 ** one or more times to free up some space before the allocation is made. 01348 ** 01349 ** The limit is called "soft", because if sqlite3_release_memory() cannot free 01350 ** sufficient memory to prevent the limit from being exceeded, the memory is 01351 ** allocated anyway and the current operation proceeds. 01352 ** 01353 ** This function is only available if the library was compiled with the 01354 ** SQLITE_ENABLE_MEMORY_MANAGEMENT option set. 01355 ** memory-management has been enabled. 01356 */ 01357 void sqlite3_soft_heap_limit(int); 01358 01359 /* 01360 ** This routine makes sure that all thread-local storage has been 01361 ** deallocated for the current thread. 01362 ** 01363 ** This routine is not technically necessary. All thread-local storage 01364 ** will be automatically deallocated once memory-management and 01365 ** shared-cache are disabled and the soft heap limit has been set 01366 ** to zero. This routine is provided as a convenience for users who 01367 ** want to make absolutely sure they have not forgotten something 01368 ** prior to killing off a thread. 01369 */ 01370 void sqlite3_thread_cleanup(void); 01371 01372 /* 01373 ** Undo the hack that converts floating point types to integer for 01374 ** builds on processors without floating point support. 01375 */ 01376 #ifdef SQLITE_OMIT_FLOATING_POINT 01377 # undef double 01378 #endif 01379 01380 #ifdef __cplusplus 01381 } /* End of the 'extern "C"' block */ 01382 #endif 01383 #endif