1/* 2** Copyright (c) 1999, 2000 D. Richard Hipp 3** 4** This program is free software; you can redistribute it and/or 5** modify it under the terms of the GNU General Public 6** License as published by the Free Software Foundation; either 7** version 2 of the License, or (at your option) any later version. 8** 9** This program is distributed in the hope that it will be useful, 10** but WITHOUT ANY WARRANTY; without even the implied warranty of 11** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12** General Public License for more details. 13** 14** You should have received a copy of the GNU General Public 15** License along with this library; if not, write to the 16** Free Software Foundation, Inc., 59 Temple Place - Suite 330, 17** Boston, MA 02111-1307, USA. 18** 19** Author contact information: 20** [email protected] 21** http://www.hwaci.com/drh/ 22** 23************************************************************************* 24** This header file defines the interface that the sqlite library 25** presents to client programs. 26** 27** @(#) $Id: sqlite.h.in,v 1.5 2000/10/09 12:57:01 drh Exp $ 28*/ 29#ifndef _SQLITE_H_ 30#define _SQLITE_H_ 31#include <stdarg.h> /* Needed for the definition of va_list */ 32 33/* 34** The version of the SQLite library. 35*/ 36#define SQLITE_VERSION "--VERS--" 37 38/* 39** The version string is also compiled into the library so that a program 40** can check to make sure that the lib*.a file and the *.h file are from 41** the same version. 42*/ 43extern const char sqlite_version[]; 44 45/* 46** Each open sqlite database is represented by an instance of the 47** following opaque structure. 48*/ 49typedef struct sqlite sqlite; 50 51/* 52** A function to open a new sqlite database. 53** 54** If the database does not exist and mode indicates write 55** permission, then a new database is created. If the database 56** does not exist and mode does not indicate write permission, 57** then the open fails, an error message generated (if errmsg!=0) 58** and the function returns 0. 59** 60** If mode does not indicates user write permission, then the 61** database is opened read-only. 62** 63** The Truth: As currently implemented, all databases are opened 64** for writing all the time. Maybe someday we will provide the 65** ability to open a database readonly. The mode parameters is 66** provide in anticipation of that enhancement. 67*/ 68sqlite *sqlite_open(const char *filename, int mode, char **errmsg); 69 70/* 71** A function to close the database. 72** 73** Call this function with a pointer to a structure that was previously 74** returned from sqlite_open() and the corresponding database will by closed. 75*/ 76void sqlite_close(sqlite *); 77 78/* 79** The type for a callback function. 80*/ 81typedef int (*sqlite_callback)(void*,int,char**, char**); 82 83/* 84** A function to executes one or more statements of SQL. 85** 86** If one or more of the SQL statements are queries, then 87** the callback function specified by the 3rd parameter is 88** invoked once for each row of the query result. This callback 89** should normally return 0. If the callback returns a non-zero 90** value then the query is aborted, all subsequent SQL statements 91** are skipped and the sqlite_exec() function returns the SQLITE_ABORT. 92** 93** The 4th parameter is an arbitrary pointer that is passed 94** to the callback function as its first parameter. 95** 96** The 2nd parameter to the callback function is the number of 97** columns in the query result. The 3rd parameter is an array 98** of string holding the values for each column. The 4th parameter 99** is an array of strings holding the names of each column. 100** 101** The callback function may be NULL, even for queries. A NULL 102** callback is not an error. It just means that no callback 103** will be invoked. 104** 105** If an error occurs while parsing or evaluating the SQL (but 106** not while executing the callback) then an appropriate error 107** message is written into memory obtained from malloc() and 108** *errmsg is made to point to that message. If errmsg==NULL, 109** then no error message is ever written. The return value is 110** SQLITE_ERROR if an error occurs. The calling function is 111** responsible for freeing the memory that holds the error 112** message. 113** 114** If the query could not be executed because a database file is 115** locked or busy, then this function returns SQLITE_BUSY. (This 116** behavior can be modified somewhat using the sqlite_busy_handler() 117** and sqlite_busy_timeout() functions below.) If the query could 118** not be executed because a file is missing or has incorrect 119** permissions, this function returns SQLITE_ERROR. 120*/ 121int sqlite_exec( 122 sqlite*, /* An open database */ 123 char *sql, /* SQL to be executed */ 124 sqlite_callback, /* Callback function */ 125 void *, /* 1st argument to callback function */ 126 char **errmsg /* Error msg written here */ 127); 128 129/* 130** Return values for sqlite_exec() 131*/ 132#define SQLITE_OK 0 /* Successful result */ 133#define SQLITE_INTERNAL 1 /* An internal logic error in SQLite */ 134#define SQLITE_ERROR 2 /* SQL error or missing database */ 135#define SQLITE_PERM 3 /* Access permission denied */ 136#define SQLITE_ABORT 4 /* Callback routine requested an abort */ 137#define SQLITE_BUSY 5 /* One or more database files are locked */ 138#define SQLITE_NOMEM 6 /* A malloc() failed */ 139#define SQLITE_READONLY 7 /* Attempt to write a readonly database */ 140 141/* This function returns true if the given input string comprises 142** one or more complete SQL statements. 143** 144** The algorithm is simple. If the last token other than spaces 145** and comments is a semicolon, then return true. otherwise return 146** false. 147*/ 148int sqlite_complete(const char *sql); 149 150/* 151** This routine identifies a callback function that is invoked 152** whenever an attempt is made to open a database table that is 153** currently locked by another process or thread. If the busy callback 154** is NULL, then sqlite_exec() returns SQLITE_BUSY immediately if 155** it finds a locked table. If the busy callback is not NULL, then 156** sqlite_exec() invokes the callback with three arguments. The 157** second argument is the name of the locked table and the third 158** argument is the number of times the table has been busy. If the 159** busy callback returns 0, then sqlite_exec() immediately returns 160** SQLITE_BUSY. If the callback returns non-zero, then sqlite_exec() 161** tries to open the table again and the cycle repeats. 162** 163** The default busy callback is NULL. 164** 165** Sqlite is re-entrant, so the busy handler may start a new query. 166** (It is not clear why anyone would every want to do this, but it 167** is allowed, in theory.) But the busy handler may not close the 168** database. Closing the database from a busy handler will delete 169** data structures out from under the executing query and will 170** probably result in a coredump. 171*/ 172void sqlite_busy_handler(sqlite*, int(*)(void*,const char*,int), void*); 173 174/* 175** This routine sets a busy handler that sleeps for a while when a 176** table is locked. The handler will sleep multiple times until 177** at least "ms" milleseconds of sleeping have been done. After 178** "ms" milleseconds of sleeping, the handler returns 0 which 179** causes sqlite_exec() to return SQLITE_BUSY. 180** 181** Calling this routine with an argument less than or equal to zero 182** turns off all busy handlers. 183*/ 184void sqlite_busy_timeout(sqlite*, int ms); 185 186/* 187** This next routine is really just a wrapper around sqlite_exec(). 188** Instead of invoking a user-supplied callback for each row of the 189** result, this routine remembers each row of the result in memory 190** obtained from malloc(), then returns all of the result after the 191** query has finished. 192** 193** As an example, suppose the query result where this table: 194** 195** Name | Age 196** ----------------------- 197** Alice | 43 198** Bob | 28 199** Cindy | 21 200** 201** If the 3rd argument were &azResult then after the function returns 202** azResult will contain the following data: 203** 204** azResult[0] = "Name"; 205** azResult[1] = "Age"; 206** azResult[2] = "Alice"; 207** azResult[3] = "43"; 208** azResult[4] = "Bob"; 209** azResult[5] = "28"; 210** azResult[6] = "Cindy"; 211** azResult[7] = "21"; 212** 213** Notice that there is an extra row of data containing the column 214** headers. But the *nrow return value is still 3. *ncolumn is 215** set to 2. In general, the number of values inserted into azResult 216** will be ((*nrow) + 1)*(*ncolumn). 217** 218** After the calling function has finished using the result, it should 219** pass the result data pointer to sqlite_free_table() in order to 220** release the memory that was malloc-ed. Because of the way the 221** malloc() happens, the calling function must not try to call 222** malloc() directly. Only sqlite_free_table() is able to release 223** the memory properly and safely. 224** 225** The return value of this routine is the same as from sqlite_exec(). 226*/ 227int sqlite_get_table( 228 sqlite*, /* An open database */ 229 char *sql, /* SQL to be executed */ 230 char ***resultp, /* Result written to a char *[] that this points to */ 231 int *nrow, /* Number of result rows written here */ 232 int *ncolumn, /* Number of result columns written here */ 233 char **errmsg /* Error msg written here */ 234); 235 236/* 237** Call this routine to free the memory that sqlite_get_table() allocated. 238*/ 239void sqlite_free_table(char **result); 240 241/* 242** The following routines are wrappers around sqlite_exec() and 243** sqlite_get_table(). The only difference between the routines that 244** follow and the originals is that the second argument to the 245** routines that follow is really a printf()-style format 246** string describing the SQL to be executed. Arguments to the format 247** string appear at the end of the argument list. 248** 249** All of the usual printf formatting options apply. In addition, there 250** is a "%q" option. %q works like %s in that it substitutes a null-terminated 251** string from the argument list. But %q also double every '\'' character. 252** %q is designed for use inside a string literal. By doubling each '\'' 253** character is escapes that character and allows it to be inserted into 254** the string. 255** 256** For example, so some string variable contains text as follows: 257** 258** char *zText = "It's a happy day!"; 259** 260** We can use this text in an SQL statement as follows: 261** 262** sqlite_exec_printf(db, "INSERT INTO table VALUES('%q')", 263** callback1, 0, 0, zText); 264** 265** Because the %q format string is used, the '\'' character in zText 266** is escaped and the SQL generated is as follows: 267** 268** INSERT INTO table1 VALUES('It''s a happy day!') 269** 270** This is correct. Had we used %s instead of %q, the generated SQL 271** would have looked like this: 272** 273** INSERT INTO table1 VALUES('It's a happy day!'); 274** 275** This second example is an SQL syntax error. As a general rule you 276** should always use %q instead of %s when inserting text into a string 277** literal. 278*/ 279int sqlite_exec_printf( 280 sqlite*, /* An open database */ 281 char *sqlFormat, /* printf-style format string for the SQL */ 282 sqlite_callback, /* Callback function */ 283 void *, /* 1st argument to callback function */ 284 char **errmsg, /* Error msg written here */ 285 ... /* Arguments to the format string. */ 286); 287int sqlite_exec_vprintf( 288 sqlite*, /* An open database */ 289 char *sqlFormat, /* printf-style format string for the SQL */ 290 sqlite_callback, /* Callback function */ 291 void *, /* 1st argument to callback function */ 292 char **errmsg, /* Error msg written here */ 293 va_list ap /* Arguments to the format string. */ 294); 295int sqlite_get_table_printf( 296 sqlite*, /* An open database */ 297 char *sqlFormat, /* printf-style format string for the SQL */ 298 char ***resultp, /* Result written to a char *[] that this points to */ 299 int *nrow, /* Number of result rows written here */ 300 int *ncolumn, /* Number of result columns written here */ 301 char **errmsg, /* Error msg written here */ 302 ... /* Arguments to the format string */ 303); 304int sqlite_get_table_vprintf( 305 sqlite*, /* An open database */ 306 char *sqlFormat, /* printf-style format string for the SQL */ 307 char ***resultp, /* Result written to a char *[] that this points to */ 308 int *nrow, /* Number of result rows written here */ 309 int *ncolumn, /* Number of result columns written here */ 310 char **errmsg, /* Error msg written here */ 311 va_list ap /* Arguments to the format string */ 312); 313 314 315#endif /* _SQLITE_H_ */ 316