Back to index

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