17c478bd9Sstevel@tonic-gate/*
27c478bd9Sstevel@tonic-gate** 2001 September 15
37c478bd9Sstevel@tonic-gate**
47c478bd9Sstevel@tonic-gate** The author disclaims copyright to this source code.  In place of
57c478bd9Sstevel@tonic-gate** a legal notice, here is a blessing:
67c478bd9Sstevel@tonic-gate**
77c478bd9Sstevel@tonic-gate**    May you do good and not evil.
87c478bd9Sstevel@tonic-gate**    May you find forgiveness for yourself and forgive others.
97c478bd9Sstevel@tonic-gate**    May you share freely, never taking more than you give.
107c478bd9Sstevel@tonic-gate**
117c478bd9Sstevel@tonic-gate*************************************************************************
127c478bd9Sstevel@tonic-gate** This header file defines the interface that the SQLite library
137c478bd9Sstevel@tonic-gate** presents to client programs.
147c478bd9Sstevel@tonic-gate**
157c478bd9Sstevel@tonic-gate** @(#) $Id: sqlite.h.in,v 1.60 2004/03/14 22:12:35 drh Exp $
167c478bd9Sstevel@tonic-gate*/
177c478bd9Sstevel@tonic-gate#ifndef _SQLITE_H_
187c478bd9Sstevel@tonic-gate#define _SQLITE_H_
197c478bd9Sstevel@tonic-gate#include <stdarg.h>     /* Needed for the definition of va_list */
207c478bd9Sstevel@tonic-gate
217c478bd9Sstevel@tonic-gate/*
227c478bd9Sstevel@tonic-gate** Make sure we can call this stuff from C++.
237c478bd9Sstevel@tonic-gate*/
247c478bd9Sstevel@tonic-gate#ifdef __cplusplus
257c478bd9Sstevel@tonic-gateextern "C" {
267c478bd9Sstevel@tonic-gate#endif
277c478bd9Sstevel@tonic-gate
287c478bd9Sstevel@tonic-gate/*
297c478bd9Sstevel@tonic-gate** The version of the SQLite library.
307c478bd9Sstevel@tonic-gate*/
317c478bd9Sstevel@tonic-gate#define SQLITE_VERSION         "--VERS--"
327c478bd9Sstevel@tonic-gate
337c478bd9Sstevel@tonic-gate/*
347c478bd9Sstevel@tonic-gate** The version string is also compiled into the library so that a program
357c478bd9Sstevel@tonic-gate** can check to make sure that the lib*.a file and the *.h file are from
367c478bd9Sstevel@tonic-gate** the same version.
377c478bd9Sstevel@tonic-gate*/
387c478bd9Sstevel@tonic-gateextern const char sqlite_version[];
397c478bd9Sstevel@tonic-gate
407c478bd9Sstevel@tonic-gate/*
417c478bd9Sstevel@tonic-gate** The SQLITE_UTF8 macro is defined if the library expects to see
427c478bd9Sstevel@tonic-gate** UTF-8 encoded data.  The SQLITE_ISO8859 macro is defined if the
437c478bd9Sstevel@tonic-gate** iso8859 encoded should be used.
447c478bd9Sstevel@tonic-gate*/
457c478bd9Sstevel@tonic-gate#define SQLITE_--ENCODING-- 1
467c478bd9Sstevel@tonic-gate
477c478bd9Sstevel@tonic-gate/*
487c478bd9Sstevel@tonic-gate** The following constant holds one of two strings, "UTF-8" or "iso8859",
497c478bd9Sstevel@tonic-gate** depending on which character encoding the SQLite library expects to
507c478bd9Sstevel@tonic-gate** see.  The character encoding makes a difference for the LIKE and GLOB
517c478bd9Sstevel@tonic-gate** operators and for the LENGTH() and SUBSTR() functions.
527c478bd9Sstevel@tonic-gate*/
537c478bd9Sstevel@tonic-gateextern const char sqlite_encoding[];
547c478bd9Sstevel@tonic-gate
557c478bd9Sstevel@tonic-gate/*
567c478bd9Sstevel@tonic-gate** Each open sqlite database is represented by an instance of the
577c478bd9Sstevel@tonic-gate** following opaque structure.
587c478bd9Sstevel@tonic-gate*/
597c478bd9Sstevel@tonic-gatetypedef struct sqlite sqlite;
607c478bd9Sstevel@tonic-gate
617c478bd9Sstevel@tonic-gate/*
62*1da57d55SToomas Soome** A function to open a new sqlite database.
637c478bd9Sstevel@tonic-gate**
647c478bd9Sstevel@tonic-gate** If the database does not exist and mode indicates write
657c478bd9Sstevel@tonic-gate** permission, then a new database is created.  If the database
667c478bd9Sstevel@tonic-gate** does not exist and mode does not indicate write permission,
677c478bd9Sstevel@tonic-gate** then the open fails, an error message generated (if errmsg!=0)
687c478bd9Sstevel@tonic-gate** and the function returns 0.
69*1da57d55SToomas Soome**
70*1da57d55SToomas Soome** If mode does not indicates user write permission, then the
717c478bd9Sstevel@tonic-gate** database is opened read-only.
727c478bd9Sstevel@tonic-gate**
737c478bd9Sstevel@tonic-gate** The Truth:  As currently implemented, all databases are opened
747c478bd9Sstevel@tonic-gate** for writing all the time.  Maybe someday we will provide the
757c478bd9Sstevel@tonic-gate** ability to open a database readonly.  The mode parameters is
767c478bd9Sstevel@tonic-gate** provided in anticipation of that enhancement.
777c478bd9Sstevel@tonic-gate*/
787c478bd9Sstevel@tonic-gatesqlite *sqlite_open(const char *filename, int mode, char **errmsg);
797c478bd9Sstevel@tonic-gate
807c478bd9Sstevel@tonic-gate/*
817c478bd9Sstevel@tonic-gate** A function to close the database.
827c478bd9Sstevel@tonic-gate**
837c478bd9Sstevel@tonic-gate** Call this function with a pointer to a structure that was previously
847c478bd9Sstevel@tonic-gate** returned from sqlite_open() and the corresponding database will by closed.
857c478bd9Sstevel@tonic-gate*/
867c478bd9Sstevel@tonic-gatevoid sqlite_close(sqlite *);
877c478bd9Sstevel@tonic-gate
887c478bd9Sstevel@tonic-gate/*
897c478bd9Sstevel@tonic-gate** The type for a callback function.
907c478bd9Sstevel@tonic-gate*/
917c478bd9Sstevel@tonic-gatetypedef int (*sqlite_callback)(void*,int,char**, char**);
927c478bd9Sstevel@tonic-gate
937c478bd9Sstevel@tonic-gate/*
947c478bd9Sstevel@tonic-gate** A function to executes one or more statements of SQL.
957c478bd9Sstevel@tonic-gate**
967c478bd9Sstevel@tonic-gate** If one or more of the SQL statements are queries, then
977c478bd9Sstevel@tonic-gate** the callback function specified by the 3rd parameter is
987c478bd9Sstevel@tonic-gate** invoked once for each row of the query result.  This callback
997c478bd9Sstevel@tonic-gate** should normally return 0.  If the callback returns a non-zero
1007c478bd9Sstevel@tonic-gate** value then the query is aborted, all subsequent SQL statements
1017c478bd9Sstevel@tonic-gate** are skipped and the sqlite_exec() function returns the SQLITE_ABORT.
1027c478bd9Sstevel@tonic-gate**
1037c478bd9Sstevel@tonic-gate** The 4th parameter is an arbitrary pointer that is passed
1047c478bd9Sstevel@tonic-gate** to the callback function as its first parameter.
1057c478bd9Sstevel@tonic-gate**
1067c478bd9Sstevel@tonic-gate** The 2nd parameter to the callback function is the number of
1077c478bd9Sstevel@tonic-gate** columns in the query result.  The 3rd parameter to the callback
1087c478bd9Sstevel@tonic-gate** is an array of strings holding the values for each column.
1097c478bd9Sstevel@tonic-gate** The 4th parameter to the callback is an array of strings holding
1107c478bd9Sstevel@tonic-gate** the names of each column.
1117c478bd9Sstevel@tonic-gate**
1127c478bd9Sstevel@tonic-gate** The callback function may be NULL, even for queries.  A NULL
1137c478bd9Sstevel@tonic-gate** callback is not an error.  It just means that no callback
1147c478bd9Sstevel@tonic-gate** will be invoked.
1157c478bd9Sstevel@tonic-gate**
1167c478bd9Sstevel@tonic-gate** If an error occurs while parsing or evaluating the SQL (but
1177c478bd9Sstevel@tonic-gate** not while executing the callback) then an appropriate error
1187c478bd9Sstevel@tonic-gate** message is written into memory obtained from malloc() and
1197c478bd9Sstevel@tonic-gate** *errmsg is made to point to that message.  The calling function
1207c478bd9Sstevel@tonic-gate** is responsible for freeing the memory that holds the error
1217c478bd9Sstevel@tonic-gate** message.   Use sqlite_freemem() for this.  If errmsg==NULL,
1227c478bd9Sstevel@tonic-gate** then no error message is ever written.
1237c478bd9Sstevel@tonic-gate**
1247c478bd9Sstevel@tonic-gate** The return value is is SQLITE_OK if there are no errors and
1257c478bd9Sstevel@tonic-gate** some other return code if there is an error.  The particular
126*1da57d55SToomas Soome** return value depends on the type of error.
1277c478bd9Sstevel@tonic-gate**
1287c478bd9Sstevel@tonic-gate** If the query could not be executed because a database file is
1297c478bd9Sstevel@tonic-gate** locked or busy, then this function returns SQLITE_BUSY.  (This
1307c478bd9Sstevel@tonic-gate** behavior can be modified somewhat using the sqlite_busy_handler()
1317c478bd9Sstevel@tonic-gate** and sqlite_busy_timeout() functions below.)
1327c478bd9Sstevel@tonic-gate*/
1337c478bd9Sstevel@tonic-gateint sqlite_exec(
1347c478bd9Sstevel@tonic-gate  sqlite*,                      /* An open database */
1357c478bd9Sstevel@tonic-gate  const char *sql,              /* SQL to be executed */
1367c478bd9Sstevel@tonic-gate  sqlite_callback,              /* Callback function */
1377c478bd9Sstevel@tonic-gate  void *,                       /* 1st argument to callback function */
1387c478bd9Sstevel@tonic-gate  char **errmsg                 /* Error msg written here */
1397c478bd9Sstevel@tonic-gate);
1407c478bd9Sstevel@tonic-gate
1417c478bd9Sstevel@tonic-gate/*
1427c478bd9Sstevel@tonic-gate** Return values for sqlite_exec() and sqlite_step()
1437c478bd9Sstevel@tonic-gate*/
1447c478bd9Sstevel@tonic-gate#define SQLITE_OK           0   /* Successful result */
1457c478bd9Sstevel@tonic-gate#define SQLITE_ERROR        1   /* SQL error or missing database */
1467c478bd9Sstevel@tonic-gate#define SQLITE_INTERNAL     2   /* An internal logic error in SQLite */
1477c478bd9Sstevel@tonic-gate#define SQLITE_PERM         3   /* Access permission denied */
1487c478bd9Sstevel@tonic-gate#define SQLITE_ABORT        4   /* Callback routine requested an abort */
1497c478bd9Sstevel@tonic-gate#define SQLITE_BUSY         5   /* The database file is locked */
1507c478bd9Sstevel@tonic-gate#define SQLITE_LOCKED       6   /* A table in the database is locked */
1517c478bd9Sstevel@tonic-gate#define SQLITE_NOMEM        7   /* A malloc() failed */
1527c478bd9Sstevel@tonic-gate#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
1537c478bd9Sstevel@tonic-gate#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite_interrupt() */
1547c478bd9Sstevel@tonic-gate#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
1557c478bd9Sstevel@tonic-gate#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
1567c478bd9Sstevel@tonic-gate#define SQLITE_NOTFOUND    12   /* (Internal Only) Table or record not found */
1577c478bd9Sstevel@tonic-gate#define SQLITE_FULL        13   /* Insertion failed because database is full */
1587c478bd9Sstevel@tonic-gate#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
1597c478bd9Sstevel@tonic-gate#define SQLITE_PROTOCOL    15   /* Database lock protocol error */
1607c478bd9Sstevel@tonic-gate#define SQLITE_EMPTY       16   /* (Internal Only) Database table is empty */
1617c478bd9Sstevel@tonic-gate#define SQLITE_SCHEMA      17   /* The database schema changed */
1627c478bd9Sstevel@tonic-gate#define SQLITE_TOOBIG      18   /* Too much data for one row of a table */
1637c478bd9Sstevel@tonic-gate#define SQLITE_CONSTRAINT  19   /* Abort due to contraint violation */
1647c478bd9Sstevel@tonic-gate#define SQLITE_MISMATCH    20   /* Data type mismatch */
1657c478bd9Sstevel@tonic-gate#define SQLITE_MISUSE      21   /* Library used incorrectly */
1667c478bd9Sstevel@tonic-gate#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
1677c478bd9Sstevel@tonic-gate#define SQLITE_AUTH        23   /* Authorization denied */
1687c478bd9Sstevel@tonic-gate#define SQLITE_FORMAT      24   /* Auxiliary database format error */
1697c478bd9Sstevel@tonic-gate#define SQLITE_RANGE       25   /* 2nd parameter to sqlite_bind out of range */
1707c478bd9Sstevel@tonic-gate#define SQLITE_NOTADB      26   /* File opened that is not a database file */
1717c478bd9Sstevel@tonic-gate#define SQLITE_ROW         100  /* sqlite_step() has another row ready */
1727c478bd9Sstevel@tonic-gate#define SQLITE_DONE        101  /* sqlite_step() has finished executing */
1737c478bd9Sstevel@tonic-gate
1747c478bd9Sstevel@tonic-gate/*
1757c478bd9Sstevel@tonic-gate** Each entry in an SQLite table has a unique integer key.  (The key is
1767c478bd9Sstevel@tonic-gate** the value of the INTEGER PRIMARY KEY column if there is such a column,
1777c478bd9Sstevel@tonic-gate** otherwise the key is generated at random.  The unique key is always
1787c478bd9Sstevel@tonic-gate** available as the ROWID, OID, or _ROWID_ column.)  The following routine
1797c478bd9Sstevel@tonic-gate** returns the integer key of the most recent insert in the database.
1807c478bd9Sstevel@tonic-gate**
1817c478bd9Sstevel@tonic-gate** This function is similar to the mysql_insert_id() function from MySQL.
1827c478bd9Sstevel@tonic-gate*/
1837c478bd9Sstevel@tonic-gateint sqlite_last_insert_rowid(sqlite*);
1847c478bd9Sstevel@tonic-gate
1857c478bd9Sstevel@tonic-gate/*
1867c478bd9Sstevel@tonic-gate** This function returns the number of database rows that were changed
1877c478bd9Sstevel@tonic-gate** (or inserted or deleted) by the most recent called sqlite_exec().
1887c478bd9Sstevel@tonic-gate**
1897c478bd9Sstevel@tonic-gate** All changes are counted, even if they were later undone by a
1907c478bd9Sstevel@tonic-gate** ROLLBACK or ABORT.  Except, changes associated with creating and
1917c478bd9Sstevel@tonic-gate** dropping tables are not counted.
1927c478bd9Sstevel@tonic-gate**
1937c478bd9Sstevel@tonic-gate** If a callback invokes sqlite_exec() recursively, then the changes
1947c478bd9Sstevel@tonic-gate** in the inner, recursive call are counted together with the changes
1957c478bd9Sstevel@tonic-gate** in the outer call.
1967c478bd9Sstevel@tonic-gate**
1977c478bd9Sstevel@tonic-gate** SQLite implements the command "DELETE FROM table" without a WHERE clause
1987c478bd9Sstevel@tonic-gate** by dropping and recreating the table.  (This is much faster than going
1997c478bd9Sstevel@tonic-gate** through and deleting individual elements form the table.)  Because of
2007c478bd9Sstevel@tonic-gate** this optimization, the change count for "DELETE FROM table" will be
2017c478bd9Sstevel@tonic-gate** zero regardless of the number of elements that were originally in the
2027c478bd9Sstevel@tonic-gate** table. To get an accurate count of the number of rows deleted, use
2037c478bd9Sstevel@tonic-gate** "DELETE FROM table WHERE 1" instead.
2047c478bd9Sstevel@tonic-gate*/
2057c478bd9Sstevel@tonic-gateint sqlite_changes(sqlite*);
2067c478bd9Sstevel@tonic-gate
2077c478bd9Sstevel@tonic-gate/*
2087c478bd9Sstevel@tonic-gate** This function returns the number of database rows that were changed
2097c478bd9Sstevel@tonic-gate** by the last INSERT, UPDATE, or DELETE statment executed by sqlite_exec(),
2107c478bd9Sstevel@tonic-gate** or by the last VM to run to completion. The change count is not updated
2117c478bd9Sstevel@tonic-gate** by SQL statements other than INSERT, UPDATE or DELETE.
2127c478bd9Sstevel@tonic-gate**
2137c478bd9Sstevel@tonic-gate** Changes are counted, even if they are later undone by a ROLLBACK or
2147c478bd9Sstevel@tonic-gate** ABORT. Changes associated with trigger programs that execute as a
2157c478bd9Sstevel@tonic-gate** result of the INSERT, UPDATE, or DELETE statement are not counted.
2167c478bd9Sstevel@tonic-gate**
2177c478bd9Sstevel@tonic-gate** If a callback invokes sqlite_exec() recursively, then the changes
2187c478bd9Sstevel@tonic-gate** in the inner, recursive call are counted together with the changes
2197c478bd9Sstevel@tonic-gate** in the outer call.
2207c478bd9Sstevel@tonic-gate**
2217c478bd9Sstevel@tonic-gate** SQLite implements the command "DELETE FROM table" without a WHERE clause
2227c478bd9Sstevel@tonic-gate** by dropping and recreating the table.  (This is much faster than going
2237c478bd9Sstevel@tonic-gate** through and deleting individual elements form the table.)  Because of
2247c478bd9Sstevel@tonic-gate** this optimization, the change count for "DELETE FROM table" will be
2257c478bd9Sstevel@tonic-gate** zero regardless of the number of elements that were originally in the
2267c478bd9Sstevel@tonic-gate** table. To get an accurate count of the number of rows deleted, use
2277c478bd9Sstevel@tonic-gate** "DELETE FROM table WHERE 1" instead.
2287c478bd9Sstevel@tonic-gate**
2297c478bd9Sstevel@tonic-gate******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
2307c478bd9Sstevel@tonic-gate*/
2317c478bd9Sstevel@tonic-gateint sqlite_last_statement_changes(sqlite*);
2327c478bd9Sstevel@tonic-gate
2337c478bd9Sstevel@tonic-gate/* If the parameter to this routine is one of the return value constants
2347c478bd9Sstevel@tonic-gate** defined above, then this routine returns a constant text string which
2357c478bd9Sstevel@tonic-gate** descripts (in English) the meaning of the return value.
2367c478bd9Sstevel@tonic-gate*/
2377c478bd9Sstevel@tonic-gateconst char *sqlite_error_string(int);
2387c478bd9Sstevel@tonic-gate#define sqliteErrStr sqlite_error_string  /* Legacy. Do not use in new code. */
2397c478bd9Sstevel@tonic-gate
2407c478bd9Sstevel@tonic-gate/* This function causes any pending database operation to abort and
2417c478bd9Sstevel@tonic-gate** return at its earliest opportunity.  This routine is typically
2427c478bd9Sstevel@tonic-gate** called in response to a user action such as pressing "Cancel"
2437c478bd9Sstevel@tonic-gate** or Ctrl-C where the user wants a long query operation to halt
2447c478bd9Sstevel@tonic-gate** immediately.
2457c478bd9Sstevel@tonic-gate*/
2467c478bd9Sstevel@tonic-gatevoid sqlite_interrupt(sqlite*);
2477c478bd9Sstevel@tonic-gate
2487c478bd9Sstevel@tonic-gate
2497c478bd9Sstevel@tonic-gate/* This function returns true if the given input string comprises
2507c478bd9Sstevel@tonic-gate** one or more complete SQL statements.
2517c478bd9Sstevel@tonic-gate**
2527c478bd9Sstevel@tonic-gate** The algorithm is simple.  If the last token other than spaces
2537c478bd9Sstevel@tonic-gate** and comments is a semicolon, then return true.  otherwise return
2547c478bd9Sstevel@tonic-gate** false.
2557c478bd9Sstevel@tonic-gate*/
2567c478bd9Sstevel@tonic-gateint sqlite_complete(const char *sql);
2577c478bd9Sstevel@tonic-gate
2587c478bd9Sstevel@tonic-gate/*
2597c478bd9Sstevel@tonic-gate** This routine identifies a callback function that is invoked
2607c478bd9Sstevel@tonic-gate** whenever an attempt is made to open a database table that is
2617c478bd9Sstevel@tonic-gate** currently locked by another process or thread.  If the busy callback
2627c478bd9Sstevel@tonic-gate** is NULL, then sqlite_exec() returns SQLITE_BUSY immediately if
2637c478bd9Sstevel@tonic-gate** it finds a locked table.  If the busy callback is not NULL, then
2647c478bd9Sstevel@tonic-gate** sqlite_exec() invokes the callback with three arguments.  The
2657c478bd9Sstevel@tonic-gate** second argument is the name of the locked table and the third
2667c478bd9Sstevel@tonic-gate** argument is the number of times the table has been busy.  If the
2677c478bd9Sstevel@tonic-gate** busy callback returns 0, then sqlite_exec() immediately returns
2687c478bd9Sstevel@tonic-gate** SQLITE_BUSY.  If the callback returns non-zero, then sqlite_exec()
2697c478bd9Sstevel@tonic-gate** tries to open the table again and the cycle repeats.
2707c478bd9Sstevel@tonic-gate**
2717c478bd9Sstevel@tonic-gate** The default busy callback is NULL.
2727c478bd9Sstevel@tonic-gate**
273*1da57d55SToomas Soome** Sqlite is re-entrant, so the busy handler may start a new query.
2747c478bd9Sstevel@tonic-gate** (It is not clear why anyone would every want to do this, but it
2757c478bd9Sstevel@tonic-gate** is allowed, in theory.)  But the busy handler may not close the
276*1da57d55SToomas Soome** database.  Closing the database from a busy handler will delete
277*1da57d55SToomas Soome** data structures out from under the executing query and will
2787c478bd9Sstevel@tonic-gate** probably result in a coredump.
2797c478bd9Sstevel@tonic-gate*/
2807c478bd9Sstevel@tonic-gatevoid sqlite_busy_handler(sqlite*, int(*)(void*,const char*,int), void*);
2817c478bd9Sstevel@tonic-gate
2827c478bd9Sstevel@tonic-gate/*
2837c478bd9Sstevel@tonic-gate** This routine sets a busy handler that sleeps for a while when a
284*1da57d55SToomas Soome** table is locked.  The handler will sleep multiple times until
2857c478bd9Sstevel@tonic-gate** at least "ms" milleseconds of sleeping have been done.  After
2867c478bd9Sstevel@tonic-gate** "ms" milleseconds of sleeping, the handler returns 0 which
2877c478bd9Sstevel@tonic-gate** causes sqlite_exec() to return SQLITE_BUSY.
2887c478bd9Sstevel@tonic-gate**
2897c478bd9Sstevel@tonic-gate** Calling this routine with an argument less than or equal to zero
2907c478bd9Sstevel@tonic-gate** turns off all busy handlers.
2917c478bd9Sstevel@tonic-gate*/
2927c478bd9Sstevel@tonic-gatevoid sqlite_busy_timeout(sqlite*, int ms);
2937c478bd9Sstevel@tonic-gate
2947c478bd9Sstevel@tonic-gate/*
2957c478bd9Sstevel@tonic-gate** This next routine is really just a wrapper around sqlite_exec().
2967c478bd9Sstevel@tonic-gate** Instead of invoking a user-supplied callback for each row of the
2977c478bd9Sstevel@tonic-gate** result, this routine remembers each row of the result in memory
2987c478bd9Sstevel@tonic-gate** obtained from malloc(), then returns all of the result after the
299*1da57d55SToomas Soome** query has finished.
3007c478bd9Sstevel@tonic-gate**
3017c478bd9Sstevel@tonic-gate** As an example, suppose the query result where this table:
3027c478bd9Sstevel@tonic-gate**
3037c478bd9Sstevel@tonic-gate**        Name        | Age
3047c478bd9Sstevel@tonic-gate**        -----------------------
3057c478bd9Sstevel@tonic-gate**        Alice       | 43
3067c478bd9Sstevel@tonic-gate**        Bob         | 28
3077c478bd9Sstevel@tonic-gate**        Cindy       | 21
3087c478bd9Sstevel@tonic-gate**
3097c478bd9Sstevel@tonic-gate** If the 3rd argument were &azResult then after the function returns
3107c478bd9Sstevel@tonic-gate** azResult will contain the following data:
3117c478bd9Sstevel@tonic-gate**
3127c478bd9Sstevel@tonic-gate**        azResult[0] = "Name";
3137c478bd9Sstevel@tonic-gate**        azResult[1] = "Age";
3147c478bd9Sstevel@tonic-gate**        azResult[2] = "Alice";
3157c478bd9Sstevel@tonic-gate**        azResult[3] = "43";
3167c478bd9Sstevel@tonic-gate**        azResult[4] = "Bob";
3177c478bd9Sstevel@tonic-gate**        azResult[5] = "28";
3187c478bd9Sstevel@tonic-gate**        azResult[6] = "Cindy";
3197c478bd9Sstevel@tonic-gate**        azResult[7] = "21";
3207c478bd9Sstevel@tonic-gate**
3217c478bd9Sstevel@tonic-gate** Notice that there is an extra row of data containing the column
3227c478bd9Sstevel@tonic-gate** headers.  But the *nrow return value is still 3.  *ncolumn is
3237c478bd9Sstevel@tonic-gate** set to 2.  In general, the number of values inserted into azResult
3247c478bd9Sstevel@tonic-gate** will be ((*nrow) + 1)*(*ncolumn).
3257c478bd9Sstevel@tonic-gate**
326*1da57d55SToomas Soome** After the calling function has finished using the result, it should
327*1da57d55SToomas Soome** pass the result data pointer to sqlite_free_table() in order to
328*1da57d55SToomas Soome** release the memory that was malloc-ed.  Because of the way the
329*1da57d55SToomas Soome** malloc() happens, the calling function must not try to call
330*1da57d55SToomas Soome** malloc() directly.  Only sqlite_free_table() is able to release
3317c478bd9Sstevel@tonic-gate** the memory properly and safely.
3327c478bd9Sstevel@tonic-gate**
3337c478bd9Sstevel@tonic-gate** The return value of this routine is the same as from sqlite_exec().
3347c478bd9Sstevel@tonic-gate*/
3357c478bd9Sstevel@tonic-gateint sqlite_get_table(
3367c478bd9Sstevel@tonic-gate  sqlite*,               /* An open database */
3377c478bd9Sstevel@tonic-gate  const char *sql,       /* SQL to be executed */
3387c478bd9Sstevel@tonic-gate  char ***resultp,       /* Result written to a char *[]  that this points to */
3397c478bd9Sstevel@tonic-gate  int *nrow,             /* Number of result rows written here */
3407c478bd9Sstevel@tonic-gate  int *ncolumn,          /* Number of result columns written here */
3417c478bd9Sstevel@tonic-gate  char **errmsg          /* Error msg written here */
3427c478bd9Sstevel@tonic-gate);
3437c478bd9Sstevel@tonic-gate
3447c478bd9Sstevel@tonic-gate/*
3457c478bd9Sstevel@tonic-gate** Call this routine to free the memory that sqlite_get_table() allocated.
3467c478bd9Sstevel@tonic-gate*/
3477c478bd9Sstevel@tonic-gatevoid sqlite_free_table(char **result);
3487c478bd9Sstevel@tonic-gate
3497c478bd9Sstevel@tonic-gate/*
3507c478bd9Sstevel@tonic-gate** The following routines are wrappers around sqlite_exec() and
3517c478bd9Sstevel@tonic-gate** sqlite_get_table().  The only difference between the routines that
352*1da57d55SToomas Soome** follow and the originals is that the second argument to the
3537c478bd9Sstevel@tonic-gate** routines that follow is really a printf()-style format
3547c478bd9Sstevel@tonic-gate** string describing the SQL to be executed.  Arguments to the format
3557c478bd9Sstevel@tonic-gate** string appear at the end of the argument list.
3567c478bd9Sstevel@tonic-gate**
3577c478bd9Sstevel@tonic-gate** All of the usual printf formatting options apply.  In addition, there
3587c478bd9Sstevel@tonic-gate** is a "%q" option.  %q works like %s in that it substitutes a null-terminated
3597c478bd9Sstevel@tonic-gate** string from the argument list.  But %q also doubles every '\'' character.
3607c478bd9Sstevel@tonic-gate** %q is designed for use inside a string literal.  By doubling each '\''
3617c478bd9Sstevel@tonic-gate** character it escapes that character and allows it to be inserted into
3627c478bd9Sstevel@tonic-gate** the string.
3637c478bd9Sstevel@tonic-gate**
3647c478bd9Sstevel@tonic-gate** For example, so some string variable contains text as follows:
3657c478bd9Sstevel@tonic-gate**
3667c478bd9Sstevel@tonic-gate**      char *zText = "It's a happy day!";
3677c478bd9Sstevel@tonic-gate**
3687c478bd9Sstevel@tonic-gate** We can use this text in an SQL statement as follows:
3697c478bd9Sstevel@tonic-gate**
3707c478bd9Sstevel@tonic-gate**      sqlite_exec_printf(db, "INSERT INTO table VALUES('%q')",
3717c478bd9Sstevel@tonic-gate**          callback1, 0, 0, zText);
3727c478bd9Sstevel@tonic-gate**
3737c478bd9Sstevel@tonic-gate** Because the %q format string is used, the '\'' character in zText
3747c478bd9Sstevel@tonic-gate** is escaped and the SQL generated is as follows:
3757c478bd9Sstevel@tonic-gate**
3767c478bd9Sstevel@tonic-gate**      INSERT INTO table1 VALUES('It''s a happy day!')
3777c478bd9Sstevel@tonic-gate**
3787c478bd9Sstevel@tonic-gate** This is correct.  Had we used %s instead of %q, the generated SQL
3797c478bd9Sstevel@tonic-gate** would have looked like this:
3807c478bd9Sstevel@tonic-gate**
3817c478bd9Sstevel@tonic-gate**      INSERT INTO table1 VALUES('It's a happy day!');
3827c478bd9Sstevel@tonic-gate**
3837c478bd9Sstevel@tonic-gate** This second example is an SQL syntax error.  As a general rule you
384*1da57d55SToomas Soome** should always use %q instead of %s when inserting text into a string
3857c478bd9Sstevel@tonic-gate** literal.
3867c478bd9Sstevel@tonic-gate*/
3877c478bd9Sstevel@tonic-gateint sqlite_exec_printf(
3887c478bd9Sstevel@tonic-gate  sqlite*,                      /* An open database */
3897c478bd9Sstevel@tonic-gate  const char *sqlFormat,        /* printf-style format string for the SQL */
3907c478bd9Sstevel@tonic-gate  sqlite_callback,              /* Callback function */
3917c478bd9Sstevel@tonic-gate  void *,                       /* 1st argument to callback function */
3927c478bd9Sstevel@tonic-gate  char **errmsg,                /* Error msg written here */
3937c478bd9Sstevel@tonic-gate  ...                           /* Arguments to the format string. */
3947c478bd9Sstevel@tonic-gate);
3957c478bd9Sstevel@tonic-gateint sqlite_exec_vprintf(
3967c478bd9Sstevel@tonic-gate  sqlite*,                      /* An open database */
3977c478bd9Sstevel@tonic-gate  const char *sqlFormat,        /* printf-style format string for the SQL */
3987c478bd9Sstevel@tonic-gate  sqlite_callback,              /* Callback function */
3997c478bd9Sstevel@tonic-gate  void *,                       /* 1st argument to callback function */
4007c478bd9Sstevel@tonic-gate  char **errmsg,                /* Error msg written here */
4017c478bd9Sstevel@tonic-gate  va_list ap                    /* Arguments to the format string. */
4027c478bd9Sstevel@tonic-gate);
4037c478bd9Sstevel@tonic-gateint sqlite_get_table_printf(
4047c478bd9Sstevel@tonic-gate  sqlite*,               /* An open database */
4057c478bd9Sstevel@tonic-gate  const char *sqlFormat, /* printf-style format string for the SQL */
4067c478bd9Sstevel@tonic-gate  char ***resultp,       /* Result written to a char *[]  that this points to */
4077c478bd9Sstevel@tonic-gate  int *nrow,             /* Number of result rows written here */
4087c478bd9Sstevel@tonic-gate  int *ncolumn,          /* Number of result columns written here */
4097c478bd9Sstevel@tonic-gate  char **errmsg,         /* Error msg written here */
4107c478bd9Sstevel@tonic-gate  ...                    /* Arguments to the format string */
4117c478bd9Sstevel@tonic-gate);
4127c478bd9Sstevel@tonic-gateint sqlite_get_table_vprintf(
4137c478bd9Sstevel@tonic-gate  sqlite*,               /* An open database */
4147c478bd9Sstevel@tonic-gate  const char *sqlFormat, /* printf-style format string for the SQL */
4157c478bd9Sstevel@tonic-gate  char ***resultp,       /* Result written to a char *[]  that this points to */
4167c478bd9Sstevel@tonic-gate  int *nrow,             /* Number of result rows written here */
4177c478bd9Sstevel@tonic-gate  int *ncolumn,          /* Number of result columns written here */
4187c478bd9Sstevel@tonic-gate  char **errmsg,         /* Error msg written here */
4197c478bd9Sstevel@tonic-gate  va_list ap             /* Arguments to the format string */
4207c478bd9Sstevel@tonic-gate);
4217c478bd9Sstevel@tonic-gatechar *sqlite_mprintf(const char*,...);
4227c478bd9Sstevel@tonic-gatechar *sqlite_vmprintf(const char*, va_list);
4237c478bd9Sstevel@tonic-gate
4247c478bd9Sstevel@tonic-gate/*
4257c478bd9Sstevel@tonic-gate** Windows systems should call this routine to free memory that
4267c478bd9Sstevel@tonic-gate** is returned in the in the errmsg parameter of sqlite_open() when
4277c478bd9Sstevel@tonic-gate** SQLite is a DLL.  For some reason, it does not work to call free()
4287c478bd9Sstevel@tonic-gate** directly.
4297c478bd9Sstevel@tonic-gate*/
4307c478bd9Sstevel@tonic-gatevoid sqlite_freemem(void *p);
4317c478bd9Sstevel@tonic-gate
4327c478bd9Sstevel@tonic-gate/*
4337c478bd9Sstevel@tonic-gate** Windows systems need functions to call to return the sqlite_version
4347c478bd9Sstevel@tonic-gate** and sqlite_encoding strings.
4357c478bd9Sstevel@tonic-gate*/
4367c478bd9Sstevel@tonic-gateconst char *sqlite_libversion(void);
4377c478bd9Sstevel@tonic-gateconst char *sqlite_libencoding(void);
4387c478bd9Sstevel@tonic-gate
4397c478bd9Sstevel@tonic-gate/*
4407c478bd9Sstevel@tonic-gate** A pointer to the following structure is used to communicate with
4417c478bd9Sstevel@tonic-gate** the implementations of user-defined functions.
4427c478bd9Sstevel@tonic-gate*/
4437c478bd9Sstevel@tonic-gatetypedef struct sqlite_func sqlite_func;
4447c478bd9Sstevel@tonic-gate
4457c478bd9Sstevel@tonic-gate/*
4467c478bd9Sstevel@tonic-gate** Use the following routines to create new user-defined functions.  See
4477c478bd9Sstevel@tonic-gate** the documentation for details.
4487c478bd9Sstevel@tonic-gate*/
4497c478bd9Sstevel@tonic-gateint sqlite_create_function(
4507c478bd9Sstevel@tonic-gate  sqlite*,                  /* Database where the new function is registered */
4517c478bd9Sstevel@tonic-gate  const char *zName,        /* Name of the new function */
4527c478bd9Sstevel@tonic-gate  int nArg,                 /* Number of arguments.  -1 means any number */
4537c478bd9Sstevel@tonic-gate  void (*xFunc)(sqlite_func*,int,const char**),  /* C code to implement */
4547c478bd9Sstevel@tonic-gate  void *pUserData           /* Available via the sqlite_user_data() call */
4557c478bd9Sstevel@tonic-gate);
4567c478bd9Sstevel@tonic-gateint sqlite_create_aggregate(
4577c478bd9Sstevel@tonic-gate  sqlite*,                  /* Database where the new function is registered */
4587c478bd9Sstevel@tonic-gate  const char *zName,        /* Name of the function */
4597c478bd9Sstevel@tonic-gate  int nArg,                 /* Number of arguments */
4607c478bd9Sstevel@tonic-gate  void (*xStep)(sqlite_func*,int,const char**), /* Called for each row */
4617c478bd9Sstevel@tonic-gate  void (*xFinalize)(sqlite_func*),       /* Called once to get final result */
4627c478bd9Sstevel@tonic-gate  void *pUserData           /* Available via the sqlite_user_data() call */
4637c478bd9Sstevel@tonic-gate);
4647c478bd9Sstevel@tonic-gate
4657c478bd9Sstevel@tonic-gate/*
4667c478bd9Sstevel@tonic-gate** Use the following routine to define the datatype returned by a
4677c478bd9Sstevel@tonic-gate** user-defined function.  The second argument can be one of the
4687c478bd9Sstevel@tonic-gate** constants SQLITE_NUMERIC, SQLITE_TEXT, or SQLITE_ARGS or it
4697c478bd9Sstevel@tonic-gate** can be an integer greater than or equal to zero.  When the datatype
4707c478bd9Sstevel@tonic-gate** parameter is non-negative, the type of the result will be the
4717c478bd9Sstevel@tonic-gate** same as the datatype-th argument.  If datatype==SQLITE_NUMERIC
4727c478bd9Sstevel@tonic-gate** then the result is always numeric.  If datatype==SQLITE_TEXT then
4737c478bd9Sstevel@tonic-gate** the result is always text.  If datatype==SQLITE_ARGS then the result
4747c478bd9Sstevel@tonic-gate** is numeric if any argument is numeric and is text otherwise.
4757c478bd9Sstevel@tonic-gate*/
4767c478bd9Sstevel@tonic-gateint sqlite_function_type(
4777c478bd9Sstevel@tonic-gate  sqlite *db,               /* The database there the function is registered */
4787c478bd9Sstevel@tonic-gate  const char *zName,        /* Name of the function */
4797c478bd9Sstevel@tonic-gate  int datatype              /* The datatype for this function */
4807c478bd9Sstevel@tonic-gate);
4817c478bd9Sstevel@tonic-gate#define SQLITE_NUMERIC     (-1)
4827c478bd9Sstevel@tonic-gate#define SQLITE_TEXT        (-2)
4837c478bd9Sstevel@tonic-gate#define SQLITE_ARGS        (-3)
4847c478bd9Sstevel@tonic-gate
4857c478bd9Sstevel@tonic-gate/*
4867c478bd9Sstevel@tonic-gate** The user function implementations call one of the following four routines
4877c478bd9Sstevel@tonic-gate** in order to return their results.  The first parameter to each of these
4887c478bd9Sstevel@tonic-gate** routines is a copy of the first argument to xFunc() or xFinialize().
4897c478bd9Sstevel@tonic-gate** The second parameter to these routines is the result to be returned.
4907c478bd9Sstevel@tonic-gate** A NULL can be passed as the second parameter to sqlite_set_result_string()
4917c478bd9Sstevel@tonic-gate** in order to return a NULL result.
4927c478bd9Sstevel@tonic-gate**
4937c478bd9Sstevel@tonic-gate** The 3rd argument to _string and _error is the number of characters to
4947c478bd9Sstevel@tonic-gate** take from the string.  If this argument is negative, then all characters
4957c478bd9Sstevel@tonic-gate** up to and including the first '\000' are used.
4967c478bd9Sstevel@tonic-gate**
4977c478bd9Sstevel@tonic-gate** The sqlite_set_result_string() function allocates a buffer to hold the
4987c478bd9Sstevel@tonic-gate** result and returns a pointer to this buffer.  The calling routine
4997c478bd9Sstevel@tonic-gate** (that is, the implmentation of a user function) can alter the content
5007c478bd9Sstevel@tonic-gate** of this buffer if desired.
5017c478bd9Sstevel@tonic-gate*/
5027c478bd9Sstevel@tonic-gatechar *sqlite_set_result_string(sqlite_func*,const char*,int);
5037c478bd9Sstevel@tonic-gatevoid sqlite_set_result_int(sqlite_func*,int);
5047c478bd9Sstevel@tonic-gatevoid sqlite_set_result_double(sqlite_func*,double);
5057c478bd9Sstevel@tonic-gatevoid sqlite_set_result_error(sqlite_func*,const char*,int);
5067c478bd9Sstevel@tonic-gate
5077c478bd9Sstevel@tonic-gate/*
5087c478bd9Sstevel@tonic-gate** The pUserData parameter to the sqlite_create_function() and
5097c478bd9Sstevel@tonic-gate** sqlite_create_aggregate() routines used to register user functions
5107c478bd9Sstevel@tonic-gate** is available to the implementation of the function using this
5117c478bd9Sstevel@tonic-gate** call.
5127c478bd9Sstevel@tonic-gate*/
5137c478bd9Sstevel@tonic-gatevoid *sqlite_user_data(sqlite_func*);
5147c478bd9Sstevel@tonic-gate
5157c478bd9Sstevel@tonic-gate/*
5167c478bd9Sstevel@tonic-gate** Aggregate functions use the following routine to allocate
5177c478bd9Sstevel@tonic-gate** a structure for storing their state.  The first time this routine
5187c478bd9Sstevel@tonic-gate** is called for a particular aggregate, a new structure of size nBytes
5197c478bd9Sstevel@tonic-gate** is allocated, zeroed, and returned.  On subsequent calls (for the
5207c478bd9Sstevel@tonic-gate** same aggregate instance) the same buffer is returned.  The implementation
5217c478bd9Sstevel@tonic-gate** of the aggregate can use the returned buffer to accumulate data.
5227c478bd9Sstevel@tonic-gate**
5237c478bd9Sstevel@tonic-gate** The buffer allocated is freed automatically be SQLite.
5247c478bd9Sstevel@tonic-gate*/
5257c478bd9Sstevel@tonic-gatevoid *sqlite_aggregate_context(sqlite_func*, int nBytes);
5267c478bd9Sstevel@tonic-gate
5277c478bd9Sstevel@tonic-gate/*
5287c478bd9Sstevel@tonic-gate** The next routine returns the number of calls to xStep for a particular
5297c478bd9Sstevel@tonic-gate** aggregate function instance.  The current call to xStep counts so this
5307c478bd9Sstevel@tonic-gate** routine always returns at least 1.
5317c478bd9Sstevel@tonic-gate*/
5327c478bd9Sstevel@tonic-gateint sqlite_aggregate_count(sqlite_func*);
5337c478bd9Sstevel@tonic-gate
5347c478bd9Sstevel@tonic-gate/*
5357c478bd9Sstevel@tonic-gate** This routine registers a callback with the SQLite library.  The
5367c478bd9Sstevel@tonic-gate** callback is invoked (at compile-time, not at run-time) for each
5377c478bd9Sstevel@tonic-gate** attempt to access a column of a table in the database.  The callback
5387c478bd9Sstevel@tonic-gate** returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire
5397c478bd9Sstevel@tonic-gate** SQL statement should be aborted with an error and SQLITE_IGNORE
5407c478bd9Sstevel@tonic-gate** if the column should be treated as a NULL value.
5417c478bd9Sstevel@tonic-gate*/
5427c478bd9Sstevel@tonic-gateint sqlite_set_authorizer(
5437c478bd9Sstevel@tonic-gate  sqlite*,
5447c478bd9Sstevel@tonic-gate  int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
5457c478bd9Sstevel@tonic-gate  void *pUserData
5467c478bd9Sstevel@tonic-gate);
5477c478bd9Sstevel@tonic-gate
5487c478bd9Sstevel@tonic-gate/*
5497c478bd9Sstevel@tonic-gate** The second parameter to the access authorization function above will
5507c478bd9Sstevel@tonic-gate** be one of the values below.  These values signify what kind of operation
5517c478bd9Sstevel@tonic-gate** is to be authorized.  The 3rd and 4th parameters to the authorization
5527c478bd9Sstevel@tonic-gate** function will be parameters or NULL depending on which of the following
5537c478bd9Sstevel@tonic-gate** codes is used as the second parameter.  The 5th parameter is the name
5547c478bd9Sstevel@tonic-gate** of the database ("main", "temp", etc.) if applicable.  The 6th parameter
5557c478bd9Sstevel@tonic-gate** is the name of the inner-most trigger or view that is responsible for
556*1da57d55SToomas Soome** the access attempt or NULL if this access attempt is directly from
5577c478bd9Sstevel@tonic-gate** input SQL code.
5587c478bd9Sstevel@tonic-gate**
5597c478bd9Sstevel@tonic-gate**                                          Arg-3           Arg-4
5607c478bd9Sstevel@tonic-gate*/
5617c478bd9Sstevel@tonic-gate#define SQLITE_COPY                  0   /* Table Name      File Name       */
5627c478bd9Sstevel@tonic-gate#define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
5637c478bd9Sstevel@tonic-gate#define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
5647c478bd9Sstevel@tonic-gate#define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
5657c478bd9Sstevel@tonic-gate#define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
5667c478bd9Sstevel@tonic-gate#define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
5677c478bd9Sstevel@tonic-gate#define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */
5687c478bd9Sstevel@tonic-gate#define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */
5697c478bd9Sstevel@tonic-gate#define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */
5707c478bd9Sstevel@tonic-gate#define SQLITE_DELETE                9   /* Table Name      NULL            */
5717c478bd9Sstevel@tonic-gate#define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */
5727c478bd9Sstevel@tonic-gate#define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */
5737c478bd9Sstevel@tonic-gate#define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */
5747c478bd9Sstevel@tonic-gate#define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */
5757c478bd9Sstevel@tonic-gate#define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */
5767c478bd9Sstevel@tonic-gate#define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */
5777c478bd9Sstevel@tonic-gate#define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */
5787c478bd9Sstevel@tonic-gate#define SQLITE_DROP_VIEW            17   /* View Name       NULL            */
5797c478bd9Sstevel@tonic-gate#define SQLITE_INSERT               18   /* Table Name      NULL            */
5807c478bd9Sstevel@tonic-gate#define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */
5817c478bd9Sstevel@tonic-gate#define SQLITE_READ                 20   /* Table Name      Column Name     */
5827c478bd9Sstevel@tonic-gate#define SQLITE_SELECT               21   /* NULL            NULL            */
5837c478bd9Sstevel@tonic-gate#define SQLITE_TRANSACTION          22   /* NULL            NULL            */
5847c478bd9Sstevel@tonic-gate#define SQLITE_UPDATE               23   /* Table Name      Column Name     */
5857c478bd9Sstevel@tonic-gate#define SQLITE_ATTACH               24   /* Filename        NULL            */
5867c478bd9Sstevel@tonic-gate#define SQLITE_DETACH               25   /* Database Name   NULL            */
5877c478bd9Sstevel@tonic-gate
5887c478bd9Sstevel@tonic-gate
5897c478bd9Sstevel@tonic-gate/*
5907c478bd9Sstevel@tonic-gate** The return value of the authorization function should be one of the
5917c478bd9Sstevel@tonic-gate** following constants:
5927c478bd9Sstevel@tonic-gate*/
5937c478bd9Sstevel@tonic-gate/* #define SQLITE_OK  0   // Allow access (This is actually defined above) */
5947c478bd9Sstevel@tonic-gate#define SQLITE_DENY   1   /* Abort the SQL statement with an error */
5957c478bd9Sstevel@tonic-gate#define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
5967c478bd9Sstevel@tonic-gate
5977c478bd9Sstevel@tonic-gate/*
5987c478bd9Sstevel@tonic-gate** Register a function that is called at every invocation of sqlite_exec()
5997c478bd9Sstevel@tonic-gate** or sqlite_compile().  This function can be used (for example) to generate
6007c478bd9Sstevel@tonic-gate** a log file of all SQL executed against a database.
6017c478bd9Sstevel@tonic-gate*/
6027c478bd9Sstevel@tonic-gatevoid *sqlite_trace(sqlite*, void(*xTrace)(void*,const char*), void*);
6037c478bd9Sstevel@tonic-gate
6047c478bd9Sstevel@tonic-gate/*** The Callback-Free API
605*1da57d55SToomas Soome**
6067c478bd9Sstevel@tonic-gate** The following routines implement a new way to access SQLite that does not
6077c478bd9Sstevel@tonic-gate** involve the use of callbacks.
6087c478bd9Sstevel@tonic-gate**
6097c478bd9Sstevel@tonic-gate** An sqlite_vm is an opaque object that represents a single SQL statement
6107c478bd9Sstevel@tonic-gate** that is ready to be executed.
6117c478bd9Sstevel@tonic-gate*/
6127c478bd9Sstevel@tonic-gatetypedef struct sqlite_vm sqlite_vm;
6137c478bd9Sstevel@tonic-gate
6147c478bd9Sstevel@tonic-gate/*
6157c478bd9Sstevel@tonic-gate** To execute an SQLite query without the use of callbacks, you first have
6167c478bd9Sstevel@tonic-gate** to compile the SQL using this routine.  The 1st parameter "db" is a pointer
6177c478bd9Sstevel@tonic-gate** to an sqlite object obtained from sqlite_open().  The 2nd parameter
6187c478bd9Sstevel@tonic-gate** "zSql" is the text of the SQL to be compiled.   The remaining parameters
6197c478bd9Sstevel@tonic-gate** are all outputs.
6207c478bd9Sstevel@tonic-gate**
6217c478bd9Sstevel@tonic-gate** *pzTail is made to point to the first character past the end of the first
6227c478bd9Sstevel@tonic-gate** SQL statement in zSql.  This routine only compiles the first statement
6237c478bd9Sstevel@tonic-gate** in zSql, so *pzTail is left pointing to what remains uncompiled.
6247c478bd9Sstevel@tonic-gate**
6257c478bd9Sstevel@tonic-gate** *ppVm is left pointing to a "virtual machine" that can be used to execute
6267c478bd9Sstevel@tonic-gate** the compiled statement.  Or if there is an error, *ppVm may be set to NULL.
6277c478bd9Sstevel@tonic-gate** If the input text contained no SQL (if the input is and empty string or
6287c478bd9Sstevel@tonic-gate** a comment) then *ppVm is set to NULL.
6297c478bd9Sstevel@tonic-gate**
6307c478bd9Sstevel@tonic-gate** If any errors are detected during compilation, an error message is written
6317c478bd9Sstevel@tonic-gate** into space obtained from malloc() and *pzErrMsg is made to point to that
6327c478bd9Sstevel@tonic-gate** error message.  The calling routine is responsible for freeing the text
6337c478bd9Sstevel@tonic-gate** of this message when it has finished with it.  Use sqlite_freemem() to
6347c478bd9Sstevel@tonic-gate** free the message.  pzErrMsg may be NULL in which case no error message
6357c478bd9Sstevel@tonic-gate** will be generated.
6367c478bd9Sstevel@tonic-gate**
6377c478bd9Sstevel@tonic-gate** On success, SQLITE_OK is returned.  Otherwise and error code is returned.
6387c478bd9Sstevel@tonic-gate*/
6397c478bd9Sstevel@tonic-gateint sqlite_compile(
6407c478bd9Sstevel@tonic-gate  sqlite *db,                   /* The open database */
6417c478bd9Sstevel@tonic-gate  const char *zSql,             /* SQL statement to be compiled */
6427c478bd9Sstevel@tonic-gate  const char **pzTail,          /* OUT: uncompiled tail of zSql */
6437c478bd9Sstevel@tonic-gate  sqlite_vm **ppVm,             /* OUT: the virtual machine to execute zSql */
6447c478bd9Sstevel@tonic-gate  char **pzErrmsg               /* OUT: Error message. */
6457c478bd9Sstevel@tonic-gate);
6467c478bd9Sstevel@tonic-gate
6477c478bd9Sstevel@tonic-gate/*
6487c478bd9Sstevel@tonic-gate** After an SQL statement has been compiled, it is handed to this routine
6497c478bd9Sstevel@tonic-gate** to be executed.  This routine executes the statement as far as it can
6507c478bd9Sstevel@tonic-gate** go then returns.  The return value will be one of SQLITE_DONE,
6517c478bd9Sstevel@tonic-gate** SQLITE_ERROR, SQLITE_BUSY, SQLITE_ROW, or SQLITE_MISUSE.
6527c478bd9Sstevel@tonic-gate**
6537c478bd9Sstevel@tonic-gate** SQLITE_DONE means that the execute of the SQL statement is complete
6547c478bd9Sstevel@tonic-gate** an no errors have occurred.  sqlite_step() should not be called again
6557c478bd9Sstevel@tonic-gate** for the same virtual machine.  *pN is set to the number of columns in
6567c478bd9Sstevel@tonic-gate** the result set and *pazColName is set to an array of strings that
6577c478bd9Sstevel@tonic-gate** describe the column names and datatypes.  The name of the i-th column
6587c478bd9Sstevel@tonic-gate** is (*pazColName)[i] and the datatype of the i-th column is
6597c478bd9Sstevel@tonic-gate** (*pazColName)[i+*pN].  *pazValue is set to NULL.
6607c478bd9Sstevel@tonic-gate**
6617c478bd9Sstevel@tonic-gate** SQLITE_ERROR means that the virtual machine encountered a run-time
6627c478bd9Sstevel@tonic-gate** error.  sqlite_step() should not be called again for the same
6637c478bd9Sstevel@tonic-gate** virtual machine.  *pN is set to 0 and *pazColName and *pazValue are set
6647c478bd9Sstevel@tonic-gate** to NULL.  Use sqlite_finalize() to obtain the specific error code
6657c478bd9Sstevel@tonic-gate** and the error message text for the error.
6667c478bd9Sstevel@tonic-gate**
6677c478bd9Sstevel@tonic-gate** SQLITE_BUSY means that an attempt to open the database failed because
6687c478bd9Sstevel@tonic-gate** another thread or process is holding a lock.  The calling routine
6697c478bd9Sstevel@tonic-gate** can try again to open the database by calling sqlite_step() again.
6707c478bd9Sstevel@tonic-gate** The return code will only be SQLITE_BUSY if no busy handler is registered
6717c478bd9Sstevel@tonic-gate** using the sqlite_busy_handler() or sqlite_busy_timeout() routines.  If
6727c478bd9Sstevel@tonic-gate** a busy handler callback has been registered but returns 0, then this
6737c478bd9Sstevel@tonic-gate** routine will return SQLITE_ERROR and sqltie_finalize() will return
6747c478bd9Sstevel@tonic-gate** SQLITE_BUSY when it is called.
6757c478bd9Sstevel@tonic-gate**
6767c478bd9Sstevel@tonic-gate** SQLITE_ROW means that a single row of the result is now available.
6777c478bd9Sstevel@tonic-gate** The data is contained in *pazValue.  The value of the i-th column is
6787c478bd9Sstevel@tonic-gate** (*azValue)[i].  *pN and *pazColName are set as described in SQLITE_DONE.
6797c478bd9Sstevel@tonic-gate** Invoke sqlite_step() again to advance to the next row.
6807c478bd9Sstevel@tonic-gate**
6817c478bd9Sstevel@tonic-gate** SQLITE_MISUSE is returned if sqlite_step() is called incorrectly.
6827c478bd9Sstevel@tonic-gate** For example, if you call sqlite_step() after the virtual machine
6837c478bd9Sstevel@tonic-gate** has halted (after a prior call to sqlite_step() has returned SQLITE_DONE)
6847c478bd9Sstevel@tonic-gate** or if you call sqlite_step() with an incorrectly initialized virtual
6857c478bd9Sstevel@tonic-gate** machine or a virtual machine that has been deleted or that is associated
6867c478bd9Sstevel@tonic-gate** with an sqlite structure that has been closed.
6877c478bd9Sstevel@tonic-gate*/
6887c478bd9Sstevel@tonic-gateint sqlite_step(
6897c478bd9Sstevel@tonic-gate  sqlite_vm *pVm,              /* The virtual machine to execute */
6907c478bd9Sstevel@tonic-gate  int *pN,                     /* OUT: Number of columns in result */
6917c478bd9Sstevel@tonic-gate  const char ***pazValue,      /* OUT: Column data */
6927c478bd9Sstevel@tonic-gate  const char ***pazColName     /* OUT: Column names and datatypes */
6937c478bd9Sstevel@tonic-gate);
6947c478bd9Sstevel@tonic-gate
6957c478bd9Sstevel@tonic-gate/*
6967c478bd9Sstevel@tonic-gate** This routine is called to delete a virtual machine after it has finished
6977c478bd9Sstevel@tonic-gate** executing.  The return value is the result code.  SQLITE_OK is returned
6987c478bd9Sstevel@tonic-gate** if the statement executed successfully and some other value is returned if
6997c478bd9Sstevel@tonic-gate** there was any kind of error.  If an error occurred and pzErrMsg is not
7007c478bd9Sstevel@tonic-gate** NULL, then an error message is written into memory obtained from malloc()
7017c478bd9Sstevel@tonic-gate** and *pzErrMsg is made to point to that error message.  The calling routine
7027c478bd9Sstevel@tonic-gate** should use sqlite_freemem() to delete this message when it has finished
7037c478bd9Sstevel@tonic-gate** with it.
7047c478bd9Sstevel@tonic-gate**
7057c478bd9Sstevel@tonic-gate** This routine can be called at any point during the execution of the
7067c478bd9Sstevel@tonic-gate** virtual machine.  If the virtual machine has not completed execution
7077c478bd9Sstevel@tonic-gate** when this routine is called, that is like encountering an error or
7087c478bd9Sstevel@tonic-gate** an interrupt.  (See sqlite_interrupt().)  Incomplete updates may be
7097c478bd9Sstevel@tonic-gate** rolled back and transactions cancelled,  depending on the circumstances,
7107c478bd9Sstevel@tonic-gate** and the result code returned will be SQLITE_ABORT.
7117c478bd9Sstevel@tonic-gate*/
7127c478bd9Sstevel@tonic-gateint sqlite_finalize(sqlite_vm*, char **pzErrMsg);
7137c478bd9Sstevel@tonic-gate
7147c478bd9Sstevel@tonic-gate/*
7157c478bd9Sstevel@tonic-gate** This routine deletes the virtual machine, writes any error message to
7167c478bd9Sstevel@tonic-gate** *pzErrMsg and returns an SQLite return code in the same way as the
7177c478bd9Sstevel@tonic-gate** sqlite_finalize() function.
7187c478bd9Sstevel@tonic-gate**
7197c478bd9Sstevel@tonic-gate** Additionally, if ppVm is not NULL, *ppVm is left pointing to a new virtual
7207c478bd9Sstevel@tonic-gate** machine loaded with the compiled version of the original query ready for
7217c478bd9Sstevel@tonic-gate** execution.
7227c478bd9Sstevel@tonic-gate**
7237c478bd9Sstevel@tonic-gate** If sqlite_reset() returns SQLITE_SCHEMA, then *ppVm is set to NULL.
7247c478bd9Sstevel@tonic-gate**
7257c478bd9Sstevel@tonic-gate******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
7267c478bd9Sstevel@tonic-gate*/
7277c478bd9Sstevel@tonic-gateint sqlite_reset(sqlite_vm*, char **pzErrMsg);
7287c478bd9Sstevel@tonic-gate
7297c478bd9Sstevel@tonic-gate/*
7307c478bd9Sstevel@tonic-gate** If the SQL that was handed to sqlite_compile contains variables that
7317c478bd9Sstevel@tonic-gate** are represeted in the SQL text by a question mark ('?').  This routine
7327c478bd9Sstevel@tonic-gate** is used to assign values to those variables.
7337c478bd9Sstevel@tonic-gate**
7347c478bd9Sstevel@tonic-gate** The first parameter is a virtual machine obtained from sqlite_compile().
7357c478bd9Sstevel@tonic-gate** The 2nd "idx" parameter determines which variable in the SQL statement
7367c478bd9Sstevel@tonic-gate** to bind the value to.  The left most '?' is 1.  The 3rd parameter is
7377c478bd9Sstevel@tonic-gate** the value to assign to that variable.  The 4th parameter is the number
7387c478bd9Sstevel@tonic-gate** of bytes in the value, including the terminating \000 for strings.
7397c478bd9Sstevel@tonic-gate** Finally, the 5th "copy" parameter is TRUE if SQLite should make its
7407c478bd9Sstevel@tonic-gate** own private copy of this value, or false if the space that the 3rd
7417c478bd9Sstevel@tonic-gate** parameter points to will be unchanging and can be used directly by
7427c478bd9Sstevel@tonic-gate** SQLite.
7437c478bd9Sstevel@tonic-gate**
7447c478bd9Sstevel@tonic-gate** Unbound variables are treated as having a value of NULL.  To explicitly
7457c478bd9Sstevel@tonic-gate** set a variable to NULL, call this routine with the 3rd parameter as a
7467c478bd9Sstevel@tonic-gate** NULL pointer.
7477c478bd9Sstevel@tonic-gate**
7487c478bd9Sstevel@tonic-gate** If the 4th "len" parameter is -1, then strlen() is used to find the
7497c478bd9Sstevel@tonic-gate** length.
7507c478bd9Sstevel@tonic-gate**
7517c478bd9Sstevel@tonic-gate** This routine can only be called immediately after sqlite_compile()
7527c478bd9Sstevel@tonic-gate** or sqlite_reset() and before any calls to sqlite_step().
7537c478bd9Sstevel@tonic-gate**
7547c478bd9Sstevel@tonic-gate******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
7557c478bd9Sstevel@tonic-gate*/
7567c478bd9Sstevel@tonic-gateint sqlite_bind(sqlite_vm*, int idx, const char *value, int len, int copy);
7577c478bd9Sstevel@tonic-gate
7587c478bd9Sstevel@tonic-gate/*
7597c478bd9Sstevel@tonic-gate** This routine configures a callback function - the progress callback - that
7607c478bd9Sstevel@tonic-gate** is invoked periodically during long running calls to sqlite_exec(),
7617c478bd9Sstevel@tonic-gate** sqlite_step() and sqlite_get_table(). An example use for this API is to keep
7627c478bd9Sstevel@tonic-gate** a GUI updated during a large query.
7637c478bd9Sstevel@tonic-gate**
7647c478bd9Sstevel@tonic-gate** The progress callback is invoked once for every N virtual machine opcodes,
7657c478bd9Sstevel@tonic-gate** where N is the second argument to this function. The progress callback
7667c478bd9Sstevel@tonic-gate** itself is identified by the third argument to this function. The fourth
7677c478bd9Sstevel@tonic-gate** argument to this function is a void pointer passed to the progress callback
7687c478bd9Sstevel@tonic-gate** function each time it is invoked.
7697c478bd9Sstevel@tonic-gate**
770*1da57d55SToomas Soome** If a call to sqlite_exec(), sqlite_step() or sqlite_get_table() results
7717c478bd9Sstevel@tonic-gate** in less than N opcodes being executed, then the progress callback is not
7727c478bd9Sstevel@tonic-gate** invoked.
773*1da57d55SToomas Soome**
7747c478bd9Sstevel@tonic-gate** Calling this routine overwrites any previously installed progress callback.
7757c478bd9Sstevel@tonic-gate** To remove the progress callback altogether, pass NULL as the third
7767c478bd9Sstevel@tonic-gate** argument to this function.
7777c478bd9Sstevel@tonic-gate**
778*1da57d55SToomas Soome** If the progress callback returns a result other than 0, then the current
7797c478bd9Sstevel@tonic-gate** query is immediately terminated and any database changes rolled back. If the
7807c478bd9Sstevel@tonic-gate** query was part of a larger transaction, then the transaction is not rolled
781*1da57d55SToomas Soome** back and remains active. The sqlite_exec() call returns SQLITE_ABORT.
7827c478bd9Sstevel@tonic-gate**
7837c478bd9Sstevel@tonic-gate******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
7847c478bd9Sstevel@tonic-gate*/
7857c478bd9Sstevel@tonic-gatevoid sqlite_progress_handler(sqlite*, int, int(*)(void*), void*);
7867c478bd9Sstevel@tonic-gate
7877c478bd9Sstevel@tonic-gate/*
7887c478bd9Sstevel@tonic-gate** Register a callback function to be invoked whenever a new transaction
7897c478bd9Sstevel@tonic-gate** is committed.  The pArg argument is passed through to the callback.
7907c478bd9Sstevel@tonic-gate** callback.  If the callback function returns non-zero, then the commit
7917c478bd9Sstevel@tonic-gate** is converted into a rollback.
7927c478bd9Sstevel@tonic-gate**
7937c478bd9Sstevel@tonic-gate** If another function was previously registered, its pArg value is returned.
7947c478bd9Sstevel@tonic-gate** Otherwise NULL is returned.
7957c478bd9Sstevel@tonic-gate**
7967c478bd9Sstevel@tonic-gate** Registering a NULL function disables the callback.
7977c478bd9Sstevel@tonic-gate**
7987c478bd9Sstevel@tonic-gate******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
7997c478bd9Sstevel@tonic-gate*/
8007c478bd9Sstevel@tonic-gatevoid *sqlite_commit_hook(sqlite*, int(*)(void*), void*);
8017c478bd9Sstevel@tonic-gate
8027c478bd9Sstevel@tonic-gate/*
8037c478bd9Sstevel@tonic-gate** Open an encrypted SQLite database.  If pKey==0 or nKey==0, this routine
8047c478bd9Sstevel@tonic-gate** is the same as sqlite_open().
8057c478bd9Sstevel@tonic-gate**
8067c478bd9Sstevel@tonic-gate** The code to implement this API is not available in the public release
8077c478bd9Sstevel@tonic-gate** of SQLite.
8087c478bd9Sstevel@tonic-gate*/
8097c478bd9Sstevel@tonic-gatesqlite *sqlite_open_encrypted(
8107c478bd9Sstevel@tonic-gate  const char *zFilename,   /* Name of the encrypted database */
8117c478bd9Sstevel@tonic-gate  const void *pKey,        /* Pointer to the key */
8127c478bd9Sstevel@tonic-gate  int nKey,                /* Number of bytes in the key */
8137c478bd9Sstevel@tonic-gate  int *pErrcode,           /* Write error code here */
8147c478bd9Sstevel@tonic-gate  char **pzErrmsg          /* Write error message here */
8157c478bd9Sstevel@tonic-gate);
8167c478bd9Sstevel@tonic-gate
8177c478bd9Sstevel@tonic-gate/*
8187c478bd9Sstevel@tonic-gate** Change the key on an open database.  If the current database is not
8197c478bd9Sstevel@tonic-gate** encrypted, this routine will encrypt it.  If pNew==0 or nNew==0, the
8207c478bd9Sstevel@tonic-gate** database is decrypted.
8217c478bd9Sstevel@tonic-gate**
8227c478bd9Sstevel@tonic-gate** The code to implement this API is not available in the public release
8237c478bd9Sstevel@tonic-gate** of SQLite.
8247c478bd9Sstevel@tonic-gate*/
8257c478bd9Sstevel@tonic-gateint sqlite_rekey(
8267c478bd9Sstevel@tonic-gate  sqlite *db,                    /* Database to be rekeyed */
8277c478bd9Sstevel@tonic-gate  const void *pKey, int nKey     /* The new key */
8287c478bd9Sstevel@tonic-gate);
8297c478bd9Sstevel@tonic-gate
8307c478bd9Sstevel@tonic-gate/*
8317c478bd9Sstevel@tonic-gate** Encode a binary buffer "in" of size n bytes so that it contains
832*1da57d55SToomas Soome** no instances of characters '\'' or '\000'.  The output is
8337c478bd9Sstevel@tonic-gate** null-terminated and can be used as a string value in an INSERT
8347c478bd9Sstevel@tonic-gate** or UPDATE statement.  Use sqlite_decode_binary() to convert the
8357c478bd9Sstevel@tonic-gate** string back into its original binary.
8367c478bd9Sstevel@tonic-gate**
8377c478bd9Sstevel@tonic-gate** The result is written into a preallocated output buffer "out".
8387c478bd9Sstevel@tonic-gate** "out" must be able to hold at least 2 +(257*n)/254 bytes.
8397c478bd9Sstevel@tonic-gate** In other words, the output will be expanded by as much as 3
8407c478bd9Sstevel@tonic-gate** bytes for every 254 bytes of input plus 2 bytes of fixed overhead.
8417c478bd9Sstevel@tonic-gate** (This is approximately 2 + 1.0118*n or about a 1.2% size increase.)
8427c478bd9Sstevel@tonic-gate**
8437c478bd9Sstevel@tonic-gate** The return value is the number of characters in the encoded
8447c478bd9Sstevel@tonic-gate** string, excluding the "\000" terminator.
8457c478bd9Sstevel@tonic-gate**
8467c478bd9Sstevel@tonic-gate** If out==NULL then no output is generated but the routine still returns
8477c478bd9Sstevel@tonic-gate** the number of characters that would have been generated if out had
8487c478bd9Sstevel@tonic-gate** not been NULL.
8497c478bd9Sstevel@tonic-gate*/
8507c478bd9Sstevel@tonic-gateint sqlite_encode_binary(const unsigned char *in, int n, unsigned char *out);
8517c478bd9Sstevel@tonic-gate
8527c478bd9Sstevel@tonic-gate/*
8537c478bd9Sstevel@tonic-gate** Decode the string "in" into binary data and write it into "out".
8547c478bd9Sstevel@tonic-gate** This routine reverses the encoding created by sqlite_encode_binary().
8557c478bd9Sstevel@tonic-gate** The output will always be a few bytes less than the input.  The number
8567c478bd9Sstevel@tonic-gate** of bytes of output is returned.  If the input is not a well-formed
8577c478bd9Sstevel@tonic-gate** encoding, -1 is returned.
8587c478bd9Sstevel@tonic-gate**
8597c478bd9Sstevel@tonic-gate** The "in" and "out" parameters may point to the same buffer in order
8607c478bd9Sstevel@tonic-gate** to decode a string in place.
8617c478bd9Sstevel@tonic-gate*/
8627c478bd9Sstevel@tonic-gateint sqlite_decode_binary(const unsigned char *in, unsigned char *out);
8637c478bd9Sstevel@tonic-gate
8647c478bd9Sstevel@tonic-gate#ifdef __cplusplus
8657c478bd9Sstevel@tonic-gate}  /* End of the 'extern "C"' block */
8667c478bd9Sstevel@tonic-gate#endif
8677c478bd9Sstevel@tonic-gate
8687c478bd9Sstevel@tonic-gate#endif /* _SQLITE_H_ */
869