drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 1 | /* |
drh | b19a2bc | 2001-09-16 00:13:26 +0000 | [diff] [blame^] | 2 | ** 2001 September 15 |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 3 | ** |
drh | b19a2bc | 2001-09-16 00:13:26 +0000 | [diff] [blame^] | 4 | ** The author disclaims copyright to this source code. In place of |
| 5 | ** a legal notice, here is a blessing: |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 6 | ** |
drh | b19a2bc | 2001-09-16 00:13:26 +0000 | [diff] [blame^] | 7 | ** 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. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 10 | ** |
| 11 | ************************************************************************* |
drh | b19a2bc | 2001-09-16 00:13:26 +0000 | [diff] [blame^] | 12 | ** This header file defines the interface that the SQLite library |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 13 | ** presents to client programs. |
| 14 | ** |
drh | b19a2bc | 2001-09-16 00:13:26 +0000 | [diff] [blame^] | 15 | ** @(#) $Id: sqlite.h.in,v 1.17 2001/09/16 00:13:27 drh Exp $ |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 16 | */ |
| 17 | #ifndef _SQLITE_H_ |
| 18 | #define _SQLITE_H_ |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 19 | #include <stdarg.h> /* Needed for the definition of va_list */ |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 20 | |
| 21 | /* |
drh | b217a57 | 2000-08-22 13:40:18 +0000 | [diff] [blame] | 22 | ** The version of the SQLite library. |
drh | 303aaa7 | 2000-08-17 10:22:34 +0000 | [diff] [blame] | 23 | */ |
drh | b217a57 | 2000-08-22 13:40:18 +0000 | [diff] [blame] | 24 | #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 | */ |
| 31 | extern const char sqlite_version[]; |
drh | 303aaa7 | 2000-08-17 10:22:34 +0000 | [diff] [blame] | 32 | |
| 33 | /* |
drh | 297ecf1 | 2001-04-05 15:57:13 +0000 | [diff] [blame] | 34 | ** 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 | */ |
drh | fbc3eab | 2001-04-06 16:13:42 +0000 | [diff] [blame] | 46 | extern const char sqlite_encoding[]; |
drh | 297ecf1 | 2001-04-05 15:57:13 +0000 | [diff] [blame] | 47 | |
| 48 | /* |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 49 | ** Each open sqlite database is represented by an instance of the |
| 50 | ** following opaque structure. |
| 51 | */ |
| 52 | typedef 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 | */ |
| 71 | sqlite *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 | */ |
| 79 | void sqlite_close(sqlite *); |
| 80 | |
| 81 | /* |
| 82 | ** The type for a callback function. |
| 83 | */ |
| 84 | typedef 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 |
drh | 58b9576 | 2000-06-02 01:17:37 +0000 | [diff] [blame] | 94 | ** are skipped and the sqlite_exec() function returns the SQLITE_ABORT. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 95 | ** |
| 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 |
drh | b19a2bc | 2001-09-16 00:13:26 +0000 | [diff] [blame^] | 100 | ** 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. |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 104 | ** |
| 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 |
drh | b19a2bc | 2001-09-16 00:13:26 +0000 | [diff] [blame^] | 112 | ** *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. |
drh | 58b9576 | 2000-06-02 01:17:37 +0000 | [diff] [blame] | 119 | ** |
| 120 | ** If the query could not be executed because a database file is |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 121 | ** locked or busy, then this function returns SQLITE_BUSY. (This |
| 122 | ** behavior can be modified somewhat using the sqlite_busy_handler() |
drh | b19a2bc | 2001-09-16 00:13:26 +0000 | [diff] [blame^] | 123 | ** and sqlite_busy_timeout() functions below.) |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 124 | */ |
| 125 | int 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 | |
drh | 58b9576 | 2000-06-02 01:17:37 +0000 | [diff] [blame] | 133 | /* |
drh | 98699b5 | 2000-10-09 12:57:00 +0000 | [diff] [blame] | 134 | ** Return values for sqlite_exec() |
drh | 58b9576 | 2000-06-02 01:17:37 +0000 | [diff] [blame] | 135 | */ |
| 136 | #define SQLITE_OK 0 /* Successful result */ |
drh | 4c50439 | 2000-10-16 22:06:40 +0000 | [diff] [blame] | 137 | #define SQLITE_ERROR 1 /* SQL error or missing database */ |
| 138 | #define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */ |
drh | eec553b | 2000-06-02 01:51:20 +0000 | [diff] [blame] | 139 | #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 */ |
drh | 4c50439 | 2000-10-16 22:06:40 +0000 | [diff] [blame] | 144 | #define SQLITE_INTERRUPT 8 /* Operation terminated by sqlite_interrupt() */ |
drh | b19a2bc | 2001-09-16 00:13:26 +0000 | [diff] [blame^] | 145 | #define SQLITE_IOERR 9 /* Some kind of disk I/O error occurred */ |
drh | 41a2b48 | 2001-01-20 19:52:49 +0000 | [diff] [blame] | 146 | #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 */ |
drh | 960e8c6 | 2001-04-03 16:53:21 +0000 | [diff] [blame] | 149 | #define SQLITE_CANTOPEN 13 /* Unable to open the database file */ |
| 150 | #define SQLITE_PROTOCOL 14 /* Database lock protocol error */ |
drh | 5e00f6c | 2001-09-13 13:46:56 +0000 | [diff] [blame] | 151 | #define SQLITE_EMPTY 15 /* Database table is empty */ |
drh | 50e5dad | 2001-09-15 00:57:28 +0000 | [diff] [blame] | 152 | #define SQLITE_SCHEMA 16 /* The database schema changed */ |
drh | 092d035 | 2001-09-15 13:15:12 +0000 | [diff] [blame] | 153 | #define SQLITE_TOOBIG 17 /* Too much data for one row of a table */ |
drh | 4c50439 | 2000-10-16 22:06:40 +0000 | [diff] [blame] | 154 | |
| 155 | /* This function causes any pending database operation to abort and |
| 156 | ** return at its earliest opportunity. This routine is typically |
drh | 66b89c8 | 2000-11-28 20:47:17 +0000 | [diff] [blame] | 157 | ** called in response to a user action such as pressing "Cancel" |
drh | 4c50439 | 2000-10-16 22:06:40 +0000 | [diff] [blame] | 158 | ** or Ctrl-C where the user wants a long query operation to halt |
| 159 | ** immediately. |
| 160 | */ |
| 161 | void sqlite_interrupt(sqlite*); |
| 162 | |
drh | eec553b | 2000-06-02 01:51:20 +0000 | [diff] [blame] | 163 | |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 164 | /* 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 | */ |
| 171 | int sqlite_complete(const char *sql); |
| 172 | |
drh | 2dfbbca | 2000-07-28 14:32:48 +0000 | [diff] [blame] | 173 | /* |
| 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 | */ |
| 195 | void 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 | */ |
| 207 | void sqlite_busy_timeout(sqlite*, int ms); |
| 208 | |
drh | e371033 | 2000-09-29 13:30:53 +0000 | [diff] [blame] | 209 | /* |
| 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 |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 214 | ** 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 |
drh | 98699b5 | 2000-10-09 12:57:00 +0000 | [diff] [blame] | 225 | ** azResult will contain the following data: |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 226 | ** |
| 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. |
drh | e371033 | 2000-09-29 13:30:53 +0000 | [diff] [blame] | 247 | ** |
| 248 | ** The return value of this routine is the same as from sqlite_exec(). |
| 249 | */ |
| 250 | int 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 | */ |
| 262 | void sqlite_free_table(char **result); |
| 263 | |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 264 | /* |
| 265 | ** The following routines are wrappers around sqlite_exec() and |
drh | 98699b5 | 2000-10-09 12:57:00 +0000 | [diff] [blame] | 266 | ** sqlite_get_table(). The only difference between the routines that |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 267 | ** 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 |
drh | 66b89c8 | 2000-11-28 20:47:17 +0000 | [diff] [blame] | 274 | ** string from the argument list. But %q also doubles every '\'' character. |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 275 | ** %q is designed for use inside a string literal. By doubling each '\'' |
drh | 66b89c8 | 2000-11-28 20:47:17 +0000 | [diff] [blame] | 276 | ** character it escapes that character and allows it to be inserted into |
drh | a18c568 | 2000-10-08 22:20:57 +0000 | [diff] [blame] | 277 | ** 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 | */ |
| 302 | int 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 | ); |
| 310 | int 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 | ); |
| 318 | int 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 | ); |
| 327 | int 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 | |
drh | 7589723 | 2000-05-29 14:26:00 +0000 | [diff] [blame] | 337 | #endif /* _SQLITE_H_ */ |