blob: d757cd45ec4e54c02bfcb9c1c7e825c0e043098a [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**
drhb19a2bc2001-09-16 00:13:26 +000015** @(#) $Id: sqlite.h.in,v 1.17 2001/09/16 00:13:27 drh Exp $
drh75897232000-05-29 14:26:00 +000016*/
17#ifndef _SQLITE_H_
18#define _SQLITE_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/*
drhb217a572000-08-22 13:40:18 +000022** The version of the SQLite library.
drh303aaa72000-08-17 10:22:34 +000023*/
drhb217a572000-08-22 13:40:18 +000024#define SQLITE_VERSION "--VERS--"
25
26/*
27** The version string is also compiled into the library so that a program
28** can check to make sure that the lib*.a file and the *.h file are from
29** the same version.
30*/
31extern const char sqlite_version[];
drh303aaa72000-08-17 10:22:34 +000032
33/*
drh297ecf12001-04-05 15:57:13 +000034** The SQLITE_UTF8 macro is defined if the library expects to see
35** UTF-8 encoded data. The SQLITE_ISO8859 macro is defined if the
36** iso8859 encoded should be used.
37*/
38#define SQLITE_--ENCODING-- 1
39
40/*
41** The following constant holds one of two strings, "UTF-8" or "iso8859",
42** depending on which character encoding the SQLite library expects to
43** see. The character encoding makes a difference for the LIKE and GLOB
44** operators and for the LENGTH() and SUBSTR() functions.
45*/
drhfbc3eab2001-04-06 16:13:42 +000046extern const char sqlite_encoding[];
drh297ecf12001-04-05 15:57:13 +000047
48/*
drh75897232000-05-29 14:26:00 +000049** Each open sqlite database is represented by an instance of the
50** following opaque structure.
51*/
52typedef struct sqlite sqlite;
53
54/*
55** A function to open a new sqlite database.
56**
57** If the database does not exist and mode indicates write
58** permission, then a new database is created. If the database
59** does not exist and mode does not indicate write permission,
60** then the open fails, an error message generated (if errmsg!=0)
61** and the function returns 0.
62**
63** If mode does not indicates user write permission, then the
64** database is opened read-only.
65**
66** The Truth: As currently implemented, all databases are opened
67** for writing all the time. Maybe someday we will provide the
68** ability to open a database readonly. The mode parameters is
69** provide in anticipation of that enhancement.
70*/
71sqlite *sqlite_open(const char *filename, int mode, char **errmsg);
72
73/*
74** A function to close the database.
75**
76** Call this function with a pointer to a structure that was previously
77** returned from sqlite_open() and the corresponding database will by closed.
78*/
79void sqlite_close(sqlite *);
80
81/*
82** The type for a callback function.
83*/
84typedef int (*sqlite_callback)(void*,int,char**, char**);
85
86/*
87** A function to executes one or more statements of SQL.
88**
89** If one or more of the SQL statements are queries, then
90** the callback function specified by the 3rd parameter is
91** invoked once for each row of the query result. This callback
92** should normally return 0. If the callback returns a non-zero
93** value then the query is aborted, all subsequent SQL statements
drh58b95762000-06-02 01:17:37 +000094** are skipped and the sqlite_exec() function returns the SQLITE_ABORT.
drh75897232000-05-29 14:26:00 +000095**
96** The 4th parameter is an arbitrary pointer that is passed
97** to the callback function as its first parameter.
98**
99** The 2nd parameter to the callback function is the number of
drhb19a2bc2001-09-16 00:13:26 +0000100** columns in the query result. The 3rd parameter to the callback
101** is an array of strings holding the values for each column.
102** The 4th parameter to the callback is an array of strings holding
103** the names of each column.
drh75897232000-05-29 14:26:00 +0000104**
105** The callback function may be NULL, even for queries. A NULL
106** callback is not an error. It just means that no callback
107** will be invoked.
108**
109** If an error occurs while parsing or evaluating the SQL (but
110** not while executing the callback) then an appropriate error
111** message is written into memory obtained from malloc() and
drhb19a2bc2001-09-16 00:13:26 +0000112** *errmsg is made to point to that message. The calling function
113** is responsible for freeing the memory that holds the error
114** message. If errmsg==NULL, then no error message is ever written.
115**
116** The return value is is SQLITE_OK if there are no errors and
117** some other return code if there is an error. The particular
118** return value depends on the type of error.
drh58b95762000-06-02 01:17:37 +0000119**
120** If the query could not be executed because a database file is
drh2dfbbca2000-07-28 14:32:48 +0000121** locked or busy, then this function returns SQLITE_BUSY. (This
122** behavior can be modified somewhat using the sqlite_busy_handler()
drhb19a2bc2001-09-16 00:13:26 +0000123** and sqlite_busy_timeout() functions below.)
drh75897232000-05-29 14:26:00 +0000124*/
125int sqlite_exec(
126 sqlite*, /* An open database */
127 char *sql, /* SQL to be executed */
128 sqlite_callback, /* Callback function */
129 void *, /* 1st argument to callback function */
130 char **errmsg /* Error msg written here */
131);
132
drh58b95762000-06-02 01:17:37 +0000133/*
drh98699b52000-10-09 12:57:00 +0000134** Return values for sqlite_exec()
drh58b95762000-06-02 01:17:37 +0000135*/
136#define SQLITE_OK 0 /* Successful result */
drh4c504392000-10-16 22:06:40 +0000137#define SQLITE_ERROR 1 /* SQL error or missing database */
138#define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */
drheec553b2000-06-02 01:51:20 +0000139#define SQLITE_PERM 3 /* Access permission denied */
140#define SQLITE_ABORT 4 /* Callback routine requested an abort */
141#define SQLITE_BUSY 5 /* One or more database files are locked */
142#define SQLITE_NOMEM 6 /* A malloc() failed */
143#define SQLITE_READONLY 7 /* Attempt to write a readonly database */
drh4c504392000-10-16 22:06:40 +0000144#define SQLITE_INTERRUPT 8 /* Operation terminated by sqlite_interrupt() */
drhb19a2bc2001-09-16 00:13:26 +0000145#define SQLITE_IOERR 9 /* Some kind of disk I/O error occurred */
drh41a2b482001-01-20 19:52:49 +0000146#define SQLITE_CORRUPT 10 /* The database disk image is malformed */
147#define SQLITE_NOTFOUND 11 /* Table or record not found */
148#define SQLITE_FULL 12 /* Insertion failed because database is full */
drh960e8c62001-04-03 16:53:21 +0000149#define SQLITE_CANTOPEN 13 /* Unable to open the database file */
150#define SQLITE_PROTOCOL 14 /* Database lock protocol error */
drh5e00f6c2001-09-13 13:46:56 +0000151#define SQLITE_EMPTY 15 /* Database table is empty */
drh50e5dad2001-09-15 00:57:28 +0000152#define SQLITE_SCHEMA 16 /* The database schema changed */
drh092d0352001-09-15 13:15:12 +0000153#define SQLITE_TOOBIG 17 /* Too much data for one row of a table */
drh4c504392000-10-16 22:06:40 +0000154
155/* This function causes any pending database operation to abort and
156** return at its earliest opportunity. This routine is typically
drh66b89c82000-11-28 20:47:17 +0000157** called in response to a user action such as pressing "Cancel"
drh4c504392000-10-16 22:06:40 +0000158** or Ctrl-C where the user wants a long query operation to halt
159** immediately.
160*/
161void sqlite_interrupt(sqlite*);
162
drheec553b2000-06-02 01:51:20 +0000163
drh75897232000-05-29 14:26:00 +0000164/* This function returns true if the given input string comprises
165** one or more complete SQL statements.
166**
167** The algorithm is simple. If the last token other than spaces
168** and comments is a semicolon, then return true. otherwise return
169** false.
170*/
171int sqlite_complete(const char *sql);
172
drh2dfbbca2000-07-28 14:32:48 +0000173/*
174** This routine identifies a callback function that is invoked
175** whenever an attempt is made to open a database table that is
176** currently locked by another process or thread. If the busy callback
177** is NULL, then sqlite_exec() returns SQLITE_BUSY immediately if
178** it finds a locked table. If the busy callback is not NULL, then
179** sqlite_exec() invokes the callback with three arguments. The
180** second argument is the name of the locked table and the third
181** argument is the number of times the table has been busy. If the
182** busy callback returns 0, then sqlite_exec() immediately returns
183** SQLITE_BUSY. If the callback returns non-zero, then sqlite_exec()
184** tries to open the table again and the cycle repeats.
185**
186** The default busy callback is NULL.
187**
188** Sqlite is re-entrant, so the busy handler may start a new query.
189** (It is not clear why anyone would every want to do this, but it
190** is allowed, in theory.) But the busy handler may not close the
191** database. Closing the database from a busy handler will delete
192** data structures out from under the executing query and will
193** probably result in a coredump.
194*/
195void sqlite_busy_handler(sqlite*, int(*)(void*,const char*,int), void*);
196
197/*
198** This routine sets a busy handler that sleeps for a while when a
199** table is locked. The handler will sleep multiple times until
200** at least "ms" milleseconds of sleeping have been done. After
201** "ms" milleseconds of sleeping, the handler returns 0 which
202** causes sqlite_exec() to return SQLITE_BUSY.
203**
204** Calling this routine with an argument less than or equal to zero
205** turns off all busy handlers.
206*/
207void sqlite_busy_timeout(sqlite*, int ms);
208
drhe3710332000-09-29 13:30:53 +0000209/*
210** This next routine is really just a wrapper around sqlite_exec().
211** Instead of invoking a user-supplied callback for each row of the
212** result, this routine remembers each row of the result in memory
213** obtained from malloc(), then returns all of the result after the
drha18c5682000-10-08 22:20:57 +0000214** query has finished.
215**
216** As an example, suppose the query result where this table:
217**
218** Name | Age
219** -----------------------
220** Alice | 43
221** Bob | 28
222** Cindy | 21
223**
224** If the 3rd argument were &azResult then after the function returns
drh98699b52000-10-09 12:57:00 +0000225** azResult will contain the following data:
drha18c5682000-10-08 22:20:57 +0000226**
227** azResult[0] = "Name";
228** azResult[1] = "Age";
229** azResult[2] = "Alice";
230** azResult[3] = "43";
231** azResult[4] = "Bob";
232** azResult[5] = "28";
233** azResult[6] = "Cindy";
234** azResult[7] = "21";
235**
236** Notice that there is an extra row of data containing the column
237** headers. But the *nrow return value is still 3. *ncolumn is
238** set to 2. In general, the number of values inserted into azResult
239** will be ((*nrow) + 1)*(*ncolumn).
240**
241** After the calling function has finished using the result, it should
242** pass the result data pointer to sqlite_free_table() in order to
243** release the memory that was malloc-ed. Because of the way the
244** malloc() happens, the calling function must not try to call
245** malloc() directly. Only sqlite_free_table() is able to release
246** the memory properly and safely.
drhe3710332000-09-29 13:30:53 +0000247**
248** The return value of this routine is the same as from sqlite_exec().
249*/
250int sqlite_get_table(
251 sqlite*, /* An open database */
252 char *sql, /* SQL to be executed */
253 char ***resultp, /* Result written to a char *[] that this points to */
254 int *nrow, /* Number of result rows written here */
255 int *ncolumn, /* Number of result columns written here */
256 char **errmsg /* Error msg written here */
257);
258
259/*
260** Call this routine to free the memory that sqlite_get_table() allocated.
261*/
262void sqlite_free_table(char **result);
263
drha18c5682000-10-08 22:20:57 +0000264/*
265** The following routines are wrappers around sqlite_exec() and
drh98699b52000-10-09 12:57:00 +0000266** sqlite_get_table(). The only difference between the routines that
drha18c5682000-10-08 22:20:57 +0000267** follow and the originals is that the second argument to the
268** routines that follow is really a printf()-style format
269** string describing the SQL to be executed. Arguments to the format
270** string appear at the end of the argument list.
271**
272** All of the usual printf formatting options apply. In addition, there
273** is a "%q" option. %q works like %s in that it substitutes a null-terminated
drh66b89c82000-11-28 20:47:17 +0000274** string from the argument list. But %q also doubles every '\'' character.
drha18c5682000-10-08 22:20:57 +0000275** %q is designed for use inside a string literal. By doubling each '\''
drh66b89c82000-11-28 20:47:17 +0000276** character it escapes that character and allows it to be inserted into
drha18c5682000-10-08 22:20:57 +0000277** the string.
278**
279** For example, so some string variable contains text as follows:
280**
281** char *zText = "It's a happy day!";
282**
283** We can use this text in an SQL statement as follows:
284**
285** sqlite_exec_printf(db, "INSERT INTO table VALUES('%q')",
286** callback1, 0, 0, zText);
287**
288** Because the %q format string is used, the '\'' character in zText
289** is escaped and the SQL generated is as follows:
290**
291** INSERT INTO table1 VALUES('It''s a happy day!')
292**
293** This is correct. Had we used %s instead of %q, the generated SQL
294** would have looked like this:
295**
296** INSERT INTO table1 VALUES('It's a happy day!');
297**
298** This second example is an SQL syntax error. As a general rule you
299** should always use %q instead of %s when inserting text into a string
300** literal.
301*/
302int sqlite_exec_printf(
303 sqlite*, /* An open database */
304 char *sqlFormat, /* printf-style format string for the SQL */
305 sqlite_callback, /* Callback function */
306 void *, /* 1st argument to callback function */
307 char **errmsg, /* Error msg written here */
308 ... /* Arguments to the format string. */
309);
310int sqlite_exec_vprintf(
311 sqlite*, /* An open database */
312 char *sqlFormat, /* printf-style format string for the SQL */
313 sqlite_callback, /* Callback function */
314 void *, /* 1st argument to callback function */
315 char **errmsg, /* Error msg written here */
316 va_list ap /* Arguments to the format string. */
317);
318int sqlite_get_table_printf(
319 sqlite*, /* An open database */
320 char *sqlFormat, /* printf-style format string for the SQL */
321 char ***resultp, /* Result written to a char *[] that this points to */
322 int *nrow, /* Number of result rows written here */
323 int *ncolumn, /* Number of result columns written here */
324 char **errmsg, /* Error msg written here */
325 ... /* Arguments to the format string */
326);
327int sqlite_get_table_vprintf(
328 sqlite*, /* An open database */
329 char *sqlFormat, /* printf-style format string for the SQL */
330 char ***resultp, /* Result written to a char *[] that this points to */
331 int *nrow, /* Number of result rows written here */
332 int *ncolumn, /* Number of result columns written here */
333 char **errmsg, /* Error msg written here */
334 va_list ap /* Arguments to the format string */
335);
336
drh75897232000-05-29 14:26:00 +0000337#endif /* _SQLITE_H_ */