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