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