src/sqlite.h.in

/*
** 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.
**
** @(#) $Id: sqlite.h.in,v 1.80 2004/05/26 06:18:38 danielk1977 Exp $
*/
#ifndef _SQLITE_H_
#define _SQLITE_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

/*
** The version of the SQLite library.
*/
#define SQLITE_VERSION         "--VERS--"

/*
** The version string is also compiled into the library so that a program
** can check to make sure that the lib*.a file and the *.h file are from
** the same version.
*/
extern const char sqlite3_version[];

/*
** The SQLITE_UTF8 macro is defined if the library expects to see
** UTF-8 encoded data.  The SQLITE_ISO8859 macro is defined if the
** iso8859 encoded should be used.
*/
#define SQLITE_--ENCODING-- 1

/*
** The following constant holds one of two strings, "UTF-8" or "iso8859",
** depending on which character encoding the SQLite library expects to
** see.  The character encoding makes a difference for the LIKE and GLOB
** operators and for the LENGTH() and SUBSTR() functions.
*/
extern const char sqlite3_encoding[];

/*
** Each open sqlite database is represented by an instance of the
** following opaque structure.
*/
typedef struct sqlite sqlite;
typedef struct sqlite sqlite3;


/*
** A function to close the database.
**
** Call this function with a pointer to a structure that was previously
** returned from sqlite3_open() and the corresponding database will by closed.
*/
void sqlite3_close(sqlite *);

/*
** The type for a callback function.
*/
typedef int (*sqlite_callback)(void*,int,char**, char**);

/*
** A function to executes one or more statements of SQL.
**
** 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 is an arbitrary pointer that is passed
** 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.
** The 4th parameter to the callback is an array of strings 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 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_freemem() 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 return code if there is an error.  The particular
** return value depends on the type of error. 
**
** If the query could not be executed because a database file is
** locked or busy, then this function returns SQLITE_BUSY.  (This
** behavior can be modified somewhat using the sqlite3_busy_handler()
** and sqlite3_busy_timeout() functions below.)
*/
int sqlite3_exec(
  sqlite*,                      /* An open database */
  const char *sql,              /* SQL to be executed */
  sqlite_callback,              /* Callback function */
  void *,                       /* 1st argument to callback function */
  char **errmsg                 /* Error msg written here */
);

/*
** Return values for sqlite3_exec() and sqlite3_step()
*/
#define SQLITE_OK           0   /* Successful result */
#define SQLITE_ERROR        1   /* SQL error or missing database */
#define SQLITE_INTERNAL     2   /* An 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   /* (Internal Only) 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   /* Database lock protocol error */
#define SQLITE_EMPTY       16   /* Database is empty */
#define SQLITE_SCHEMA      17   /* The database schema changed */
#define SQLITE_TOOBIG      18   /* Too much data for one row of a table */
#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 */

/*
** Each entry in an SQLite table has a unique integer key.  (The key is
** the value of the INTEGER PRIMARY KEY column if there is such a column,
** otherwise the key is generated at random.  The unique key is always
** available as the ROWID, OID, or _ROWID_ column.)  The following routine
** returns the integer key of the most recent insert in the database.
**
** This function is similar to the mysql_insert_id() function from MySQL.
*/
int sqlite3_last_insert_rowid(sqlite*);

/*
** This function returns the number of database rows that were changed
** (or inserted or deleted) by the most recent called sqlite3_exec().
**
** 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() 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 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_changes(sqlite*);

/*
** This function returns the number of database rows that were changed
** by the last INSERT, UPDATE, or DELETE statment executed by sqlite3_exec(),
** or by the last VM to run to completion. The change count is not updated
** by SQL statements other than INSERT, UPDATE or DELETE.
**
** Changes are counted, even if they are later undone by a ROLLBACK or
** ABORT. Changes associated with trigger programs that execute as a
** result of the INSERT, UPDATE, or DELETE statement are not counted.
**
** If a callback invokes sqlite3_exec() 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 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.
**
******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
*/
int sqlite3_last_statement_changes(sqlite*);

/* If the parameter to this routine is one of the return value constants
** defined above, then this routine returns a constant text string which
** descripts (in English) the meaning of the return value.
*/
const char *sqlite3_error_string(int);
#define sqliteErrStr sqlite3_error_string  /* Legacy. Do not use in new code. */

/* 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.
*/
void sqlite3_interrupt(sqlite*);


/* This function returns true if the given input string comprises
** one or more complete SQL statements.
**
** The algorithm is simple.  If the last token other than spaces
** and comments is a semicolon, then return true.  otherwise return
** false.
*/
int sqlite3_complete(const char *sql);

/*
** This routine identifies a callback function that is invoked
** whenever an attempt is made to open a database table that is
** currently locked by another process or thread.  If the busy callback
** is NULL, then sqlite3_exec() returns SQLITE_BUSY immediately if
** it finds a locked table.  If the busy callback is not NULL, then
** sqlite3_exec() invokes the callback with three arguments.  The
** second argument is the name of the locked table and the third
** argument is the number of times the table has been busy.  If the
** busy callback returns 0, then sqlite3_exec() immediately returns
** SQLITE_BUSY.  If the callback returns non-zero, then sqlite3_exec()
** tries to open the table again and the cycle repeats.
**
** The default busy callback is NULL.
**
** 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 coredump.
*/
void sqlite3_busy_handler(sqlite*, int(*)(void*,const char*,int), void*);

/*
** 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" milleseconds of sleeping have been done.  After
** "ms" milleseconds of sleeping, the handler returns 0 which
** causes sqlite3_exec() to return SQLITE_BUSY.
**
** Calling this routine with an argument less than or equal to zero
** turns off all busy handlers.
*/
void sqlite3_busy_timeout(sqlite*, int ms);

/*
** This next routine is really just a 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 malloc(), then returns all of the result after the
** query has finished. 
**
** As an example, suppose the query result where this table:
**
**        Name        | Age
**        -----------------------
**        Alice       | 43
**        Bob         | 28
**        Cindy       | 21
**
** If the 3rd argument were &azResult then after the function returns
** azResult will contain the following data:
**
**        azResult[0] = "Name";
**        azResult[1] = "Age";
**        azResult[2] = "Alice";
**        azResult[3] = "43";
**        azResult[4] = "Bob";
**        azResult[5] = "28";
**        azResult[6] = "Cindy";
**        azResult[7] = "21";
**
** 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 
** malloc() happens, the calling function must not try to call 
** malloc() 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(
  sqlite*,               /* 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 */
);

/*
** Call this routine to free the memory that sqlite3_get_table() allocated.
*/
void sqlite3_free_table(char **result);

/*
** The following routines are wrappers around sqlite3_exec() and
** sqlite3_get_table().  The only difference between the routines that
** follow and the originals is that the second argument to the 
** routines that follow is really a printf()-style format
** string describing the SQL to be executed.  Arguments to the format
** string appear at the end of the argument list.
**
** All of the usual printf formatting options apply.  In addition, there
** is a "%q" option.  %q 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:
**
**      char *zText = "It's a happy day!";
**
** We can use this text in an SQL statement as follows:
**
**      sqlite3_exec_printf(db, "INSERT INTO table VALUES('%q')",
**          callback1, 0, 0, zText);
**
** Because the %q format string is used, the '\'' character in zText
** is escaped and the SQL generated is as follows:
**
**      INSERT INTO table1 VALUES('It''s a happy day!')
**
** This is correct.  Had we used %s instead of %q, the generated SQL
** would have looked like this:
**
**      INSERT INTO table1 VALUES('It's a happy day!');
**
** 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.
*/
int sqlite3_exec_printf(
  sqlite*,                      /* An open database */
  const char *sqlFormat,        /* printf-style format string for the SQL */
  sqlite_callback,              /* Callback function */
  void *,                       /* 1st argument to callback function */
  char **errmsg,                /* Error msg written here */
  ...                           /* Arguments to the format string. */
);
int sqlite3_exec_vprintf(
  sqlite*,                      /* An open database */
  const char *sqlFormat,        /* printf-style format string for the SQL */
  sqlite_callback,              /* Callback function */
  void *,                       /* 1st argument to callback function */
  char **errmsg,                /* Error msg written here */
  va_list ap                    /* Arguments to the format string. */
);
int sqlite3_get_table_printf(
  sqlite*,               /* An open database */
  const char *sqlFormat, /* printf-style format string for the SQL */
  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 */
  ...                    /* Arguments to the format string */
);
int sqlite3_get_table_vprintf(
  sqlite*,               /* An open database */
  const char *sqlFormat, /* printf-style format string for the SQL */
  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 */
  va_list ap             /* Arguments to the format string */
);
char *sqlite3_mprintf(const char*,...);
char *sqlite3_vmprintf(const char*, va_list);

/*
** Windows systems should call this routine to free memory that
** is returned in the in the errmsg parameter of sqlite3_open() when
** SQLite is a DLL.  For some reason, it does not work to call free()
** directly.
*/
void sqlite3_freemem(void *p);

/*
** Windows systems need functions to call to return the sqlite3_version
** and sqlite3_encoding strings.
*/
const char *sqlite3_libversion(void);
const char *sqlite3_libencoding(void);

/*
** This routine registers a callback with the SQLite library.  The
** callback is invoked (at compile-time, not at run-time) for each
** attempt to access a column of a table in the database.  The callback
** returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire
** SQL statement should be aborted with an error and SQLITE_IGNORE
** if the column should be treated as a NULL value.
*/
int sqlite3_set_authorizer(
  sqlite*,
  int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
  void *pUserData
);

/*
** The second parameter to the access authorization function above will
** be one of the values below.  These values signify what kind of operation
** is to be authorized.  The 3rd and 4th parameters to the authorization
** function will be parameters or NULL depending on which of the following
** codes is used as the second parameter.  The 5th parameter is the name
** of the database ("main", "temp", etc.) if applicable.  The 6th parameter
** 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 
** input SQL code.
**
**                                          Arg-3           Arg-4
*/
#define SQLITE_COPY                  0   /* Table Name      File Name       */
#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            */


/*
** The return value of the authorization function should be one of the
** following constants:
*/
/* #define SQLITE_OK  0   // Allow access (This is actually defined above) */
#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 */

/*
** Register a function that is called at every invocation of sqlite3_exec()
** or sqlite3_prepare().  This function can be used (for example) to generate
** a log file of all SQL executed against a database.
*/
void *sqlite3_trace(sqlite*, void(*xTrace)(void*,const char*), void*);

/*
** This routine configures a callback function - the progress callback - that
** is invoked periodically during long running calls to sqlite3_exec(),
** sqlite3_step() and sqlite3_get_table(). An example use for this API is to keep
** a GUI updated during a large query.
**
** The progress callback is invoked once for every N virtual machine opcodes,
** where N is the second argument to this function. The progress callback
** itself is identified by the third argument to this function. The fourth
** argument to this function is a void pointer passed to the progress callback
** function each time it is invoked.
**
** If a call to sqlite3_exec(), sqlite3_step() or sqlite3_get_table() results 
** in less than N opcodes being executed, then the progress callback is not
** invoked.
** 
** To remove the progress callback altogether, pass NULL as the third
** argument to this function.
**
** If the progress callback returns a result other than 0, then the current 
** query is immediately terminated and any database changes rolled back. If the
** query was part of a larger transaction, then the transaction is not rolled
** back and remains active. The sqlite3_exec() call returns SQLITE_ABORT. 
**
******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
*/
void sqlite3_progress_handler(sqlite*, int, int(*)(void*), void*);

/*
** Register a callback function to be invoked whenever a new transaction
** is committed.  The pArg argument is passed through to the callback.
** callback.  If the callback function returns non-zero, then the commit
** is converted into a rollback.
**
** If another function was previously registered, its pArg value is returned.
** Otherwise NULL is returned.
**
** Registering a NULL function disables the callback.
**
******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
*/
void *sqlite3_commit_hook(sqlite*, int(*)(void*), void*);

/*
** Open an encrypted SQLite database.  If pKey==0 or nKey==0, this routine
** is the same as sqlite3_open().
**
** The code to implement this API is not available in the public release
** of SQLite.
*/
sqlite *sqlite3_open_encrypted(
  const char *zFilename,   /* Name of the encrypted database */
  const void *pKey,        /* Pointer to the key */
  int nKey,                /* Number of bytes in the key */
  int *pErrcode,           /* Write error code here */
  char **pzErrmsg          /* Write error message here */
);

/*
** Change the key on an open database.  If the current database is not
** encrypted, this routine will encrypt it.  If pNew==0 or nNew==0, the
** database is decrypted.
**
** The code to implement this API is not available in the public release
** of SQLite.
*/
int sqlite_rekey(
  sqlite *db,                    /* Database to be rekeyed */
  const void *pKey, int nKey     /* The new key */
);

/*
** Encode a binary buffer "in" of size n bytes so that it contains
** no instances of characters '\'' or '\000'.  The output is 
** null-terminated and can be used as a string value in an INSERT
** or UPDATE statement.  Use sqlite_decode_binary() to convert the
** string back into its original binary.
**
** The result is written into a preallocated output buffer "out".
** "out" must be able to hold at least 2 +(257*n)/254 bytes.
** In other words, the output will be expanded by as much as 3
** bytes for every 254 bytes of input plus 2 bytes of fixed overhead.
** (This is approximately 2 + 1.0118*n or about a 1.2% size increase.)
**
** The return value is the number of characters in the encoded
** string, excluding the "\000" terminator.
**
** If out==NULL then no output is generated but the routine still returns
** the number of characters that would have been generated if out had
** not been NULL.
*/
int sqlite_encode_binary(const unsigned char *in, int n, unsigned char *out);

/*
** Decode the string "in" into binary data and write it into "out".
** This routine reverses the encoding created by sqlite_encode_binary().
** The output will always be a few bytes less than the input.  The number
** of bytes of output is returned.  If the input is not a well-formed
** encoding, -1 is returned.
**
** The "in" and "out" parameters may point to the same buffer in order
** to decode a string in place.
*/
int sqlite_decode_binary(const unsigned char *in, unsigned char *out);

/*
** Open the sqlite database file "filename", where "filename" is UTF-8
** encoded. An sqlite3* handle is returned in *ppDb, even if an error 
** occurs. If the database is opened (or created) successfully, then 
** SQLITE_OK is returned. Otherwise an error code is returned and the
** sqlite3_errmsg() function may be used to obtain an English language
** explanation of the error.
**
** If the database file does not exist, then a new database is created
** using UTF-8 text encoding.
**
** Whether or not an error occurs when it is opened, resources associated
** with the sqlite3* handle should be released by passing it to
** sqlite3_close() when it is no longer required.
*/
int sqlite3_open(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb,         /* OUT: SQLite db handle */
  const char **args       /* Null terminated array of option strings */
);

/*
** Open the sqlite database file "filename", where "filename" is native
** byte order UTF-16 encoded. An sqlite3* handle is returned in *ppDb, even
** if an error occurs. If the database is opened (or created) successfully,
** then SQLITE_OK is returned. Otherwise an error code is returned and the
** sqlite3_errmsg() function may be used to obtain an English language
** explanation of the error.
**
** If the database file does not exist, then a new database is created
** using UTF-16 text encoding in the machines native byte order.
**
** Whether or not an error occurs when it is opened, resources associated
** with the sqlite3* handle should be released by passing it to
** sqlite3_close() when it is no longer required.
*/
int sqlite3_open16(
  const void *filename,   /* Database filename (UTF-16) */
  sqlite3 **ppDb,         /* OUT: SQLite db handle */
  const char **args       /* Null terminated array of option strings */
);

/*
** Return the error code for the most recent sqlite3_* API call associated
** with sqlite3 handle 'db'. SQLITE_OK is returned if the most recent 
** API call was successful.
**
** Calls to many sqlite3_* functions set the error code and string returned
** by sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16()
** (overwriting the previous values). Note that calls to sqlite3_errcode(),
** sqlite3_errmsg() and sqlite3_errmsg16() themselves do not affect the
** results of future invocations.
**
** Assuming no other intervening sqlite3_* API calls are made, the error
** code returned by this function is associated with the same error as
** the strings  returned by sqlite3_errmsg() and sqlite3_errmsg16().
*/
int sqlite3_errcode(sqlite3 *db);

/*
** Return a pointer to a UTF-8 encoded string describing in english the
** error condition for the most recent sqlite3_* API call. The returned
** string is always terminated by an 0x00 byte.
**
** The string "not an error" is returned when the most recent API call was
** successful.
*/
const char *sqlite3_errmsg(sqlite3*);

/*
** Return a pointer to a UTF-16 native byte order encoded string describing
** in english the error condition for the most recent sqlite3_* API call.
** The returned string is always terminated by a pair of 0x00 bytes.
**
** The string "not an error" is returned when the most recent API call was
** successful.
*/
const void *sqlite3_errmsg16(sqlite3*);

/*
** An instance of the following opaque structure is used to represent
** a compiled SQL statment.
*/
typedef struct sqlite3_stmt sqlite3_stmt;

/*
** To execute an SQL query, it must first be compiled into a byte-code
** program using one of the following routines. The only difference between
** them is that the second argument, specifying the SQL statement to
** compile, is assumed to be encoded in UTF-8 for the sqlite3_prepare()
** function and UTF-16 for sqlite3_prepare16().
**
** The first parameter "db" is an SQLite database handle. The second
** parameter "zSql" is the statement to be compiled, encoded as either
** UTF-8 or UTF-16 (see above). If the next parameter, "nBytes", is less
** than zero, then zSql is read up to the first nul terminator.  If
** "nBytes" is not less than zero, then it is the length of the string zSql
** in bytes (not characters).
**
** *pzTail is made to point to the first byte past the end of the first
** SQL statement in zSql.  This routine only compiles the first statement
** in zSql, so *pzTail is left pointing to what remains uncompiled.
**
** *ppStmt is left pointing to a compiled SQL statement that can be
** executed using sqlite3_step().  Or if there is an error, *ppStmt may be
** set to NULL.  If the input text contained no SQL (if the input is and
** empty string or a comment) then *ppStmt is set to NULL.
**
** On success, SQLITE_OK is returned.  Otherwise an error code is returned.
*/
int sqlite3_prepare(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nBytes,             /* Length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
int sqlite3_prepare16(
  sqlite3 *db,            /* Database handle */
  const void *zSql,       /* SQL statement, UTF-16 encoded */
  int nBytes,             /* Length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const void **pzTail     /* OUT: Pointer to unused portion of zSql */
);

/*
** Return the number of columns in the result set returned by the compiled
** SQL statement. This routine returns 0 if pStmt is an SQL statement
** that does not return data (for example an UPDATE).
*/
int sqlite3_column_count(sqlite3_stmt *pStmt);

/*
** The first parameter is a compiled SQL statement. This function returns
** the column heading for the Nth column of that statement, where N is the
** second function parameter. The string returned is UTF-8 encoded.
*/
const char *sqlite3_column_name(sqlite3_stmt*,int);

/*
** The first parameter is a compiled SQL statement. This function returns
** the column heading for the Nth column of that statement, where N is the
** second function parameter. The string returned is UTF-16 encoded.
*/
const void *sqlite3_column_name16(sqlite3_stmt*,int);

/*
** The first parameter is a compiled SQL statement. If this statement
** is a SELECT statement, the Nth column of the returned result set 
** of the SELECT is a table column then the declared type of the table
** column is returned. If the Nth column of the result set is not at table
** column, then a NULL pointer is returned. The returned string is always
** UTF-8 encoded. For example, in the database schema:
**
** CREATE TABLE t1(c1 VARIANT);
**
** And the following statement compiled:
**
** SELECT c1 + 1, 0 FROM t1;
**
** Then this routine would return the string "VARIANT" for the second
** result column (i==1), and a NULL pointer for the first result column
** (i==0).
*/
const char *sqlite3_column_decltype(sqlite3_stmt *, int i);

/*
** The first parameter is a compiled SQL statement. If this statement
** is a SELECT statement, the Nth column of the returned result set 
** of the SELECT is a table column then the declared type of the table
** column is returned. If the Nth column of the result set is not at table
** column, then a NULL pointer is returned. The returned string is always
** UTF-16 encoded. For example, in the database schema:
**
** CREATE TABLE t1(c1 VARINT);
**
** And the following statement compiled:
**
** SELECT c1 + 1, 0 FROM t1;
**
** Then this routine would return the string "VARIANT" for the second
** result column (i==1), and a NULL pointer for the first result column
** (i==0).
*/
const void *sqlite3_column_decltype16(sqlite3_stmt*,int);

/*
** This routine is used to bind a 32-bit integer value to a variable
** in an SQL statement compiled by sqlite3_prepare(). See comments for
** sqlite3_prepare() for more details on SQL statement variables.
**
** The first argument is a pointer to an SQL statement previously
** obtained from a call to sqlite3_prepare(). The second parameter "i"
** determines the parameter to bind the value "iValue" to.
*/
int sqlite3_bind_int32(sqlite3_stmt*, int i, int iValue);

/*
** This routine is used to bind a 64-bit integer value to a variable
** in an SQL statement compiled by sqlite3_prepare(). See comments for
** sqlite3_prepare() for more details on SQL statement variables.
**
** The first argument is a pointer to an SQL statement previously
** obtained from a call to sqlite3_prepare(). The second parameter "i"
** determines the parameter to bind the value "iValue" to.
*/
int sqlite3_bind_int64(sqlite3_stmt*, int i, long long int iValue);

/*
** This routine is used to bind a real (floating point) value to a variable
** in an SQL statement compiled by sqlite3_prepare(). See comments for
** sqlite3_prepare() for more details on SQL statement variables.
**
** The first argument is a pointer to an SQL statement previously obtained
** from a call to sqlite3_prepare(). The second parameter "i" determines
** the parameter to bind the value "iValue" to. Internally, SQLite will
** manipulate the value as a 64-bit IEEE float.
*/
int sqlite3_bind_double(sqlite3_stmt*, int i, double iValue);

/*
** This routine is used to bind a NULL value to a variable in an SQL
** statement compiled by sqlite3_prepare(). See comments for
** sqlite3_prepare() for more details on SQL statement variables.
**
** The first argument is a pointer to an SQL statement previously obtained
** from a call to sqlite3_prepare(). The second parameter "i" determines
** the parameter to bind the NULL value to.
*/
int sqlite3_bind_null(sqlite3_stmt*, int i);

/*
** This routine is used to bind a UTF-8 string value to a variable in an
** SQL statement compiled by sqlite3_prepare(). See comments for
** sqlite3_prepare() for more details on SQL statement variables.
**
** The first argument is a pointer to an SQL statement previously obtained
** from a call to sqlite3_prepare(). The second parameter "i" determines
** the parameter to bind the value to. Parameter three "z" is a pointer
** to the UTF-8 string. 
**
** The fourth "n" parameter is the number of bytes (not characters) in the
** string pointed to by "z". "n" may or may not include any nul terminator
** character. If "n" is less than zero, then SQLite assumes that "z" is
** a nul terminated string.
**
** If paramater "eCopy" is true, then SQLite makes a copy of the string
** pointed to by "z". If "eCopy" is false, then SQLite stores a pointer to
** the original string data. In this case the caller must ensure that the
** string data remains stable until after the SQL statement has been
** finalised or another value bound to variable "i".
*/
int sqlite3_bind_text(sqlite3_stmt*, int i, const char* z, int n, int eCopy);

/*
** This routine is used to bind a UTF-16 string value to a variable in an
** SQL statement compiled by sqlite3_prepare(). See comments for
** sqlite3_prepare() for more details on SQL statement variables.
**
** The first argument is a pointer to an SQL statement previously obtained
** from a call to sqlite3_prepare(). The second parameter "i" determines
** the parameter to bind the value to. Parameter three "z" is a pointer to
** the UTF-16 string. If the string does not begin with a byte-order-mark,
** it is assumed to be encoded in the native byte order of the machine.
**
** The fourth "n" parameter is the number of bytes (not characters) in the
** string pointed to by "z". "n" may or may not include any nul terminator
** character. If "n" is less than zero, then SQLite assumes that "z" is
** terminated by a pair of 0x00 characters.
**
** If paramater "eCopy" is true, then SQLite makes a copy of the string
** pointed to by "z". If "eCopy" is false, then SQLite stores a pointer to
** the original string data. In this case the caller must ensure that the
** string data remains stable until after the SQL statement has been
** finalised or another value bound to variable "i".
*/
int sqlite3_bind_text16(sqlite3_stmt*, int i, const void *z, int, int eCopy);

/*
** This routine is used to bind a blob value to a variable in an
** SQL statement compiled by sqlite3_prepare(). See comments for
** sqlite3_prepare() for more details on SQL statement variables.
**
** The first argument is a pointer to an SQL statement previously obtained
** from a call to sqlite3_prepare(). The second parameter "i" determines
** the parameter to bind the value to. Parameter three "z" is a pointer to
** the blob of data.
**
** The fourth "n" parameter is the number of bytes in the blob pointed to
** by "z". "n" may not be less than zero.
**
** If paramater "eCopy" is true, then SQLite makes a copy of the blob
** pointed to by "z". If "eCopy" is false, then SQLite stores a pointer to
** the original blob data. In this case the caller must ensure that the
** blob data remains stable until after the SQL statement has been
** finalised or another value bound to variable "i".
*/
int sqlite3_bind_blob(sqlite3_stmt*, int i, const void *z, int n, int eCopy);

/* 
** After an SQL query has been compiled with a call to either
** sqlite3_prepare() or sqlite3_prepare16(), then this function must be
** called one or more times to execute the statement.
**
** The return value will be either SQLITE_BUSY, SQLITE_DONE, 
** SQLITE_ROW, SQLITE_ERROR, or SQLITE_MISUSE.
**
** SQLITE_BUSY means that the database engine attempted to open
** a locked database and there is no busy callback registered.
** Call sqlite3_step() again to retry the open.
**
** SQLITE_DONE means that the statement has finished executing
** successfully.  sqlite3_step() should not be called again on this virtual
** machine.
**
** If the SQL statement being executed returns any data, then 
** SQLITE_ROW is returned each time a new row of data is ready
** for processing by the caller. The values may be accessed using
** the sqlite3_column_*() functions described below. sqlite3_step()
** is called again to retrieve the next row of data.
** 
** SQLITE_ERROR means that a run-time error (such as a constraint
** violation) has occurred.  sqlite3_step() should not be called again on
** the VM. More information may be found by calling sqlite3_errmsg().
**
** SQLITE_MISUSE means that the this routine was called inappropriately.
** Perhaps it was called on a virtual machine that had already been
** finalized or on one that had previously returned SQLITE_ERROR or
** SQLITE_DONE.  Or it could be the case the the same database connection
** is being used simulataneously by two or more threads.
*/
int sqlite3_step(sqlite3_stmt*);

/*
** Return the number of values in the current row of the result set.
**
** After a call to sqlite3_step() that returns SQLITE_ROW, this routine
** will return the same value as the sqlite3_column_count() function.
** After sqlite3_step() has returned an SQLITE_DONE, SQLITE_BUSY or
** error code, or before sqlite3_step() has been called on a 
** compiled SQL statement, this routine returns zero.
*/
int sqlite3_data_count(sqlite3_stmt *pStmt);

#define SQLITE3_INTEGER  1
#define SQLITE3_FLOAT    2
#define SQLITE3_TEXT     3
#define SQLITE3_BLOB     4
#define SQLITE3_NULL     5

/*
** The first parameter is a compiled SQL statement for which the most
** recent call to sqlite3_step() has returned SQLITE_ROW. This routine
** retrieves the type of the Nth column of the current row, where
** N is the second function parameter.
**
** The value type is one of SQLITE3_INTEGER, SQLITE3_FLOAT, SQLITE3_TEXT,
** SQLITE3_BLOB and SQLITE3_NULL.
*/
int sqlite3_column_type(sqlite3_stmt *pStmt, int i);

/*
** The first parameter is a compiled SQL statement for which the most
** recent call to sqlite3_step() has returned SQLITE_ROW. This routine
** retrieves the value of the Nth column of the current row, where
** N is the second function parameter.
**
** The value returned depends on the type of the SQL column value, as
** returned by sqlite3_column_type():
**
** SQLITE3_NULL      A Null pointer.
** SQLITE3_INTEGER   String representation of the integer, UTF-8 encoded.
** SQLITE3_FLOAT     String representation of the real, UTF-8 encoded.
** SQLITE3_TEXT      The string UTF-8 encoded.
** SQLITE3_BLOB      A pointer to the blob of data.
*/
const unsigned char *sqlite3_column_data(sqlite3_stmt*,int);

/*
** The first parameter is a compiled SQL statement for which the most
** recent call to sqlite3_step() has returned SQLITE_ROW. This routine
** retrieves the value of the Nth column of the current row, where
** N is the second function parameter.
**
** The value returned depends on the type of the SQL column value, as
** returned by sqlite3_column_type():
**
** SQLITE3_NULL      A Null pointer.
** SQLITE3_INTEGER   String representation of the integer, UTF-16 encoded.
** SQLITE3_FLOAT     String representation of the real, UTF-16 encoded.
** SQLITE3_TEXT      The string UTF-16 encoded.
** SQLITE3_BLOB      A pointer to the blob of data.
*/
const void *sqlite3_column_data16(sqlite3_stmt*,int);

/*
** The first parameter is a compiled SQL statement for which the most
** recent call to sqlite3_step() has returned SQLITE_ROW. This routine
** retrieves the length of the data in bytes returned by the
** sqlite3_column_data() routine for the same second parameter value.
**
** If sqlite3_column_data() returns a UTF-8 string, then the length
** returned by this function includes the nul terminator character at the
** end of the UTF-8 string.
*/
int sqlite3_column_bytes(sqlite3_stmt*,int);

/*
** The first parameter is a compiled SQL statement for which the most
** recent call to sqlite3_step() has returned SQLITE_ROW. This routine
** retrieves the length of the data in bytes returned by the
** sqlite3_column_data() routine for the same second parameter value.
**
** If sqlite3_column_data() returns a UTF-16 string, then the length
** returned by this function includes the nul terminator character (two
** bytes) at the end of the UTF-16 string.
*/
int sqlite3_column_bytes16(sqlite3_stmt *, int);

/*
** The first parameter is a compiled SQL statement for which the most
** recent call to sqlite3_step() has returned SQLITE_ROW. This routine
** retrieves the value of the Nth column of the current row, where
** N is the second function parameter as an integer.
**
** SQLITE3_NULL      0
** SQLITE3_INTEGER   The integer value.
** SQLITE3_FLOAT     The integer component of the real (2^63 if too large)
** SQLITE3_TEXT      Integer conversion of string, or 0
** SQLITE3_BLOB      0
*/
long long int sqlite3_column_int(sqlite3_stmt*,int);

/*
** The first parameter is a compiled SQL statement for which the most
** recent call to sqlite3_step() has returned SQLITE_ROW. This routine
** retrieves the value of the Nth column of the current row, where
** N is the second function parameter as an integer.
**
** SQLITE3_NULL      0.0
** SQLITE3_INTEGER   The value of the integer. Some rounding may occur.
** SQLITE3_FLOAT     The value of the float.
** SQLITE3_TEXT      Real number conversion of string, or 0.0
** SQLITE3_BLOB      0.0
*/
double sqlite3_column_float(sqlite3_stmt*,int);

/*
** The sqlite3_finalize() function is called to delete a compiled
** SQL statement obtained by a previous call to sqlite3_prepare()
** or sqlite3_prepare16(). If the statement was executed successfully, or
** not executed at all, then SQLITE_OK is returned. If execution of the
** statement failed then an error code is returned. 
**
** This routine can be called at any point during the execution of the
** virtual machine.  If the virtual machine has not completed execution
** when this routine is called, that is like encountering an error or
** an interrupt.  (See sqlite3_interrupt().)  Incomplete updates may be
** rolled back and transactions cancelled,  depending on the circumstances,
** and the result code returned will be SQLITE_ABORT.
*/
int sqlite3_finalize(sqlite3_stmt *pStmt);

/*
** The sqlite3_reset() function is called to reset a compiled SQL
** statement obtained by a previous call to sqlite3_prepare() or
** sqlite3_prepare16() back to it's initial state, ready to be re-executed.
** Any SQL statement variables that had values bound to them using
** the sqlite3_bind_*() API retain their values.
*/
int sqlite3_reset(sqlite3_stmt *pStmt);

/*
** Pointers to the following two opaque structures are used to communicate
** with the implementations of user-defined functions.
*/
typedef struct sqlite3_context sqlite3_context;
typedef struct Mem sqlite3_value;

/*
** The following two functions are used to add user functions or aggregates
** implemented in C to the SQL langauge interpreted by SQLite. The
** difference only between the two is that the second parameter, the
** name of the (scalar) function or aggregate, is encoded in UTF-8 for
** sqlite3_create_function() and UTF-16 for sqlite3_create_function16().
**
** The first argument is the database handle that the new function or
** aggregate is to be added to. If a single program uses more than one
** database handle internally, then user functions or aggregates must 
** be added individually to each database handle with which they will be
** used.
**
** The third parameter is the number of arguments that the function or
** aggregate takes. If this parameter is negative, then the function or
** aggregate may take any number of arguments.
**
** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are
** pointers to user implemented C functions that implement the user
** function or aggregate. A scalar function requires an implementation of
** the xFunc callback only, NULL pointers should be passed as the xStep
** and xFinal parameters. An aggregate function requires an implementation
** of xStep and xFinal, but NULL should be passed for xFunc. To delete an
** existing user function or aggregate, pass NULL for all three function
** callback. Specifying an inconstent set of callback values, such as an
** xFunc and an xFinal, or an xStep but no xFinal, SQLITE_ERROR is
** returned.
*/
int sqlite3_create_function(
  sqlite3 *,
  const char *zFunctionName,
  int nArg,
  int eTextRep,
  int iCollateArg,
  void*,
  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  void (*xFinal)(sqlite3_context*)
);
int sqlite3_create_function16(
  sqlite3*,
  const void *zFunctionName,
  int nArg,
  int eTextRep,
  int iCollateArg,
  void*,
  void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  void (*xFinal)(sqlite3_context*)
);

/*
** Use the following routine to define the datatype returned by a
** user-defined function.  The second argument can be one of the
** constants SQLITE_NUMERIC, SQLITE_TEXT, or SQLITE_ARGS or it
** can be an integer greater than or equal to zero.  When the datatype
** parameter is non-negative, the type of the result will be the
** same as the datatype-th argument.  If datatype==SQLITE_NUMERIC
** then the result is always numeric.  If datatype==SQLITE_TEXT then
** the result is always text.  If datatype==SQLITE_ARGS then the result
** is numeric if any argument is numeric and is text otherwise.
*/
int sqlite3_function_type(
  sqlite *db,               /* The database there the function is registered */
  const char *zName,        /* Name of the function */
  int datatype              /* The datatype for this function */
);
#define SQLITE_NUMERIC     (-1)
#define SQLITE_TEXT        (-2)
#define SQLITE_ARGS        (-3)

/*
** The next routine returns the number of calls to xStep for a particular
** aggregate function instance.  The current call to xStep counts so this
** routine always returns at least 1.
*/
int sqlite3_aggregate_count(sqlite3_context*);


/*
** Return the type of the sqlite3_value* passed as the first argument. 
** The type is one of SQLITE3_NULL, SQLITE3_INTEGER, SQLITE3_FLOAT,
** SQLITE3_TEXT or SQLITE3_BLOB.
*/
int sqlite3_value_type(sqlite3_value*);

/*
** Return the value of the sqlite3_value* passed as the first argument.
** The value returned depends on the type of the value, as returned by
** sqlite3_value_type():
**
** SQLITE3_NULL      A Null pointer.
** SQLITE3_INTEGER   String representation of the integer, UTF-8 encoded.
** SQLITE3_FLOAT     String representation of the real, UTF-8 encoded.
** SQLITE3_TEXT      The string UTF-8 encoded.
** SQLITE3_BLOB      A pointer to the blob of data.
*/ 
const unsigned char *sqlite3_value_data(sqlite3_value*);

/*
** Return the number of bytes in the string or blob returned by a call
** to sqlite3_value_data() on the same sqlite3_value* object.
*/
int sqlite3_value_bytes(sqlite3_value*);

/*
** Return the value of the sqlite3_value* passed as the first argument.
** The value returned depends on the type of the value, as returned by
** sqlite3_value_type():
**
** SQLITE3_NULL      A Null pointer.
** SQLITE3_INTEGER   String representation of the integer, UTF-16 encoded.
** SQLITE3_FLOAT     String representation of the real, UTF-16 encoded.
** SQLITE3_TEXT      The string UTF-16 encoded.
** SQLITE3_BLOB      A pointer to the blob of data.
*/ 
const void *sqlite3_value_data16(sqlite3_value*);

/*
** Return the number of bytes in the string or blob returned by a call
** to sqlite3_value_data16() on the same sqlite3_value* object.
*/
int sqlite3_value_bytes16(sqlite3_value*);

/*
** Return the value of the sqlite3_value* passed as the first argument.
** The value returned depends on the type of the value, as returned by
** sqlite3_value_type():
**
** SQLITE3_NULL      0
** SQLITE3_INTEGER   The integer value.
** SQLITE3_FLOAT     The integer component of the real (2^63 if too large)
** SQLITE3_TEXT      Integer conversion of string, or 0
** SQLITE3_BLOB      0
*/
long long int sqlite3_value_int(sqlite3_value*);

/*
** Return the value of the sqlite3_value* passed as the first argument.
** The value returned depends on the type of the value, as returned by
** sqlite3_value_type():
**
** SQLITE3_NULL      0.0
** SQLITE3_INTEGER   The value of the integer. Some rounding may occur.
** SQLITE3_FLOAT     The value of the float.
** SQLITE3_TEXT      Real number conversion of string, or 0.0
** SQLITE3_BLOB      0.0
*/
double sqlite3_value_float(sqlite3_value*);

/*
** Aggregate functions use the following routine to allocate
** a structure for storing their state.  The first time this routine
** is called for a particular aggregate, a new structure of size nBytes
** is allocated, zeroed, and returned.  On subsequent calls (for the
** same aggregate instance) the same buffer is returned.  The implementation
** of the aggregate can use the returned buffer to accumulate data.
**
** The buffer allocated is freed automatically by SQLite.
*/
void *sqlite3_get_context(sqlite3_context*, int nBytes);

/*
** The pUserData parameter to the sqlite3_create_function() and
** sqlite3_create_aggregate() routines used to register user functions
** is available to the implementation of the function using this
** call.
*/
void *sqlite3_user_data(sqlite3_context*);

/*
** The following three functions may be called from within a user-defined
** function callback or a user-defined aggregate finalizer callback. The
** result of the user-defined function or aggregate is set to the value of
** the second parameter. Any value previously set as the return value via
** an sqlite3_result_*() call is overwritten.
**
** The first parameter to each of these routines must be a copy of the
** sqlite3_context* pointer passed to the user-defined function or
** aggregate finalizer function.
*/
void sqlite3_result_int32(sqlite3_context*, int);
void sqlite3_result_int64(sqlite3_context*, long long int);
void sqlite3_result_double(sqlite3_context*, double);

/*
** This function may be called from within a user-defined function callback
** or a user-defined aggregate finalizer callback. The result of the
** user-defined function or aggregate is set to NULL.  Any value previously
** set as the return value via an sqlite3_result_*() call is overwritten.
**
** The parameter to this routine must be a copy of the sqlite3_context*
** pointer passed to the user-defined function or aggregate finalizer
** function.
*/
void sqlite3_result_null(sqlite3_context*);

/*
** The following two functions may be called from within a user-defined or
** a user-defined aggregate finalizer callback to return a text value. 
** The second parameter is a pointer to the string, encoded in UTF-8 
** for sqlite3_result_text() and UTF-16 (machine byte order) for
** sqlite3_result_text16(). 
**
** If the third parameter, n,  is positive, it is the number of bytes (not
** characters) in the string data. A negative n value indicates that the
** string may be read up to the nul terminator character.
**
** If the fourth parameter is non-zero, then a copy is made of the string.
** Otherwise, SQLite stores a pointer to the original string data.
**
** The first parameter to this routine must be a copy of the
** sqlite3_context* pointer passed to the user-defined function or
** aggregate finalizer function.
*/
void sqlite3_result_text(sqlite3_context*, const char*, int n, int eCopy);
void sqlite3_result_text16(sqlite3_context*, const void*, int n, int eCopy);

/*
** The following function may be called from within a user-defined or a
** user-defined aggregate finalizer callback to return a blob value.  The
** second parameter is a pointer to the blob of data. The third parameter
** is the number of bytes of data in the blob.
**
** If the fourth parameter is non-zero, then a copy is made of the blob.
** Otherwise, SQLite stores a pointer to the original blob data.
**
** The first parameter to this routine must be a copy of the
** sqlite3_context* pointer passed to the user-defined function or
** aggregate finalizer function.
*/
void sqlite3_result_blob(sqlite3_context*, const void*, int n, int eCopy);

/*
** These routines are used from within a user-defined or a user-defined
** aggregate finalizer callback to return an error. The second parameter
** is a pointer to a string describing the error, or NULL if no explanation
** is provided.
**
** The string should be encoded in UTF-8 for sqlite3_result_error() and
** UTF-16 (machine byte order) for sqlite3_result_error16().
**
** If not negative, the third parameter is the number of bytes (not
** characters) in the string passed as the second argument. If the third
** parameter is negative, then the string is read up to the first nul
** terminator character.
*/
void sqlite3_result_error(sqlite3_context*, const char*, int);
void sqlite3_result_error16(sqlite3_context*, const void*, int);

#ifdef __cplusplus
}  /* End of the 'extern "C"' block */
#endif
#endif