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.
**
** @(#) $Id: sqlite.h.in,v 1.222 2007/08/15 11:28:56 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++.

/*
** 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_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: 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
** of 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 {
  struct sqlite3_io_methods *pMethods;  /* Methods against the open file */
};

/*
** CAPI3REF: OS Interface File Virtual Methods Object
**
** Every open file in the [sqlite3_vfs] xOpen method contains a pointer to
** an instance of the following 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_BARRIER,
** SQLITE_SYNC_NORMAL, SQLITE_SYNC_FULL.  The first choice means that
** data is not necessarily synced to disk completely, only that
** all writes that occur before the sync complete before any
** writes that occur after the sync.  The second flag is the
** normal fsync().  The third flag is a 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
** SQLITE_LOCK_NONE, SQLITE_LOCK_READ, SQLITE_LOCK_RESERVED,
** SQLITE_LOCK_PENDING, or SQLITE_LOCK_EXCLUSIVE.  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.
** 
** xBreakLock() attempts to break a lock held by another process.
** This can be used to remove a stale dot-file lock, for example.
** It returns 0 on success and non-zero for a failure.
**
** 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, sqlite_int64 iOfst);
  int (*xWrite)(sqlite3_file*, void*, int iAmt, sqlite_int64 iOfst);
  int (*xTruncate)(sqlite3_file*, sqlite_int64 size);
  int (*xSync)(sqlite3_file*, int flags);
  int (*xFileSize)(sqlite3_file*, sqlite_int64 *pSize);
  int (*xLock)(sqlite3_file*, int);
  int (*xUnlock)(sqlite3_file*, int);
  int (*xCheckReservedLock)(sqlite3_file*);
  int (*xBreakLock)(sqlite3_file*);
  int (*xSectorSize)(sqlite3_file*);
  int (*xDeviceCharacteristics)(sqlite3_file*);
  /* Additional methods may be added in future releases */
};

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

*/
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.  szOsFile is the size of the subclassed sqlite3_file

** structure used by this VFS.  mxPathname is the maximum length of
** a pathname in this VFS.
**
** The nRef field is incremented and decremented by SQLite to keep
** count of the number of users of the VFS.  This field and
** vfsMutex, pNext, and pPrev are the only fields in the sqlite3_vfs 
** structure that SQLite will ever modify.  These fields are modified 
** within an sqlite3_mutex_serialize() call so that updates are threadsafe.
** 
** The sqlite3_vfs.vfsMutex is a mutex used by the OS interface.
** It should initially be NULL.  SQLite will initialize this field
** using sqlite3_mutex_allocate() upon first use of the adaptor
** by sqlite3_open_v2() and will deallocate the mutex when the
** last user closes.  In other words, vfsMutex will be allocated
** when nRef transitions from 0 to 1 and will be deallocated when
** nRef transitions from 1 to 0.
**
** Registered vfs modules are kept on a linked list formed by
** the pNext and pPrev pointers.  The [sqlite3_register_vfs()]
** and [sqlite3_unregister_vfs()] interfaces manage this list
** in a thread-safe way.  The [sqlite3_find_vfs()] searches the
** list.
**
** 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_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:
** 

** if a file is readable and writable, or SQLITE_ACCESS_READONLY
** to test to see if a file is read-only.  The file can be a 
** directory.
** 
** SQLite will always allocate at least mxPathname+1 byte for
** the output buffers for xGetTempName and xFullPathname.
** 
** 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 generated.  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 */
  int nRef;                /* Number of references to this structure */
  sqlite3_mutex *vfsMutex; /* A mutex for this VFS */
  sqlite3_vfs *pNext;      /* Next registered VFS */
  sqlite3_vfs *pPrev;      /* Previous registered VFS */
  const char *zName;       /* Name of this virtual file system */
  void *pAppData;          /* Application context */
  int (*xOpen)(void *pAppData, const char *zName, sqlite3_file*,
               int flags, int *pOutFlags);
  int (*xDelete)(void *pAppData, const char *zName);
  int (*xAccess)(void *pAppData, const char *zName, int flags);
  int (*xGetTempName)(void *pAppData, char *zOut);
  int (*xFullPathname)(void *pAppData, const char *zName, char *zOut);


  void *(*xDlOpen)(void *pAppData, char *zFilename);
  void (*xDlError)(void*, int nByte, char *zErrMsg);
  void *(*xDlSym)(void*, const char *zSymbol);
  void (*xDlclose)(void*);







  int (*xRandomness)(void *pAppData, int nByte, char *zOut);
  int (*xSleep)(void *pAppData, int microseconds);
  int (*xCurrentTime)(void *pAppData, double*);





  /* New fields may be appended in figure versions.  The iVersion
  ** value will increment whenever this happens. */
};

/*
** CAPI3REF: Enable Or Disable Extended Result Codes
**
** This routine enables or disables the

char *sqlite3_mprintf(const char*,...);
char *sqlite3_vmprintf(const char*, va_list);
char *sqlite3_snprintf(int,char*,const char*, ...);

/*
** CAPI3REF: Memory Allocation Functions
**
** The SQLite sources include a memory allocation subsystem
** that implements the interfaces shown here.
**
** The SQLite core uses these three routines for all of its own
** internal memory allocation needs.  The default implementation
** of the memory allocation subsystem uses the malloc(), realloc()
** and free() provided by the standard C library.  However, if 

** SQLite is compiled with the following C preprocessor macro
**
** <blockquote>SQLITE_OMIT_MEMORY_ALLOCATION</blockquote>
**
** then no implementation is provided for these routines by
** SQLite.  The application that links against SQLite is
** expected to provide its own implementation.
*/
void *sqlite3_malloc(int);
void *sqlite3_realloc(void*, int);
void sqlite3_free(void*);

/*
** CAPI3REF: Memory Allocator Statistics
**
** In addition to the basic three allocation routines 
** [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()],
** the memory allocation subsystem included with the SQLite
** sources provides the interfaces shown below.
**
** The first of these two routines returns the amount of memory 
** currently outstanding (malloced but not freed).  The second
** returns the largest instantaneous amount of outstanding
** memory.  The highwater mark is reset if the argument is
** true.  The SQLite core does not use either of these routines
** and so they do not have to be implemented by the application
** if SQLITE_OMIT_MEMORY_ALLOCATION is defined.  These routines
** are provided by the default memory subsystem for diagnostic
** purposes.
*/
sqlite3_uint64 sqlite3_memory_used(void);
sqlite3_uint64 sqlite3_memory_highwater(int resetFlag);

/*
** CAPI3REF: Memory Allocation Alarms
**
** The [sqlite3_memory_alarm] routine is used to register
** a callback on memory allocation events.
**
** This routine registers or clears a callbacks that fires when
** the amount of memory allocated exceeds iThreshold.  Only
** a single callback can be registered at a time.  Each call
** to [sqlite3_memory_alarm()] overwrites the previous callback.
** The callback is disabled by setting xCallback to a NULL
** pointer.
** 
** The parameters to the callback are the pArg value, the 
** amount of memory currently in use, and the size of the
** allocation that provoked the callback.  The callback will
** presumably invoke [sqlite3_free()] to free up memory space.
** The callback may invoke [sqlite3_malloc()] or [sqlite3_realloc()]
** but if it does, no additional callbacks will be invoked by
** the recursive calls.
**
** The [sqlite3_soft_heap_limit()] interface works by registering
** a memory alarm at the soft heap limit and invoking 
** [sqlite3_release_memory()] in the alarm callback.  Application
** programs should not attempt to use the [sqlite3_memory_alarm()]
** interface because doing so will interfere with the
** [sqlite3_soft_heap_limit()] module.
*/
int sqlite3_memory_alarm(
  void(*xCallback)(void *pArg, sqlite3_uint64 used, unsigned int N),
  void *pArg,
  sqlite3_uint64 iThreshold
);


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

** not previously exist, an error is returned.  The second option opens
** the database for reading and writing but the database must already
** exist or an error is returned.  The third option opens the database
** for reading and writing and creates it if it does not already exist.
** The third options is behavior that is used always for sqlite3_open()
** and sqlite3_open16().
**
** The fourth parameter to sqlite3_open_v2() is the name of the
** [sqlite3_vfs] object that defines the operating system 
** interface that the new database connection should use.  If the
** fourth parameter is a NULL pointer then a default suitable for
** the host environment is substituted.
**
** Note to windows users:  The encoding used for the filename argument
** of sqlite3_open() must be UTF-8, not whatever codepage is currently
** defined.  Filenames containing international characters must be converted

  const void *filename,   /* Database filename (UTF-16) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);
int sqlite3_open_v2(
  const void *filename,   /* Database filename (UTF-16) */
  sqlite3 **ppDb,         /* OUT: SQLite db handle */
  int flags,              /* Flags */
  const char *zVfs        /* Name of VFS module to use */
);

/*
** CAPI3REF: Error Codes And Messages
**
** The sqlite3_errcode() interface returns the numeric
** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code]

**
** On success, SQLITE_OK is returned. Otherwise, an 
** [SQLITE_ERROR | SQLite error code] or an
** [SQLITE_IOERR_READ | extended error code] is returned.
*/
int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);

/*
** CAPI3REF:  Virtual File System Objects
**
** A virtual filesystem (VFS) is an [sqlite3_vfs] object
** that SQLite uses to interact
** with the underlying operating system.  Most builds come with a
** single default VFS that is appropriate for the host computer.
** New VFSes can be registered and existing VFSes can be unregistered.
** The following interfaces are provided.
**
** The sqlite3_find_vfs() interface returns a pointer to a VFS given its
** name.  Names are case sensitive.  If there is no match, a NULL
** pointer is returned.  If zVfsName is NULL then the default 
** VFS is returned.
**
** New VFSes are registered with sqlite3_register_vfs().  Each
** new VFS becomes the default VFS if the makeDflt flag is set.
** The same VFS can be registered multiple times without injury.
** To make an existing VFS into the default VFS, register it again
** with the makeDflt flag set.
** 
** Unregister a VFS with the sqlite3_unregister_vfs() interface.
** If the default VFS is unregistered, another VFS is chosen as
** the default.  The choice for the new VFS is arbitrary.
*/
sqlite3_vfs *sqlite3_find_vfs(const char *zVfsName);
int sqlite3_register_vfs(sqlite3_vfs*, int makeDflt);
int sqlite3_unregister_vfs(sqlite3_vfs*);

/*
** CAPI3REF: Mutexes
**
** The SQLite core uses these routines for thread
** synchronization.  Though they are intended for internal
** use by SQLite, code that links against SQLite is
** permitted to use any of these routines.
**
** The SQLite source code contains multiple implementations 
** of these mutex routines that can be selected at compile-time
** by defining one of the following C preprocessor macros:
**
** <ul>
** <li>   SQLITE_MUTEX_PTHREAD
** <li>   SQLITE_MUTEX_WIN32
** <li>   SQLITE_MUTEX_NOOP
** <li>   SQLITE_MUTEX_APPDEF
** </ul>
**
** If none of the above macros is defined, the code uses
** a default implementation.  
** 
** The SQLITE_MUTEX_NOOP implementation is a set of routines 
** that does no real locking and is appropriate for use in 
** a single-threaded application.
** 
** If the SQLITE_MUTEX_APPDEF is defined, then no mutex
** implementation is included with the library.  The
** mutex interface routines defined above are external
** references in the SQLite library for which implementations
** must be provided by the application.
**
** The sqlite3_mutex_alloc() routine allocates a new
** mutex and returns a pointer to it.  If it returns NULL
** that means that a mutex could not be allocated.  SQLite
** will unwind its stack and return an error.  The argument
** to sqlite3_mutex_alloc() is usually zero, which causes
** any space required for the mutex to be obtained from
** sqlite3_malloc().  However if the argument is a positive
** integer less than SQLITE_NUM_STATIC_MUTEX, then a pointer
** to a static mutex is returned.  There are a finite number
** of static mutexes.  Static mutexes should not be passed
** to sqlite3_mutex_free().  Static mutexes are used internally
** by the SQLite core and should not be used by the application.
**
** The sqlite3_mutex_free() routine deallocates a previously
** allocated mutex.  SQLite is careful to deallocate every
** mutex that it allocates.
**
** The sqlite3_mutex_enter() routine attempts to enter a
** mutex.  If another thread is already within the mutex,
** sqlite3_mutex_enter() will return SQLITE_BUSY if blockFlag
** is zero, or it will block and wait for the other thread to
** exit if blockFlag is non-zero.  Mutexes are recursive.  The
** same thread can enter a single mutex multiple times.  Each
** entrance must be matched with a corresponding exit before
** another thread is able to enter the mutex.
**
** The sqlite3_mutex_exit() routine exits a mutex that was
** previously entered by the same thread.  The behavior
** is undefined if the mutex is not currently entered or
** is not currently allocated.  SQLite will never do either.
**
** The sqlite3_mutex_serialize() routine is used to serialize 
** a subroutine.  The subroutine given in the argument is invoked
** while holding a static mutex.  This ensures that no other
** thread is running this same subroutine at the same time.
*/
sqlite3_mutex *sqlite3_mutex_alloc(int);
void sqlite3_mutex_free(sqlite3_mutex*);
int sqlite3_mutex_enter(sqlite3_mutex*, int blockFlag);
void sqlite3_mutex_leave(sqlite3_mutex*);
int sqlite3_mutex_serialize(void(*)(void*), void*);


/*
** Undo the hack that converts floating point types to integer for
** builds on processors without floating point support.
*/
#ifdef SQLITE_OMIT_FLOATING_POINT