/*

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

/*

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

**

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

#define SQLITE_VERSION_NUMBER 3005001

/*

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

*/

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

**

** This routine returns TRUE (nonzero) if SQLite was compiled with

** all of its mutexes enabled and is thus threadsafe.  It returns

** zero if the particular build is for single-threaded operation

** only.

**

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

**

** This is an experimental API and may go away or change in future

** releases.

*/

int sqlite3_threadsafe(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()], [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

**

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

typedef 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

**

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

** returned from [sqlite3_open()], [sqlite3_open16()], or

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

**

** Passing this routine a database connection that has already been

** closed results in undefined behavior.  If other interfaces that

** reference the same database connection are pending (either in the

** same thread or in different threads) when this routine is called,

** then the behavior is undefined and is almost certainly undesirable.

*/

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 using [sqlite3_free()].

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

#define SQLITE_IOERR_NOMEM         (SQLITE_IOERR | (12<<8))

/*

** CAPI3REF: Flags For File Open Operations

**

** 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_READONLY         0x00000001

#define SQLITE_OPEN_READWRITE        0x00000002

#define SQLITE_OPEN_CREATE           0x00000004

#define SQLITE_OPEN_DELETEONCLOSE    0x00000008

#define SQLITE_OPEN_EXCLUSIVE        0x00000010

#define SQLITE_OPEN_MAIN_DB          0x00000100

#define SQLITE_OPEN_TEMP_DB          0x00000200

#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

**

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

**

** The SQLITE_IOCAP_ATOMIC property means that all writes of

** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values

** mean that writes of blocks that are nnn bytes in size and

** are aligned to an address which is an integer multiple of

** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means

** that when data is appended to a file, the data is appended

** first then the size of the file is extended, never the other

** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that

** information is written to disk in the same order as calls

** to xWrite().

*/

#define SQLITE_IOCAP_ATOMIC          0x00000001

#define SQLITE_IOCAP_ATOMIC512       0x00000002

#define SQLITE_IOCAP_ATOMIC1K        0x00000004

#define SQLITE_IOCAP_ATOMIC2K        0x00000008

#define SQLITE_IOCAP_ATOMIC4K        0x00000010

#define SQLITE_IOCAP_ATOMIC8K        0x00000020

#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

**

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

**

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

**

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

**

** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to

** an instance of the this object.  This object defines the

** methods used to perform various operations against the open file.

**

** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or

** [SQLITE_SYNC_FULL].  The first choice is the normal fsync().

*  The second choice is an

** OS-X style fullsync.  The SQLITE_SYNC_DATA flag may be ORed in to

** indicate that only the data of the file and not its inode needs to be

** synced.

** 

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

** <li> [SQLITE_LOCK_EXCLUSIVE].

** </ul>

** xLock() increases the lock. xUnlock() decreases the lock.  

** The xCheckReservedLock() method looks

** to see if any database connection, either in this

** process or in some other process, is holding an RESERVED,

** PENDING, or EXCLUSIVE lock on the file.  It returns true

** if such a lock exists and false if not.

** 

** The xFileControl() method is a generic interface that allows custom

** VFS implementations to directly control an open file using the

** [sqlite3_file_control()] interface.  The second "op" argument

** is an integer opcode.   The third

** argument is a generic pointer which is intended to be a pointer

** to a structure that may contain arguments or space in which to

** write return values.  Potential uses for xFileControl() might be

** functions to enable blocking locks with timeouts, to change the

** locking strategy (for example to use dot-file locks), to inquire

** about the status of a lock, or to break stale locks.  The SQLite

** core reserves opcodes less than 100 for its own use. 

** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.

** Applications that define a custom xFileControl method should use opcodes 

** greater than 100 to avoid conflicts.

**

** The xSectorSize() method returns the sector size of the

** device that underlies the file.  The sector size is the

** minimum write that can be performed without disturbing

** other bytes in the file.  The xDeviceCharacteristics()

** method returns a bit vector describing behaviors of the

** underlying device:

**

** <ul>

** <li> [SQLITE_IOCAP_ATOMIC]

** <li> [SQLITE_IOCAP_ATOMIC512]

** <li> [SQLITE_IOCAP_ATOMIC1K]

** <li> [SQLITE_IOCAP_ATOMIC2K]

** <li> [SQLITE_IOCAP_ATOMIC4K]

** <li> [SQLITE_IOCAP_ATOMIC8K]

** <li> [SQLITE_IOCAP_ATOMIC16K]

** <li> [SQLITE_IOCAP_ATOMIC32K]

** <li> [SQLITE_IOCAP_ATOMIC64K]

** <li> [SQLITE_IOCAP_SAFE_APPEND]

** <li> [SQLITE_IOCAP_SEQUENTIAL]

** </ul>

**

** The SQLITE_IOCAP_ATOMIC property means that all writes of

** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values

** mean that writes of blocks that are nnn bytes in size and

** are aligned to an address which is an integer multiple of

** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means

** that when data is appended to a file, the data is appended

** first then the size of the file is extended, never the other

** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that

** information is written to disk in the same order as calls

** to xWrite().

*/

typedef struct sqlite3_io_methods sqlite3_io_methods;

struct sqlite3_io_methods {

  int iVersion;

  int (*xClose)(sqlite3_file*);

  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);

  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);

  int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);

  int (*xSync)(sqlite3_file*, int flags);

  int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);

  int (*xLock)(sqlite3_file*, int);

  int (*xUnlock)(sqlite3_file*, int);

  int (*xCheckReservedLock)(sqlite3_file*);

  int (*xFileControl)(sqlite3_file*, int op, void *pArg);

  int (*xSectorSize)(sqlite3_file*);

  int (*xDeviceCharacteristics)(sqlite3_file*);

  /* Additional methods may be added in future releases */

};

/*

** CAPI3REF: Standard File Control Opcodes

**

** These integer constants are opcodes for the xFileControl method

** of the [sqlite3_io_methods] object and to the [sqlite3_file_control()]

** interface.

**

** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging.  This

** opcode cases the xFileControl method to write the current state of

** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],

** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])

** into an integer that the pArg argument points to.  This capability

** is used during testing and only needs to be supported when SQLITE_TEST

** is defined.

*/

#define SQLITE_FCNTL_LOCKSTATE        1

/*

** CAPI3REF: Mutex Handle

**

** The mutex module within SQLite defines [sqlite3_mutex] to be an

** abstract type for a mutex object.  The SQLite core never looks

** at the internal representation of an [sqlite3_mutex].  It only

** deals with pointers to the [sqlite3_mutex] object.

**

** Mutexes are created using [sqlite3_mutex_alloc()].

*/

typedef struct sqlite3_mutex sqlite3_mutex;

/*

** CAPI3REF: OS Interface Object

**

** An instance of this object defines the interface between the

** SQLite core and the underlying operating system.  The "vfs"

** in the name of the object stands for "virtual file system".

**

** The iVersion field is initially 1 but may be larger for future

** versions of SQLite.  Additional fields may be appended to this

** object when the iVersion value is increased.

**

** The szOsFile field is the size of the subclassed [sqlite3_file]

** structure used by this VFS.  mxPathname is the maximum length of

** a pathname in this VFS.

**

** Registered vfs modules are kept on a linked list formed by

** the pNext pointer.  The [sqlite3_vfs_register()]

** and [sqlite3_vfs_unregister()] interfaces manage this list

** in a thread-safe way.  The [sqlite3_vfs_find()] interface

** searches the list.

**

** The pNext field is the only fields in the sqlite3_vfs 

** structure that SQLite will ever modify.  SQLite will only access

** or modify this field while holding a particular static mutex.

** The application should never modify anything within the sqlite3_vfs

** object once the object has been registered.

**

** The zName field holds the name of the VFS module.  The name must

** be unique across all VFS modules.

**

** SQLite will guarantee that the zFilename string passed to

** xOpen() is a full pathname as generated by xFullPathname() and

** that the string will be valid and unchanged until xClose() is

** called.  So the [sqlite3_file] can store a pointer to the

** filename if it needs to remember the filename for some reason.

**

** The flags argument to xOpen() is a copy of the flags argument

** to [sqlite3_open_v2()].  If [sqlite3_open()] or [sqlite3_open16()]

** is used, then flags is [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].

** If xOpen() opens a file read-only then it sets *pOutFlags to

** include [SQLITE_OPEN_READONLY].  Other bits in *pOutFlags may be

** set.

** 

** SQLite will also add one of the following flags to the xOpen()

** call, depending on the object being opened:

** 

** <ul>

** <li>  [SQLITE_OPEN_MAIN_DB]

** <li>  [SQLITE_OPEN_MAIN_JOURNAL]

** <li>  [SQLITE_OPEN_TEMP_DB]

** <li>  [SQLITE_OPEN_TEMP_JOURNAL]

** <li>  [SQLITE_OPEN_TRANSIENT_DB]

** <li>  [SQLITE_OPEN_SUBJOURNAL]

** <li>  [SQLITE_OPEN_MASTER_JOURNAL]

** </ul>

**

** The file I/O implementation can use the object type flags to

** changes the way it deals with files.  For example, an application

** that does not care about crash recovery or rollback, might make

** the open of a journal file a no-op.  Writes to this journal are

** also a no-op.  Any attempt to read the journal return SQLITE_IOERR.

** Or the implementation might recognize the a database file will

** be doing page-aligned sector reads and writes in a random order

** and set up its I/O subsystem accordingly.

** 

** SQLite might also add one of the following flags to the xOpen

** method:

** 

** <ul>

** <li> [SQLITE_OPEN_DELETEONCLOSE]

** <li> [SQLITE_OPEN_EXCLUSIVE]

** </ul>

** 

** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be

** deleted when it is closed.  This will always be set for TEMP 

** databases and journals and for subjournals.  The 

** [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened

** for exclusive access.  This flag is set for all files except

** for the main database file.

** 

** Space to hold the  [sqlite3_file] structure passed as the third 

** argument to xOpen is allocated by caller (the SQLite core). 

** szOsFile bytes are allocated for this object.  The xOpen method

** fills in the allocated space.

** 

** The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] 

** to test for the existance of a file,

** or [SQLITE_ACCESS_READWRITE] to test to see

** if a file is readable and writable, or [SQLITE_ACCESS_READ]

** to test to see if a file is at least readable.  The file can be a 

** directory.

** 

** SQLite will always allocate at least mxPathname+1 byte for

** the output buffers for xGetTempname and xFullPathname. The exact

** size of the output buffer is also passed as a parameter to both 

** methods. If the output buffer is not large enough, SQLITE_CANTOPEN

** should be returned. As this is handled as a fatal error by SQLite,

** vfs implementations should endevour to prevent this by setting 

** mxPathname to a sufficiently large value.

** 

** The xRandomness(), xSleep(), and xCurrentTime() interfaces

** are not strictly a part of the filesystem, but they are

** included in the VFS structure for completeness.

** The xRandomness() function attempts to return nBytes bytes

** of good-quality randomness into zOut.  The return value is

** the actual number of bytes of randomness obtained.  The

** xSleep() method cause the calling thread to sleep for at

** least the number of microseconds given.  The xCurrentTime()

** method returns a Julian Day Number for the current date and

** time.

*/

typedef struct sqlite3_vfs sqlite3_vfs;

struct sqlite3_vfs {

  int iVersion;            /* Structure version number */

  int szOsFile;            /* Size of subclassed sqlite3_file */

  int mxPathname;          /* Maximum file pathname length */

  sqlite3_vfs *pNext;      /* Next registered VFS */

  const char *zName;       /* Name of this virtual file system */

  void *pAppData;          /* Pointer to application-specific data */

  int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,

               int flags, int *pOutFlags);

  int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);

  int (*xAccess)(sqlite3_vfs*, const char *zName, int flags);

  int (*xGetTempname)(sqlite3_vfs*, int nOut, char *zOut);

  int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);

  void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);

  void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);

  void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol);

  void (*xDlClose)(sqlite3_vfs*, void*);

  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);

  int (*xSleep)(sqlite3_vfs*, int microseconds);

  int (*xCurrentTime)(sqlite3_vfs*, double*);

  /* New fields may be appended in figure versions.  The iVersion

  ** value will increment whenever this happens. */

};

/*

** CAPI3REF: Flags for the xAccess VFS method

**

** These integer constants can be used as the third parameter to

** the xAccess method of an [sqlite3_vfs] object.  They determine

** the kind of what kind of permissions the xAccess method is

** looking for.  With SQLITE_ACCESS_EXISTS, the xAccess method

** simply checks to see if the file exists.  With SQLITE_ACCESS_READWRITE,

** the xAccess method checks to see if the file is both readable

** and writable.  With SQLITE_ACCESS_READ the xAccess method

** checks to see if the file is readable.

*/

#define SQLITE_ACCESS_EXISTS    0

#define SQLITE_ACCESS_READWRITE 1

#define SQLITE_ACCESS_READ      2

/*

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

**

** If another thread does a new insert on the same database connection

** while this routine is running and thus changes the last insert rowid,

** then the return value of this routine is undefined.

*/

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

**

** If another thread makes changes on the same database connection

** while this routine is running then the return value of this routine

** is undefined.

*/

int sqlite3_changes(sqlite3*);

/*