4 ** The author disclaims copyright to this source code. In place of
5 ** a legal notice, here is a blessing:
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.
11 *************************************************************************
12 ** This header file defines the interface that the SQLite library
13 ** presents to client programs.
15 ** @(#) $Id: sqlite3.h,v 1.1 2008/10/02 10:51:04 guigues Exp $
19 #include <stdarg.h> /* Needed for the definition of va_list */
22 ** Make sure we can call this stuff from C++.
29 ** The version of the SQLite library.
32 # undef SQLITE_VERSION
34 # define SQLITE_VERSION "3.0.8"
38 ** The version string is also compiled into the library so that a program
39 ** can check to make sure that the lib*.a file and the *.h file are from
40 ** the same version. The sqlite3_libversion() function returns a pointer
41 ** to the sqlite3_version variable - useful in DLLs which cannot access
44 extern const char sqlite3_version[];
45 const char *sqlite3_libversion(void);
48 ** Each open sqlite database is represented by an instance of the
49 ** following opaque structure.
51 typedef struct sqlite3 sqlite3;
55 ** Some compilers do not support the "long long" datatype. So we have
56 ** to do a typedef that for 64-bit integers that depends on what compiler
59 #if defined(_MSC_VER) || defined(__BORLANDC__)
60 typedef __int64 sqlite_int64;
61 typedef unsigned __int64 sqlite_uint64;
63 typedef long long int sqlite_int64;
64 typedef unsigned long long int sqlite_uint64;
69 ** A function to close the database.
71 ** Call this function with a pointer to a structure that was previously
72 ** returned from sqlite3_open() and the corresponding database will by closed.
74 ** All SQL statements prepared using sqlite3_prepare() or
75 ** sqlite3_prepare16() must be deallocated using sqlite3_finalize() before
76 ** this routine is called. Otherwise, SQLITE_BUSY is returned and the
77 ** database connection remains open.
79 int sqlite3_close(sqlite3 *);
82 ** The type for a callback function.
84 typedef int (*sqlite3_callback)(void*,int,char**, char**);
87 ** A function to executes one or more statements of SQL.
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
94 ** are skipped and the sqlite3_exec() function returns the SQLITE_ABORT.
96 ** The 4th parameter is an arbitrary pointer that is passed
97 ** to the callback function as its first parameter.
99 ** The 2nd parameter to the callback function is the number of
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.
105 ** The callback function may be NULL, even for queries. A NULL
106 ** callback is not an error. It just means that no callback
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
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. Use sqlite3_free() for this. If errmsg==NULL,
115 ** then no error message is ever written.
117 ** The return value is is SQLITE_OK if there are no errors and
118 ** some other return code if there is an error. The particular
119 ** return value depends on the type of error.
121 ** If the query could not be executed because a database file is
122 ** locked or busy, then this function returns SQLITE_BUSY. (This
123 ** behavior can be modified somewhat using the sqlite3_busy_handler()
124 ** and sqlite3_busy_timeout() functions below.)
127 sqlite3*, /* An open database */
128 const char *sql, /* SQL to be executed */
129 sqlite3_callback, /* Callback function */
130 void *, /* 1st argument to callback function */
131 char **errmsg /* Error msg written here */
135 ** Return values for sqlite3_exec() and sqlite3_step()
137 #define SQLITE_OK 0 /* Successful result */
138 #define SQLITE_ERROR 1 /* SQL error or missing database */
139 #define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */
140 #define SQLITE_PERM 3 /* Access permission denied */
141 #define SQLITE_ABORT 4 /* Callback routine requested an abort */
142 #define SQLITE_BUSY 5 /* The database file is locked */
143 #define SQLITE_LOCKED 6 /* A table in the database is locked */
144 #define SQLITE_NOMEM 7 /* A malloc() failed */
145 #define SQLITE_READONLY 8 /* Attempt to write a readonly database */
146 #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
147 #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
148 #define SQLITE_CORRUPT 11 /* The database disk image is malformed */
149 #define SQLITE_NOTFOUND 12 /* (Internal Only) Table or record not found */
150 #define SQLITE_FULL 13 /* Insertion failed because database is full */
151 #define SQLITE_CANTOPEN 14 /* Unable to open the database file */
152 #define SQLITE_PROTOCOL 15 /* Database lock protocol error */
153 #define SQLITE_EMPTY 16 /* Database is empty */
154 #define SQLITE_SCHEMA 17 /* The database schema changed */
155 #define SQLITE_TOOBIG 18 /* Too much data for one row of a table */
156 #define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */
157 #define SQLITE_MISMATCH 20 /* Data type mismatch */
158 #define SQLITE_MISUSE 21 /* Library used incorrectly */
159 #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
160 #define SQLITE_AUTH 23 /* Authorization denied */
161 #define SQLITE_FORMAT 24 /* Auxiliary database format error */
162 #define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
163 #define SQLITE_NOTADB 26 /* File opened that is not a database file */
164 #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
165 #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
168 ** Each entry in an SQLite table has a unique integer key. (The key is
169 ** the value of the INTEGER PRIMARY KEY column if there is such a column,
170 ** otherwise the key is generated at random. The unique key is always
171 ** available as the ROWID, OID, or _ROWID_ column.) The following routine
172 ** returns the integer key of the most recent insert in the database.
174 ** This function is similar to the mysql_insert_id() function from MySQL.
176 sqlite_int64 sqlite3_last_insert_rowid(sqlite3*);
179 ** This function returns the number of database rows that were changed
180 ** (or inserted or deleted) by the most recent called sqlite3_exec().
182 ** All changes are counted, even if they were later undone by a
183 ** ROLLBACK or ABORT. Except, changes associated with creating and
184 ** dropping tables are not counted.
186 ** If a callback invokes sqlite3_exec() recursively, then the changes
187 ** in the inner, recursive call are counted together with the changes
188 ** in the outer call.
190 ** SQLite implements the command "DELETE FROM table" without a WHERE clause
191 ** by dropping and recreating the table. (This is much faster than going
192 ** through and deleting individual elements form the table.) Because of
193 ** this optimization, the change count for "DELETE FROM table" will be
194 ** zero regardless of the number of elements that were originally in the
195 ** table. To get an accurate count of the number of rows deleted, use
196 ** "DELETE FROM table WHERE 1" instead.
198 int sqlite3_changes(sqlite3*);
201 ** This function returns the number of database rows that have been
202 ** modified by INSERT, UPDATE or DELETE statements since the database handle
203 ** was opened. This includes UPDATE, INSERT and DELETE statements executed
204 ** as part of trigger programs. All changes are counted as soon as the
205 ** statement that makes them is completed (when the statement handle is
206 ** passed to sqlite3_reset() or sqlite_finalise()).
208 ** SQLite implements the command "DELETE FROM table" without a WHERE clause
209 ** by dropping and recreating the table. (This is much faster than going
210 ** through and deleting individual elements form the table.) Because of
211 ** this optimization, the change count for "DELETE FROM table" will be
212 ** zero regardless of the number of elements that were originally in the
213 ** table. To get an accurate count of the number of rows deleted, use
214 ** "DELETE FROM table WHERE 1" instead.
216 int sqlite3_total_changes(sqlite3*);
218 /* This function causes any pending database operation to abort and
219 ** return at its earliest opportunity. This routine is typically
220 ** called in response to a user action such as pressing "Cancel"
221 ** or Ctrl-C where the user wants a long query operation to halt
224 void sqlite3_interrupt(sqlite3*);
227 /* These functions return true if the given input string comprises
228 ** one or more complete SQL statements. For the sqlite3_complete() call,
229 ** the parameter must be a nul-terminated UTF-8 string. For
230 ** sqlite3_complete16(), a nul-terminated machine byte order UTF-16 string
233 ** The algorithm is simple. If the last token other than spaces
234 ** and comments is a semicolon, then return true. otherwise return
237 int sqlite3_complete(const char *sql);
238 int sqlite3_complete16(const void *sql);
241 ** This routine identifies a callback function that is invoked
242 ** whenever an attempt is made to open a database table that is
243 ** currently locked by another process or thread. If the busy callback
244 ** is NULL, then sqlite3_exec() returns SQLITE_BUSY immediately if
245 ** it finds a locked table. If the busy callback is not NULL, then
246 ** sqlite3_exec() invokes the callback with three arguments. The
247 ** second argument is the name of the locked table and the third
248 ** argument is the number of times the table has been busy. If the
249 ** busy callback returns 0, then sqlite3_exec() immediately returns
250 ** SQLITE_BUSY. If the callback returns non-zero, then sqlite3_exec()
251 ** tries to open the table again and the cycle repeats.
253 ** The default busy callback is NULL.
255 ** Sqlite is re-entrant, so the busy handler may start a new query.
256 ** (It is not clear why anyone would every want to do this, but it
257 ** is allowed, in theory.) But the busy handler may not close the
258 ** database. Closing the database from a busy handler will delete
259 ** data structures out from under the executing query and will
260 ** probably result in a coredump.
262 int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
265 ** This routine sets a busy handler that sleeps for a while when a
266 ** table is locked. The handler will sleep multiple times until
267 ** at least "ms" milleseconds of sleeping have been done. After
268 ** "ms" milleseconds of sleeping, the handler returns 0 which
269 ** causes sqlite3_exec() to return SQLITE_BUSY.
271 ** Calling this routine with an argument less than or equal to zero
272 ** turns off all busy handlers.
274 int sqlite3_busy_timeout(sqlite3*, int ms);
277 ** This next routine is really just a wrapper around sqlite3_exec().
278 ** Instead of invoking a user-supplied callback for each row of the
279 ** result, this routine remembers each row of the result in memory
280 ** obtained from malloc(), then returns all of the result after the
281 ** query has finished.
283 ** As an example, suppose the query result where this table:
286 ** -----------------------
291 ** If the 3rd argument were &azResult then after the function returns
292 ** azResult will contain the following data:
294 ** azResult[0] = "Name";
295 ** azResult[1] = "Age";
296 ** azResult[2] = "Alice";
297 ** azResult[3] = "43";
298 ** azResult[4] = "Bob";
299 ** azResult[5] = "28";
300 ** azResult[6] = "Cindy";
301 ** azResult[7] = "21";
303 ** Notice that there is an extra row of data containing the column
304 ** headers. But the *nrow return value is still 3. *ncolumn is
305 ** set to 2. In general, the number of values inserted into azResult
306 ** will be ((*nrow) + 1)*(*ncolumn).
308 ** After the calling function has finished using the result, it should
309 ** pass the result data pointer to sqlite3_free_table() in order to
310 ** release the memory that was malloc-ed. Because of the way the
311 ** malloc() happens, the calling function must not try to call
312 ** malloc() directly. Only sqlite3_free_table() is able to release
313 ** the memory properly and safely.
315 ** The return value of this routine is the same as from sqlite3_exec().
317 int sqlite3_get_table(
318 sqlite3*, /* An open database */
319 const char *sql, /* SQL to be executed */
320 char ***resultp, /* Result written to a char *[] that this points to */
321 int *nrow, /* Number of result rows written here */
322 int *ncolumn, /* Number of result columns written here */
323 char **errmsg /* Error msg written here */
327 ** Call this routine to free the memory that sqlite3_get_table() allocated.
329 void sqlite3_free_table(char **result);
332 ** The following routines are variants of the "sprintf()" from the
333 ** standard C library. The resulting string is written into memory
334 ** obtained from malloc() so that there is never a possiblity of buffer
335 ** overflow. These routines also implement some additional formatting
336 ** options that are useful for constructing SQL statements.
338 ** The strings returned by these routines should be freed by calling
341 ** All of the usual printf formatting options apply. In addition, there
342 ** is a "%q" option. %q works like %s in that it substitutes a null-terminated
343 ** string from the argument list. But %q also doubles every '\'' character.
344 ** %q is designed for use inside a string literal. By doubling each '\''
345 ** character it escapes that character and allows it to be inserted into
348 ** For example, so some string variable contains text as follows:
350 ** char *zText = "It's a happy day!";
352 ** We can use this text in an SQL statement as follows:
354 ** sqlite3_exec_printf(db, "INSERT INTO table VALUES('%q')",
355 ** callback1, 0, 0, zText);
357 ** Because the %q format string is used, the '\'' character in zText
358 ** is escaped and the SQL generated is as follows:
360 ** INSERT INTO table1 VALUES('It''s a happy day!')
362 ** This is correct. Had we used %s instead of %q, the generated SQL
363 ** would have looked like this:
365 ** INSERT INTO table1 VALUES('It's a happy day!');
367 ** This second example is an SQL syntax error. As a general rule you
368 ** should always use %q instead of %s when inserting text into a string
371 char *sqlite3_mprintf(const char*,...);
372 char *sqlite3_vmprintf(const char*, va_list);
373 void sqlite3_free(char *z);
374 char *sqlite3_snprintf(int,char*,const char*, ...);
376 #ifndef SQLITE_OMIT_AUTHORIZATION
378 ** This routine registers a callback with the SQLite library. The
379 ** callback is invoked (at compile-time, not at run-time) for each
380 ** attempt to access a column of a table in the database. The callback
381 ** returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire
382 ** SQL statement should be aborted with an error and SQLITE_IGNORE
383 ** if the column should be treated as a NULL value.
385 int sqlite3_set_authorizer(
387 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
393 ** The second parameter to the access authorization function above will
394 ** be one of the values below. These values signify what kind of operation
395 ** is to be authorized. The 3rd and 4th parameters to the authorization
396 ** function will be parameters or NULL depending on which of the following
397 ** codes is used as the second parameter. The 5th parameter is the name
398 ** of the database ("main", "temp", etc.) if applicable. The 6th parameter
399 ** is the name of the inner-most trigger or view that is responsible for
400 ** the access attempt or NULL if this access attempt is directly from
405 #define SQLITE_COPY 0 /* Table Name File Name */
406 #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
407 #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
408 #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
409 #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
410 #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
411 #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
412 #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
413 #define SQLITE_CREATE_VIEW 8 /* View Name NULL */
414 #define SQLITE_DELETE 9 /* Table Name NULL */
415 #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
416 #define SQLITE_DROP_TABLE 11 /* Table Name NULL */
417 #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
418 #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
419 #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
420 #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
421 #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
422 #define SQLITE_DROP_VIEW 17 /* View Name NULL */
423 #define SQLITE_INSERT 18 /* Table Name NULL */
424 #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
425 #define SQLITE_READ 20 /* Table Name Column Name */
426 #define SQLITE_SELECT 21 /* NULL NULL */
427 #define SQLITE_TRANSACTION 22 /* NULL NULL */
428 #define SQLITE_UPDATE 23 /* Table Name Column Name */
429 #define SQLITE_ATTACH 24 /* Filename NULL */
430 #define SQLITE_DETACH 25 /* Database Name NULL */
434 ** The return value of the authorization function should be one of the
435 ** following constants:
437 /* #define SQLITE_OK 0 // Allow access (This is actually defined above) */
438 #define SQLITE_DENY 1 /* Abort the SQL statement with an error */
439 #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
442 ** Register a function that is called at every invocation of sqlite3_exec()
443 ** or sqlite3_prepare(). This function can be used (for example) to generate
444 ** a log file of all SQL executed against a database.
446 void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
449 ** This routine configures a callback function - the progress callback - that
450 ** is invoked periodically during long running calls to sqlite3_exec(),
451 ** sqlite3_step() and sqlite3_get_table(). An example use for this API is to keep
452 ** a GUI updated during a large query.
454 ** The progress callback is invoked once for every N virtual machine opcodes,
455 ** where N is the second argument to this function. The progress callback
456 ** itself is identified by the third argument to this function. The fourth
457 ** argument to this function is a void pointer passed to the progress callback
458 ** function each time it is invoked.
460 ** If a call to sqlite3_exec(), sqlite3_step() or sqlite3_get_table() results
461 ** in less than N opcodes being executed, then the progress callback is not
464 ** To remove the progress callback altogether, pass NULL as the third
465 ** argument to this function.
467 ** If the progress callback returns a result other than 0, then the current
468 ** query is immediately terminated and any database changes rolled back. If the
469 ** query was part of a larger transaction, then the transaction is not rolled
470 ** back and remains active. The sqlite3_exec() call returns SQLITE_ABORT.
472 ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
474 void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
477 ** Register a callback function to be invoked whenever a new transaction
478 ** is committed. The pArg argument is passed through to the callback.
479 ** callback. If the callback function returns non-zero, then the commit
480 ** is converted into a rollback.
482 ** If another function was previously registered, its pArg value is returned.
483 ** Otherwise NULL is returned.
485 ** Registering a NULL function disables the callback.
487 ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ******
489 void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
492 ** Open the sqlite database file "filename". The "filename" is UTF-8
493 ** encoded for sqlite3_open() and UTF-16 encoded in the native byte order
494 ** for sqlite3_open16(). An sqlite3* handle is returned in *ppDb, even
495 ** if an error occurs. If the database is opened (or created) successfully,
496 ** then SQLITE_OK is returned. Otherwise an error code is returned. The
497 ** sqlite3_errmsg() or sqlite3_errmsg16() routines can be used to obtain
498 ** an English language description of the error.
500 ** If the database file does not exist, then a new database is created.
501 ** The encoding for the database is UTF-8 if sqlite3_open() is called and
502 ** UTF-16 if sqlite3_open16 is used.
504 ** Whether or not an error occurs when it is opened, resources associated
505 ** with the sqlite3* handle should be released by passing it to
506 ** sqlite3_close() when it is no longer required.
509 const char *filename, /* Database filename (UTF-8) */
510 sqlite3 **ppDb /* OUT: SQLite db handle */
513 const void *filename, /* Database filename (UTF-16) */
514 sqlite3 **ppDb /* OUT: SQLite db handle */
518 ** Return the error code for the most recent sqlite3_* API call associated
519 ** with sqlite3 handle 'db'. SQLITE_OK is returned if the most recent
520 ** API call was successful.
522 ** Calls to many sqlite3_* functions set the error code and string returned
523 ** by sqlite3_errcode(), sqlite3_errmsg() and sqlite3_errmsg16()
524 ** (overwriting the previous values). Note that calls to sqlite3_errcode(),
525 ** sqlite3_errmsg() and sqlite3_errmsg16() themselves do not affect the
526 ** results of future invocations.
528 ** Assuming no other intervening sqlite3_* API calls are made, the error
529 ** code returned by this function is associated with the same error as
530 ** the strings returned by sqlite3_errmsg() and sqlite3_errmsg16().
532 int sqlite3_errcode(sqlite3 *db);
535 ** Return a pointer to a UTF-8 encoded string describing in english the
536 ** error condition for the most recent sqlite3_* API call. The returned
537 ** string is always terminated by an 0x00 byte.
539 ** The string "not an error" is returned when the most recent API call was
542 const char *sqlite3_errmsg(sqlite3*);
545 ** Return a pointer to a UTF-16 native byte order encoded string describing
546 ** in english the error condition for the most recent sqlite3_* API call.
547 ** The returned string is always terminated by a pair of 0x00 bytes.
549 ** The string "not an error" is returned when the most recent API call was
552 const void *sqlite3_errmsg16(sqlite3*);
555 ** An instance of the following opaque structure is used to represent
556 ** a compiled SQL statment.
558 typedef struct sqlite3_stmt sqlite3_stmt;
561 ** To execute an SQL query, it must first be compiled into a byte-code
562 ** program using one of the following routines. The only difference between
563 ** them is that the second argument, specifying the SQL statement to
564 ** compile, is assumed to be encoded in UTF-8 for the sqlite3_prepare()
565 ** function and UTF-16 for sqlite3_prepare16().
567 ** The first parameter "db" is an SQLite database handle. The second
568 ** parameter "zSql" is the statement to be compiled, encoded as either
569 ** UTF-8 or UTF-16 (see above). If the next parameter, "nBytes", is less
570 ** than zero, then zSql is read up to the first nul terminator. If
571 ** "nBytes" is not less than zero, then it is the length of the string zSql
572 ** in bytes (not characters).
574 ** *pzTail is made to point to the first byte past the end of the first
575 ** SQL statement in zSql. This routine only compiles the first statement
576 ** in zSql, so *pzTail is left pointing to what remains uncompiled.
578 ** *ppStmt is left pointing to a compiled SQL statement that can be
579 ** executed using sqlite3_step(). Or if there is an error, *ppStmt may be
580 ** set to NULL. If the input text contained no SQL (if the input is and
581 ** empty string or a comment) then *ppStmt is set to NULL.
583 ** On success, SQLITE_OK is returned. Otherwise an error code is returned.
586 sqlite3 *db, /* Database handle */
587 const char *zSql, /* SQL statement, UTF-8 encoded */
588 int nBytes, /* Length of zSql in bytes. */
589 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
590 const char **pzTail /* OUT: Pointer to unused portion of zSql */
592 int sqlite3_prepare16(
593 sqlite3 *db, /* Database handle */
594 const void *zSql, /* SQL statement, UTF-16 encoded */
595 int nBytes, /* Length of zSql in bytes. */
596 sqlite3_stmt **ppStmt, /* OUT: Statement handle */
597 const void **pzTail /* OUT: Pointer to unused portion of zSql */
601 ** Pointers to the following two opaque structures are used to communicate
602 ** with the implementations of user-defined functions.
604 typedef struct sqlite3_context sqlite3_context;
605 typedef struct Mem sqlite3_value;
608 ** In the SQL strings input to sqlite3_prepare() and sqlite3_prepare16(),
609 ** one or more literals can be replace by a wildcard "?" or ":N:" where
610 ** N is an integer. These value of these wildcard literals can be set
611 ** using the routines listed below.
613 ** In every case, the first parameter is a pointer to the sqlite3_stmt
614 ** structure returned from sqlite3_prepare(). The second parameter is the
615 ** index of the wildcard. The first "?" has an index of 1. ":N:" wildcards
618 ** The fifth parameter to sqlite3_bind_blob(), sqlite3_bind_text(), and
619 ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
620 ** text after SQLite has finished with it. If the fifth argument is the
621 ** special value SQLITE_STATIC, then the library assumes that the information
622 ** is in static, unmanaged space and does not need to be freed. If the
623 ** fifth argument has the value SQLITE_TRANSIENT, then SQLite makes its
624 ** own private copy of the data.
626 ** The sqlite3_bind_* routine must be called before sqlite3_step() after
627 ** an sqlite3_prepare() or sqlite3_reset(). Unbound wildcards are interpreted
630 int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
631 int sqlite3_bind_double(sqlite3_stmt*, int, double);
632 int sqlite3_bind_int(sqlite3_stmt*, int, int);
633 int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite_int64);
634 int sqlite3_bind_null(sqlite3_stmt*, int);
635 int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
636 int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
637 int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
640 ** Return the number of wildcards in a compiled SQL statement. This
641 ** routine was added to support DBD::SQLite.
643 int sqlite3_bind_parameter_count(sqlite3_stmt*);
646 ** Return the name of the i-th parameter. Ordinary wildcards "?" are
647 ** nameless and a NULL is returned. For wildcards of the form :N or
648 ** $vvvv the complete text of the wildcard is returned.
649 ** NULL is returned if the index is out of range.
651 const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
654 ** Return the index of a parameter with the given name. The name
655 ** must match exactly. If no parameter with the given name is found,
658 int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
661 ** Return the number of columns in the result set returned by the compiled
662 ** SQL statement. This routine returns 0 if pStmt is an SQL statement
663 ** that does not return data (for example an UPDATE).
665 int sqlite3_column_count(sqlite3_stmt *pStmt);
668 ** The first parameter is a compiled SQL statement. This function returns
669 ** the column heading for the Nth column of that statement, where N is the
670 ** second function parameter. The string returned is UTF-8 for
671 ** sqlite3_column_name() and UTF-16 for sqlite3_column_name16().
673 const char *sqlite3_column_name(sqlite3_stmt*,int);
674 const void *sqlite3_column_name16(sqlite3_stmt*,int);
677 ** The first parameter is a compiled SQL statement. If this statement
678 ** is a SELECT statement, the Nth column of the returned result set
679 ** of the SELECT is a table column then the declared type of the table
680 ** column is returned. If the Nth column of the result set is not at table
681 ** column, then a NULL pointer is returned. The returned string is always
682 ** UTF-8 encoded. For example, in the database schema:
684 ** CREATE TABLE t1(c1 VARIANT);
686 ** And the following statement compiled:
688 ** SELECT c1 + 1, 0 FROM t1;
690 ** Then this routine would return the string "VARIANT" for the second
691 ** result column (i==1), and a NULL pointer for the first result column
694 const char *sqlite3_column_decltype(sqlite3_stmt *, int i);
697 ** The first parameter is a compiled SQL statement. If this statement
698 ** is a SELECT statement, the Nth column of the returned result set
699 ** of the SELECT is a table column then the declared type of the table
700 ** column is returned. If the Nth column of the result set is not at table
701 ** column, then a NULL pointer is returned. The returned string is always
702 ** UTF-16 encoded. For example, in the database schema:
704 ** CREATE TABLE t1(c1 INTEGER);
706 ** And the following statement compiled:
708 ** SELECT c1 + 1, 0 FROM t1;
710 ** Then this routine would return the string "INTEGER" for the second
711 ** result column (i==1), and a NULL pointer for the first result column
714 const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
717 ** After an SQL query has been compiled with a call to either
718 ** sqlite3_prepare() or sqlite3_prepare16(), then this function must be
719 ** called one or more times to execute the statement.
721 ** The return value will be either SQLITE_BUSY, SQLITE_DONE,
722 ** SQLITE_ROW, SQLITE_ERROR, or SQLITE_MISUSE.
724 ** SQLITE_BUSY means that the database engine attempted to open
725 ** a locked database and there is no busy callback registered.
726 ** Call sqlite3_step() again to retry the open.
728 ** SQLITE_DONE means that the statement has finished executing
729 ** successfully. sqlite3_step() should not be called again on this virtual
732 ** If the SQL statement being executed returns any data, then
733 ** SQLITE_ROW is returned each time a new row of data is ready
734 ** for processing by the caller. The values may be accessed using
735 ** the sqlite3_column_*() functions described below. sqlite3_step()
736 ** is called again to retrieve the next row of data.
738 ** SQLITE_ERROR means that a run-time error (such as a constraint
739 ** violation) has occurred. sqlite3_step() should not be called again on
740 ** the VM. More information may be found by calling sqlite3_errmsg().
742 ** SQLITE_MISUSE means that the this routine was called inappropriately.
743 ** Perhaps it was called on a virtual machine that had already been
744 ** finalized or on one that had previously returned SQLITE_ERROR or
745 ** SQLITE_DONE. Or it could be the case the the same database connection
746 ** is being used simulataneously by two or more threads.
748 int sqlite3_step(sqlite3_stmt*);
751 ** Return the number of values in the current row of the result set.
753 ** After a call to sqlite3_step() that returns SQLITE_ROW, this routine
754 ** will return the same value as the sqlite3_column_count() function.
755 ** After sqlite3_step() has returned an SQLITE_DONE, SQLITE_BUSY or
756 ** error code, or before sqlite3_step() has been called on a
757 ** compiled SQL statement, this routine returns zero.
759 int sqlite3_data_count(sqlite3_stmt *pStmt);
762 ** Values are stored in the database in one of the following fundamental
765 #define SQLITE_INTEGER 1
766 #define SQLITE_FLOAT 2
767 /* #define SQLITE_TEXT 3 // See below */
768 #define SQLITE_BLOB 4
769 #define SQLITE_NULL 5
772 ** SQLite version 2 defines SQLITE_TEXT differently. To allow both
773 ** version 2 and version 3 to be included, undefine them both if a
774 ** conflict is seen. Define SQLITE3_TEXT to be the version 3 value.
779 # define SQLITE_TEXT 3
781 #define SQLITE3_TEXT 3
784 ** The next group of routines returns information about the information
785 ** in a single column of the current result row of a query. In every
786 ** case the first parameter is a pointer to the SQL statement that is being
787 ** executed (the sqlite_stmt* that was returned from sqlite3_prepare()) and
788 ** the second argument is the index of the column for which information
789 ** should be returned. iCol is zero-indexed. The left-most column as an
792 ** If the SQL statement is not currently point to a valid row, or if the
793 ** the colulmn index is out of range, the result is undefined.
795 ** These routines attempt to convert the value where appropriate. For
796 ** example, if the internal representation is FLOAT and a text result
797 ** is requested, sprintf() is used internally to do the conversion
798 ** automatically. The following table details the conversions that
801 ** Internal Type Requested Type Conversion
802 ** ------------- -------------- --------------------------
803 ** NULL INTEGER Result is 0
804 ** NULL FLOAT Result is 0.0
805 ** NULL TEXT Result is an empty string
806 ** NULL BLOB Result is a zero-length BLOB
807 ** INTEGER FLOAT Convert from integer to float
808 ** INTEGER TEXT ASCII rendering of the integer
809 ** INTEGER BLOB Same as for INTEGER->TEXT
810 ** FLOAT INTEGER Convert from float to integer
811 ** FLOAT TEXT ASCII rendering of the float
812 ** FLOAT BLOB Same as FLOAT->TEXT
813 ** TEXT INTEGER Use atoi()
814 ** TEXT FLOAT Use atof()
815 ** TEXT BLOB No change
816 ** BLOB INTEGER Convert to TEXT then use atoi()
817 ** BLOB FLOAT Convert to TEXT then use atof()
818 ** BLOB TEXT Add a \000 terminator if needed
820 ** The following access routines are provided:
822 ** _type() Return the datatype of the result. This is one of
823 ** SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB,
825 ** _blob() Return the value of a BLOB.
826 ** _bytes() Return the number of bytes in a BLOB value or the number
827 ** of bytes in a TEXT value represented as UTF-8. The \000
828 ** terminator is included in the byte count for TEXT values.
829 ** _bytes16() Return the number of bytes in a BLOB value or the number
830 ** of bytes in a TEXT value represented as UTF-16. The \u0000
831 ** terminator is included in the byte count for TEXT values.
832 ** _double() Return a FLOAT value.
833 ** _int() Return an INTEGER value in the host computer's native
834 ** integer representation. This might be either a 32- or 64-bit
835 ** integer depending on the host.
836 ** _int64() Return an INTEGER value as a 64-bit signed integer.
837 ** _text() Return the value as UTF-8 text.
838 ** _text16() Return the value as UTF-16 text.
840 const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
841 int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
842 int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
843 double sqlite3_column_double(sqlite3_stmt*, int iCol);
844 int sqlite3_column_int(sqlite3_stmt*, int iCol);
845 sqlite_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
846 const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
847 const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
848 int sqlite3_column_type(sqlite3_stmt*, int iCol);
851 ** The sqlite3_finalize() function is called to delete a compiled
852 ** SQL statement obtained by a previous call to sqlite3_prepare()
853 ** or sqlite3_prepare16(). If the statement was executed successfully, or
854 ** not executed at all, then SQLITE_OK is returned. If execution of the
855 ** statement failed then an error code is returned.
857 ** This routine can be called at any point during the execution of the
858 ** virtual machine. If the virtual machine has not completed execution
859 ** when this routine is called, that is like encountering an error or
860 ** an interrupt. (See sqlite3_interrupt().) Incomplete updates may be
861 ** rolled back and transactions cancelled, depending on the circumstances,
862 ** and the result code returned will be SQLITE_ABORT.
864 int sqlite3_finalize(sqlite3_stmt *pStmt);
867 ** The sqlite3_reset() function is called to reset a compiled SQL
868 ** statement obtained by a previous call to sqlite3_prepare() or
869 ** sqlite3_prepare16() back to it's initial state, ready to be re-executed.
870 ** Any SQL statement variables that had values bound to them using
871 ** the sqlite3_bind_*() API retain their values.
873 int sqlite3_reset(sqlite3_stmt *pStmt);
876 ** The following two functions are used to add user functions or aggregates
877 ** implemented in C to the SQL langauge interpreted by SQLite. The
878 ** difference only between the two is that the second parameter, the
879 ** name of the (scalar) function or aggregate, is encoded in UTF-8 for
880 ** sqlite3_create_function() and UTF-16 for sqlite3_create_function16().
882 ** The first argument is the database handle that the new function or
883 ** aggregate is to be added to. If a single program uses more than one
884 ** database handle internally, then user functions or aggregates must
885 ** be added individually to each database handle with which they will be
888 ** The third parameter is the number of arguments that the function or
889 ** aggregate takes. If this parameter is negative, then the function or
890 ** aggregate may take any number of arguments.
892 ** The fourth parameter is one of SQLITE_UTF* values defined below,
893 ** indicating the encoding that the function is most likely to handle
894 ** values in. This does not change the behaviour of the programming
895 ** interface. However, if two versions of the same function are registered
896 ** with different encoding values, SQLite invokes the version likely to
897 ** minimize conversions between text encodings.
899 ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are
900 ** pointers to user implemented C functions that implement the user
901 ** function or aggregate. A scalar function requires an implementation of
902 ** the xFunc callback only, NULL pointers should be passed as the xStep
903 ** and xFinal parameters. An aggregate function requires an implementation
904 ** of xStep and xFinal, but NULL should be passed for xFunc. To delete an
905 ** existing user function or aggregate, pass NULL for all three function
906 ** callback. Specifying an inconstent set of callback values, such as an
907 ** xFunc and an xFinal, or an xStep but no xFinal, SQLITE_ERROR is
910 int sqlite3_create_function(
912 const char *zFunctionName,
916 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
917 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
918 void (*xFinal)(sqlite3_context*)
920 int sqlite3_create_function16(
922 const void *zFunctionName,
926 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
927 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
928 void (*xFinal)(sqlite3_context*)
932 ** The next routine returns the number of calls to xStep for a particular
933 ** aggregate function instance. The current call to xStep counts so this
934 ** routine always returns at least 1.
936 int sqlite3_aggregate_count(sqlite3_context*);
939 ** The next group of routines returns information about parameters to
940 ** a user-defined function. Function implementations use these routines
941 ** to access their parameters. These routines are the same as the
942 ** sqlite3_column_* routines except that these routines take a single
943 ** sqlite3_value* pointer instead of an sqlite3_stmt* and an integer
946 const void *sqlite3_value_blob(sqlite3_value*);
947 int sqlite3_value_bytes(sqlite3_value*);
948 int sqlite3_value_bytes16(sqlite3_value*);
949 double sqlite3_value_double(sqlite3_value*);
950 int sqlite3_value_int(sqlite3_value*);
951 sqlite_int64 sqlite3_value_int64(sqlite3_value*);
952 const unsigned char *sqlite3_value_text(sqlite3_value*);
953 const void *sqlite3_value_text16(sqlite3_value*);
954 const void *sqlite3_value_text16le(sqlite3_value*);
955 const void *sqlite3_value_text16be(sqlite3_value*);
956 int sqlite3_value_type(sqlite3_value*);
959 ** Aggregate functions use the following routine to allocate
960 ** a structure for storing their state. The first time this routine
961 ** is called for a particular aggregate, a new structure of size nBytes
962 ** is allocated, zeroed, and returned. On subsequent calls (for the
963 ** same aggregate instance) the same buffer is returned. The implementation
964 ** of the aggregate can use the returned buffer to accumulate data.
966 ** The buffer allocated is freed automatically by SQLite.
968 void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
971 ** The pUserData parameter to the sqlite3_create_function() and
972 ** sqlite3_create_aggregate() routines used to register user functions
973 ** is available to the implementation of the function using this
976 void *sqlite3_user_data(sqlite3_context*);
979 ** The following two functions may be used by scalar user functions to
980 ** associate meta-data with argument values. If the same value is passed to
981 ** multiple invocations of the user-function during query execution, under
982 ** some circumstances the associated meta-data may be preserved. This may
983 ** be used, for example, to add a regular-expression matching scalar
984 ** function. The compiled version of the regular expression is stored as
985 ** meta-data associated with the SQL value passed as the regular expression
988 ** Calling sqlite3_get_auxdata() returns a pointer to the meta data
989 ** associated with the Nth argument value to the current user function
990 ** call, where N is the second parameter. If no meta-data has been set for
991 ** that value, then a NULL pointer is returned.
993 ** The sqlite3_set_auxdata() is used to associate meta data with a user
994 ** function argument. The third parameter is a pointer to the meta data
995 ** to be associated with the Nth user function argument value. The fourth
996 ** parameter specifies a 'delete function' that will be called on the meta
997 ** data pointer to release it when it is no longer required. If the delete
998 ** function pointer is NULL, it is not invoked.
1000 ** In practice, meta-data is preserved between function calls for
1001 ** expressions that are constant at compile time. This includes literal
1002 ** values and SQL variables.
1004 void *sqlite3_get_auxdata(sqlite3_context*, int);
1005 void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*));
1009 ** These are special value for the destructor that is passed in as the
1010 ** final argument to routines like sqlite3_result_blob(). If the destructor
1011 ** argument is SQLITE_STATIC, it means that the content pointer is constant
1012 ** and will never change. It does not need to be destroyed. The
1013 ** SQLITE_TRANSIENT value means that the content will likely change in
1014 ** the near future and that SQLite should make its own private copy of
1015 ** the content before returning.
1017 #define SQLITE_STATIC ((void(*)(void *))0)
1018 #define SQLITE_TRANSIENT ((void(*)(void *))-1)
1021 ** User-defined functions invoke the following routines in order to
1022 ** set their return value.
1024 void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
1025 void sqlite3_result_double(sqlite3_context*, double);
1026 void sqlite3_result_error(sqlite3_context*, const char*, int);
1027 void sqlite3_result_error16(sqlite3_context*, const void*, int);
1028 void sqlite3_result_int(sqlite3_context*, int);
1029 void sqlite3_result_int64(sqlite3_context*, sqlite_int64);
1030 void sqlite3_result_null(sqlite3_context*);
1031 void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
1032 void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
1033 void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
1034 void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
1035 void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
1038 ** These are the allowed values for the eTextRep argument to
1039 ** sqlite3_create_collation and sqlite3_create_function.
1041 #define SQLITE_UTF8 1
1042 #define SQLITE_UTF16LE 2
1043 #define SQLITE_UTF16BE 3
1044 #define SQLITE_UTF16 4 /* Use native byte order */
1045 #define SQLITE_ANY 5 /* sqlite3_create_function only */
1048 ** These two functions are used to add new collation sequences to the
1049 ** sqlite3 handle specified as the first argument.
1051 ** The name of the new collation sequence is specified as a UTF-8 string
1052 ** for sqlite3_create_collation() and a UTF-16 string for
1053 ** sqlite3_create_collation16(). In both cases the name is passed as the
1054 ** second function argument.
1056 ** The third argument must be one of the constants SQLITE_UTF8,
1057 ** SQLITE_UTF16LE or SQLITE_UTF16BE, indicating that the user-supplied
1058 ** routine expects to be passed pointers to strings encoded using UTF-8,
1059 ** UTF-16 little-endian or UTF-16 big-endian respectively.
1061 ** A pointer to the user supplied routine must be passed as the fifth
1062 ** argument. If it is NULL, this is the same as deleting the collation
1063 ** sequence (so that SQLite cannot call it anymore). Each time the user
1064 ** supplied function is invoked, it is passed a copy of the void* passed as
1065 ** the fourth argument to sqlite3_create_collation() or
1066 ** sqlite3_create_collation16() as its first parameter.
1068 ** The remaining arguments to the user-supplied routine are two strings,
1069 ** each represented by a [length, data] pair and encoded in the encoding
1070 ** that was passed as the third argument when the collation sequence was
1071 ** registered. The user routine should return negative, zero or positive if
1072 ** the first string is less than, equal to, or greater than the second
1073 ** string. i.e. (STRING1 - STRING2).
1075 int sqlite3_create_collation(
1080 int(*xCompare)(void*,int,const void*,int,const void*)
1082 int sqlite3_create_collation16(
1087 int(*xCompare)(void*,int,const void*,int,const void*)
1091 ** To avoid having to register all collation sequences before a database
1092 ** can be used, a single callback function may be registered with the
1093 ** database handle to be called whenever an undefined collation sequence is
1096 ** If the function is registered using the sqlite3_collation_needed() API,
1097 ** then it is passed the names of undefined collation sequences as strings
1098 ** encoded in UTF-8. If sqlite3_collation_needed16() is used, the names
1099 ** are passed as UTF-16 in machine native byte order. A call to either
1100 ** function replaces any existing callback.
1102 ** When the user-function is invoked, the first argument passed is a copy
1103 ** of the second argument to sqlite3_collation_needed() or
1104 ** sqlite3_collation_needed16(). The second argument is the database
1105 ** handle. The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE or
1106 ** SQLITE_UTF16LE, indicating the most desirable form of the collation
1107 ** sequence function required. The fourth parameter is the name of the
1108 ** required collation sequence.
1110 ** The collation sequence is returned to SQLite by a collation-needed
1111 ** callback using the sqlite3_create_collation() or
1112 ** sqlite3_create_collation16() APIs, described above.
1114 int sqlite3_collation_needed(
1117 void(*)(void*,sqlite3*,int eTextRep,const char*)
1119 int sqlite3_collation_needed16(
1122 void(*)(void*,sqlite3*,int eTextRep,const void*)
1126 ** Specify the key for an encrypted database. This routine should be
1127 ** called right after sqlite3_open().
1129 ** The code to implement this API is not available in the public release
1133 sqlite3 *db, /* Database to be rekeyed */
1134 const void *pKey, int nKey /* The key */
1138 ** Change the key on an open database. If the current database is not
1139 ** encrypted, this routine will encrypt it. If pNew==0 or nNew==0, the
1140 ** database is decrypted.
1142 ** The code to implement this API is not available in the public release
1146 sqlite3 *db, /* Database to be rekeyed */
1147 const void *pKey, int nKey /* The new key */
1151 ** If the following global variable is made to point to a constant
1152 ** string which is the name of a directory, then all temporary files
1153 ** created by SQLite will be placed in that directory. If this variable
1154 ** is NULL pointer, then SQLite does a search for an appropriate temporary
1157 ** This variable should only be changed when there are no open databases.
1158 ** Once sqlite3_open() has been called, this variable should not be changed
1159 ** until all database connections are closed.
1161 extern const char *sqlite3_temp_directory;
1164 } /* End of the 'extern "C"' block */