SQLite

** on how SQLite interfaces are suppose to operate.
**
** The name of this file under configuration management is "sqlite.h.in".
** The makefile makes some minor changes to this file (such as inserting
** the version number) and changes its name to "sqlite3.h" as
** part of the build process.
**
** This file is also used to generate some (but not all) of the formal
** requirements for SQLite.  To this end, "shall" language is used.
** Requirements are specified as follows:
**
**      {F00000} ... shall .... {EX} commentary {END}
**
** The requirement number comes first and is enclosed in curly
** braces.  The F prefix identifies functional requirements.
** The requirement consists of all text up through the next
** {...} mark or until the end of the comment.  Text following
** {EX} is an explanatory amplification of the preceding requirement.
** Both the {EX} and the {END} are optional.
**
** @(#) $Id: sqlite.h.in,v 1.273 2007/12/01 19:23:20 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 SQLITE_VERSION_NUMBER
# undef SQLITE_VERSION_NUMBER
#endif

/*
** CAPI3REF: Compile-Time Library Version Numbers {F10100}
**

** {F10101} The SQLITE_VERSION #define in the sqlite3.h header file
** shall resolve to a string constant that identifies the SQLite library

** version in the format "X.Y.Z", where
** X is the major version number, Y is the minor version number, and Z
** is the release number or the release number followed by text "alpha"
** or "beta". {EX}
**
** The X value is always 3 in SQLite.  The X value only changes when
** backwards compatibility is broken and we intend to never break
** backwards compatibility.  The Y value only changes when
** there are major feature enhancements that are forwards compatible
** but not backwards compatible.  The Z value is incremented with
** each release but resets back to 0 when Y is incremented.
**
** {F10104} The #define named SQLITE_VERSION_NUMBER shall resolve to
** an integer constant with
** the value (X*1000000 + Y*1000 + Z) where X, Y and Z are same as in
** the SQLITE_VERSION #define, though without the optional "alpha"
** or "beta" text on the end of Z. {EX} For example, for version "3.5.3", 
** SQLITE_VERSION_NUMBER is set to 3005003.  A test like

** (SQLITE_VERSION_NUMBER>=3005003) can be used to verify at
** compile-time that the SQLite version is 3.5.3 or later. {END}
**
** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
*/
#define SQLITE_VERSION         "--VERS--"
#define SQLITE_VERSION_NUMBER --VERSION-NUMBER--

/*
** CAPI3REF: Run-Time Library Version Numbers {F10110}
**
** {F10111} The sqlite3_libversion_number() interface shall return

** the value SQLITE_VERSION_NUMBER. {EX}
** Cautious programmers may want to put add code to
** their application that compares the value returned from
** sqlite3_libversion_number() against SQLITE_VERSION_NUMBER from
** the header, in order to insure that the library and header file
** are from the same release.
**
** {F10112} The sqlite3_version[] string constant shall contain the text
** of the [SQLITE_VERSION] #define.  {F10113} The sqlite3_libversion()
** function shall return a pointer to the sqlite3_version[] string
** constant. {EX} The sqlite3_libversion() function is provided for
** DLL users who can only access functions and not constants within
** the DLL and thus cannot access the sqlite3_version[] string directly.
*/
SQLITE_EXTERN const char sqlite3_version[];
const char *sqlite3_libversion(void);
int sqlite3_libversion_number(void);

/*
** CAPI3REF: Test To See If The Library Is Threadsafe {F10200}
**
** {F10201} The sqlite3_threadsafe() routine shall return TRUE (nonzero) 
** if SQLite was compiled its mutexes enabled and FALSE (zero) if
** mutexes are disabled. {EX}


**
** Really all this routine does is return true if SQLite was compiled
** with the -DSQLITE_THREADSAFE=1 option and false if
** compiled with -DSQLITE_THREADSAFE=0.  If SQLite uses an
** application-defined mutex subsystem, malloc subsystem, collating
** sequence, VFS, SQL function, progress callback, commit hook,
** extension, or other accessories and these add-ons are not
** threadsafe, then clearly the combination will not be threadsafe
** either.  Hence, this routine never reports that the library
** is guaranteed to be threadsafe, only when it is guaranteed not
** to be. {END}



*/
int sqlite3_threadsafe(void);

/*
** CAPI3REF: Database Connection Handle {F11000}
**
** Each open SQLite database is represented by pointer to an instance of the

** CAPI3REF: 64-Bit Integer Types {F10300}
**
** Some compilers do not support the "long long" datatype.  So we have
** to do compiler-specific typedefs for 64-bit signed and unsigned integers.
**
** Many SQLite interface functions require a 64-bit integer arguments.
** Those interfaces are declared using this typedef.
**
** {F10301} Values of type sqlite_int64 or sqlite3_int64 shall be
** 64-bit twos-complement integers. {F10302} Values of type
** sqlite_uint64 or sqlite3_uint64 shall be 64-bit unsigned integers. {END}
** The sqlite3_int64 and sqlite3_uint64 typedefs are preferred.
** The sqlite_int64 and sqlite_uint64 typedefs are maintained for
** backwards compatibility only.
*/
#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;

#ifdef SQLITE_OMIT_FLOATING_POINT
# define double sqlite3_int64
#endif

/*
** CAPI3REF: Closing A Database Connection {F11100}
**
** The sqlite3_close() interface is the destructor for the [sqlite3] object.
** {F11101} A successful call to sqlite3_close() shall return SQLITE_OK.
** {F11102} A successful call to sqlite3_close() shall cause all database
** files associated with the [sqlite3] object to be closed and shall
** cause resources
** associated with the [sqlite3] object to be released.
** {F11103} A successful call to sqlite3_close()
** shall cause any pending transaction on the [sqlite3] object to be
** rolled back. {END}
**
** All SQL statements prepared using [sqlite3_prepare_v2()] or
** [sqlite3_prepare16_v2()] must be destroyed using [sqlite3_finalize()]
** before sqlite3_close() is called.  {F11104} If sqlite3_close() is
** called on a connection that has unfinalized [sqlite3_stmt] objects
** then sqlite3_close() shall return SQLITE_BUSY and the database
** connection shall remain open. {END}
**
** {U11105} Calling sqlite3_close() on a database connection that has 
** already been closed results in undefined behavior.  {U11106} If 
** other interfaces that reference the same database connection are 
** pending (either in the same thread or in different threads) when 
** sqlite3_close() is called, then the behavior is undefined.

*/
int sqlite3_close(sqlite3 *);

/*
** The type for a callback function.
** This is legacy and deprecated.  It is included for historical
** compatibility and is not documented.
*/
typedef int (*sqlite3_callback)(void*,int,char**, char**);

/*
** CAPI3REF: One-Step Query Execution Interface {F11200}
**
** The sqlite3_exec() interface runs zero or more SQL statements
** passed as the 2nd parameter.  The optional callback in the third parameter
** is invoked once for each row of result generated by the SQL statements.
** If an error occurs, sqlite3_exec() returns an appropriate error code
** and writes an error message into *errmsg if errmsg is not NULL.
**
** <b>Details:</b>
**
** {F11201} The sqlite3_exec() interface shall evaluate semicolon separated
** UTF-8 encoded SQL statements passed in as the second argument,
** in order, until either all statements have been evaluated
** or until an error or interrupt occurs.
** {EX}  The statements are prepared one by one using [sqlite3_prepare()],
** evaluated using [sqlite3_step()], then destroyed using [sqlite3_finalize()].
** {F11202} The sqlite3_exec() interface shall evaluate SQL statements using
** the database connection passed in as the first parameter. 
**
** {F11203} The sqlite3_exec() interface shall retry statements
** that give an SQLITE_SCHEMA error and shall proceed normally
** if the retry works, or shall halt and return SQLITE_SCHEMA if
** the retry fails.
**
** {F11204} If the 3rd parameter to sqlite3_exec() is not NULL then
** sqlite3_exec() shall invoke the callback function specified by
** that parameter once for each row in the result set of every query
** that sqlite3_exec() evaluates. {END} This callback
** should normally return 0.  {F11205} If the callback on
** sqlite3_exec() returns a non-zero value then the query being
** evaluated shall abort and all subsequent SQL statements in the
** 2nd parameter to sqlite3_exec() shall be
** skipped and the sqlite3_exec() function shall return the [SQLITE_ABORT].
**
** {F11206} The sqlite3_exec() interface shall pass its 4th
** parameter through as the 1st parameter to its callback function.
**
** {F11207} The sqlite3_exec() routine shall cause the 2nd parameter
** to its callback function to be the number of columns in the current 
** row of the query result.
** {F11206} The sqlite3_exec() routine shall cause the 3rd parameter to
** its callback function to be an array of N pointers where each pointers
** is the return value of [sqlite3_column_text()] for the corresponding
** result column. {F11207} The sqlite3_exec() routine shall cause
** the 4th parameter to its callback function to be an array of N pointers
** where the value of each element of the array pointer returned
** by [sqlite3_column_name()] for the corresponding column. {END}

**
** The sqlite3_exec() callback function may be NULL, even for
** queries.  A NULL callback is not an error.  It just means that no callback
** will be invoked.
**
** {F11209} If sqlite3_exec() encounters an error while parsing or evaluating
** the SQL and if the 5th parameter to sqlite3_exec() is not NULL, 
** then an appropriate error message shall be written into memory obtained
** from [sqlite3_malloc()] and *errmsg shall be made to point to that
** message.  {EX} The calling function
** is responsible for freeing the memory using [sqlite3_free()].
** If errmsg==NULL, then no error message is ever written.
** This processing apply only to error that occur during statement
** process, not to error that may occur within the callback routine itself.
** {F11210} If the call to [sqlite3_malloc()] fails while attempting to
** construct an error message for the 5th parameter of sqlite3_exec()
** then the *errmsg value is left unchanged.
**
** {F11211} The return value from sqlite3_exec() shall be SQLITE_OK if there
** are no errors. {EX} Some other [SQLITE_OK | return code] if there is
** an error.  The particular return value depends on the type of error. 

*/
int sqlite3_exec(
  sqlite3*,                                  /* An open database */
  const char *sql,                           /* SQL to be evaluted */
  int (*callback)(void*,int,char**,char**),  /* Callback function */
  void *,                                    /* 1st argument to callback */
  char **errmsg                              /* Error msg written here */
);

/*
** CAPI3REF: Result Codes {F10120}
** KEYWORDS: SQLITE_OK
**
** Many SQLite functions return an integer result code from the set shown
** above in order to indicates success or failure.
**
** The result codes above are the only ones returned by SQLite in its
** default configuration.  However, the [sqlite3_extended_result_codes()]

#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 */

/*
** CAPI3REF: Extended Result Codes {F10121}
**
** In its default configuration, SQLite API routines return one of 26 integer
** result codes described at result-codes.  However, experience has shown that
** many of these result codes are too course-grained.  They do not provide as
** much information about problems as users might like.  In an effort to
** address this, newer versions of SQLite (version 3.3.8 and later) include
** support for additional result codes that provide more detailed information
** about errors.  The extended result codes are enabled (or disabled) for 
** each database
** connection using the [sqlite3_extended_result_codes()] API.
** 
** Some of the available extended result codes are listed here.
** We expect the number of extended result codes will be expand
** over time.  Software that uses extended result codes should expect
** to see new result codes in future releases of SQLite.
** 
** The symbolic name for an extended result code always contains a related
** primary result code as a prefix.  Primary result codes contain a single
** "_" character.  Extended result codes contain two or more "_" characters.

#define SQLITE_IOERR_UNLOCK        (SQLITE_IOERR | (8<<8))
#define SQLITE_IOERR_RDLOCK        (SQLITE_IOERR | (9<<8))
#define SQLITE_IOERR_DELETE        (SQLITE_IOERR | (10<<8))
#define SQLITE_IOERR_BLOCKED       (SQLITE_IOERR | (11<<8))
#define SQLITE_IOERR_NOMEM         (SQLITE_IOERR | (12<<8))

/*
** CAPI3REF: Flags For File Open Operations {F10122}
**
** Combination of the following bit values are used as the
** third argument to the [sqlite3_open_v2()] interface and
** as fourth argument to the xOpen method of the
** [sqlite3_vfs] object.
**
*/

#define SQLITE_OPEN_TRANSIENT_DB     0x00000400
#define SQLITE_OPEN_MAIN_JOURNAL     0x00000800
#define SQLITE_OPEN_TEMP_JOURNAL     0x00001000
#define SQLITE_OPEN_SUBJOURNAL       0x00002000
#define SQLITE_OPEN_MASTER_JOURNAL   0x00004000

/*
** CAPI3REF: Device Characteristics {F10123}
**
** The xDeviceCapabilities method of the [sqlite3_io_methods]
** object returns an integer which is a vector of the following
** bit values expressing I/O characteristics of the mass storage
** device that holds the file that the [sqlite3_io_methods]
** refers to.
**

#define SQLITE_IOCAP_ATOMIC16K       0x00000040
#define SQLITE_IOCAP_ATOMIC32K       0x00000080
#define SQLITE_IOCAP_ATOMIC64K       0x00000100
#define SQLITE_IOCAP_SAFE_APPEND     0x00000200
#define SQLITE_IOCAP_SEQUENTIAL      0x00000400

/*
** CAPI3REF: File Locking Levels   {F10124}
**
** SQLite uses one of the following integer values as the second
** argument to calls it makes to the xLock() and xUnlock() methods
** of an [sqlite3_io_methods] object.
*/
#define SQLITE_LOCK_NONE          0
#define SQLITE_LOCK_SHARED        1
#define SQLITE_LOCK_RESERVED      2
#define SQLITE_LOCK_PENDING       3
#define SQLITE_LOCK_EXCLUSIVE     4

/*
** CAPI3REF: Synchronization Type Flags {F10125}
**
** When SQLite invokes the xSync() method of an [sqlite3_io_methods]
** object it uses a combination of the following integer values as
** the second argument.
**
** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
** sync operation only needs to flush data to mass storage.  Inode
** information need not be flushed.  The SQLITE_SYNC_NORMAL means 
** to use normal fsync() semantics.  The SQLITE_SYNC_FULL flag means 
** to use Mac OS-X style fullsync instead of fsync().
*/
#define SQLITE_SYNC_NORMAL        0x00002
#define SQLITE_SYNC_FULL          0x00003
#define SQLITE_SYNC_DATAONLY      0x00010


/*
** CAPI3REF: OS Interface Open File Handle {F14100}
**
** An [sqlite3_file] object represents an open file in the OS
** interface layer.  Individual OS interface implementations will
** want to subclass this object by appending additional fields
** for their own use.  The pMethods entry is a pointer to an
** [sqlite3_io_methods] object that defines methods for performing
** I/O operations on the open file.
*/
typedef struct sqlite3_file sqlite3_file;
struct sqlite3_file {
  const struct sqlite3_io_methods *pMethods;  /* Methods for an open file */
};

/*
** CAPI3REF: OS Interface File Virtual Methods Object {F14110}
**
** Every file opened by the [sqlite3_vfs] xOpen method
** contains a pointer to an instance of the the sqlite3_io_methods object.
** This object defines the
** methods used to perform various operations against the open file.
**
** {F14111} Whenever the SQLite library invokes the xSync method of
** an [sqlite3_io_methods] object, it shall supply a flags argument
** which is one of [SQLITE_SYNC_NORMAL] or [SQLITE_SYNC_FULL] optionally
** ORed with [SQLITE_SYNC_DATA]. {EX}

** [SQLITE_SYNC_NORMAL] requests a normal fsync(). [SQLITE_SYNC_FULL]
** requests an OS-X style fullsync.  The [SQLITE_SYNC_DATA] flag 
** indicates that only the data of the file and not its inode needs to be
** synced.  These flags serve as optimization hints to the underlying
** VFS and can be ignored by the VFS if they are not applicable to the
** specific application. {END}
** 
** The integer values to xLock() and xUnlock() are one of
** <ul>
** <li> [SQLITE_LOCK_NONE],
** <li> [SQLITE_LOCK_SHARED],
** <li> [SQLITE_LOCK_RESERVED],
** <li> [SQLITE_LOCK_PENDING], or

** [SQLITE_IOERR_READ | extended result codes] feature.
** By default, SQLite API routines return one of only 26 integer
** [SQLITE_OK | result codes].  When extended result codes
** are enabled by this routine, the repetoire of result codes can be
** much larger and can (hopefully) provide more detailed information
** about the cause of an error.
**
** 
** The second argument is a boolean value that turns extended result
** codes on and off.  Extended result codes are off by default for
** backwards compatibility with older versions of SQLite.
*/
int sqlite3_extended_result_codes(sqlite3*, int onoff);

/*