/*

** 2001 September 15

**

** The author disclaims copyright to this source code.  In place of

** a legal notice, here is a blessing:

**

**    May you do good and not evil.

**    May you find forgiveness for yourself and forgive others.

**    May you share freely, never taking more than you give.

**

*************************************************************************

** This header file defines the interface that the SQLite library

** presents to client programs.

**

** @(#) $Id: sqlite.h.in,v 1.189 2006/08/24 14:59:46 drh Exp $

*/

#ifndef _SQLITE3_H_

#define _SQLITE3_H_

#include <stdarg.h>     /* Needed for the definition of va_list */

/*

** Make sure we can call this stuff from C++.

*/

#ifdef __cplusplus

extern "C" {

#endif

/*

** The version of the SQLite library.

*/

#ifdef SQLITE_VERSION

# undef SQLITE_VERSION

#endif

#define SQLITE_VERSION         "3.3.7"

/*

** The format of the version string is "X.Y.Z<trailing string>", where

** X is the major version number, Y is the minor version number and Z

** is the release number. The trailing string is often "alpha" or "beta".

** For example "3.1.1beta".

**

** The SQLITE_VERSION_NUMBER is an integer with the value 

** (X*100000 + Y*1000 + Z). For example, for version "3.1.1beta", 

** SQLITE_VERSION_NUMBER is set to 3001001. To detect if they are using 

** version 3.1.1 or greater at compile time, programs may use the test 

** (SQLITE_VERSION_NUMBER>=3001001).

*/

#ifdef SQLITE_VERSION_NUMBER

# undef SQLITE_VERSION_NUMBER

#endif

#define SQLITE_VERSION_NUMBER 3003007

/*

** The version string is also compiled into the library so that a program

** can check to make sure that the lib*.a file and the *.h file are from

** the same version.  The sqlite3_libversion() function returns a pointer

** to the sqlite3_version variable - useful in DLLs which cannot access

** global variables.

*/

extern const char sqlite3_version[];

const char *sqlite3_libversion(void);

/*

** Return the value of the SQLITE_VERSION_NUMBER macro when the

** library was compiled.

*/

int sqlite3_libversion_number(void);

/*

** Each open sqlite database is represented by an instance of the

** following opaque structure.

*/

typedef struct sqlite3 sqlite3;

/*

** Some compilers do not support the "long long" datatype.  So we have

** to do a typedef that for 64-bit integers that depends on what compiler

** is being used.

*/

#ifdef SQLITE_INT64_TYPE

  typedef SQLITE_INT64_TYPE sqlite_int64;

  typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;

#elif defined(_MSC_VER) || defined(__BORLANDC__)

  typedef __int64 sqlite_int64;

  typedef unsigned __int64 sqlite_uint64;

#else

  typedef long long int sqlite_int64;

  typedef unsigned long long int sqlite_uint64;

#endif

/*

** If compiling for a processor that lacks floating point support,

** substitute integer for floating-point

*/

#ifdef SQLITE_OMIT_FLOATING_POINT

# define double sqlite_int64

#endif

/*

** A function to close the database.

**

** Call this function with a pointer to a structure that was previously

** returned from sqlite3_open() and the corresponding database will by closed.

**

** All SQL statements prepared using sqlite3_prepare() or

** sqlite3_prepare16() must be deallocated using sqlite3_finalize() before

** this routine is called. Otherwise, SQLITE_BUSY is returned and the

** database connection remains open.

*/

IMPORT_C int sqlite3_close(sqlite3 *);

/*

** The type for a callback function.

*/

typedef int (*sqlite3_callback)(void*,int,char**, char**);

/*

** A function to executes one or more statements of SQL.

**

** If one or more of the SQL statements are queries, then

** the callback function specified by the 3rd parameter is

** invoked once for each row of the query result.  This callback

** should normally return 0.  If the callback returns a non-zero

** value then the query is aborted, all subsequent SQL statements

** are skipped and the sqlite3_exec() function returns the SQLITE_ABORT.

**

** The 4th parameter is an arbitrary pointer that is passed

** to the callback function as its first parameter.

**

** The 2nd parameter to the callback function is the number of

** columns in the query result.  The 3rd parameter to the callback

** is an array of strings holding the values for each column.

** The 4th parameter to the callback is an array of strings holding

** the names of each column.

**

** The callback function may be NULL, even for queries.  A NULL

** callback is not an error.  It just means that no callback

** will be invoked.

**

** If an error occurs while parsing or evaluating the SQL (but

** not while executing the callback) then an appropriate error

** message is written into memory obtained from malloc() and

** *errmsg is made to point to that message.  The calling function

** is responsible for freeing the memory that holds the error

** message.   Use sqlite3_free() for this.  If errmsg==NULL,

** then no error message is ever written.

**

** The return value is is SQLITE_OK if there are no errors and

** some other return code if there is an error.  The particular

** return value depends on the type of error. 

**

** If the query could not be executed because a database file is

** locked or busy, then this function returns SQLITE_BUSY.  (This

** behavior can be modified somewhat using the sqlite3_busy_handler()

** and sqlite3_busy_timeout() functions below.)

*/

int sqlite3_exec(

  sqlite3*,                     /* An open database */

  const char *sql,              /* SQL to be executed */

  sqlite3_callback,             /* Callback function */

  void *,                       /* 1st argument to callback function */

  char **errmsg                 /* Error msg written here */

);

/*

** Return values for sqlite3_exec() and sqlite3_step()

*/

#define SQLITE_OK           0   /* Successful result */

/* beginning-of-error-codes */

#define SQLITE_ERROR        1   /* SQL error or missing database */

#define SQLITE_INTERNAL     2   /* NOT USED. Internal logic error in SQLite */

#define SQLITE_PERM         3   /* Access permission denied */

#define SQLITE_ABORT        4   /* Callback routine requested an abort */

#define SQLITE_BUSY         5   /* The database file is locked */

#define SQLITE_LOCKED       6   /* A table in the database is locked */

#define SQLITE_NOMEM        7   /* A malloc() failed */

#define SQLITE_READONLY     8   /* Attempt to write a readonly database */

#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/

#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */

#define SQLITE_CORRUPT     11   /* The database disk image is malformed */

#define SQLITE_NOTFOUND    12   /* NOT USED. Table or record not found */

#define SQLITE_FULL        13   /* Insertion failed because database is full */

#define SQLITE_CANTOPEN    14   /* Unable to open the database file */

#define SQLITE_PROTOCOL    15   /* Database lock protocol error */

#define SQLITE_EMPTY       16   /* Database is empty */

#define SQLITE_SCHEMA      17   /* The database schema changed */

#define SQLITE_TOOBIG      18   /* NOT USED. Too much data for one row */

#define SQLITE_CONSTRAINT  19   /* Abort due to contraint violation */

#define SQLITE_MISMATCH    20   /* Data type mismatch */

#define SQLITE_MISUSE      21   /* Library used incorrectly */

#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */

#define SQLITE_AUTH        23   /* Authorization denied */

#define SQLITE_FORMAT      24   /* Auxiliary database format error */

#define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */

#define SQLITE_NOTADB      26   /* File opened that is not a database file */

#define SQLITE_ROW         100  /* sqlite3_step() has another row ready */

#define SQLITE_DONE        101  /* sqlite3_step() has finished executing */

/* end-of-error-codes */

/*

** Each entry in an SQLite table has a unique integer key.  (The key is

** the value of the INTEGER PRIMARY KEY column if there is such a column,

** otherwise the key is generated at random.  The unique key is always

** available as the ROWID, OID, or _ROWID_ column.)  The following routine

** returns the integer key of the most recent insert in the database.

**

** This function is similar to the mysql_insert_id() function from MySQL.

*/

IMPORT_C sqlite_int64 sqlite3_last_insert_rowid(sqlite3*);

/*

** This function returns the number of database rows that were changed

** (or inserted or deleted) by the most recent called sqlite3_exec().

**

** All changes are counted, even if they were later undone by a

** ROLLBACK or ABORT.  Except, changes associated with creating and

** dropping tables are not counted.

**

** If a callback invokes sqlite3_exec() recursively, then the changes

** in the inner, recursive call are counted together with the changes

** in the outer call.

**

** SQLite implements the command "DELETE FROM table" without a WHERE clause

** by dropping and recreating the table.  (This is much faster than going

** through and deleting individual elements form the table.)  Because of

** this optimization, the change count for "DELETE FROM table" will be

** zero regardless of the number of elements that were originally in the

** table. To get an accurate count of the number of rows deleted, use

** "DELETE FROM table WHERE 1" instead.

*/

IMPORT_C int sqlite3_changes(sqlite3*);

/*

** This function returns the number of database rows that have been

** modified by INSERT, UPDATE or DELETE statements since the database handle

** was opened. This includes UPDATE, INSERT and DELETE statements executed

** as part of trigger programs. All changes are counted as soon as the

** statement that makes them is completed (when the statement handle is

** passed to sqlite3_reset() or sqlite_finalise()).

**

** SQLite implements the command "DELETE FROM table" without a WHERE clause

** by dropping and recreating the table.  (This is much faster than going

** through and deleting individual elements form the table.)  Because of

** this optimization, the change count for "DELETE FROM table" will be

** zero regardless of the number of elements that were originally in the

** table. To get an accurate count of the number of rows deleted, use

** "DELETE FROM table WHERE 1" instead.

*/

int sqlite3_total_changes(sqlite3*);

/* This function causes any pending database operation to abort and

** return at its earliest opportunity.  This routine is typically

** called in response to a user action such as pressing "Cancel"

** or Ctrl-C where the user wants a long query operation to halt

** immediately.

*/

void sqlite3_interrupt(sqlite3*);

/* These functions return true if the given input string comprises

** one or more complete SQL statements. For the sqlite3_complete() call,

** the parameter must be a nul-terminated UTF-8 string. For

** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string

** is required.

**

** The algorithm is simple.  If the last token other than spaces

** and comments is a semicolon, then return true.  otherwise return

** false.

*/

int sqlite3_complete(const char *sql);

int sqlite3_complete16(const void *sql);

/*

** This routine identifies a callback function that is invoked

** whenever an attempt is made to open a database table that is

** currently locked by another process or thread.  If the busy callback

** is NULL, then sqlite3_exec() returns SQLITE_BUSY immediately if

** it finds a locked table.  If the busy callback is not NULL, then

** sqlite3_exec() invokes the callback with three arguments.  The

** second argument is the name of the locked table and the third

** argument is the number of times the table has been busy.  If the

** busy callback returns 0, then sqlite3_exec() immediately returns

** SQLITE_BUSY.  If the callback returns non-zero, then sqlite3_exec()

** tries to open the table again and the cycle repeats.

**

** The default busy callback is NULL.

**

** Sqlite is re-entrant, so the busy handler may start a new query. 

** (It is not clear why anyone would every want to do this, but it

** is allowed, in theory.)  But the busy handler may not close the

** database.  Closing the database from a busy handler will delete 

** data structures out from under the executing query and will 

** probably result in a coredump.

*/

IMPORT_C int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);

/*

** This routine sets a busy handler that sleeps for a while when a

** table is locked.  The handler will sleep multiple times until 

** at least "ms" milleseconds of sleeping have been done.  After

** "ms" milleseconds of sleeping, the handler returns 0 which

** causes sqlite3_exec() to return SQLITE_BUSY.

**

** Calling this routine with an argument less than or equal to zero

** turns off all busy handlers.

*/

IMPORT_C int sqlite3_busy_timeout(sqlite3*, int ms);

/*

** This next routine is really just a wrapper around sqlite3_exec().

** Instead of invoking a user-supplied callback for each row of the

** result, this routine remembers each row of the result in memory

** obtained from malloc(), then returns all of the result after the

** query has finished. 

**

** As an example, suppose the query result where this table:

**

**        Name        | Age

**        -----------------------

**        Alice       | 43

**        Bob         | 28

**        Cindy       | 21

**

** If the 3rd argument were &azResult then after the function returns

** azResult will contain the following data:

**

**        azResult[0] = "Name";

**        azResult[1] = "Age";

**        azResult[2] = "Alice";

**        azResult[3] = "43";

**        azResult[4] = "Bob";

**        azResult[5] = "28";

**        azResult[6] = "Cindy";

**        azResult[7] = "21";

**

** Notice that there is an extra row of data containing the column

** headers.  But the *nrow return value is still 3.  *ncolumn is

** set to 2.  In general, the number of values inserted into azResult

** will be ((*nrow) + 1)*(*ncolumn).

**

** After the calling function has finished using the result, it should 

** pass the result data pointer to sqlite3_free_table() in order to 

** release the memory that was malloc-ed.  Because of the way the 

** malloc() happens, the calling function must not try to call 

** free() directly.  Only sqlite3_free_table() is able to release 

** the memory properly and safely.

**

** The return value of this routine is the same as from sqlite3_exec().

*/

int sqlite3_get_table(

  sqlite3*,               /* An open database */

  const char *sql,       /* SQL to be executed */

  char ***resultp,       /* Result written to a char *[]  that this points to */

  int *nrow,             /* Number of result rows written here */

  int *ncolumn,          /* Number of result columns written here */

  char **errmsg          /* Error msg written here */

);

/*

** Call this routine to free the memory that sqlite3_get_table() allocated.

*/

void sqlite3_free_table(char **result);

/*

** The following routines are variants of the "sprintf()" from the

** standard C library.  The resulting string is written into memory

** obtained from malloc() so that there is never a possiblity of buffer

** overflow.  These routines also implement some additional formatting

** options that are useful for constructing SQL statements.

**

** The strings returned by these routines should be freed by calling

** sqlite3_free().

**

** All of the usual printf formatting options apply.  In addition, there

** is a "%q" option.  %q works like %s in that it substitutes a null-terminated

** string from the argument list.  But %q also doubles every '\'' character.

** %q is designed for use inside a string literal.  By doubling each '\''

** character it escapes that character and allows it to be inserted into

** the string.

**

** For example, so some string variable contains text as follows:

**

**      char *zText = "It's a happy day!";

**

** We can use this text in an SQL statement as follows:

**

**      char *z = sqlite3_mprintf("INSERT INTO TABLES('%q')", zText);

**      sqlite3_exec(db, z, callback1, 0, 0);

**      sqlite3_free(z);

**

** Because the %q format string is used, the '\'' character in zText

** is escaped and the SQL generated is as follows:

**

**      INSERT INTO table1 VALUES('It''s a happy day!')

**

** This is correct.  Had we used %s instead of %q, the generated SQL

** would have looked like this:

**

**      INSERT INTO table1 VALUES('It's a happy day!');

**

** This second example is an SQL syntax error.  As a general rule you

** should always use %q instead of %s when inserting text into a string 

** literal.

*/

char *sqlite3_mprintf(const char*,...);

char *sqlite3_vmprintf(const char*, va_list);

char *sqlite3_snprintf(int,char*,const char*, ...);

/*

** SQLite uses its own memory allocator.  On many installations, this

** memory allocator is identical to the standard malloc()/realloc()/free()

** and can be used interchangable.  On others, the implementations are

** different.  For maximum portability, it is best not to mix calls

** to the standard malloc/realloc/free with the sqlite versions.

*/

void *sqlite3_malloc(int);

void *sqlite3_realloc(void*, int);

void sqlite3_free(void*);

#ifndef SQLITE_OMIT_AUTHORIZATION

/*

** This routine registers a callback with the SQLite library.  The

** callback is invoked (at compile-time, not at run-time) for each

** attempt to access a column of a table in the database.  The callback

** returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire

** SQL statement should be aborted with an error and SQLITE_IGNORE

** if the column should be treated as a NULL value.

*/

int sqlite3_set_authorizer(

  sqlite3*,

  int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),

  void *pUserData

);

#endif

/*

** The second parameter to the access authorization function above will

** be one of the values below.  These values signify what kind of operation

** is to be authorized.  The 3rd and 4th parameters to the authorization

** function will be parameters or NULL depending on which of the following

** codes is used as the second parameter.  The 5th parameter is the name

** of the database ("main", "temp", etc.) if applicable.  The 6th parameter

** is the name of the inner-most trigger or view that is responsible for

** the access attempt or NULL if this access attempt is directly from 

** input SQL code.

**

**                                          Arg-3           Arg-4

*/

#define SQLITE_COPY                  0   /* Table Name      File Name       */

#define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */

#define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */

#define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */

#define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */

#define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */

#define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */

#define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */

#define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */

#define SQLITE_DELETE                9   /* Table Name      NULL            */

#define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */

#define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */

#define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */

#define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */

#define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */

#define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */

#define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */

#define SQLITE_DROP_VIEW            17   /* View Name       NULL            */

#define SQLITE_INSERT               18   /* Table Name      NULL            */

#define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */

#define SQLITE_READ                 20   /* Table Name      Column Name     */

#define SQLITE_SELECT               21   /* NULL            NULL            */

#define SQLITE_TRANSACTION          22   /* NULL            NULL            */

#define SQLITE_UPDATE               23   /* Table Name      Column Name     */

#define SQLITE_ATTACH               24   /* Filename        NULL            */

#define SQLITE_DETACH               25   /* Database Name   NULL            */

#define SQLITE_ALTER_TABLE          26   /* Database Name   Table Name      */

#define SQLITE_REINDEX              27   /* Index Name      NULL            */

#define SQLITE_ANALYZE              28   /* Table Name      NULL            */

#define SQLITE_CREATE_VTABLE        29   /* Table Name      Module Name     */

#define SQLITE_DROP_VTABLE          30   /* Table Name      Module Name     */

#define SQLITE_FUNCTION             31   /* Function Name   NULL            */

/*

** The return value of the authorization function should be one of the

** following constants:

*/

/* #define SQLITE_OK  0   // Allow access (This is actually defined above) */

#define SQLITE_DENY   1   /* Abort the SQL statement with an error */

#define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */

/*

** Register a function for tracing SQL command evaluation.  The function

** registered by sqlite3_trace() is invoked at the first sqlite3_step()

** for the evaluation of an SQL statement.  The function registered by

** sqlite3_profile() runs at the end of each SQL statement and includes

** information on how long that statement ran.

**

** The sqlite3_profile() API is currently considered experimental and

** is subject to change.

*/

void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);

void *sqlite3_profile(sqlite3*,

   void(*xProfile)(void*,const char*,sqlite_uint64), void*);

/*

** This routine configures a callback function - the progress callback - that

** is invoked periodically during long running calls to sqlite3_exec(),

** sqlite3_step() and sqlite3_get_table(). An example use for this API is to 

** keep a GUI updated during a large query.

**

** The progress callback is invoked once for every N virtual machine opcodes,

** where N is the second argument to this function. The progress callback

** itself is identified by the third argument to this function. The fourth

** argument to this function is a void pointer passed to the progress callback

** function each time it is invoked.

**

** If a call to sqlite3_exec(), sqlite3_step() or sqlite3_get_table() results 

** in less than N opcodes being executed, then the progress callback is not

** invoked.

** 

** To remove the progress callback altogether, pass NULL as the third

** argument to this function.

**

** If the progress callback returns a result other than 0, then the current 

** query is immediately terminated and any database changes rolled back. If the

** query was part of a larger transaction, then the transaction is not rolled

** back and remains active. The sqlite3_exec() call returns SQLITE_ABORT. 

**

******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******