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

Generated on Mon Jun 22 10:49:31 2009 for CreaImageIO by  doxygen 1.5.3