blob: 426ba73574392bc67c84f4e6cbdf2a4ffb930bc8 [file] [log] [blame]
drh75897232000-05-29 14:26:00 +00001/*
drhb19a2bc2001-09-16 00:13:26 +00002** 2001 September 15
drh75897232000-05-29 14:26:00 +00003**
drhb19a2bc2001-09-16 00:13:26 +00004** The author disclaims copyright to this source code. In place of
5** a legal notice, here is a blessing:
drh75897232000-05-29 14:26:00 +00006**
drhb19a2bc2001-09-16 00:13:26 +00007** May you do good and not evil.
8** May you find forgiveness for yourself and forgive others.
9** May you share freely, never taking more than you give.
drh75897232000-05-29 14:26:00 +000010**
11*************************************************************************
drhb19a2bc2001-09-16 00:13:26 +000012** This header file defines the interface that the SQLite library
drh75897232000-05-29 14:26:00 +000013** presents to client programs.
14**
danielk1977c69cdfd2006-06-17 09:39:55 +000015** @(#) $Id: sqlite.h.in,v 1.180 2006/06/17 09:39:56 danielk1977 Exp $
drh75897232000-05-29 14:26:00 +000016*/
drh12057d52004-09-06 17:34:12 +000017#ifndef _SQLITE3_H_
18#define _SQLITE3_H_
drha18c5682000-10-08 22:20:57 +000019#include <stdarg.h> /* Needed for the definition of va_list */
drh75897232000-05-29 14:26:00 +000020
21/*
drh382c0242001-10-06 16:33:02 +000022** Make sure we can call this stuff from C++.
23*/
24#ifdef __cplusplus
25extern "C" {
26#endif
27
28/*
drhb86ccfb2003-01-28 23:13:10 +000029** The version of the SQLite library.
30*/
drh1e284f42004-10-06 15:52:01 +000031#ifdef SQLITE_VERSION
32# undef SQLITE_VERSION
drh1e284f42004-10-06 15:52:01 +000033#endif
danielk197799ba19e2005-02-05 07:33:34 +000034#define SQLITE_VERSION "--VERS--"
35
36/*
37** The format of the version string is "X.Y.Z<trailing string>", where
38** X is the major version number, Y is the minor version number and Z
39** is the release number. The trailing string is often "alpha" or "beta".
40** For example "3.1.1beta".
41**
42** The SQLITE_VERSION_NUMBER is an integer with the value
43** (X*100000 + Y*1000 + Z). For example, for version "3.1.1beta",
44** SQLITE_VERSION_NUMBER is set to 3001001. To detect if they are using
45** version 3.1.1 or greater at compile time, programs may use the test
46** (SQLITE_VERSION_NUMBER>=3001001).
47*/
48#ifdef SQLITE_VERSION_NUMBER
49# undef SQLITE_VERSION_NUMBER
50#endif
51#define SQLITE_VERSION_NUMBER --VERSION-NUMBER--
drhb86ccfb2003-01-28 23:13:10 +000052
53/*
drhb217a572000-08-22 13:40:18 +000054** The version string is also compiled into the library so that a program
55** can check to make sure that the lib*.a file and the *.h file are from
drh6f3a3ef2004-08-28 18:21:21 +000056** the same version. The sqlite3_libversion() function returns a pointer
57** to the sqlite3_version variable - useful in DLLs which cannot access
58** global variables.
drhb217a572000-08-22 13:40:18 +000059*/
danielk19776f8a5032004-05-10 10:34:51 +000060extern const char sqlite3_version[];
drha3f70cb2004-09-30 14:24:50 +000061const char *sqlite3_libversion(void);
drh303aaa72000-08-17 10:22:34 +000062
63/*
danielk197799ba19e2005-02-05 07:33:34 +000064** Return the value of the SQLITE_VERSION_NUMBER macro when the
65** library was compiled.
66*/
67int sqlite3_libversion_number(void);
68
69/*
drh75897232000-05-29 14:26:00 +000070** Each open sqlite database is represented by an instance of the
71** following opaque structure.
72*/
drh9bb575f2004-09-06 17:24:11 +000073typedef struct sqlite3 sqlite3;
danielk197765904932004-05-26 06:18:37 +000074
drh75897232000-05-29 14:26:00 +000075
76/*
drhefad9992004-06-22 12:13:55 +000077** Some compilers do not support the "long long" datatype. So we have
78** to do a typedef that for 64-bit integers that depends on what compiler
79** is being used.
80*/
drh27436af2006-03-28 23:57:17 +000081#ifdef SQLITE_INT64_TYPE
drh9b8f4472006-04-04 01:54:55 +000082 typedef SQLITE_INT64_TYPE sqlite_int64;
drh27436af2006-03-28 23:57:17 +000083 typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
84#elif defined(_MSC_VER) || defined(__BORLANDC__)
drhefad9992004-06-22 12:13:55 +000085 typedef __int64 sqlite_int64;
drh1211de32004-07-26 12:24:22 +000086 typedef unsigned __int64 sqlite_uint64;
drhefad9992004-06-22 12:13:55 +000087#else
88 typedef long long int sqlite_int64;
drh1211de32004-07-26 12:24:22 +000089 typedef unsigned long long int sqlite_uint64;
drhefad9992004-06-22 12:13:55 +000090#endif
91
drhb37df7b2005-10-13 02:09:49 +000092/*
93** If compiling for a processor that lacks floating point support,
94** substitute integer for floating-point
95*/
96#ifdef SQLITE_OMIT_FLOATING_POINT
97# define double sqlite_int64
98#endif
drhefad9992004-06-22 12:13:55 +000099
100/*
drh75897232000-05-29 14:26:00 +0000101** A function to close the database.
102**
103** Call this function with a pointer to a structure that was previously
danielk19776f8a5032004-05-10 10:34:51 +0000104** returned from sqlite3_open() and the corresponding database will by closed.
danielk197796d81f92004-06-19 03:33:57 +0000105**
106** All SQL statements prepared using sqlite3_prepare() or
107** sqlite3_prepare16() must be deallocated using sqlite3_finalize() before
108** this routine is called. Otherwise, SQLITE_BUSY is returned and the
109** database connection remains open.
drh75897232000-05-29 14:26:00 +0000110*/
danielk1977f9d64d22004-06-19 08:18:07 +0000111int sqlite3_close(sqlite3 *);
drh75897232000-05-29 14:26:00 +0000112
113/*
114** The type for a callback function.
115*/
drh12057d52004-09-06 17:34:12 +0000116typedef int (*sqlite3_callback)(void*,int,char**, char**);
drh75897232000-05-29 14:26:00 +0000117
118/*
119** A function to executes one or more statements of SQL.
120**
121** If one or more of the SQL statements are queries, then
122** the callback function specified by the 3rd parameter is
123** invoked once for each row of the query result. This callback
124** should normally return 0. If the callback returns a non-zero
125** value then the query is aborted, all subsequent SQL statements
danielk19776f8a5032004-05-10 10:34:51 +0000126** are skipped and the sqlite3_exec() function returns the SQLITE_ABORT.
drh75897232000-05-29 14:26:00 +0000127**
128** The 4th parameter is an arbitrary pointer that is passed
129** to the callback function as its first parameter.
130**
131** The 2nd parameter to the callback function is the number of
drhb19a2bc2001-09-16 00:13:26 +0000132** columns in the query result. The 3rd parameter to the callback
133** is an array of strings holding the values for each column.
134** The 4th parameter to the callback is an array of strings holding
135** the names of each column.
drh75897232000-05-29 14:26:00 +0000136**
137** The callback function may be NULL, even for queries. A NULL
138** callback is not an error. It just means that no callback
139** will be invoked.
140**
141** If an error occurs while parsing or evaluating the SQL (but
142** not while executing the callback) then an appropriate error
143** message is written into memory obtained from malloc() and
drhb19a2bc2001-09-16 00:13:26 +0000144** *errmsg is made to point to that message. The calling function
145** is responsible for freeing the memory that holds the error
drh3f4fedb2004-05-31 19:34:33 +0000146** message. Use sqlite3_free() for this. If errmsg==NULL,
drhb86ccfb2003-01-28 23:13:10 +0000147** then no error message is ever written.
drhb19a2bc2001-09-16 00:13:26 +0000148**
149** The return value is is SQLITE_OK if there are no errors and
150** some other return code if there is an error. The particular
151** return value depends on the type of error.
drh58b95762000-06-02 01:17:37 +0000152**
153** If the query could not be executed because a database file is
drh2dfbbca2000-07-28 14:32:48 +0000154** locked or busy, then this function returns SQLITE_BUSY. (This
danielk19776f8a5032004-05-10 10:34:51 +0000155** behavior can be modified somewhat using the sqlite3_busy_handler()
156** and sqlite3_busy_timeout() functions below.)
drh75897232000-05-29 14:26:00 +0000157*/
danielk19776f8a5032004-05-10 10:34:51 +0000158int sqlite3_exec(
drh12057d52004-09-06 17:34:12 +0000159 sqlite3*, /* An open database */
drh9f71c2e2001-11-03 23:57:09 +0000160 const char *sql, /* SQL to be executed */
drh12057d52004-09-06 17:34:12 +0000161 sqlite3_callback, /* Callback function */
drh75897232000-05-29 14:26:00 +0000162 void *, /* 1st argument to callback function */
163 char **errmsg /* Error msg written here */
164);
165
drh58b95762000-06-02 01:17:37 +0000166/*
danielk19776f8a5032004-05-10 10:34:51 +0000167** Return values for sqlite3_exec() and sqlite3_step()
drh58b95762000-06-02 01:17:37 +0000168*/
drh717e6402001-09-27 03:22:32 +0000169#define SQLITE_OK 0 /* Successful result */
drh15b9a152006-01-31 20:49:13 +0000170/* beginning-of-error-codes */
drh717e6402001-09-27 03:22:32 +0000171#define SQLITE_ERROR 1 /* SQL error or missing database */
drh2db0bbc2005-08-11 02:10:18 +0000172#define SQLITE_INTERNAL 2 /* NOT USED. Internal logic error in SQLite */
drh717e6402001-09-27 03:22:32 +0000173#define SQLITE_PERM 3 /* Access permission denied */
174#define SQLITE_ABORT 4 /* Callback routine requested an abort */
175#define SQLITE_BUSY 5 /* The database file is locked */
176#define SQLITE_LOCKED 6 /* A table in the database is locked */
177#define SQLITE_NOMEM 7 /* A malloc() failed */
178#define SQLITE_READONLY 8 /* Attempt to write a readonly database */
drh24cd67e2004-05-10 16:18:47 +0000179#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
drh717e6402001-09-27 03:22:32 +0000180#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
181#define SQLITE_CORRUPT 11 /* The database disk image is malformed */
drh2db0bbc2005-08-11 02:10:18 +0000182#define SQLITE_NOTFOUND 12 /* NOT USED. Table or record not found */
drh717e6402001-09-27 03:22:32 +0000183#define SQLITE_FULL 13 /* Insertion failed because database is full */
184#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
185#define SQLITE_PROTOCOL 15 /* Database lock protocol error */
drh24cd67e2004-05-10 16:18:47 +0000186#define SQLITE_EMPTY 16 /* Database is empty */
drh717e6402001-09-27 03:22:32 +0000187#define SQLITE_SCHEMA 17 /* The database schema changed */
drh2db0bbc2005-08-11 02:10:18 +0000188#define SQLITE_TOOBIG 18 /* NOT USED. Too much data for one row */
drh717e6402001-09-27 03:22:32 +0000189#define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */
drh8aff1012001-12-22 14:49:24 +0000190#define SQLITE_MISMATCH 20 /* Data type mismatch */
drh247be432002-05-10 05:44:55 +0000191#define SQLITE_MISUSE 21 /* Library used incorrectly */
drh8766c342002-11-09 00:33:15 +0000192#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
drhed6c8672003-01-12 18:02:16 +0000193#define SQLITE_AUTH 23 /* Authorization denied */
drh1c2d8412003-03-31 00:30:47 +0000194#define SQLITE_FORMAT 24 /* Auxiliary database format error */
danielk19776f8a5032004-05-10 10:34:51 +0000195#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
drhc602f9a2004-02-12 19:01:04 +0000196#define SQLITE_NOTADB 26 /* File opened that is not a database file */
danielk19776f8a5032004-05-10 10:34:51 +0000197#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
198#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
drh15b9a152006-01-31 20:49:13 +0000199/* end-of-error-codes */
drh717e6402001-09-27 03:22:32 +0000200
drhaf9ff332002-01-16 21:00:27 +0000201/*
202** Each entry in an SQLite table has a unique integer key. (The key is
203** the value of the INTEGER PRIMARY KEY column if there is such a column,
204** otherwise the key is generated at random. The unique key is always
205** available as the ROWID, OID, or _ROWID_ column.) The following routine
206** returns the integer key of the most recent insert in the database.
207**
208** This function is similar to the mysql_insert_id() function from MySQL.
209*/
drhefad9992004-06-22 12:13:55 +0000210sqlite_int64 sqlite3_last_insert_rowid(sqlite3*);
drhaf9ff332002-01-16 21:00:27 +0000211
drhc8d30ac2002-04-12 10:08:59 +0000212/*
213** This function returns the number of database rows that were changed
danielk19776f8a5032004-05-10 10:34:51 +0000214** (or inserted or deleted) by the most recent called sqlite3_exec().
drhc8d30ac2002-04-12 10:08:59 +0000215**
216** All changes are counted, even if they were later undone by a
217** ROLLBACK or ABORT. Except, changes associated with creating and
218** dropping tables are not counted.
219**
danielk19776f8a5032004-05-10 10:34:51 +0000220** If a callback invokes sqlite3_exec() recursively, then the changes
drhc8d30ac2002-04-12 10:08:59 +0000221** in the inner, recursive call are counted together with the changes
222** in the outer call.
223**
224** SQLite implements the command "DELETE FROM table" without a WHERE clause
225** by dropping and recreating the table. (This is much faster than going
226** through and deleting individual elements form the table.) Because of
227** this optimization, the change count for "DELETE FROM table" will be
228** zero regardless of the number of elements that were originally in the
229** table. To get an accurate count of the number of rows deleted, use
230** "DELETE FROM table WHERE 1" instead.
231*/
danielk1977f9d64d22004-06-19 08:18:07 +0000232int sqlite3_changes(sqlite3*);
drhc8d30ac2002-04-12 10:08:59 +0000233
rdcf146a772004-02-25 22:51:06 +0000234/*
danielk1977b28af712004-06-21 06:50:26 +0000235** This function returns the number of database rows that have been
236** modified by INSERT, UPDATE or DELETE statements since the database handle
237** was opened. This includes UPDATE, INSERT and DELETE statements executed
238** as part of trigger programs. All changes are counted as soon as the
239** statement that makes them is completed (when the statement handle is
240** passed to sqlite3_reset() or sqlite_finalise()).
rdcf146a772004-02-25 22:51:06 +0000241**
242** SQLite implements the command "DELETE FROM table" without a WHERE clause
243** by dropping and recreating the table. (This is much faster than going
244** through and deleting individual elements form the table.) Because of
245** this optimization, the change count for "DELETE FROM table" will be
246** zero regardless of the number of elements that were originally in the
247** table. To get an accurate count of the number of rows deleted, use
248** "DELETE FROM table WHERE 1" instead.
rdcf146a772004-02-25 22:51:06 +0000249*/
danielk1977b28af712004-06-21 06:50:26 +0000250int sqlite3_total_changes(sqlite3*);
251
drh4c504392000-10-16 22:06:40 +0000252/* This function causes any pending database operation to abort and
253** return at its earliest opportunity. This routine is typically
drh66b89c82000-11-28 20:47:17 +0000254** called in response to a user action such as pressing "Cancel"
drh4c504392000-10-16 22:06:40 +0000255** or Ctrl-C where the user wants a long query operation to halt
256** immediately.
257*/
danielk1977f9d64d22004-06-19 08:18:07 +0000258void sqlite3_interrupt(sqlite3*);
drh4c504392000-10-16 22:06:40 +0000259
drheec553b2000-06-02 01:51:20 +0000260
danielk197761de0d12004-05-27 23:56:16 +0000261/* These functions return true if the given input string comprises
262** one or more complete SQL statements. For the sqlite3_complete() call,
263** the parameter must be a nul-terminated UTF-8 string. For
264** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string
265** is required.
drh75897232000-05-29 14:26:00 +0000266**
267** The algorithm is simple. If the last token other than spaces
268** and comments is a semicolon, then return true. otherwise return
269** false.
270*/
danielk19776f8a5032004-05-10 10:34:51 +0000271int sqlite3_complete(const char *sql);
danielk197761de0d12004-05-27 23:56:16 +0000272int sqlite3_complete16(const void *sql);
drh75897232000-05-29 14:26:00 +0000273
drh2dfbbca2000-07-28 14:32:48 +0000274/*
275** This routine identifies a callback function that is invoked
276** whenever an attempt is made to open a database table that is
277** currently locked by another process or thread. If the busy callback
danielk19776f8a5032004-05-10 10:34:51 +0000278** is NULL, then sqlite3_exec() returns SQLITE_BUSY immediately if
drh2dfbbca2000-07-28 14:32:48 +0000279** it finds a locked table. If the busy callback is not NULL, then
danielk19776f8a5032004-05-10 10:34:51 +0000280** sqlite3_exec() invokes the callback with three arguments. The
drh2dfbbca2000-07-28 14:32:48 +0000281** second argument is the name of the locked table and the third
282** argument is the number of times the table has been busy. If the
danielk19776f8a5032004-05-10 10:34:51 +0000283** busy callback returns 0, then sqlite3_exec() immediately returns
284** SQLITE_BUSY. If the callback returns non-zero, then sqlite3_exec()
drh2dfbbca2000-07-28 14:32:48 +0000285** tries to open the table again and the cycle repeats.
286**
287** The default busy callback is NULL.
288**
289** Sqlite is re-entrant, so the busy handler may start a new query.
290** (It is not clear why anyone would every want to do this, but it
291** is allowed, in theory.) But the busy handler may not close the
292** database. Closing the database from a busy handler will delete
293** data structures out from under the executing query and will
294** probably result in a coredump.
295*/
danielk1977f9d64d22004-06-19 08:18:07 +0000296int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
drh2dfbbca2000-07-28 14:32:48 +0000297
298/*
299** This routine sets a busy handler that sleeps for a while when a
300** table is locked. The handler will sleep multiple times until
301** at least "ms" milleseconds of sleeping have been done. After
302** "ms" milleseconds of sleeping, the handler returns 0 which
danielk19776f8a5032004-05-10 10:34:51 +0000303** causes sqlite3_exec() to return SQLITE_BUSY.
drh2dfbbca2000-07-28 14:32:48 +0000304**
305** Calling this routine with an argument less than or equal to zero
306** turns off all busy handlers.
307*/
danielk1977f9d64d22004-06-19 08:18:07 +0000308int sqlite3_busy_timeout(sqlite3*, int ms);
drh2dfbbca2000-07-28 14:32:48 +0000309
drhe3710332000-09-29 13:30:53 +0000310/*
danielk19776f8a5032004-05-10 10:34:51 +0000311** This next routine is really just a wrapper around sqlite3_exec().
drhe3710332000-09-29 13:30:53 +0000312** Instead of invoking a user-supplied callback for each row of the
313** result, this routine remembers each row of the result in memory
314** obtained from malloc(), then returns all of the result after the
drha18c5682000-10-08 22:20:57 +0000315** query has finished.
316**
317** As an example, suppose the query result where this table:
318**
319** Name | Age
320** -----------------------
321** Alice | 43
322** Bob | 28
323** Cindy | 21
324**
325** If the 3rd argument were &azResult then after the function returns
drh98699b52000-10-09 12:57:00 +0000326** azResult will contain the following data:
drha18c5682000-10-08 22:20:57 +0000327**
328** azResult[0] = "Name";
329** azResult[1] = "Age";
330** azResult[2] = "Alice";
331** azResult[3] = "43";
332** azResult[4] = "Bob";
333** azResult[5] = "28";
334** azResult[6] = "Cindy";
335** azResult[7] = "21";
336**
337** Notice that there is an extra row of data containing the column
338** headers. But the *nrow return value is still 3. *ncolumn is
339** set to 2. In general, the number of values inserted into azResult
340** will be ((*nrow) + 1)*(*ncolumn).
341**
342** After the calling function has finished using the result, it should
danielk19776f8a5032004-05-10 10:34:51 +0000343** pass the result data pointer to sqlite3_free_table() in order to
drha18c5682000-10-08 22:20:57 +0000344** release the memory that was malloc-ed. Because of the way the
345** malloc() happens, the calling function must not try to call
danielk197799b214d2005-02-02 01:13:38 +0000346** free() directly. Only sqlite3_free_table() is able to release
drha18c5682000-10-08 22:20:57 +0000347** the memory properly and safely.
drhe3710332000-09-29 13:30:53 +0000348**
danielk19776f8a5032004-05-10 10:34:51 +0000349** The return value of this routine is the same as from sqlite3_exec().
drhe3710332000-09-29 13:30:53 +0000350*/
danielk19776f8a5032004-05-10 10:34:51 +0000351int sqlite3_get_table(
danielk1977f9d64d22004-06-19 08:18:07 +0000352 sqlite3*, /* An open database */
drh9f71c2e2001-11-03 23:57:09 +0000353 const char *sql, /* SQL to be executed */
drhe3710332000-09-29 13:30:53 +0000354 char ***resultp, /* Result written to a char *[] that this points to */
355 int *nrow, /* Number of result rows written here */
356 int *ncolumn, /* Number of result columns written here */
357 char **errmsg /* Error msg written here */
358);
359
360/*
danielk19776f8a5032004-05-10 10:34:51 +0000361** Call this routine to free the memory that sqlite3_get_table() allocated.
drhe3710332000-09-29 13:30:53 +0000362*/
danielk19776f8a5032004-05-10 10:34:51 +0000363void sqlite3_free_table(char **result);
drhe3710332000-09-29 13:30:53 +0000364
drha18c5682000-10-08 22:20:57 +0000365/*
drh4f26d6c2004-05-26 23:25:30 +0000366** The following routines are variants of the "sprintf()" from the
367** standard C library. The resulting string is written into memory
368** obtained from malloc() so that there is never a possiblity of buffer
369** overflow. These routines also implement some additional formatting
370** options that are useful for constructing SQL statements.
371**
372** The strings returned by these routines should be freed by calling
373** sqlite3_free().
drha18c5682000-10-08 22:20:57 +0000374**
375** All of the usual printf formatting options apply. In addition, there
376** is a "%q" option. %q works like %s in that it substitutes a null-terminated
drh66b89c82000-11-28 20:47:17 +0000377** string from the argument list. But %q also doubles every '\'' character.
drha18c5682000-10-08 22:20:57 +0000378** %q is designed for use inside a string literal. By doubling each '\''
drh66b89c82000-11-28 20:47:17 +0000379** character it escapes that character and allows it to be inserted into
drha18c5682000-10-08 22:20:57 +0000380** the string.
381**
382** For example, so some string variable contains text as follows:
383**
384** char *zText = "It's a happy day!";
385**
386** We can use this text in an SQL statement as follows:
387**
drh3224b322005-09-08 10:58:51 +0000388** char *z = sqlite3_mprintf("INSERT INTO TABLES('%q')", zText);
389** sqlite3_exec(db, z, callback1, 0, 0);
390** sqlite3_free(z);
drha18c5682000-10-08 22:20:57 +0000391**
392** Because the %q format string is used, the '\'' character in zText
393** is escaped and the SQL generated is as follows:
394**
395** INSERT INTO table1 VALUES('It''s a happy day!')
396**
397** This is correct. Had we used %s instead of %q, the generated SQL
398** would have looked like this:
399**
400** INSERT INTO table1 VALUES('It's a happy day!');
401**
402** This second example is an SQL syntax error. As a general rule you
403** should always use %q instead of %s when inserting text into a string
404** literal.
405*/
danielk19776f8a5032004-05-10 10:34:51 +0000406char *sqlite3_mprintf(const char*,...);
407char *sqlite3_vmprintf(const char*, va_list);
drh4f26d6c2004-05-26 23:25:30 +0000408void sqlite3_free(char *z);
drhfeac5f82004-08-01 00:10:45 +0000409char *sqlite3_snprintf(int,char*,const char*, ...);
drh5191b7e2002-03-08 02:12:00 +0000410
drh1211de32004-07-26 12:24:22 +0000411#ifndef SQLITE_OMIT_AUTHORIZATION
drh5191b7e2002-03-08 02:12:00 +0000412/*
drhed6c8672003-01-12 18:02:16 +0000413** This routine registers a callback with the SQLite library. The
drhb86ccfb2003-01-28 23:13:10 +0000414** callback is invoked (at compile-time, not at run-time) for each
415** attempt to access a column of a table in the database. The callback
416** returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire
417** SQL statement should be aborted with an error and SQLITE_IGNORE
418** if the column should be treated as a NULL value.
drhed6c8672003-01-12 18:02:16 +0000419*/
danielk19776f8a5032004-05-10 10:34:51 +0000420int sqlite3_set_authorizer(
danielk1977f9d64d22004-06-19 08:18:07 +0000421 sqlite3*,
drhe22a3342003-04-22 20:30:37 +0000422 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
drhe5f9c642003-01-13 23:27:31 +0000423 void *pUserData
drhed6c8672003-01-12 18:02:16 +0000424);
drh1211de32004-07-26 12:24:22 +0000425#endif
drhed6c8672003-01-12 18:02:16 +0000426
427/*
428** The second parameter to the access authorization function above will
drhe5f9c642003-01-13 23:27:31 +0000429** be one of the values below. These values signify what kind of operation
430** is to be authorized. The 3rd and 4th parameters to the authorization
431** function will be parameters or NULL depending on which of the following
drhe22a3342003-04-22 20:30:37 +0000432** codes is used as the second parameter. The 5th parameter is the name
433** of the database ("main", "temp", etc.) if applicable. The 6th parameter
drh5cf590c2003-04-24 01:45:04 +0000434** is the name of the inner-most trigger or view that is responsible for
435** the access attempt or NULL if this access attempt is directly from
436** input SQL code.
drhe5f9c642003-01-13 23:27:31 +0000437**
438** Arg-3 Arg-4
drhed6c8672003-01-12 18:02:16 +0000439*/
drh77ad4e42003-01-14 02:49:27 +0000440#define SQLITE_COPY 0 /* Table Name File Name */
drhe5f9c642003-01-13 23:27:31 +0000441#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
442#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
443#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
444#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
drh77ad4e42003-01-14 02:49:27 +0000445#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
drhe5f9c642003-01-13 23:27:31 +0000446#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
drh77ad4e42003-01-14 02:49:27 +0000447#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
drhe5f9c642003-01-13 23:27:31 +0000448#define SQLITE_CREATE_VIEW 8 /* View Name NULL */
449#define SQLITE_DELETE 9 /* Table Name NULL */
drh77ad4e42003-01-14 02:49:27 +0000450#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
drhe5f9c642003-01-13 23:27:31 +0000451#define SQLITE_DROP_TABLE 11 /* Table Name NULL */
drh77ad4e42003-01-14 02:49:27 +0000452#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
drhe5f9c642003-01-13 23:27:31 +0000453#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
drh77ad4e42003-01-14 02:49:27 +0000454#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
drhe5f9c642003-01-13 23:27:31 +0000455#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
drh77ad4e42003-01-14 02:49:27 +0000456#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
drhe5f9c642003-01-13 23:27:31 +0000457#define SQLITE_DROP_VIEW 17 /* View Name NULL */
458#define SQLITE_INSERT 18 /* Table Name NULL */
459#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
460#define SQLITE_READ 20 /* Table Name Column Name */
461#define SQLITE_SELECT 21 /* NULL NULL */
462#define SQLITE_TRANSACTION 22 /* NULL NULL */
463#define SQLITE_UPDATE 23 /* Table Name Column Name */
drh81e293b2003-06-06 19:00:42 +0000464#define SQLITE_ATTACH 24 /* Filename NULL */
465#define SQLITE_DETACH 25 /* Database Name NULL */
danielk19771c8c23c2004-11-12 15:53:37 +0000466#define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */
danielk19771d54df82004-11-23 15:41:16 +0000467#define SQLITE_REINDEX 27 /* Index Name NULL */
drhe6e04962005-07-23 02:17:03 +0000468#define SQLITE_ANALYZE 28 /* Table Name NULL */
danielk1977f1a381e2006-06-16 08:01:02 +0000469#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
470#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
drhed6c8672003-01-12 18:02:16 +0000471
472/*
473** The return value of the authorization function should be one of the
474** following constants:
475*/
476/* #define SQLITE_OK 0 // Allow access (This is actually defined above) */
477#define SQLITE_DENY 1 /* Abort the SQL statement with an error */
478#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
479
480/*
drh19e2d372005-08-29 23:00:03 +0000481** Register a function for tracing SQL command evaluation. The function
482** registered by sqlite3_trace() is invoked at the first sqlite3_step()
483** for the evaluation of an SQL statement. The function registered by
484** sqlite3_profile() runs at the end of each SQL statement and includes
485** information on how long that statement ran.
486**
487** The sqlite3_profile() API is currently considered experimental and
488** is subject to change.
drh18de4822003-01-16 16:28:53 +0000489*/
danielk1977f9d64d22004-06-19 08:18:07 +0000490void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
drh19e2d372005-08-29 23:00:03 +0000491void *sqlite3_profile(sqlite3*,
492 void(*xProfile)(void*,const char*,sqlite_uint64), void*);
drh18de4822003-01-16 16:28:53 +0000493
danielk1977348bb5d2003-10-18 09:37:26 +0000494/*
495** This routine configures a callback function - the progress callback - that
danielk19776f8a5032004-05-10 10:34:51 +0000496** is invoked periodically during long running calls to sqlite3_exec(),
danielk19772097e942004-11-20 06:05:56 +0000497** sqlite3_step() and sqlite3_get_table(). An example use for this API is to
498** keep a GUI updated during a large query.
danielk1977348bb5d2003-10-18 09:37:26 +0000499**
500** The progress callback is invoked once for every N virtual machine opcodes,
501** where N is the second argument to this function. The progress callback
502** itself is identified by the third argument to this function. The fourth
503** argument to this function is a void pointer passed to the progress callback
504** function each time it is invoked.
505**
danielk19776f8a5032004-05-10 10:34:51 +0000506** If a call to sqlite3_exec(), sqlite3_step() or sqlite3_get_table() results
danielk1977348bb5d2003-10-18 09:37:26 +0000507** in less than N opcodes being executed, then the progress callback is not
508** invoked.
509**
danielk1977348bb5d2003-10-18 09:37:26 +0000510** To remove the progress callback altogether, pass NULL as the third
511** argument to this function.
512**
513** If the progress callback returns a result other than 0, then the current
514** query is immediately terminated and any database changes rolled back. If the
515** query was part of a larger transaction, then the transaction is not rolled
danielk19776f8a5032004-05-10 10:34:51 +0000516** back and remains active. The sqlite3_exec() call returns SQLITE_ABORT.
drhaa940ea2004-01-15 02:44:03 +0000517**
518******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
danielk1977348bb5d2003-10-18 09:37:26 +0000519*/
danielk1977f9d64d22004-06-19 08:18:07 +0000520void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
danielk1977348bb5d2003-10-18 09:37:26 +0000521
drhaa940ea2004-01-15 02:44:03 +0000522/*
523** Register a callback function to be invoked whenever a new transaction
524** is committed. The pArg argument is passed through to the callback.
525** callback. If the callback function returns non-zero, then the commit
526** is converted into a rollback.
527**
528** If another function was previously registered, its pArg value is returned.
529** Otherwise NULL is returned.
530**
531** Registering a NULL function disables the callback.
532**
533******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
534*/
danielk1977f9d64d22004-06-19 08:18:07 +0000535void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
drhaa940ea2004-01-15 02:44:03 +0000536
drh22fbcb82004-02-01 01:22:50 +0000537/*
drh4f26d6c2004-05-26 23:25:30 +0000538** Open the sqlite database file "filename". The "filename" is UTF-8
539** encoded for sqlite3_open() and UTF-16 encoded in the native byte order
540** for sqlite3_open16(). An sqlite3* handle is returned in *ppDb, even
541** if an error occurs. If the database is opened (or created) successfully,
542** then SQLITE_OK is returned. Otherwise an error code is returned. The
543** sqlite3_errmsg() or sqlite3_errmsg16() routines can be used to obtain
544** an English language description of the error.
drh22fbcb82004-02-01 01:22:50 +0000545**
drh4f26d6c2004-05-26 23:25:30 +0000546** If the database file does not exist, then a new database is created.
547** The encoding for the database is UTF-8 if sqlite3_open() is called and
548** UTF-16 if sqlite3_open16 is used.
danielk197765904932004-05-26 06:18:37 +0000549**
550** Whether or not an error occurs when it is opened, resources associated
551** with the sqlite3* handle should be released by passing it to
552** sqlite3_close() when it is no longer required.
553*/
554int sqlite3_open(
555 const char *filename, /* Database filename (UTF-8) */
danielk19774f057f92004-06-08 00:02:33 +0000556 sqlite3 **ppDb /* OUT: SQLite db handle */
danielk197765904932004-05-26 06:18:37 +0000557);
danielk197765904932004-05-26 06:18:37 +0000558int sqlite3_open16(
559 const void *filename, /* Database filename (UTF-16) */
danielk19774f057f92004-06-08 00:02:33 +0000560 sqlite3 **ppDb /* OUT: SQLite db handle */
danielk197765904932004-05-26 06:18:37 +0000561);
danielk1977295ba552004-05-19 10:34:51 +0000562
danielk197765904932004-05-26 06:18:37 +0000563/*
564** Return the error code for the most recent sqlite3_* API call associated
565** with sqlite3 handle 'db'. SQLITE_OK is returned if the most recent
566** API call was successful.
567**
568** Calls to many sqlite3_* functions set the error code and string returned
569** by sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16()
570** (overwriting the previous values). Note that calls to sqlite3_errcode(),
571** sqlite3_errmsg() and sqlite3_errmsg16() themselves do not affect the
572** results of future invocations.
573**
574** Assuming no other intervening sqlite3_* API calls are made, the error
575** code returned by this function is associated with the same error as
576** the strings returned by sqlite3_errmsg() and sqlite3_errmsg16().
577*/
578int sqlite3_errcode(sqlite3 *db);
579
580/*
581** Return a pointer to a UTF-8 encoded string describing in english the
582** error condition for the most recent sqlite3_* API call. The returned
583** string is always terminated by an 0x00 byte.
584**
585** The string "not an error" is returned when the most recent API call was
586** successful.
587*/
588const char *sqlite3_errmsg(sqlite3*);
589
590/*
591** Return a pointer to a UTF-16 native byte order encoded string describing
592** in english the error condition for the most recent sqlite3_* API call.
593** The returned string is always terminated by a pair of 0x00 bytes.
594**
595** The string "not an error" is returned when the most recent API call was
596** successful.
597*/
598const void *sqlite3_errmsg16(sqlite3*);
599
600/*
601** An instance of the following opaque structure is used to represent
602** a compiled SQL statment.
603*/
danielk1977fc57d7b2004-05-26 02:04:57 +0000604typedef struct sqlite3_stmt sqlite3_stmt;
605
danielk1977e3209e42004-05-20 01:40:18 +0000606/*
danielk197765904932004-05-26 06:18:37 +0000607** To execute an SQL query, it must first be compiled into a byte-code
608** program using one of the following routines. The only difference between
609** them is that the second argument, specifying the SQL statement to
610** compile, is assumed to be encoded in UTF-8 for the sqlite3_prepare()
611** function and UTF-16 for sqlite3_prepare16().
612**
613** The first parameter "db" is an SQLite database handle. The second
614** parameter "zSql" is the statement to be compiled, encoded as either
615** UTF-8 or UTF-16 (see above). If the next parameter, "nBytes", is less
616** than zero, then zSql is read up to the first nul terminator. If
617** "nBytes" is not less than zero, then it is the length of the string zSql
618** in bytes (not characters).
619**
620** *pzTail is made to point to the first byte past the end of the first
621** SQL statement in zSql. This routine only compiles the first statement
622** in zSql, so *pzTail is left pointing to what remains uncompiled.
623**
624** *ppStmt is left pointing to a compiled SQL statement that can be
625** executed using sqlite3_step(). Or if there is an error, *ppStmt may be
626** set to NULL. If the input text contained no SQL (if the input is and
627** empty string or a comment) then *ppStmt is set to NULL.
628**
629** On success, SQLITE_OK is returned. Otherwise an error code is returned.
630*/
631int sqlite3_prepare(
632 sqlite3 *db, /* Database handle */
633 const char *zSql, /* SQL statement, UTF-8 encoded */
634 int nBytes, /* Length of zSql in bytes. */
635 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
636 const char **pzTail /* OUT: Pointer to unused portion of zSql */
637);
638int sqlite3_prepare16(
639 sqlite3 *db, /* Database handle */
640 const void *zSql, /* SQL statement, UTF-16 encoded */
641 int nBytes, /* Length of zSql in bytes. */
642 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
643 const void **pzTail /* OUT: Pointer to unused portion of zSql */
644);
645
646/*
drhf4479502004-05-27 03:12:53 +0000647** Pointers to the following two opaque structures are used to communicate
648** with the implementations of user-defined functions.
649*/
650typedef struct sqlite3_context sqlite3_context;
651typedef struct Mem sqlite3_value;
652
653/*
drh4f26d6c2004-05-26 23:25:30 +0000654** In the SQL strings input to sqlite3_prepare() and sqlite3_prepare16(),
drh32c0d4f2004-12-07 02:14:51 +0000655** one or more literals can be replace by parameters "?" or ":AAA" or
656** "$VVV" where AAA is an identifer and VVV is a variable name according
657** to the syntax rules of the TCL programming language.
658** The value of these parameters (also called "host parameter names") can
659** be set using the routines listed below.
drh4f26d6c2004-05-26 23:25:30 +0000660**
661** In every case, the first parameter is a pointer to the sqlite3_stmt
662** structure returned from sqlite3_prepare(). The second parameter is the
drh32c0d4f2004-12-07 02:14:51 +0000663** index of the parameter. The first parameter as an index of 1. For
664** named parameters (":AAA" or "$VVV") you can use
665** sqlite3_bind_parameter_index() to get the correct index value given
666** the parameters name. If the same named parameter occurs more than
667** once, it is assigned the same index each time.
drh4f26d6c2004-05-26 23:25:30 +0000668**
drh900dfba2004-07-21 15:21:36 +0000669** The fifth parameter to sqlite3_bind_blob(), sqlite3_bind_text(), and
670** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
671** text after SQLite has finished with it. If the fifth argument is the
672** special value SQLITE_STATIC, then the library assumes that the information
673** is in static, unmanaged space and does not need to be freed. If the
674** fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its
675** own private copy of the data.
drh4f26d6c2004-05-26 23:25:30 +0000676**
677** The sqlite3_bind_* routine must be called before sqlite3_step() after
drh32c0d4f2004-12-07 02:14:51 +0000678** an sqlite3_prepare() or sqlite3_reset(). Unbound parameterss are
679** interpreted as NULL.
drh4f26d6c2004-05-26 23:25:30 +0000680*/
danielk1977d8123362004-06-12 09:25:12 +0000681int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
drhf4479502004-05-27 03:12:53 +0000682int sqlite3_bind_double(sqlite3_stmt*, int, double);
683int sqlite3_bind_int(sqlite3_stmt*, int, int);
drhefad9992004-06-22 12:13:55 +0000684int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite_int64);
drhf4479502004-05-27 03:12:53 +0000685int sqlite3_bind_null(sqlite3_stmt*, int);
danielk1977d8123362004-06-12 09:25:12 +0000686int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
687int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
drhf4479502004-05-27 03:12:53 +0000688int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
drh4f26d6c2004-05-26 23:25:30 +0000689
690/*
drh32c0d4f2004-12-07 02:14:51 +0000691** Return the number of parameters in a compiled SQL statement. This
drh75f6a032004-07-15 14:15:00 +0000692** routine was added to support DBD::SQLite.
drh75f6a032004-07-15 14:15:00 +0000693*/
694int sqlite3_bind_parameter_count(sqlite3_stmt*);
695
696/*
drh32c0d4f2004-12-07 02:14:51 +0000697** Return the name of the i-th parameter. Ordinary parameters "?" are
698** nameless and a NULL is returned. For parameters of the form :AAA or
699** $VVV the complete text of the parameter name is returned, including
700** the initial ":" or "$". NULL is returned if the index is out of range.
drh895d7472004-08-20 16:02:39 +0000701*/
702const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
703
704/*
drhfa6bc002004-09-07 16:19:52 +0000705** Return the index of a parameter with the given name. The name
706** must match exactly. If no parameter with the given name is found,
707** return 0.
708*/
709int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
710
711/*
danielk1977600dd0b2005-01-20 01:14:23 +0000712** Set all the parameters in the compiled SQL statement to NULL.
danielk1977600dd0b2005-01-20 01:14:23 +0000713*/
714int sqlite3_clear_bindings(sqlite3_stmt*);
715
716/*
danielk197765904932004-05-26 06:18:37 +0000717** Return the number of columns in the result set returned by the compiled
718** SQL statement. This routine returns 0 if pStmt is an SQL statement
719** that does not return data (for example an UPDATE).
720*/
721int sqlite3_column_count(sqlite3_stmt *pStmt);
722
723/*
724** The first parameter is a compiled SQL statement. This function returns
725** the column heading for the Nth column of that statement, where N is the
drh4f26d6c2004-05-26 23:25:30 +0000726** second function parameter. The string returned is UTF-8 for
727** sqlite3_column_name() and UTF-16 for sqlite3_column_name16().
danielk197765904932004-05-26 06:18:37 +0000728*/
729const char *sqlite3_column_name(sqlite3_stmt*,int);
danielk197765904932004-05-26 06:18:37 +0000730const void *sqlite3_column_name16(sqlite3_stmt*,int);
731
732/*
danielk1977955de522006-02-10 02:27:42 +0000733** The first parameter to the following calls is a compiled SQL statement.
734** These functions return information about the Nth column returned by
735** the statement, where N is the second function argument.
736**
737** If the Nth column returned by the statement is not a column value,
738** then all of the functions return NULL. Otherwise, the return the
739** name of the attached database, table and column that the expression
740** extracts a value from.
741**
742** As with all other SQLite APIs, those postfixed with "16" return UTF-16
743** encoded strings, the other functions return UTF-8. The memory containing
744** the returned strings is valid until the statement handle is finalized().
danielk19774b1ae992006-02-10 03:06:10 +0000745**
746** These APIs are only available if the library was compiled with the
747** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
danielk1977955de522006-02-10 02:27:42 +0000748*/
749const char *sqlite3_column_database_name(sqlite3_stmt*,int);
750const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
751const char *sqlite3_column_table_name(sqlite3_stmt*,int);
752const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
753const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
754const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
755
756/*
danielk197765904932004-05-26 06:18:37 +0000757** The first parameter is a compiled SQL statement. If this statement
758** is a SELECT statement, the Nth column of the returned result set
759** of the SELECT is a table column then the declared type of the table
760** column is returned. If the Nth column of the result set is not at table
761** column, then a NULL pointer is returned. The returned string is always
762** UTF-8 encoded. For example, in the database schema:
763**
764** CREATE TABLE t1(c1 VARIANT);
765**
766** And the following statement compiled:
767**
danielk1977955de522006-02-10 02:27:42 +0000768** SELECT c1 + 1, c1 FROM t1;
danielk197765904932004-05-26 06:18:37 +0000769**
770** Then this routine would return the string "VARIANT" for the second
771** result column (i==1), and a NULL pointer for the first result column
772** (i==0).
773*/
774const char *sqlite3_column_decltype(sqlite3_stmt *, int i);
775
776/*
777** The first parameter is a compiled SQL statement. If this statement
778** is a SELECT statement, the Nth column of the returned result set
779** of the SELECT is a table column then the declared type of the table
780** column is returned. If the Nth column of the result set is not at table
781** column, then a NULL pointer is returned. The returned string is always
782** UTF-16 encoded. For example, in the database schema:
783**
drh4f26d6c2004-05-26 23:25:30 +0000784** CREATE TABLE t1(c1 INTEGER);
danielk197765904932004-05-26 06:18:37 +0000785**
786** And the following statement compiled:
787**
danielk1977955de522006-02-10 02:27:42 +0000788** SELECT c1 + 1, c1 FROM t1;
danielk197765904932004-05-26 06:18:37 +0000789**
drh4f26d6c2004-05-26 23:25:30 +0000790** Then this routine would return the string "INTEGER" for the second
danielk197765904932004-05-26 06:18:37 +0000791** result column (i==1), and a NULL pointer for the first result column
792** (i==0).
793*/
794const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
795
danielk1977106bb232004-05-21 10:08:53 +0000796/*
797** After an SQL query has been compiled with a call to either
798** sqlite3_prepare() or sqlite3_prepare16(), then this function must be
799** called one or more times to execute the statement.
800**
801** The return value will be either SQLITE_BUSY, SQLITE_DONE,
802** SQLITE_ROW, SQLITE_ERROR, or SQLITE_MISUSE.
803**
804** SQLITE_BUSY means that the database engine attempted to open
805** a locked database and there is no busy callback registered.
806** Call sqlite3_step() again to retry the open.
807**
808** SQLITE_DONE means that the statement has finished executing
809** successfully. sqlite3_step() should not be called again on this virtual
810** machine.
811**
812** If the SQL statement being executed returns any data, then
813** SQLITE_ROW is returned each time a new row of data is ready
814** for processing by the caller. The values may be accessed using
815** the sqlite3_column_*() functions described below. sqlite3_step()
816** is called again to retrieve the next row of data.
817**
818** SQLITE_ERROR means that a run-time error (such as a constraint
819** violation) has occurred. sqlite3_step() should not be called again on
820** the VM. More information may be found by calling sqlite3_errmsg().
821**
822** SQLITE_MISUSE means that the this routine was called inappropriately.
823** Perhaps it was called on a virtual machine that had already been
824** finalized or on one that had previously returned SQLITE_ERROR or
825** SQLITE_DONE. Or it could be the case the the same database connection
826** is being used simulataneously by two or more threads.
827*/
danielk197717240fd2004-05-26 00:07:25 +0000828int sqlite3_step(sqlite3_stmt*);
danielk1977106bb232004-05-21 10:08:53 +0000829
danielk1977106bb232004-05-21 10:08:53 +0000830/*
831** Return the number of values in the current row of the result set.
832**
833** After a call to sqlite3_step() that returns SQLITE_ROW, this routine
834** will return the same value as the sqlite3_column_count() function.
835** After sqlite3_step() has returned an SQLITE_DONE, SQLITE_BUSY or
836** error code, or before sqlite3_step() has been called on a
837** compiled SQL statement, this routine returns zero.
838*/
danielk197793d46752004-05-23 13:30:58 +0000839int sqlite3_data_count(sqlite3_stmt *pStmt);
danielk19774adee202004-05-08 08:23:19 +0000840
drh4f26d6c2004-05-26 23:25:30 +0000841/*
842** Values are stored in the database in one of the following fundamental
843** types.
844*/
drh9c054832004-05-31 18:51:57 +0000845#define SQLITE_INTEGER 1
846#define SQLITE_FLOAT 2
drh1e284f42004-10-06 15:52:01 +0000847/* #define SQLITE_TEXT 3 // See below */
drh9c054832004-05-31 18:51:57 +0000848#define SQLITE_BLOB 4
849#define SQLITE_NULL 5
danielk19774adee202004-05-08 08:23:19 +0000850
danielk1977106bb232004-05-21 10:08:53 +0000851/*
drh1e284f42004-10-06 15:52:01 +0000852** SQLite version 2 defines SQLITE_TEXT differently. To allow both
853** version 2 and version 3 to be included, undefine them both if a
854** conflict is seen. Define SQLITE3_TEXT to be the version 3 value.
855*/
856#ifdef SQLITE_TEXT
857# undef SQLITE_TEXT
858#else
859# define SQLITE_TEXT 3
860#endif
861#define SQLITE3_TEXT 3
862
863/*
drh4f26d6c2004-05-26 23:25:30 +0000864** The next group of routines returns information about the information
865** in a single column of the current result row of a query. In every
866** case the first parameter is a pointer to the SQL statement that is being
867** executed (the sqlite_stmt* that was returned from sqlite3_prepare()) and
868** the second argument is the index of the column for which information
869** should be returned. iCol is zero-indexed. The left-most column as an
870** index of 0.
danielk1977106bb232004-05-21 10:08:53 +0000871**
drh4f26d6c2004-05-26 23:25:30 +0000872** If the SQL statement is not currently point to a valid row, or if the
873** the colulmn index is out of range, the result is undefined.
874**
875** These routines attempt to convert the value where appropriate. For
876** example, if the internal representation is FLOAT and a text result
877** is requested, sprintf() is used internally to do the conversion
878** automatically. The following table details the conversions that
879** are applied:
880**
881** Internal Type Requested Type Conversion
882** ------------- -------------- --------------------------
883** NULL INTEGER Result is 0
884** NULL FLOAT Result is 0.0
885** NULL TEXT Result is an empty string
886** NULL BLOB Result is a zero-length BLOB
887** INTEGER FLOAT Convert from integer to float
888** INTEGER TEXT ASCII rendering of the integer
889** INTEGER BLOB Same as for INTEGER->TEXT
890** FLOAT INTEGER Convert from float to integer
891** FLOAT TEXT ASCII rendering of the float
892** FLOAT BLOB Same as FLOAT->TEXT
893** TEXT INTEGER Use atoi()
894** TEXT FLOAT Use atof()
895** TEXT BLOB No change
896** BLOB INTEGER Convert to TEXT then use atoi()
897** BLOB FLOAT Convert to TEXT then use atof()
898** BLOB TEXT Add a \000 terminator if needed
899**
900** The following access routines are provided:
901**
902** _type() Return the datatype of the result. This is one of
903** SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB,
904** or SQLITE_NULL.
905** _blob() Return the value of a BLOB.
906** _bytes() Return the number of bytes in a BLOB value or the number
907** of bytes in a TEXT value represented as UTF-8. The \000
908** terminator is included in the byte count for TEXT values.
909** _bytes16() Return the number of bytes in a BLOB value or the number
910** of bytes in a TEXT value represented as UTF-16. The \u0000
911** terminator is included in the byte count for TEXT values.
912** _double() Return a FLOAT value.
913** _int() Return an INTEGER value in the host computer's native
914** integer representation. This might be either a 32- or 64-bit
915** integer depending on the host.
916** _int64() Return an INTEGER value as a 64-bit signed integer.
917** _text() Return the value as UTF-8 text.
918** _text16() Return the value as UTF-16 text.
danielk1977106bb232004-05-21 10:08:53 +0000919*/
drhf4479502004-05-27 03:12:53 +0000920const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
921int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
922int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
923double sqlite3_column_double(sqlite3_stmt*, int iCol);
924int sqlite3_column_int(sqlite3_stmt*, int iCol);
drhefad9992004-06-22 12:13:55 +0000925sqlite_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
drhf4479502004-05-27 03:12:53 +0000926const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
927const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
drh4f26d6c2004-05-26 23:25:30 +0000928int sqlite3_column_type(sqlite3_stmt*, int iCol);
drh29d72102006-02-09 22:13:41 +0000929int sqlite3_column_numeric_type(sqlite3_stmt*, int iCol);
drh4be8b512006-06-13 23:51:34 +0000930sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
danielk19774adee202004-05-08 08:23:19 +0000931
danielk197765904932004-05-26 06:18:37 +0000932/*
933** The sqlite3_finalize() function is called to delete a compiled
934** SQL statement obtained by a previous call to sqlite3_prepare()
935** or sqlite3_prepare16(). If the statement was executed successfully, or
936** not executed at all, then SQLITE_OK is returned. If execution of the
937** statement failed then an error code is returned.
938**
939** This routine can be called at any point during the execution of the
940** virtual machine. If the virtual machine has not completed execution
941** when this routine is called, that is like encountering an error or
942** an interrupt. (See sqlite3_interrupt().) Incomplete updates may be
943** rolled back and transactions cancelled, depending on the circumstances,
944** and the result code returned will be SQLITE_ABORT.
945*/
946int sqlite3_finalize(sqlite3_stmt *pStmt);
947
948/*
949** The sqlite3_reset() function is called to reset a compiled SQL
950** statement obtained by a previous call to sqlite3_prepare() or
951** sqlite3_prepare16() back to it's initial state, ready to be re-executed.
952** Any SQL statement variables that had values bound to them using
953** the sqlite3_bind_*() API retain their values.
954*/
955int sqlite3_reset(sqlite3_stmt *pStmt);
956
957/*
danielk197765904932004-05-26 06:18:37 +0000958** The following two functions are used to add user functions or aggregates
959** implemented in C to the SQL langauge interpreted by SQLite. The
960** difference only between the two is that the second parameter, the
961** name of the (scalar) function or aggregate, is encoded in UTF-8 for
962** sqlite3_create_function() and UTF-16 for sqlite3_create_function16().
963**
964** The first argument is the database handle that the new function or
965** aggregate is to be added to. If a single program uses more than one
966** database handle internally, then user functions or aggregates must
967** be added individually to each database handle with which they will be
968** used.
969**
970** The third parameter is the number of arguments that the function or
971** aggregate takes. If this parameter is negative, then the function or
972** aggregate may take any number of arguments.
973**
danielk1977d8123362004-06-12 09:25:12 +0000974** The fourth parameter is one of SQLITE_UTF* values defined below,
975** indicating the encoding that the function is most likely to handle
976** values in. This does not change the behaviour of the programming
977** interface. However, if two versions of the same function are registered
978** with different encoding values, SQLite invokes the version likely to
979** minimize conversions between text encodings.
danielk1977d02eb1f2004-06-06 09:44:03 +0000980**
danielk197765904932004-05-26 06:18:37 +0000981** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are
982** pointers to user implemented C functions that implement the user
983** function or aggregate. A scalar function requires an implementation of
984** the xFunc callback only, NULL pointers should be passed as the xStep
985** and xFinal parameters. An aggregate function requires an implementation
986** of xStep and xFinal, but NULL should be passed for xFunc. To delete an
987** existing user function or aggregate, pass NULL for all three function
988** callback. Specifying an inconstent set of callback values, such as an
989** xFunc and an xFinal, or an xStep but no xFinal, SQLITE_ERROR is
990** returned.
991*/
992int sqlite3_create_function(
993 sqlite3 *,
994 const char *zFunctionName,
995 int nArg,
996 int eTextRep,
danielk197765904932004-05-26 06:18:37 +0000997 void*,
998 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
999 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
1000 void (*xFinal)(sqlite3_context*)
1001);
1002int sqlite3_create_function16(
1003 sqlite3*,
1004 const void *zFunctionName,
1005 int nArg,
1006 int eTextRep,
danielk197765904932004-05-26 06:18:37 +00001007 void*,
1008 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
1009 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
1010 void (*xFinal)(sqlite3_context*)
1011);
1012
1013/*
drhcf85a512006-02-09 18:35:29 +00001014** This function is deprecated. Do not use it. It continues to exist
1015** so as not to break legacy code. But new code should avoid using it.
danielk197765904932004-05-26 06:18:37 +00001016*/
1017int sqlite3_aggregate_count(sqlite3_context*);
1018
danielk19770ffba6b2004-05-24 09:10:10 +00001019/*
drh4f26d6c2004-05-26 23:25:30 +00001020** The next group of routines returns information about parameters to
1021** a user-defined function. Function implementations use these routines
1022** to access their parameters. These routines are the same as the
1023** sqlite3_column_* routines except that these routines take a single
1024** sqlite3_value* pointer instead of an sqlite3_stmt* and an integer
1025** column number.
danielk19770ffba6b2004-05-24 09:10:10 +00001026*/
drhf4479502004-05-27 03:12:53 +00001027const void *sqlite3_value_blob(sqlite3_value*);
1028int sqlite3_value_bytes(sqlite3_value*);
1029int sqlite3_value_bytes16(sqlite3_value*);
1030double sqlite3_value_double(sqlite3_value*);
1031int sqlite3_value_int(sqlite3_value*);
drhefad9992004-06-22 12:13:55 +00001032sqlite_int64 sqlite3_value_int64(sqlite3_value*);
drhf4479502004-05-27 03:12:53 +00001033const unsigned char *sqlite3_value_text(sqlite3_value*);
1034const void *sqlite3_value_text16(sqlite3_value*);
danielk1977d8123362004-06-12 09:25:12 +00001035const void *sqlite3_value_text16le(sqlite3_value*);
1036const void *sqlite3_value_text16be(sqlite3_value*);
danielk197793d46752004-05-23 13:30:58 +00001037int sqlite3_value_type(sqlite3_value*);
drh29d72102006-02-09 22:13:41 +00001038int sqlite3_value_numeric_type(sqlite3_value*);
danielk19770ffba6b2004-05-24 09:10:10 +00001039
1040/*
danielk19770ae8b832004-05-25 12:05:56 +00001041** Aggregate functions use the following routine to allocate
1042** a structure for storing their state. The first time this routine
1043** is called for a particular aggregate, a new structure of size nBytes
1044** is allocated, zeroed, and returned. On subsequent calls (for the
1045** same aggregate instance) the same buffer is returned. The implementation
1046** of the aggregate can use the returned buffer to accumulate data.
1047**
1048** The buffer allocated is freed automatically by SQLite.
1049*/
drh4f26d6c2004-05-26 23:25:30 +00001050void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
danielk19777e18c252004-05-25 11:47:24 +00001051
1052/*
drhc0f2a012005-07-09 02:39:40 +00001053** The pUserData parameter to the sqlite3_create_function()
1054** routine used to register user functions is available to
1055** the implementation of the function using this call.
danielk19777e18c252004-05-25 11:47:24 +00001056*/
1057void *sqlite3_user_data(sqlite3_context*);
1058
1059/*
danielk1977682f68b2004-06-05 10:22:17 +00001060** The following two functions may be used by scalar user functions to
1061** associate meta-data with argument values. If the same value is passed to
1062** multiple invocations of the user-function during query execution, under
1063** some circumstances the associated meta-data may be preserved. This may
1064** be used, for example, to add a regular-expression matching scalar
1065** function. The compiled version of the regular expression is stored as
1066** meta-data associated with the SQL value passed as the regular expression
1067** pattern.
1068**
1069** Calling sqlite3_get_auxdata() returns a pointer to the meta data
1070** associated with the Nth argument value to the current user function
1071** call, where N is the second parameter. If no meta-data has been set for
1072** that value, then a NULL pointer is returned.
1073**
1074** The sqlite3_set_auxdata() is used to associate meta data with a user
1075** function argument. The third parameter is a pointer to the meta data
1076** to be associated with the Nth user function argument value. The fourth
1077** parameter specifies a 'delete function' that will be called on the meta
1078** data pointer to release it when it is no longer required. If the delete
1079** function pointer is NULL, it is not invoked.
1080**
1081** In practice, meta-data is preserved between function calls for
1082** expressions that are constant at compile time. This includes literal
1083** values and SQL variables.
1084*/
1085void *sqlite3_get_auxdata(sqlite3_context*, int);
1086void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*));
1087
drha2854222004-06-17 19:04:17 +00001088
1089/*
1090** These are special value for the destructor that is passed in as the
1091** final argument to routines like sqlite3_result_blob(). If the destructor
1092** argument is SQLITE_STATIC, it means that the content pointer is constant
1093** and will never change. It does not need to be destroyed. The
1094** SQLITE_TRANSIENT value means that the content will likely change in
1095** the near future and that SQLite should make its own private copy of
1096** the content before returning.
1097*/
danielk1977d8123362004-06-12 09:25:12 +00001098#define SQLITE_STATIC ((void(*)(void *))0)
1099#define SQLITE_TRANSIENT ((void(*)(void *))-1)
1100
danielk1977682f68b2004-06-05 10:22:17 +00001101/*
drh4f26d6c2004-05-26 23:25:30 +00001102** User-defined functions invoke the following routines in order to
1103** set their return value.
danielk19777e18c252004-05-25 11:47:24 +00001104*/
danielk1977d8123362004-06-12 09:25:12 +00001105void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
drh4f26d6c2004-05-26 23:25:30 +00001106void sqlite3_result_double(sqlite3_context*, double);
danielk19777e18c252004-05-25 11:47:24 +00001107void sqlite3_result_error(sqlite3_context*, const char*, int);
1108void sqlite3_result_error16(sqlite3_context*, const void*, int);
drh4f26d6c2004-05-26 23:25:30 +00001109void sqlite3_result_int(sqlite3_context*, int);
drhefad9992004-06-22 12:13:55 +00001110void sqlite3_result_int64(sqlite3_context*, sqlite_int64);
drh4f26d6c2004-05-26 23:25:30 +00001111void sqlite3_result_null(sqlite3_context*);
danielk1977d8123362004-06-12 09:25:12 +00001112void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
1113void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
1114void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
1115void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
drh4f26d6c2004-05-26 23:25:30 +00001116void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
drhf9b596e2004-05-26 16:54:42 +00001117
drh52619df2004-06-11 17:48:02 +00001118/*
1119** These are the allowed values for the eTextRep argument to
1120** sqlite3_create_collation and sqlite3_create_function.
1121*/
drh7d9bd4e2006-02-16 18:16:36 +00001122#define SQLITE_UTF8 1
1123#define SQLITE_UTF16LE 2
1124#define SQLITE_UTF16BE 3
1125#define SQLITE_UTF16 4 /* Use native byte order */
1126#define SQLITE_ANY 5 /* sqlite3_create_function only */
1127#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
danielk1977466be562004-06-10 02:16:01 +00001128
danielk19777cedc8d2004-06-10 10:50:08 +00001129/*
1130** These two functions are used to add new collation sequences to the
1131** sqlite3 handle specified as the first argument.
1132**
1133** The name of the new collation sequence is specified as a UTF-8 string
1134** for sqlite3_create_collation() and a UTF-16 string for
1135** sqlite3_create_collation16(). In both cases the name is passed as the
1136** second function argument.
1137**
1138** The third argument must be one of the constants SQLITE_UTF8,
1139** SQLITE_UTF16LE or SQLITE_UTF16BE, indicating that the user-supplied
1140** routine expects to be passed pointers to strings encoded using UTF-8,
1141** UTF-16 little-endian or UTF-16 big-endian respectively.
1142**
1143** A pointer to the user supplied routine must be passed as the fifth
1144** argument. If it is NULL, this is the same as deleting the collation
1145** sequence (so that SQLite cannot call it anymore). Each time the user
1146** supplied function is invoked, it is passed a copy of the void* passed as
1147** the fourth argument to sqlite3_create_collation() or
1148** sqlite3_create_collation16() as its first parameter.
1149**
1150** The remaining arguments to the user-supplied routine are two strings,
1151** each represented by a [length, data] pair and encoded in the encoding
1152** that was passed as the third argument when the collation sequence was
1153** registered. The user routine should return negative, zero or positive if
1154** the first string is less than, equal to, or greater than the second
1155** string. i.e. (STRING1 - STRING2).
1156*/
danielk19770202b292004-06-09 09:55:16 +00001157int sqlite3_create_collation(
1158 sqlite3*,
1159 const char *zName,
danielk19777cedc8d2004-06-10 10:50:08 +00001160 int eTextRep,
danielk19770202b292004-06-09 09:55:16 +00001161 void*,
1162 int(*xCompare)(void*,int,const void*,int,const void*)
1163);
1164int sqlite3_create_collation16(
1165 sqlite3*,
1166 const char *zName,
danielk19777cedc8d2004-06-10 10:50:08 +00001167 int eTextRep,
danielk19770202b292004-06-09 09:55:16 +00001168 void*,
1169 int(*xCompare)(void*,int,const void*,int,const void*)
1170);
1171
danielk19777cedc8d2004-06-10 10:50:08 +00001172/*
1173** To avoid having to register all collation sequences before a database
1174** can be used, a single callback function may be registered with the
1175** database handle to be called whenever an undefined collation sequence is
1176** required.
1177**
1178** If the function is registered using the sqlite3_collation_needed() API,
1179** then it is passed the names of undefined collation sequences as strings
1180** encoded in UTF-8. If sqlite3_collation_needed16() is used, the names
1181** are passed as UTF-16 in machine native byte order. A call to either
1182** function replaces any existing callback.
1183**
1184** When the user-function is invoked, the first argument passed is a copy
1185** of the second argument to sqlite3_collation_needed() or
1186** sqlite3_collation_needed16(). The second argument is the database
1187** handle. The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE or
1188** SQLITE_UTF16LE, indicating the most desirable form of the collation
1189** sequence function required. The fourth parameter is the name of the
1190** required collation sequence.
1191**
1192** The collation sequence is returned to SQLite by a collation-needed
1193** callback using the sqlite3_create_collation() or
1194** sqlite3_create_collation16() APIs, described above.
1195*/
1196int sqlite3_collation_needed(
1197 sqlite3*,
1198 void*,
1199 void(*)(void*,sqlite3*,int eTextRep,const char*)
1200);
1201int sqlite3_collation_needed16(
1202 sqlite3*,
1203 void*,
1204 void(*)(void*,sqlite3*,int eTextRep,const void*)
1205);
1206
drh2011d5f2004-07-22 02:40:37 +00001207/*
1208** Specify the key for an encrypted database. This routine should be
1209** called right after sqlite3_open().
1210**
1211** The code to implement this API is not available in the public release
1212** of SQLite.
1213*/
1214int sqlite3_key(
1215 sqlite3 *db, /* Database to be rekeyed */
1216 const void *pKey, int nKey /* The key */
1217);
1218
1219/*
1220** Change the key on an open database. If the current database is not
1221** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the
1222** database is decrypted.
1223**
1224** The code to implement this API is not available in the public release
1225** of SQLite.
1226*/
1227int sqlite3_rekey(
1228 sqlite3 *db, /* Database to be rekeyed */
1229 const void *pKey, int nKey /* The new key */
1230);
danielk19770202b292004-06-09 09:55:16 +00001231
drhab3f9fe2004-08-14 17:10:10 +00001232/*
danielk1977600dd0b2005-01-20 01:14:23 +00001233** Sleep for a little while. The second parameter is the number of
1234** miliseconds to sleep for.
1235**
1236** If the operating system does not support sleep requests with
1237** milisecond time resolution, then the time will be rounded up to
1238** the nearest second. The number of miliseconds of sleep actually
1239** requested from the operating system is returned.
danielk1977600dd0b2005-01-20 01:14:23 +00001240*/
1241int sqlite3_sleep(int);
1242
1243/*
drh65efb652005-06-12 22:12:39 +00001244** Return TRUE (non-zero) if the statement supplied as an argument needs
drhd89bd002005-01-22 03:03:54 +00001245** to be recompiled. A statement needs to be recompiled whenever the
1246** execution environment changes in a way that would alter the program
1247** that sqlite3_prepare() generates. For example, if new functions or
1248** collating sequences are registered or if an authorizer function is
1249** added or changed.
1250**
drhd89bd002005-01-22 03:03:54 +00001251*/
1252int sqlite3_expired(sqlite3_stmt*);
1253
1254/*
drhf8db1bc2005-04-22 02:38:37 +00001255** Move all bindings from the first prepared statement over to the second.
1256** This routine is useful, for example, if the first prepared statement
1257** fails with an SQLITE_SCHEMA error. The same SQL can be prepared into
1258** the second prepared statement then all of the bindings transfered over
1259** to the second statement before the first statement is finalized.
drhf8db1bc2005-04-22 02:38:37 +00001260*/
1261int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
1262
1263/*
tpoindex9a09a3c2004-12-20 19:01:32 +00001264** If the following global variable is made to point to a
drhab3f9fe2004-08-14 17:10:10 +00001265** string which is the name of a directory, then all temporary files
1266** created by SQLite will be placed in that directory. If this variable
1267** is NULL pointer, then SQLite does a search for an appropriate temporary
1268** file directory.
1269**
danielk19776b456a22005-03-21 04:04:02 +00001270** Once sqlite3_open() has been called, changing this variable will invalidate
1271** the current temporary database, if any.
drhab3f9fe2004-08-14 17:10:10 +00001272*/
tpoindex9a09a3c2004-12-20 19:01:32 +00001273extern char *sqlite3_temp_directory;
drhab3f9fe2004-08-14 17:10:10 +00001274
danielk19776b456a22005-03-21 04:04:02 +00001275/*
1276** This function is called to recover from a malloc() failure that occured
1277** within the SQLite library. Normally, after a single malloc() fails the
1278** library refuses to function (all major calls return SQLITE_NOMEM).
drh9a7e6082005-03-31 22:26:19 +00001279** This function restores the library state so that it can be used again.
danielk19776b456a22005-03-21 04:04:02 +00001280**
1281** All existing statements (sqlite3_stmt pointers) must be finalized or
1282** reset before this call is made. Otherwise, SQLITE_BUSY is returned.
1283** If any in-memory databases are in use, either as a main or TEMP
1284** database, SQLITE_ERROR is returned. In either of these cases, the
1285** library is not reset and remains unusable.
1286**
1287** This function is *not* threadsafe. Calling this from within a threaded
1288** application when threads other than the caller have used SQLite is
1289** dangerous and will almost certainly result in malfunctions.
1290**
1291** This functionality can be omitted from a build by defining the
1292** SQLITE_OMIT_GLOBALRECOVER at compile time.
1293*/
drhd9cb6ac2005-10-20 07:28:17 +00001294int sqlite3_global_recover(void);
danielk19776b456a22005-03-21 04:04:02 +00001295
drh3e1d8e62005-05-26 16:23:34 +00001296/*
1297** Test to see whether or not the database connection is in autocommit
1298** mode. Return TRUE if it is and FALSE if not. Autocommit mode is on
1299** by default. Autocommit is disabled by a BEGIN statement and reenabled
1300** by the next COMMIT or ROLLBACK.
drh3e1d8e62005-05-26 16:23:34 +00001301*/
1302int sqlite3_get_autocommit(sqlite3*);
1303
drh51942bc2005-06-12 22:01:42 +00001304/*
1305** Return the sqlite3* database handle to which the prepared statement given
1306** in the argument belongs. This is the same database handle that was
1307** the first argument to the sqlite3_prepare() that was used to create
1308** the statement in the first place.
1309*/
1310sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
drh3e1d8e62005-05-26 16:23:34 +00001311
drhb37df7b2005-10-13 02:09:49 +00001312/*
danielk197794eb6a12005-12-15 15:22:08 +00001313** Register a callback function with the database connection identified by the
1314** first argument to be invoked whenever a row is updated, inserted or deleted.
1315** Any callback set by a previous call to this function for the same
1316** database connection is overridden.
1317**
1318** The second argument is a pointer to the function to invoke when a
1319** row is updated, inserted or deleted. The first argument to the callback is
1320** a copy of the third argument to sqlite3_update_hook. The second callback
1321** argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending
1322** on the operation that caused the callback to be invoked. The third and
1323** fourth arguments to the callback contain pointers to the database and
1324** table name containing the affected row. The final callback parameter is
1325** the rowid of the row. In the case of an update, this is the rowid after
1326** the update takes place.
1327**
1328** The update hook is not invoked when internal system tables are
1329** modified (i.e. sqlite_master and sqlite_sequence).
danielk197771fd80b2005-12-16 06:54:01 +00001330**
1331** If another function was previously registered, its pArg value is returned.
1332** Otherwise NULL is returned.
danielk197794eb6a12005-12-15 15:22:08 +00001333*/
danielk197771fd80b2005-12-16 06:54:01 +00001334void *sqlite3_update_hook(
danielk197794eb6a12005-12-15 15:22:08 +00001335 sqlite3*,
1336 void(*)(void *,int ,char const *,char const *,sqlite_int64),
1337 void*
1338);
danielk197713a68c32005-12-15 10:11:30 +00001339
danielk1977f3f06bb2005-12-16 15:24:28 +00001340/*
1341** Register a callback to be invoked whenever a transaction is rolled
1342** back.
1343**
1344** The new callback function overrides any existing rollback-hook
1345** callback. If there was an existing callback, then it's pArg value
1346** (the third argument to sqlite3_rollback_hook() when it was registered)
1347** is returned. Otherwise, NULL is returned.
1348**
1349** For the purposes of this API, a transaction is said to have been
1350** rolled back if an explicit "ROLLBACK" statement is executed, or
1351** an error or constraint causes an implicit rollback to occur. The
1352** callback is not invoked if a transaction is automatically rolled
1353** back because the database connection is closed.
1354*/
danielk197771fd80b2005-12-16 06:54:01 +00001355void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
1356
danielk19777ddad962005-12-12 06:53:03 +00001357/*
danielk1977aef0bf62005-12-30 16:28:01 +00001358** This function is only available if the library is compiled without
1359** the SQLITE_OMIT_SHARED_CACHE macro defined. It is used to enable or
1360** disable (if the argument is true or false, respectively) the
1361** "shared pager" feature.
1362*/
1363int sqlite3_enable_shared_cache(int);
1364
1365/*
danielk197752622822006-01-09 09:59:49 +00001366** Attempt to free N bytes of heap memory by deallocating non-essential
1367** memory allocations held by the database library (example: memory
1368** used to cache database pages to improve performance).
1369**
drh6f7adc82006-01-11 21:41:20 +00001370** This function is not a part of standard builds. It is only created
1371** if SQLite is compiled with the SQLITE_ENABLE_MEMORY_MANAGEMENT macro.
danielk197752622822006-01-09 09:59:49 +00001372*/
1373int sqlite3_release_memory(int);
1374
1375/*
1376** Place a "soft" limit on the amount of heap memory that may be allocated by
1377** SQLite within the current thread. If an internal allocation is requested
1378** that would exceed the specified limit, sqlite3_release_memory() is invoked
1379** one or more times to free up some space before the allocation is made.
1380**
1381** The limit is called "soft", because if sqlite3_release_memory() cannot free
1382** sufficient memory to prevent the limit from being exceeded, the memory is
1383** allocated anyway and the current operation proceeds.
1384**
drh6f7adc82006-01-11 21:41:20 +00001385** This function is only available if the library was compiled with the
1386** SQLITE_ENABLE_MEMORY_MANAGEMENT option set.
danielk197752622822006-01-09 09:59:49 +00001387** memory-management has been enabled.
1388*/
drhd2d4a6b2006-01-10 15:18:27 +00001389void sqlite3_soft_heap_limit(int);
danielk197752622822006-01-09 09:59:49 +00001390
1391/*
drh6f7adc82006-01-11 21:41:20 +00001392** This routine makes sure that all thread-local storage has been
1393** deallocated for the current thread.
1394**
1395** This routine is not technically necessary. All thread-local storage
1396** will be automatically deallocated once memory-management and
1397** shared-cache are disabled and the soft heap limit has been set
1398** to zero. This routine is provided as a convenience for users who
1399** want to make absolutely sure they have not forgotten something
1400** prior to killing off a thread.
1401*/
1402void sqlite3_thread_cleanup(void);
1403
1404/*
danielk1977deb802c2006-02-09 13:43:28 +00001405** Return meta information about a specific column of a specific database
1406** table accessible using the connection handle passed as the first function
1407** argument.
1408**
1409** The column is identified by the second, third and fourth parameters to
1410** this function. The second parameter is either the name of the database
1411** (i.e. "main", "temp" or an attached database) containing the specified
1412** table or NULL. If it is NULL, then all attached databases are searched
1413** for the table using the same algorithm as the database engine uses to
1414** resolve unqualified table references.
1415**
1416** The third and fourth parameters to this function are the table and column
1417** name of the desired column, respectively. Neither of these parameters
1418** may be NULL.
1419**
1420** Meta information is returned by writing to the memory locations passed as
1421** the 5th and subsequent parameters to this function. Any of these
1422** arguments may be NULL, in which case the corresponding element of meta
1423** information is ommitted.
1424**
1425** Parameter Output Type Description
1426** -----------------------------------
1427**
1428** 5th const char* Data type
1429** 6th const char* Name of the default collation sequence
1430** 7th int True if the column has a NOT NULL constraint
1431** 8th int True if the column is part of the PRIMARY KEY
1432** 9th int True if the column is AUTOINCREMENT
1433**
1434**
1435** The memory pointed to by the character pointers returned for the
1436** declaration type and collation sequence is valid only until the next
1437** call to any sqlite API function.
1438**
1439** If the specified table is actually a view, then an error is returned.
1440**
1441** If the specified column is "rowid", "oid" or "_rowid_" and an
1442** INTEGER PRIMARY KEY column has been explicitly declared, then the output
1443** parameters are set for the explicitly declared column. If there is no
1444** explicitly declared IPK column, then the output parameters are set as
1445** follows:
1446**
1447** data type: "INTEGER"
1448** collation sequence: "BINARY"
1449** not null: 0
1450** primary key: 1
1451** auto increment: 0
1452**
1453** This function may load one or more schemas from database files. If an
1454** error occurs during this process, or if the requested table or column
1455** cannot be found, an SQLITE error code is returned and an error message
1456** left in the database handle (to be retrieved using sqlite3_errmsg()).
danielk19774b1ae992006-02-10 03:06:10 +00001457**
1458** This API is only available if the library was compiled with the
1459** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
danielk1977deb802c2006-02-09 13:43:28 +00001460*/
1461int sqlite3_table_column_metadata(
1462 sqlite3 *db, /* Connection handle */
1463 const char *zDbName, /* Database name or NULL */
1464 const char *zTableName, /* Table name */
1465 const char *zColumnName, /* Column name */
1466 char const **pzDataType, /* OUTPUT: Declared data type */
1467 char const **pzCollSeq, /* OUTPUT: Collation sequence name */
1468 int *pNotNull, /* OUTPUT: True if NOT NULL constraint exists */
1469 int *pPrimaryKey, /* OUTPUT: True if column part of PK */
1470 int *pAutoinc /* OUTPUT: True if colums is auto-increment */
1471);
1472
1473/*
drh1e397f82006-06-08 15:28:43 +00001474****** EXPERIMENTAL - subject to change without notice **************
1475**
1476** Attempt to load an SQLite extension library contained in the file
1477** zFile. The entry point is zProc. zProc may be 0 in which case the
1478** name of the entry point is derived from the filename.
1479**
1480** Return SQLITE_OK on success and SQLITE_ERROR if something goes wrong.
1481**
1482** If an error occurs and pzErrMsg is not 0, then fill *pzErrMsg with
1483** error message text. The calling function should free this memory
1484** by calling sqlite3_free().
1485**
1486** The entry point name is derived from the filename according to the
1487** following steps:
1488**
1489** * Convert the name to lower case
1490** * Remove the path prefix from the name
1491** * Remove the first "." and all following characters from the name
1492** * If the name begins with "lib" remove the first 3 characters
1493** * Remove all characters that are not US-ASCII alphanumerics
1494** or underscores
1495** * Remove any leading digits and underscores from the name
1496** * Append "_init" to the name
1497**
1498** So, for example, if the input filename is "/home/drh/libtest1.52.so"
1499** then the entry point would be computed as "test1_init".
1500**
1501** The derived entry point name is limited to a reasonable number of
1502** characters (currently 200).
1503**
1504****** EXPERIMENTAL - subject to change without notice **************
1505*/
1506int sqlite3_load_extension(
1507 sqlite3 *db, /* Load the extension into this database connection */
1508 const char *zFile, /* Name of the shared library containing extension */
1509 const char *zProc, /* Entry point. Derived from zFile if 0 */
1510 char **pzErrMsg /* Put error message here if not 0 */
1511);
1512
1513/*
drhe09daa92006-06-10 13:29:31 +00001514****** EXPERIMENTAL - subject to change without notice **************
drh9eff6162006-06-12 21:59:13 +00001515**
1516** The interface to the virtual-table mechanism is currently considered
1517** to be experimental. The interface might change in incompatible ways.
1518** If this is a problem for you, do not use the interface at this time.
1519**
1520** When the virtual-table mechanism stablizes, we will declare the
1521** interface fixed, support it indefinitely, and remove this comment.
1522*/
1523
1524/*
1525** Structures used by the virtual table interface
drhe09daa92006-06-10 13:29:31 +00001526*/
1527typedef struct sqlite3_vtab sqlite3_vtab;
1528typedef struct sqlite3_index_info sqlite3_index_info;
1529typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
1530typedef struct sqlite3_module sqlite3_module;
drh9eff6162006-06-12 21:59:13 +00001531
1532/*
1533** A module is a class of virtual tables. Each module is defined
1534** by an instance of the following structure. This structure consists
1535** mostly of methods for the module.
1536*/
drhe09daa92006-06-10 13:29:31 +00001537struct sqlite3_module {
1538 int iVersion;
drhb9bb7c12006-06-11 23:41:55 +00001539 const char *zName;
danielk19779da9d472006-06-14 06:58:15 +00001540 int (*xCreate)(sqlite3*, void *pAux,
drhe09daa92006-06-10 13:29:31 +00001541 int argc, char **argv,
1542 sqlite3_vtab **ppVTab);
danielk19779da9d472006-06-14 06:58:15 +00001543 int (*xConnect)(sqlite3*, void *pAux,
drhe09daa92006-06-10 13:29:31 +00001544 int argc, char **argv,
1545 sqlite3_vtab **ppVTab);
1546 int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
1547 int (*xDisconnect)(sqlite3_vtab *pVTab);
1548 int (*xDestroy)(sqlite3_vtab *pVTab);
1549 int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
1550 int (*xClose)(sqlite3_vtab_cursor*);
drh4be8b512006-06-13 23:51:34 +00001551 int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
drhe09daa92006-06-10 13:29:31 +00001552 int argc, sqlite3_value **argv);
1553 int (*xNext)(sqlite3_vtab_cursor*);
1554 int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
1555 int (*xRowid)(sqlite3_vtab_cursor*, sqlite_int64 *pRowid);
danielk19771f6eec52006-06-16 06:17:47 +00001556 int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite_int64 *);
drhe09daa92006-06-10 13:29:31 +00001557 int (*xBegin)(sqlite3_vtab *pVTab);
1558 int (*xSync)(sqlite3_vtab *pVTab);
1559 int (*xCommit)(sqlite3_vtab *pVTab);
1560 int (*xRollback)(sqlite3_vtab *pVTab);
drhe09daa92006-06-10 13:29:31 +00001561};
drh9eff6162006-06-12 21:59:13 +00001562
1563/*
1564** The sqlite3_index_info structure and its substructures is used to
1565** pass information into and receive the reply from the xBestIndex
1566** method of an sqlite3_module. The fields under **Inputs** are the
1567** inputs to xBestIndex and are read-only. xBestIndex inserts its
1568** results into the **Outputs** fields.
1569**
1570** The aConstraint[] array records WHERE clause constraints of the
1571** form:
1572**
1573** column OP expr
1574**
1575** Where OP is =, <, <=, >, or >=. The particular operator is stored
1576** in aConstraint[].op. The index of the column is stored in
1577** aConstraint[].iColumn. aConstraint[].usable is TRUE if the
1578** expr on the right-hand side can be evaluated (and thus the constraint
1579** is usable) and false if it cannot.
1580**
1581** The optimizer automatically inverts terms of the form "expr OP column"
1582** and makes other simplificatinos to the WHERE clause in an attempt to
1583** get as many WHERE clause terms into the form shown above as possible.
1584** The aConstraint[] array only reports WHERE clause terms in the correct
1585** form that refer to the particular virtual table being queried.
1586**
1587** Information about the ORDER BY clause is stored in aOrderBy[].
1588** Each term of aOrderBy records a column of the ORDER BY clause.
1589**
1590** The xBestIndex method must fill aConstraintUsage[] with information
danielk19775fac9f82006-06-13 14:16:58 +00001591** about what parameters to pass to xFilter. If argvIndex>0 then
drh9eff6162006-06-12 21:59:13 +00001592** the right-hand side of the corresponding aConstraint[] is evaluated
1593** and becomes the argvIndex-th entry in argv. If aConstraintUsage[].omit
1594** is true, then the constraint is assumed to be fully handled by the
1595** virtual table and is not checked again by SQLite.
1596**
drh4be8b512006-06-13 23:51:34 +00001597** The idxNum and idxPtr values are recorded and passed into xFilter.
1598** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true.
drh9eff6162006-06-12 21:59:13 +00001599**
1600** The orderByConsumed means that output from xFilter will occur in
1601** the correct order to satisfy the ORDER BY clause so that no separate
1602** sorting step is required.
1603**
1604** The estimatedCost value is an estimate of the cost of doing the
1605** particular lookup. A full scan of a table with N entries should have
1606** a cost of N. A binary search of a table of N entries should have a
1607** cost of approximately log(N).
1608*/
drhe09daa92006-06-10 13:29:31 +00001609struct sqlite3_index_info {
1610 /* Inputs */
drh9eff6162006-06-12 21:59:13 +00001611 const int nConstraint; /* Number of entries in aConstraint */
1612 const struct sqlite3_index_constraint {
1613 int iColumn; /* Column on left-hand side of constraint */
1614 unsigned char op; /* Constraint operator */
1615 unsigned char usable; /* True if this constraint is usable */
1616 int iTermOffset; /* Used internally - xBestIndex should ignore */
1617 } *const aConstraint; /* Table of WHERE clause constraints */
1618 const int nOrderBy; /* Number of terms in the ORDER BY clause */
1619 const struct sqlite3_index_orderby {
1620 int iColumn; /* Column number */
1621 unsigned char desc; /* True for DESC. False for ASC. */
1622 } *const aOrderBy; /* The ORDER BY clause */
drhe09daa92006-06-10 13:29:31 +00001623
1624 /* Outputs */
drh9eff6162006-06-12 21:59:13 +00001625 struct sqlite3_index_constraint_usage {
1626 int argvIndex; /* if >0, constraint is part of argv to xFilter */
1627 unsigned char omit; /* Do not code a test for this constraint */
1628 } *const aConstraintUsage;
drh4be8b512006-06-13 23:51:34 +00001629 int idxNum; /* Number used to identify the index */
1630 char *idxStr; /* String, possibly obtained from sqlite3_malloc */
1631 int needToFreeIdxStr; /* Free idxStr using sqlite3_free() if true */
drh9eff6162006-06-12 21:59:13 +00001632 int orderByConsumed; /* True if output is already ordered */
1633 double estimatedCost; /* Estimated cost of using this index */
drhe09daa92006-06-10 13:29:31 +00001634};
drh9eff6162006-06-12 21:59:13 +00001635#define SQLITE_INDEX_CONSTRAINT_EQ 2
1636#define SQLITE_INDEX_CONSTRAINT_GT 4
1637#define SQLITE_INDEX_CONSTRAINT_LE 8
1638#define SQLITE_INDEX_CONSTRAINT_LT 16
1639#define SQLITE_INDEX_CONSTRAINT_GE 32
1640#define SQLITE_INDEX_CONSTRAINT_MATCH 64
1641
1642/*
1643** This routine is used to register a new module name with an SQLite
1644** connection. Module names must be registered before creating new
1645** virtual tables on the module, or before using preexisting virtual
1646** tables of the module.
1647*/
drhb9bb7c12006-06-11 23:41:55 +00001648int sqlite3_create_module(
drh9eff6162006-06-12 21:59:13 +00001649 sqlite3 *db, /* SQLite connection to register module with */
1650 const char *zName, /* Name of the module */
danielk1977d1ab1ba2006-06-15 04:28:13 +00001651 const sqlite3_module *, /* Methods for the module */
1652 void * /* Client data for xCreate/xConnect */
drhb9bb7c12006-06-11 23:41:55 +00001653);
drhe09daa92006-06-10 13:29:31 +00001654
drh9eff6162006-06-12 21:59:13 +00001655/*
1656** Every module implementation uses a subclass of the following structure
1657** to describe a particular instance of the module. Each subclass will
1658** be taylored to the specific needs of the module implementation. The
1659** purpose of this superclass is to define certain fields that are common
1660** to all module implementations.
1661*/
1662struct sqlite3_vtab {
drha967e882006-06-13 01:04:52 +00001663 const sqlite3_module *pModule; /* The module for this virtual table */
drh9eff6162006-06-12 21:59:13 +00001664 /* Virtual table implementations will typically add additional fields */
1665};
1666
1667/* Every module implementation uses a subclass of the following structure
1668** to describe cursors that point into the virtual table and are used
1669** to loop through the virtual table. Cursors are created using the
1670** xOpen method of the module. Each module implementation will define
1671** the content of a cursor structure to suit its own needs.
1672**
1673** This superclass exists in order to define fields of the cursor that
1674** are common to all implementations.
1675*/
1676struct sqlite3_vtab_cursor {
1677 sqlite3_vtab *pVtab; /* Virtual table of this cursor */
1678 /* Virtual table implementations will typically add additional fields */
1679};
1680
1681/*
1682** The xCreate and xConnect methods of a module use the following API
1683** to declare the format (the names and datatypes of the columns) of
1684** the virtual tables they implement.
1685*/
danielk19777e6ebfb2006-06-12 11:24:37 +00001686int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable);
drhe09daa92006-06-10 13:29:31 +00001687
1688/*
drh9eff6162006-06-12 21:59:13 +00001689** The interface to the virtual-table mechanism defined above (back up
1690** to a comment remarkably similar to this one) is currently considered
1691** to be experimental. The interface might change in incompatible ways.
1692** If this is a problem for you, do not use the interface at this time.
1693**
1694** When the virtual-table mechanism stablizes, we will declare the
1695** interface fixed, support it indefinitely, and remove this comment.
1696**
1697****** EXPERIMENTAL - subject to change without notice **************
1698*/
1699
1700/*
drhb37df7b2005-10-13 02:09:49 +00001701** Undo the hack that converts floating point types to integer for
1702** builds on processors without floating point support.
1703*/
1704#ifdef SQLITE_OMIT_FLOATING_POINT
1705# undef double
1706#endif
1707
drh382c0242001-10-06 16:33:02 +00001708#ifdef __cplusplus
1709} /* End of the 'extern "C"' block */
1710#endif
danielk19774adee202004-05-08 08:23:19 +00001711#endif