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

Generated on Mon Apr 6 14:05:58 2009 for COSTA by  doxygen 1.5.2