/*

** 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$

*/

#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

/*

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

**

** The version of the SQLite library is contained in the sqlite3.h

** header file in a #define named SQLITE_VERSION.  The SQLITE_VERSION

** macro resolves to a string constant.

**

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

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

** is the release number.  The X.Y.Z might be followed by "alpha" or "beta".

** For example "3.1.1beta".

**

** 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.

**

** The SQLITE_VERSION_NUMBER is an integer with the value 

** (X*1000000 + 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).

**

** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].

*/

#define SQLITE_VERSION         "3.4.1"

#define SQLITE_VERSION_NUMBER 3004001

/*

** CAPI3REF: Run-Time Library Version Numbers

**

** These routines return values equivalent to the header constants

** [SQLITE_VERSION] and [SQLITE_VERSION_NUMBER].  The values returned

** by this routines should only be different from the header values

** if you compile your program using an sqlite3.h header from a

** different version of SQLite that the version of the library you

** link against.

**

** The sqlite3_version[] string constant contains the text of the

** [SQLITE_VERSION] string.  The sqlite3_libversion() function returns

** a poiner to the sqlite3_version[] string constant.  The function

** is provided for DLL users who can only access functions and not

** constants within the DLL.

*/

extern const char sqlite3_version[];

const char *sqlite3_libversion(void);

int sqlite3_libversion_number(void);

/*

** CAPI3REF: Database Connection Handle

**

** 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] interface is its constructor

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

**

** 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.

*/

#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

/*

** CAPI3REF: Closing A Database Connection

**

** 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_v2()] or

** [sqlite3_prepare16_v2()] must be destroyed using [sqlite3_finalize()]

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

** database connection remains open.

*/

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

**

** This interface is used to do a one-time evaluatation of zero

** or more SQL statements.  UTF-8 text of the SQL statements to

** be evaluted is passed in as the second parameter.  The statements

** are prepared one by one using [sqlite3_prepare()], evaluated

** using [sqlite3_step()], then destroyed using [sqlite3_finalize()].

**

** 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 to this interface is an arbitrary pointer that is

** passed through 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

** as extracted using [sqlite3_column_text()].

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

** obtained using [sqlite3_column_name()] and 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 [sqlite3_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 [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

** 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()]

** API can be used to set a database connectoin to return more detailed

** result codes.

**

** See also: [SQLITE_IOERR_READ | extended result codes]

**

*/

#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   /* NOT USED. Database lock protocol error */

#define SQLITE_EMPTY       16   /* Database is empty */

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

#define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */

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

/*

** CAPI3REF: Extended Result Codes

**

** 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 above.

** 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.

** The numeric value of an extended result code can be converted to its

** corresponding primary result code by masking off the lower 8 bytes.

**

** The SQLITE_OK result code will never be extended.  It will always

** be exactly zero.

*/

#define SQLITE_IOERR_READ          (SQLITE_IOERR | (1<<8))

#define SQLITE_IOERR_SHORT_READ    (SQLITE_IOERR | (2<<8))

#define SQLITE_IOERR_WRITE         (SQLITE_IOERR | (3<<8))

#define SQLITE_IOERR_FSYNC         (SQLITE_IOERR | (4<<8))

#define SQLITE_IOERR_DIR_FSYNC     (SQLITE_IOERR | (5<<8))

#define SQLITE_IOERR_TRUNCATE      (SQLITE_IOERR | (6<<8))

#define SQLITE_IOERR_FSTAT         (SQLITE_IOERR | (7<<8))

#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))

/*

** CAPI3REF: Enable Or Disable Extended Result Codes

**

** This routine enables or disables the

** [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);

/*

** CAPI3REF: Last Insert Rowid

**

** Each entry in an SQLite table has a unique 64-bit signed integer key

** called the "rowid". The rowid is always available as an undeclared

** column named ROWID, OID, or _ROWID_.  If the table has a column of

** type INTEGER PRIMARY KEY then that column is another an alias for the

** rowid.

**

** This routine returns the rowid of the most recent INSERT into

** the database from the database connection given in the first 

** argument.  If no inserts have ever occurred on this database

** connection, zero is returned.

**

** If an INSERT occurs within a trigger, then the rowid of the

** inserted row is returned by this routine as long as the trigger

** is running.  But once the trigger terminates, the value returned

** by this routine reverts to the last value inserted before the

** trigger fired.

*/

sqlite_int64 sqlite3_last_insert_rowid(sqlite3*);

/*

** CAPI3REF: Count The Number Of Rows Modified

**

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

** (or inserted or deleted) by the most recent SQL statement.  Only

** changes that are directly specified by the INSERT, UPDATE, or

** DELETE statement are counted.  Auxiliary changes caused by

** triggers are not counted.  Use the [sqlite3_total_changes()] function

** to find the total number of changes including changes caused by triggers.

**

** Within the body of a trigger, the sqlite3_changes() interface can be

** called to find the number of

** changes in the most recently completed INSERT, UPDATE, or DELETE

** statement within the body of the trigger.

**

** 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()] or [sqlite3_step()] 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 from 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_changes(sqlite3*);

/*

** CAPI3REF: Total Number Of Rows Modified

***

** 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()]).

**

** See also the [sqlite3_change()] interface.

**

** 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*);

/*

** CAPI3REF: Interrupt A Long-Running Query

**

** 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.

**

** It is safe to call this routine from a thread different from the

** thread that is currently running the database operation.

**

** The SQL operation that is interrupted will return [SQLITE_INTERRUPT].

** If an interrupted operation was an update that is inside an

** explicit transaction, then the entire transaction will be rolled

** back automatically.

*/

void sqlite3_interrupt(sqlite3*);

/*

** CAPI3REF: Determine If An SQL Statement Is Complete

**

** 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.

**

** These routines are useful for command-line input to determine if the

** currently entered text forms one or more complete SQL statements or

** if additional input is needed before sending the statements into

** SQLite for parsing. The algorithm is simple.  If the 

** last token other than spaces and comments is a semicolon, then return 

** true.  Actually, the algorithm is a little more complicated than that

** in order to deal with triggers, but the basic idea is the same:  the

** statement is not complete unless it ends in a semicolon.

*/

int sqlite3_complete(const char *sql);

int sqlite3_complete16(const void *sql);

/*

** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors

**

** This routine identifies a callback function that might be invoked

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

** that another thread or process has locked.

** If the busy callback is NULL, then [SQLITE_BUSY]

** (or sometimes [SQLITE_IOERR_BLOCKED])

** is returned immediately upon encountering the lock.

** If the busy callback is not NULL, then the

** callback will be invoked with two arguments.  The

** first argument to the handler is a copy of the void* pointer which

** is the third argument to this routine.  The second argument to

** the handler is the number of times that the busy handler has

** been invoked for this locking event. If the

** busy callback returns 0, then no additional attempts are made to

** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.

** If the callback returns non-zero, then another attempt is made to open the

** database for reading and the cycle repeats.

**

** The presence of a busy handler does not guarantee that

** it will be invoked when there is lock contention.

** If SQLite determines that invoking the busy handler could result in

** a deadlock, it will return [SQLITE_BUSY] instead.

** Consider a scenario where one process is holding a read lock that

** it is trying to promote to a reserved lock and

** a second process is holding a reserved lock that it is trying

** to promote to an exclusive lock.  The first process cannot proceed

** because it is blocked by the second and the second process cannot

** proceed because it is blocked by the first.  If both processes

** invoke the busy handlers, neither will make any progress.  Therefore,

** SQLite returns [SQLITE_BUSY] for the first process, hoping that this

** will induce the first process to release its read lock and allow

** the second process to proceed.

**

** The default busy callback is NULL.

**

** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED] when

** SQLite is in the middle of a large transaction where all the

** changes will not fit into the in-memory cache.  SQLite will

** already hold a RESERVED lock on the database file, but it needs

** to promote this lock to EXCLUSIVE so that it can spill cache

** pages into the database file without harm to concurrent

** readers.  If it is unable to promote the lock, then the in-memory

** cache will be left in an inconsistent state and so the error

** code is promoted from the relatively benign [SQLITE_BUSY] to

** the more severe [SQLITE_IOERR_BLOCKED].  This error code promotion

** forces an automatic rollback of the changes. See the

** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">

** CorruptionFollowingBusyError</a> wiki page for a discussion of why

** this is important.

**	

** 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 segmentation fault or other runtime error.

**

** There can only be a single busy handler defined for each database

** connection.  Setting a new busy handler clears any previous one.

** Note that calling [sqlite3_busy_timeout()] will also set or clear

** the busy handler.

*/

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

/*

** CAPI3REF: Set A Busy Timeout

**

** 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" milliseconds of sleeping have been done.  After

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

** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].

**

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

** turns off all busy handlers.

**

** There can only be a single busy handler for a particular database

** connection.  If another busy handler was defined  

** (using [sqlite3_busy_handler()]) prior to calling

** this routine, that other busy handler is cleared.

*/

int sqlite3_busy_timeout(sqlite3*, int ms);

/*

** CAPI3REF: Convenience Routines For Running Queries

**

** This next routine is a convenience 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 [sqlite3_malloc()], then returns all of the result after the

** query has finished. 

**

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

**

** <pre>

**        Name        | Age

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

**        Alice       | 43

**        Bob         | 28

**        Cindy       | 21

** </pre>

**

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

** azResult will contain the following data:

**

** <pre>

**        azResult[0] = "Name";

**        azResult[1] = "Age";

**        azResult[2] = "Alice";

**        azResult[3] = "43";

**        azResult[4] = "Bob";

**        azResult[5] = "28";

**        azResult[6] = "Cindy";

**        azResult[7] = "21";

** </pre>

**

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

** [sqlite3_malloc()] happens, the calling function must not try to call 

** [sqlite3_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 */

);

void sqlite3_free_table(char **result);

/*

** CAPI3REF: Formatted String Printing Functions

**

** These routines are workalikes of the "printf()" family of functions

** from the standard C library.

**

** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their

** results into memory obtained from [sqlite_malloc()].

** The strings returned by these two routines should be

** released by [sqlite3_free()].  Both routines return a

** NULL pointer if [sqlite3_malloc()] is unable to allocate enough

** memory to hold the resulting string.

**

** In sqlite3_snprintf() routine is similar to "snprintf()" from

** the standard C library.  The result is written into the

** buffer supplied as the second parameter whose size is given by

** the first parameter.  Note that the order of the

** first two parameters is reversed from snprintf().  This is an

** historical accident that cannot be fixed without breaking

** backwards compatibility.  Note also that sqlite3_snprintf()

** returns a pointer to its buffer instead of the number of

** characters actually written into the buffer.  We admit that

** the number of characters written would be a more useful return

** value but we cannot change the implementation of sqlite3_snprintf()

** now without breaking compatibility.

**

** As long as the buffer size is greater than zero, sqlite3_snprintf()

** guarantees that the buffer is always zero-terminated.  The first

** parameter "n" is the total size of the buffer, including space for

** the zero terminator.  So the longest string that can be completely

** written will be n-1 characters.

**

** These routines all implement some additional formatting

** options that are useful for constructing SQL statements.

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

** is are "%q" and "%Q" options.

**

** The %q option 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:

**

** <blockquote><pre>

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

** </pre></blockquote>

**

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

**

** <blockquote><pre>

**  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);

**  sqlite3_exec(db, zSQL, 0, 0, 0);

**  sqlite3_free(zSQL);

** </pre></blockquote>

**

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

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

**

** <blockquote><pre>

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

** </pre></blockquote>

**

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

** would have looked like this:

**

** <blockquote><pre>

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

** </pre></blockquote>

**

** 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.

**

** The %Q option works like %q except it also adds single quotes around

** the outside of the total string.  Or if the parameter in the argument

** list is a NULL pointer, %Q substitutes the text "NULL" (without single

** quotes) in place of the %Q option.  So, for example, one could say:

**

** <blockquote><pre>

**  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);

**  sqlite3_exec(db, zSQL, 0, 0, 0);

**  sqlite3_free(zSQL);

** </pre></blockquote>

**

** The code above will render a correct SQL statement in the zSQL

** variable even if the zText variable is a NULL pointer.

*/

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

char *sqlite3_vmprintf(const char*, va_list);

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

/*

** CAPI3REF: Memory Allocation Functions

**

** SQLite uses its own memory allocator.  On some 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*);

/*

** CAPI3REF: Compile-Time Authorization Callbacks

***

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

** The authorizer callback is invoked as SQL statements are being compiled

** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],

** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()].  At various

** points during the compilation process, as logic is being created

** to perform various actions, the authorizer callback is invoked to

** see if those actions are allowed.  The authorizer callback should

** return SQLITE_OK to allow the action, [SQLITE_IGNORE] to disallow the

** specific action but allow the SQL statement to continue to be

** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be

** rejected with an error.  

**

** Depending on the action, the [SQLITE_IGNORE] and [SQLITE_DENY] return

** codes might mean something different or they might mean the same

** thing.  If the action is, for example, to perform a delete opertion,

** then [SQLITE_IGNORE] and [SQLITE_DENY] both cause the statement compilation

** to fail with an error.  But if the action is to read a specific column

** from a specific table, then [SQLITE_DENY] will cause the entire

** statement to fail but [SQLITE_IGNORE] will cause a NULL value to be

** read instead of the actual column value.

**

** The first parameter to the authorizer callback is a copy of

** the third parameter to the sqlite3_set_authorizer() interface.

** The second parameter to the callback is an integer 

** [SQLITE_COPY | action code] that specifies the particular action

** to be authorized.  The available action codes are

** [SQLITE_COPY | documented separately].  The third through sixth

** parameters to the callback are strings that contain additional

** details about the action to be authorized.

**

** An authorizer is used when preparing SQL statements from an untrusted

** source, to ensure that the SQL statements do not try to access data

** that they are not allowed to see, or that they do not try to

** execute malicious statements that damage the database.  For

** example, an application may allow a user to enter arbitrary

** SQL queries for evaluation by a database.  But the application does

** not want the user to be able to make arbitrary changes to the

** database.  An authorizer could then be put in place while the

** user-entered SQL is being prepared that disallows everything

** except SELECT statements.  

**

** Only a single authorizer can be in place on a database connection

** at a time.  Each call to sqlite3_set_authorizer overrides the

** previous call.  A NULL authorizer means that no authorization

** callback is invoked.  The default authorizer is NULL.

**

** Note that the authorizer callback is invoked only during 

** [sqlite3_prepare()] or its variants.  Authorization is not

** performed during statement evaluation in [sqlite3_step()].

*/

int sqlite3_set_authorizer(

  sqlite3*,

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

  void *pUserData

);

/*

** CAPI3REF: Authorizer Return Codes

**

** The [sqlite3_set_authorizer | authorizer callback function] must

** return either [SQLITE_OK] or one of these two constants in order

** to signal SQLite whether or not the action is permitted.  See the

** [sqlite3_set_authorizer | authorizer documentation] for additional

** information.

*/

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

/*

** CAPI3REF: Authorizer Action Codes

**

** The [sqlite3_set_authorizer()] interface registers a callback function

** that is invoked to authorizer certain SQL statement actions.  The

** second parameter to the callback is an integer code that specifies

** what action is being authorized.  These are the integer action codes that

** the authorizer callback may be passed.

**

** These action code values signify what kind of operation is to be 

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

** function will be parameters or NULL depending on which of these

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

** authorizer callback is the name of the database ("main", "temp", 

** etc.) if applicable.  The 6th parameter to the authorizer callback

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

** top-level SQL code.

*/

/******************************************* 3rd ************ 4th ***********/

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

#define SQLITE_COPY                  0   /* No longer used */

/*

** CAPI3REF: Tracing And Profiling Functions

**

** These routines register callback functions that can be used for

** tracing and profiling the execution of SQL statements.

** The callback function registered by sqlite3_trace() is invoked

** at the first [sqlite3_step()] for the evaluation of an SQL statement.

** The callback function registered by sqlite3_profile() is invoked

** as each SQL statement finishes 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*);