SQLite

3.5.9

** 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.323 2008/06/09 21:57:23 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++.

** checks to see if the file is readable.
*/
#define SQLITE_ACCESS_EXISTS    0
#define SQLITE_ACCESS_READWRITE 1
#define SQLITE_ACCESS_READ      2

/*
** CAPI3REF: SQLite Configuration Definition {F10180}
**
** A pointer to an instance of the sqlite3_configuration structure
** may be optionally passed into the [sqlite3_initialize()] interface
** in order to set up a custom configuration for the SQLite library.
**
** The xMemInit() routine is called with pMemClientData as an argument
** at [sqlite3_initialize()].  xMemShutdown is called at 


** [sqlite3_shutdown()].
**
** If the xMemSize pointer may be omitted,
** but if it is, then the following SQLite interfaces will not work
** correctly:
**
** <ul>
** <li>   [sqlite3_memory_used()]
** <li>   [sqlite3_memory_highwater()]
** <li>   [sqlite3_soft_heap_limit()]
** </ul>
**
** If xMemSize is defined, then SQLite will hold the
** [SQLITE_MUTEX_STATIC_MEM] mutex will accessing any of xMemAlloc,
** xMemRealloc, or xMemFree.  If xMemSize is NULL then the
** [SQLITE_MUTEX_STATIC_MEM] mutex is never used.
**
** The xPageAlloc and xPageFree functions are alternative memory 
** allocators for page cache pages.  If undefined
** then xMemAlloc and xMemFree will be used.
**
** The xTempAlloc and xTempFree functions are alternative memory
** allocators for short-lived temporary space.
** If undefined then xMemAlloc and xMemFree above will be used.
**
** None of the mutex subsystem fields are ever accessed
** if SQLite is compiled with -DSQLITE_THREADSAFE=0.
**
** The xMutexInit routine is called by each effective [sqlite3_initialize()]
** and xMutexShutdown is called by each valid [sqlite3_shutdown()].
**
** If bSerializeConnection is true then SQLite will use one or more
** [SQLITE_MUTEX_RECURSIVE] mutexes to serialize access to 
** [database connection] and [prepared statement] objects.  If
** bSerializeConnection is false, then it is the application's
** responsibiility to serialize access to these objects.
**
** The xMutexTry interface is an optimization that does not
** come up often and can be omitted.  If omitted, xMutexEnter
** will be used in its place.
**
** The xMutexHeld and xMutexNotHeld interfaces are used for testing
** purposes only.  It is ok for these functions to report false
** positives.  These functions are only used within the argument of
** assert() statements.
*/
typedef struct sqlite3_configuration sqlite3_configuration;
struct sqlite3_configuration {
  /* Memory allocation subsystem interface */
  void *pMemClientData;             /* Argument to xMemInit and xMemShutdown */
  int (*xMemInit)(void*);           /* May be NULL */
  int (*xMemShutdown)(void*);       /* May be NULL */
  void *(*xMemAlloc)(int);
  void *(*xMemRealloc)(void*, int);
  void (*xMemFree)(void*);
  int (*xMemSize)(void*);                /* May be NULL */
  /* Alternative memory allocators for page cache and transient storage */
  void *(*xPageAlloc)(int iSize);        /* May be NULL */
  void (*xPageFree)(void*, int iSize);   /* May be NULL */
  void *(*xTempAlloc)(int iSize);        /* May be NULL */
  void (*xTempFree)(void*);              /* May be NULL */
  /* Parameters optionally used by some alternative memory allocators. */
  sqlite3_int64 nMemHeap;      /* Total memory available for allocating */
  void *pMemHeap;              /* Pointer to memory space to be allocated */
  int mnMemAlloc;              /* Minimum allocation size */
  int mxMemAlloc;              /* Maximum allocation size */
  int nTemp;                   /* Maximum temp space available */
  int mxTemp;                  /* Maximum temp space allocation size */
  /* Mutex methods */
  void *pMutexClientData;            /* Arg to xMutexInit and xMutexShutdown */
  int (*xMutexInit)(void*);          /* May be NULL */
  int (*xMutexShutdown)(void*);      /* May be NULL */
  int bSerializeConnection;
  sqlite3_mutex *(*xMutexAlloc)(int mutexType);
  void (*xMutexFree)(sqlite3_mutex*);
  void (*xMutexEnter)(sqlite3_mutex*);
  int (*xMutexTry)(sqlite3_mutex*);       /* May be NULL */
  void (*xMutexLeave)(sqlite3_mutex*);
  int (*xMutexHeld)(sqlite3_mutex*);      /* May be NULL */
  int (*xMutexNotHeld)(sqlite3_mutex*);   /* May be NULL */
};

/*
** CAPI3REF: Initialize The SQLite Library {F10140}
**
** The sqlite3_initialize() interface is used to initialize the
** SQLite library.  The sqlite3_initialize() routine is only effective
** the first time it is called within a process, or the first time it
** is called after a call to sqlite3_shutdown().  Other SQLite APIs
** might invoke sqlite3_initialize() internally, so in order for
** an application to be sure that its call to sqlite3_initialize()
** is first, it should invoke sqlite3_initialize() prior to invoking any
** other SQLite interface (with the possible exception of
** sqlite3_default_configuration() as described below.)
**
** If the parameter to sqlite3_initialize() is NULL then a default
** configuration is used.  A copy of the default configuration can
** be obtained using the sqlite3_default_configuration() interface.
** An application that only wants to make slight adjustments to the
** configuration can invoke sqlite3_default_configuration() to populate
** an initially empty [sqlite3_configuration] structure, make whatever
** changes to that structure are desired, then invoke sqlite3_initialize()
** to register the new configuration.  
**
** The sqlite3_default_configuration() interface does not invoke 
** sqlite3_initialize() so an application can call
** sqlite3_default_configuration() before sqlite3_initialize() and still
** be assured that its call to sqlite3_initialize() is the first.
** The configuration returned by sqlite3_default_configuration() is
** a compiled-in default.  Changing the configuration using a call
** to sqlite3_initialize() does not change the value returned by
** sqlite3_default_configuration().  The sqlite3_default_configuration()
** interface is threadsafe.
**
** The second parameter to both sqlite3_initialize() and
** sqlite3_default_configuration() should always be the
** SQLITE_VERSION_NUMBER constant.  The content of the
** [sqlite3_configuration] structure may change in future versions of
** SQLite and so the sqlite3_initialize() and 
** sqlite3_default_configuration()) functions need to know the
** version of the header file that defined the [sqlite3_configuration]
** structure in order to use the structure correctly.
**
** The sqlite3_default_configuration() interface returns SQLITE_OK on
** success.  If the iVersion parameter is such that SQLite is unable
** to fill in the [sqlite3_configuration] structure, then the interface
** will return SQLITE_ERROR.
**
** The application must insure that the initial call to sqlite3_initialize()
** is serialized.  This means that multi-threaded applications should invoke
** sqlite3_initialize() in the main thread prior to starting any other
** threads that might use SQLite.  In the general case, SQLite depends on
** the application to serialize access to sqlite3_initialize() because SQLite
** cannot create a mutex to do the serialization itself until after
** sqlite3_initialize() has run.  In the current unix and win32
** implementations, SQLite is able to serialize access to sqlite3_initialize()
** on its own, but this is not true for all embedded platforms and might
** not be true for unix and win32 in future releases.
**
** SQLite makes a copy of the content of the [sqlite3_configuration] structure
** that is passed into sqlite3_initialize().  Hence the application is free
** to deallocate or modify the [sqlite3_configuration] structure after
** sqlite3_initialize() returns.
**
** Once sqlite3_initialize() has been successfully invoked once, all
** subsequent calls to sqlite3_initialize() are ignored until
** sqlite3_shutdown() is run.  After sqlite3_shutdown() has been invoked,
** the next call to sqlite3_initialize() is effective for a single call
** but after that sqlite3_initialize() again becomes a no-up.  In other words,
** a call to sqlite3_initialize() is only effective if it is the first
** invocation for the process or if it is invoked immediately after a
** call to sqlite3_shutdown().
**
** The sqlite3_initialize() routine returns SQLITE_OK on success.
** If sqlite3_initialize() returns any value other than SQLITE_OK then
** the SQLite library is not safe to use.

**
** The sqlite3_shutdown() interface clears a prior initialization and
** enables SQLite to be reinitialized.  The application must insure that
** the sqlite3_shutdown() interface is only called when there are no
** outstanding memory allocations or mutexes, no open database connections,
** and no other SQLite interfaces are being called in different threads.
** If sqlite3_shutdown() is called while there are still outstanding
** memory allocations or mutexes, or open database connections, or while
** another thread is making a call to any SQLite interface, then the
** result is undefined and could be segmentation fault or other
** fatal application error.
**
** As currently implemented, sqlite3_shutdown() always returns SQLITE_OK,
** however this might change in a future release of SQLite.
** 
** The sqlite3_on_shutdown() interface registers a callback to be invoked


** the next time sqlite3_shutdown() is called.  Each callback is invoked
** only once at the next sqlite3_shutdown() call.  Callbacks must be

** reregistered in order to be run on subsequent sqlite3_shutdown() calls.
** Each call to sqlite3_on_shutdown() allocates a little bit of memory
** used to hold the callback function pointer and the corresponding
** application data pointer.  The memory is freed after the callback is
** invoked.  The callbacks registered by sqlite3_on_callback() are invoked
** in the order in which they were registered.  If the same callback is
** registered multiple times, it is invoked multiple times.  All callbacks
** are invoked prior to the xMemShutdown() and xMutexShutdown() methods

** of the sqlite3_configuration structure.
**
** The sqlite3_on_shutdown() interface returns SQLITE_OK on success, or
** SQLITE_NOMEM if it is unable to allocate memory to hold the pointer
** to the callback function and corresponding application data pointer.



*/
int sqlite3_initialize(const sqlite3_configuration*, int iVersion);
int sqlite3_default_configuration(sqlite3_configuration*, int iVersion);
int sqlite3_on_shutdown(void (*)(void*), void*);
int sqlite3_shutdown(void);

































































































/*
** CAPI3REF: Enable Or Disable Extended Result Codes {F12200}
**
** The sqlite3_extended_result_codes() routine enables or disables the
** [SQLITE_IOERR_READ | extended result codes] feature of SQLite.
** The extended result codes are disabled by default for historical

** protected and unprotected sqlite3_value objects and they can be
** used interchangeable.  However, for maximum code portability it
** is recommended that applications make the distinction between
** between protected and unprotected sqlite3_value objects even if
** they are single threaded.
**
** The sqlite3_value objects that are passed as parameters into the
** implementation of application-defined SQL functions are protected.


** The sqlite3_value object returned by
** [sqlite3_column_value()] is unprotected.
** Unprotected sqlite3_value objects may only be used with
** [sqlite3_result_value()] and [sqlite3_bind_value()].  All other

** interfaces that use sqlite3_value require protected sqlite3_value objects.
*/
typedef struct Mem sqlite3_value;

/*
** CAPI3REF:  SQL Function Context Object {F16001}
**
** The context in which an SQL function executes is stored in an
** sqlite3_context object.  A pointer to an sqlite3_context
** object is always first parameter to application-defined SQL functions.








*/
typedef struct sqlite3_context sqlite3_context;

/*
** CAPI3REF:  Binding Values To Prepared Statements {F13500}
**
** In the SQL strings input to [sqlite3_prepare_v2()] and its