/*** 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.  If a C-function, structure, datatype,** or constant definition does not appear in this file, then it is** not a published API of SQLite, is subject to change without** notice, and should not be referenced by programs that use SQLite.**** Some of the definitions that are in this file are marked as** "experimental".  Experimental interfaces are normally new** features recently added to SQLite.  We do not anticipate changes ** to experimental interfaces but reserve to make minor changes if** experience from use "in the wild" suggest such changes are prudent.**** The official C-language API documentation for SQLite is derived** from comments in this file.  This file is the authoritative source** 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.**** @(#) $Id: sqlite.h.in,v 1.284 2008/02/06 14:11:35 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 __cplusplusextern "C" {#endif/*** Add the ability to override 'extern'*/#ifndef SQLITE_EXTERN# define SQLITE_EXTERN extern#endif/*** Make sure these symbols where not defined by some previous header** file.*/#ifdef SQLITE_VERSION# undef SQLITE_VERSION#endif#ifdef SQLITE_VERSION_NUMBER# undef SQLITE_VERSION_NUMBER#endif/*** CAPI3REF: Compile-Time Library Version Numbers {F10010}**** The SQLITE_VERSION and SQLITE_VERSION_NUMBER #defines in** the sqlite3.h file specify the version of SQLite with which** that header file is associated.**** The "version" of SQLite is a strong of the form "X.Y.Z".** The phrase "alpha" or "beta" might be appended after the Z.** The X value is major version number always 3 in SQLite3.** The X value only changes when  backwards compatibility is** broken and we intend to never break** backwards compatibility.  The Y value is the minor version** number and only changes when** there are major feature enhancements that are forwards compatible** but not backwards compatible.  The Z value is release number** and is incremented with** each release but resets back to 0 when Y is incremented.**** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].**** INVARIANTS:**** {F10011} The SQLITE_VERSION #define in the sqlite3.h header file**          evaluates to a string literal that is the SQLite version**          with which the header file is associated.**** {F10014} The SQLITE_VERSION_NUMBER #define resolves to an integer**          with the value  (X*1000000 + Y*1000 + Z) where X, Y, and**          Z are the major version, minor version, and release number.*/#define SQLITE_VERSION         "3.5.6"#define SQLITE_VERSION_NUMBER 3005006/*** CAPI3REF: Run-Time Library Version Numbers {F10020}** KEYWORDS: sqlite3_version**** These features provide the same information as the [SQLITE_VERSION]** and [SQLITE_VERSION_NUMBER] #defines in the header, but are associated** with the library instead of the header file.  Cautious programmers might** include a check in their application to verify that ** sqlite3_libversion_number() always returns the value ** [SQLITE_VERSION_NUMBER].**** The sqlite3_libversion() function returns the same information as is** in the sqlite3_version[] string constant.  The function is provided** for use in DLLs since DLL users usually do not have direct access to string** constants within the DLL.**** INVARIANTS:**** {F10021} The [sqlite3_libversion_number()] interface returns an integer**          equal to [SQLITE_VERSION_NUMBER]. **** {F10022} The [sqlite3_version] string constant contains the text of the**          [SQLITE_VERSION] string. **** {F10023} The [sqlite3_libversion()] function returns**          a pointer to the [sqlite3_version] string constant.*/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 {F10100}**** SQLite can be compiled with or without mutexes.  When** the SQLITE_THREADSAFE C preprocessor macro is true, mutexes** are enabled and SQLite is threadsafe.  When that macro os false,** the mutexes are omitted.  Without the mutexes, it is not safe** to use SQLite from more than one thread.**** There is a measurable performance penalty for enabling mutexes.** So if speed is of utmost importance, it makes sense to disable** the mutexes.  But for maximum safety, mutexes should be enabled.** The default behavior is for mutexes to be enabled.**** This interface can be used by a program to make sure that the** version of SQLite that it is linking against was compiled with** the desired setting of the SQLITE_THREADSAFE macro.**** INVARIANTS:**** {F10101} The [sqlite3_threadsafe()] function returns nonzero if**          SQLite was compiled with its mutexes enabled or zero**          if SQLite was compiled with mutexes disabled.*/int sqlite3_threadsafe(void);/*** CAPI3REF: Database Connection Handle {F12000}** KEYWORDS: {database connection}**** Each open SQLite database is represented by pointer to an instance of the** opaque structure named "sqlite3".  It is useful to think of an sqlite3** pointer as an object.  The [sqlite3_open()], [sqlite3_open16()], and** [sqlite3_open_v2()] interfaces are its constructors** and [sqlite3_close()] is its destructor.  There are many other interfaces** (such as [sqlite3_prepare_v2()], [sqlite3_create_function()], and** [sqlite3_busy_timeout()] to name but three) that are methods on this** object.*/typedef struct sqlite3 sqlite3;/*** CAPI3REF: 64-Bit Integer Types {F10200}** KEYWORDS: sqlite_int64 sqlite_uint64**** Because there is no cross-platform way to specify 64-bit integer types** SQLite includes typedefs for 64-bit signed and unsigned integers.**** The sqlite3_int64 and sqlite3_uint64 are the preferred type** definitions.  The sqlite_int64 and sqlite_uint64 types are** supported for backwards compatibility only.**** INVARIANTS:**** {F10201} The [sqlite_int64] and [sqlite3_int64] types specify a**          64-bit signed integer.**** {F10202} The [sqlite_uint64] and [sqlite3_uint64] types specify**          a 64-bit unsigned integer.*/#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;#endiftypedef sqlite_int64 sqlite3_int64;typedef sqlite_uint64 sqlite3_uint64;/*** If compiling for a processor that lacks floating point support,** substitute integer for floating-point*/#ifdef SQLITE_OMIT_FLOATING_POINT# define double sqlite3_int64#endif/*** CAPI3REF: Closing A Database Connection {F12010}**** This routine is the destructor for the [sqlite3] object.  **** Applications should [sqlite3_finalize | finalize] all** [prepared statements] and** [sqlite3_blob_close | close] all [sqlite3_blob | BLOBs] ** associated with the [sqlite3] object prior** to attempting to close the [sqlite3] object.**** <todo>What happens to pending transactions?  Are they** rolled back, or abandoned?</todo>**** INVARIANTS:**** {F12011} The [sqlite3_close()] interface destroys an [sqlite3] object**          allocated by a prior call to [sqlite3_open()],**          [sqlite3_open16()], or [sqlite3_open_v2()].**** {F12012} The [sqlite3_close()] function releases all memory used by the**          connection and closes all open files.**** {F12013} If the database connection contains**          [prepared statements] that have not been**          finalized by [sqlite3_finalize()], then [sqlite3_close()]**          returns [SQLITE_BUSY] and leaves the connection open.**** {F12014} Giving sqlite3_close() a NULL pointer is a harmless no-op.**** LIMITATIONS:**** {U12015} The parameter to [sqlite3_close()] must be an [sqlite3] object**          pointer previously obtained from [sqlite3_open()] or the **          equivalent, or NULL.**** {U12016} The parameter to [sqlite3_close()] must not have been previously**          closed.*/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 {F12100}**** The sqlite3_exec() interface is a convenient way of running** one or more SQL statements without a lot of C code.  The** SQL statements are passed in as the second parameter to** sqlite3_exec().  The statements are evaluated one by one** until either an error or an interrupt is encountered or** until they are all done.  The 3rd parameter is an optional** callback that is invoked once for each row of any query results** produced by the SQL statements.  The 5th parameter tells where** to write any error messages.**** The sqlite3_exec() interface is implemented in terms of** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].** The sqlite3_exec() routine does nothing that cannot be done** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].** The sqlite3_exec() is just a convenient wrapper.**** INVARIANTS:** ** {F12101} The [sqlite3_exec()] interface evaluates zero or more UTF-8**          encoded, semicolon-separated, SQL statements in the**          zero-terminated string of its 2nd parameter within the**          context of the [sqlite3] object given in the 1st parameter.**** {F12104} The return value of [sqlite3_exec()] is SQLITE_OK if all**          SQL statements run successfully.**** {F12105} The return value of [sqlite3_exec()] is an appropriate **          non-zero error code if any SQL statement fails.**** {F12107} If one or more of the SQL statements handed to [sqlite3_exec()]**          return results and the 3rd parameter is not NULL, then**          the callback function specified by the 3rd parameter is**          invoked once for each row of result.**** {F12110} If the callback returns a non-zero value then [sqlite3_exec()]**          will aborted the SQL statement it is currently evaluating,**          skip all subsequent SQL statements, and return [SQLITE_ABORT].**          <todo>What happens to *errmsg here?  Does the result code for**          sqlite3_errcode() get set?</todo>**