1 /* 2 ** 2001 September 15 3 ** 4 ** The author disclaims copyright to this source code. In place of 5 ** a legal notice, here is a blessing: 6 ** 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. 10 ** 11 ************************************************************************* 12 ** This header file defines the interface that the SQLite library 13 ** presents to client programs. 14 ** 15 ** @(#) $Id$ 16 */ 17 #ifndef _SQLITE_H_ 18 #define _SQLITE_H_ 19 #include <stdarg.h> /* Needed for the definition of va_list */ 20 21 /* 22 ** Make sure we can call this stuff from C++. 23 */ 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 /* 29 ** The version of the SQLite library. 30 */ 31 #define SQLITE_VERSION "2.8.17" 32 33 /* 34 ** The version string is also compiled into the library so that a program 35 ** can check to make sure that the lib*.a file and the *.h file are from 36 ** the same version. 37 */ 38 extern const char sqlite_version[]; 39 40 /* 41 ** The SQLITE_UTF8 macro is defined if the library expects to see 42 ** UTF-8 encoded data. The SQLITE_ISO8859 macro is defined if the 43 ** iso8859 encoded should be used. 44 */ 45 #define SQLITE_ISO8859 1 46 47 /* 48 ** The following constant holds one of two strings, "UTF-8" or "iso8859", 49 ** depending on which character encoding the SQLite library expects to 50 ** see. The character encoding makes a difference for the LIKE and GLOB 51 ** operators and for the LENGTH() and SUBSTR() functions. 52 */ 53 extern const char sqlite_encoding[]; 54 55 /* 56 ** Each open sqlite database is represented by an instance of the 57 ** following opaque structure. 58 */ 59 typedef struct sqlite sqlite; 60 61 /* 62 ** A function to open a new sqlite database. 63 ** 64 ** If the database does not exist and mode indicates write 65 ** permission, then a new database is created. If the database 66 ** does not exist and mode does not indicate write permission, 67 ** then the open fails, an error message generated (if errmsg!=0) 68 ** and the function returns 0. 69 ** 70 ** If mode does not indicates user write permission, then the 71 ** database is opened read-only. 72 ** 73 ** The Truth: As currently implemented, all databases are opened 74 ** for writing all the time. Maybe someday we will provide the 75 ** ability to open a database readonly. The mode parameters is 76 ** provided in anticipation of that enhancement. 77 */ 78 sqlite *sqlite_open(const char *filename, int mode, char **errmsg); 79 80 /* 81 ** A function to close the database. 82 ** 83 ** Call this function with a pointer to a structure that was previously 84 ** returned from sqlite_open() and the corresponding database will by closed. 85 */ 86 void sqlite_close(sqlite *); 87 88 /* 89 ** The type for a callback function. 90 */ 91 typedef int (*sqlite_callback)(void*,int,char**, char**); 92 93 /* 94 ** A function to executes one or more statements of SQL. 95 ** 96 ** If one or more of the SQL statements are queries, then 97 ** the callback function specified by the 3rd parameter is 98 ** invoked once for each row of the query result. This callback 99 ** should normally return 0. If the callback returns a non-zero 100 ** value then the query is aborted, all subsequent SQL statements 101 ** are skipped and the sqlite_exec() function returns the SQLITE_ABORT. 102 ** 103 ** The 4th parameter is an arbitrary pointer that is passed 104 ** to the callback function as its first parameter. 105 ** 106 ** The 2nd parameter to the callback function is the number of 107 ** columns in the query result. The 3rd parameter to the callback 108 ** is an array of strings holding the values for each column. 109 ** The 4th parameter to the callback is an array of strings holding 110 ** the names of each column. 111 ** 112 ** The callback function may be NULL, even for queries. A NULL 113 ** callback is not an error. It just means that no callback 114 ** will be invoked. 115 ** 116 ** If an error occurs while parsing or evaluating the SQL (but 117 ** not while executing the callback) then an appropriate error 118 ** message is written into memory obtained from malloc() and 119 ** *errmsg is made to point to that message. The calling function 120 ** is responsible for freeing the memory that holds the error 121 ** message. Use sqlite_freemem() for this. If errmsg==NULL, 122 ** then no error message is ever written. 123 ** 124 ** The return value is is SQLITE_OK if there are no errors and 125 ** some other return code if there is an error. The particular 126 ** return value depends on the type of error. 127 ** 128 ** If the query could not be executed because a database file is 129 ** locked or busy, then this function returns SQLITE_BUSY. (This 130 ** behavior can be modified somewhat using the sqlite_busy_handler() 131 ** and sqlite_busy_timeout() functions below.) 132 */ 133 int sqlite_exec( 134 sqlite*, /* An open database */ 135 const char *sql, /* SQL to be executed */ 136 sqlite_callback, /* Callback function */ 137 void *, /* 1st argument to callback function */ 138 char **errmsg /* Error msg written here */ 139 ); 140 141 /* 142 ** Return values for sqlite_exec() and sqlite_step() 143 */ 144 #define SQLITE_OK 0 /* Successful result */ 145 #define SQLITE_ERROR 1 /* SQL error or missing database */ 146 #define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */ 147 #define SQLITE_PERM 3 /* Access permission denied */ 148 #define SQLITE_ABORT 4 /* Callback routine requested an abort */ 149 #define SQLITE_BUSY 5 /* The database file is locked */ 150 #define SQLITE_LOCKED 6 /* A table in the database is locked */ 151 #define SQLITE_NOMEM 7 /* A malloc() failed */ 152 #define SQLITE_READONLY 8 /* Attempt to write a readonly database */ 153 #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite_interrupt() */ 154 #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ 155 #define SQLITE_CORRUPT 11 /* The database disk image is malformed */ 156 #define SQLITE_NOTFOUND 12 /* (Internal Only) Table or record not found */ 157 #define SQLITE_FULL 13 /* Insertion failed because database is full */ 158 #define SQLITE_CANTOPEN 14 /* Unable to open the database file */ 159 #define SQLITE_PROTOCOL 15 /* Database lock protocol error */ 160 #define SQLITE_EMPTY 16 /* (Internal Only) Database table is empty */ 161 #define SQLITE_SCHEMA 17 /* The database schema changed */ 162 #define SQLITE_TOOBIG 18 /* Too much data for one row of a table */ 163 #define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */ 164 #define SQLITE_MISMATCH 20 /* Data type mismatch */ 165 #define SQLITE_MISUSE 21 /* Library used incorrectly */ 166 #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ 167 #define SQLITE_AUTH 23 /* Authorization denied */ 168 #define SQLITE_FORMAT 24 /* Auxiliary database format error */ 169 #define SQLITE_RANGE 25 /* 2nd parameter to sqlite_bind out of range */ 170 #define SQLITE_NOTADB 26 /* File opened that is not a database file */ 171 #define SQLITE_ROW 100 /* sqlite_step() has another row ready */ 172 #define SQLITE_DONE 101 /* sqlite_step() has finished executing */ 173 174 /* 175 ** Each entry in an SQLite table has a unique integer key. (The key is 176 ** the value of the INTEGER PRIMARY KEY column if there is such a column, 177 ** otherwise the key is generated at random. The unique key is always 178 ** available as the ROWID, OID, or _ROWID_ column.) The following routine 179 ** returns the integer key of the most recent insert in the database. 180 ** 181 ** This function is similar to the mysql_insert_id() function from MySQL. 182 */ 183 int sqlite_last_insert_rowid(sqlite*); 184 185 /* 186 ** This function returns the number of database rows that were changed 187 ** (or inserted or deleted) by the most recent called sqlite_exec(). 188 ** 189 ** All changes are counted, even if they were later undone by a 190 ** ROLLBACK or ABORT. Except, changes associated with creating and 191 ** dropping tables are not counted. 192 ** 193 ** If a callback invokes sqlite_exec() recursively, then the changes 194 ** in the inner, recursive call are counted together with the changes 195 ** in the outer call. 196 ** 197 ** SQLite implements the command "DELETE FROM table" without a WHERE clause 198 ** by dropping and recreating the table. (This is much faster than going 199 ** through and deleting individual elements form the table.) Because of 200 ** this optimization, the change count for "DELETE FROM table" will be 201 ** zero regardless of the number of elements that were originally in the 202 ** table. To get an accurate count of the number of rows deleted, use 203 ** "DELETE FROM table WHERE 1" instead. 204 */ 205 int sqlite_changes(sqlite*); 206 207 /* If the parameter to this routine is one of the return value constants 208 ** defined above, then this routine returns a constant text string which 209 ** descripts (in English) the meaning of the return value. 210 */ 211 const char *sqlite_error_string(int); 212 #define sqliteErrStr sqlite_error_string /* Legacy. Do not use in new code. */ 213 214 /* This function causes any pending database operation to abort and 215 ** return at its earliest opportunity. This routine is typically 216 ** called in response to a user action such as pressing "Cancel" 217 ** or Ctrl-C where the user wants a long query operation to halt 218 ** immediately. 219 */ 220 void sqlite_interrupt(sqlite*); 221 222 223 /* This function returns true if the given input string comprises 224 ** one or more complete SQL statements. 225 ** 226 ** The algorithm is simple. If the last token other than spaces 227 ** and comments is a semicolon, then return true. otherwise return 228 ** false. 229 */ 230 int sqlite_complete(const char *sql); 231 232 /* 233 ** This routine identifies a callback function that is invoked 234 ** whenever an attempt is made to open a database table that is 235 ** currently locked by another process or thread. If the busy callback 236 ** is NULL, then sqlite_exec() returns SQLITE_BUSY immediately if 237 ** it finds a locked table. If the busy callback is not NULL, then 238 ** sqlite_exec() invokes the callback with three arguments. The 239 ** second argument is the name of the locked table and the third 240 ** argument is the number of times the table has been busy. If the 241 ** busy callback returns 0, then sqlite_exec() immediately returns 242 ** SQLITE_BUSY. If the callback returns non-zero, then sqlite_exec() 243 ** tries to open the table again and the cycle repeats. 244 ** 245 ** The default busy callback is NULL. 246 ** 247 ** Sqlite is re-entrant, so the busy handler may start a new query. 248 ** (It is not clear why anyone would every want to do this, but it 249 ** is allowed, in theory.) But the busy handler may not close the 250 ** database. Closing the database from a busy handler will delete 251 ** data structures out from under the executing query and will 252 ** probably result in a coredump. 253 */ 254 void sqlite_busy_handler(sqlite*, int(*)(void*,const char*,int), void*); 255 256 /* 257 ** This routine sets a busy handler that sleeps for a while when a 258 ** table is locked. The handler will sleep multiple times until 259 ** at least "ms" milleseconds of sleeping have been done. After 260 ** "ms" milleseconds of sleeping, the handler returns 0 which 261 ** causes sqlite_exec() to return SQLITE_BUSY. 262 ** 263 ** Calling this routine with an argument less than or equal to zero 264 ** turns off all busy handlers. 265 */ 266 void sqlite_busy_timeout(sqlite*, int ms); 267 268 /* 269 ** This next routine is really just a wrapper around sqlite_exec(). 270 ** Instead of invoking a user-supplied callback for each row of the 271 ** result, this routine remembers each row of the result in memory 272 ** obtained from malloc(), then returns all of the result after the 273 ** query has finished. 274 ** 275 ** As an example, suppose the query result where this table: 276 ** 277 ** Name | Age 278 ** ----------------------- 279 ** Alice | 43 280 ** Bob | 28 281 ** Cindy | 21 282 ** 283 ** If the 3rd argument were &azResult then after the function returns 284 ** azResult will contain the following data: 285 ** 286 ** azResult[0] = "Name"; 287 ** azResult[1] = "Age"; 288 ** azResult[2] = "Alice"; 289 ** azResult[3] = "43"; 290 ** azResult[4] = "Bob"; 291 ** azResult[5] = "28"; 292 ** azResult[6] = "Cindy"; 293 ** azResult[7] = "21"; 294 ** 295 ** Notice that there is an extra row of data containing the column 296 ** headers. But the *nrow return value is still 3. *ncolumn is 297 ** set to 2. In general, the number of values inserted into azResult 298 ** will be ((*nrow) + 1)*(*ncolumn). 299 ** 300 ** After the calling function has finished using the result, it should 301 ** pass the result data pointer to sqlite_free_table() in order to 302 ** release the memory that was malloc-ed. Because of the way the 303 ** malloc() happens, the calling function must not try to call 304 ** malloc() directly. Only sqlite_free_table() is able to release 305 ** the memory properly and safely. 306 ** 307 ** The return value of this routine is the same as from sqlite_exec(). 308 */ 309 int sqlite_get_table( 310 sqlite*, /* An open database */ 311 const char *sql, /* SQL to be executed */ 312 char ***resultp, /* Result written to a char *[] that this points to */ 313 int *nrow, /* Number of result rows written here */ 314 int *ncolumn, /* Number of result columns written here */ 315 char **errmsg /* Error msg written here */ 316 ); 317 318 /* 319 ** Call this routine to free the memory that sqlite_get_table() allocated. 320 */ 321 void sqlite_free_table(char **result); 322 323 /* 324 ** The following routines are wrappers around sqlite_exec() and 325 ** sqlite_get_table(). The only difference between the routines that 326 ** follow and the originals is that the second argument to the 327 ** routines that follow is really a printf()-style format 328 ** string describing the SQL to be executed. Arguments to the format 329 ** string appear at the end of the argument list. 330 ** 331 ** All of the usual printf formatting options apply. In addition, there 332 ** is a "%q" option. %q works like %s in that it substitutes a null-terminated 333 ** string from the argument list. But %q also doubles every '\'' character. 334 ** %q is designed for use inside a string literal. By doubling each '\'' 335 ** character it escapes that character and allows it to be inserted into 336 ** the string. 337 ** 338 ** For example, so some string variable contains text as follows: 339 ** 340 ** char *zText = "It's a happy day!"; 341 ** 342 ** We can use this text in an SQL statement as follows: 343 ** 344 ** sqlite_exec_printf(db, "INSERT INTO table VALUES('%q')", 345 ** callback1, 0, 0, zText); 346 ** 347 ** Because the %q format string is used, the '\'' character in zText 348 ** is escaped and the SQL generated is as follows: 349 ** 350 ** INSERT INTO table1 VALUES('It''s a happy day!') 351 ** 352 ** This is correct. Had we used %s instead of %q, the generated SQL 353 ** would have looked like this: 354 ** 355 ** INSERT INTO table1 VALUES('It's a happy day!'); 356 ** 357 ** This second example is an SQL syntax error. As a general rule you 358 ** should always use %q instead of %s when inserting text into a string 359 ** literal. 360 */ 361 int sqlite_exec_printf( 362 sqlite*, /* An open database */ 363 const char *sqlFormat, /* printf-style format string for the SQL */ 364 sqlite_callback, /* Callback function */ 365 void *, /* 1st argument to callback function */ 366 char **errmsg, /* Error msg written here */ 367 ... /* Arguments to the format string. */ 368 ); 369 int sqlite_exec_vprintf( 370 sqlite*, /* An open database */ 371 const char *sqlFormat, /* printf-style format string for the SQL */ 372 sqlite_callback, /* Callback function */ 373 void *, /* 1st argument to callback function */ 374 char **errmsg, /* Error msg written here */ 375 va_list ap /* Arguments to the format string. */ 376 ); 377 int sqlite_get_table_printf( 378 sqlite*, /* An open database */ 379 const char *sqlFormat, /* printf-style format string for the SQL */ 380 char ***resultp, /* Result written to a char *[] that this points to */ 381 int *nrow, /* Number of result rows written here */ 382 int *ncolumn, /* Number of result columns written here */ 383 char **errmsg, /* Error msg written here */ 384 ... /* Arguments to the format string */ 385 ); 386 int sqlite_get_table_vprintf( 387 sqlite*, /* An open database */ 388 const char *sqlFormat, /* printf-style format string for the SQL */ 389 char ***resultp, /* Result written to a char *[] that this points to */ 390 int *nrow, /* Number of result rows written here */ 391 int *ncolumn, /* Number of result columns written here */ 392 char **errmsg, /* Error msg written here */ 393 va_list ap /* Arguments to the format string */ 394 ); 395 char *sqlite_mprintf(const char*,...); 396 char *sqlite_vmprintf(const char*, va_list); 397 398 /* 399 ** Windows systems should call this routine to free memory that 400 ** is returned in the in the errmsg parameter of sqlite_open() when 401 ** SQLite is a DLL. For some reason, it does not work to call free() 402 ** directly. 403 */ 404 void sqlite_freemem(void *p); 405 406 /* 407 ** Windows systems need functions to call to return the sqlite_version 408 ** and sqlite_encoding strings. 409 */ 410 const char *sqlite_libversion(void); 411 const char *sqlite_libencoding(void); 412 413 /* 414 ** A pointer to the following structure is used to communicate with 415 ** the implementations of user-defined functions. 416 */ 417 typedef struct sqlite_func sqlite_func; 418 419 /* 420 ** Use the following routines to create new user-defined functions. See 421 ** the documentation for details. 422 */ 423 int sqlite_create_function( 424 sqlite*, /* Database where the new function is registered */ 425 const char *zName, /* Name of the new function */ 426 int nArg, /* Number of arguments. -1 means any number */ 427 void (*xFunc)(sqlite_func*,int,const char**), /* C code to implement */ 428 void *pUserData /* Available via the sqlite_user_data() call */ 429 ); 430 int sqlite_create_aggregate( 431 sqlite*, /* Database where the new function is registered */ 432 const char *zName, /* Name of the function */ 433 int nArg, /* Number of arguments */ 434 void (*xStep)(sqlite_func*,int,const char**), /* Called for each row */ 435 void (*xFinalize)(sqlite_func*), /* Called once to get final result */ 436 void *pUserData /* Available via the sqlite_user_data() call */ 437 ); 438 439 /* 440 ** Use the following routine to define the datatype returned by a 441 ** user-defined function. The second argument can be one of the 442 ** constants SQLITE_NUMERIC, SQLITE_TEXT, or SQLITE_ARGS or it 443 ** can be an integer greater than or equal to zero. The datatype 444 ** will be numeric or text (the only two types supported) if the 445 ** argument is SQLITE_NUMERIC or SQLITE_TEXT. If the argument is 446 ** SQLITE_ARGS, then the datatype is numeric if any argument to the 447 ** function is numeric and is text otherwise. If the second argument 448 ** is an integer, then the datatype of the result is the same as the 449 ** parameter to the function that corresponds to that integer. 450 */ 451 int sqlite_function_type( 452 sqlite *db, /* The database there the function is registered */ 453 const char *zName, /* Name of the function */ 454 int datatype /* The datatype for this function */ 455 ); 456 #define SQLITE_NUMERIC (-1) 457 #define SQLITE_TEXT (-2) 458 #define SQLITE_ARGS (-3) 459 460 /* 461 ** The user function implementations call one of the following four routines 462 ** in order to return their results. The first parameter to each of these 463 ** routines is a copy of the first argument to xFunc() or xFinialize(). 464 ** The second parameter to these routines is the result to be returned. 465 ** A NULL can be passed as the second parameter to sqlite_set_result_string() 466 ** in order to return a NULL result. 467 ** 468 ** The 3rd argument to _string and _error is the number of characters to 469 ** take from the string. If this argument is negative, then all characters 470 ** up to and including the first '\000' are used. 471 ** 472 ** The sqlite_set_result_string() function allocates a buffer to hold the 473 ** result and returns a pointer to this buffer. The calling routine 474 ** (that is, the implmentation of a user function) can alter the content 475 ** of this buffer if desired. 476 */ 477 char *sqlite_set_result_string(sqlite_func*,const char*,int); 478 void sqlite_set_result_int(sqlite_func*,int); 479 void sqlite_set_result_double(sqlite_func*,double); 480 void sqlite_set_result_error(sqlite_func*,const char*,int); 481 482 /* 483 ** The pUserData parameter to the sqlite_create_function() and 484 ** sqlite_create_aggregate() routines used to register user functions 485 ** is available to the implementation of the function using this 486 ** call. 487 */ 488 void *sqlite_user_data(sqlite_func*); 489 490 /* 491 ** Aggregate functions use the following routine to allocate 492 ** a structure for storing their state. The first time this routine 493 ** is called for a particular aggregate, a new structure of size nBytes 494 ** is allocated, zeroed, and returned. On subsequent calls (for the 495 ** same aggregate instance) the same buffer is returned. The implementation 496 ** of the aggregate can use the returned buffer to accumulate data. 497 ** 498 ** The buffer allocated is freed automatically be SQLite. 499 */ 500 void *sqlite_aggregate_context(sqlite_func*, int nBytes); 501 502 /* 503 ** The next routine returns the number of calls to xStep for a particular 504 ** aggregate function instance. The current call to xStep counts so this 505 ** routine always returns at least 1. 506 */ 507 int sqlite_aggregate_count(sqlite_func*); 508 509 /* 510 ** This routine registers a callback with the SQLite library. The 511 ** callback is invoked (at compile-time, not at run-time) for each 512 ** attempt to access a column of a table in the database. The callback 513 ** returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire 514 ** SQL statement should be aborted with an error and SQLITE_IGNORE 515 ** if the column should be treated as a NULL value. 516 */ 517 int sqlite_set_authorizer( 518 sqlite*, 519 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*), 520 void *pUserData 521 ); 522 523 /* 524 ** The second parameter to the access authorization function above will 525 ** be one of the values below. These values signify what kind of operation 526 ** is to be authorized. The 3rd and 4th parameters to the authorization 527 ** function will be parameters or NULL depending on which of the following 528 ** codes is used as the second parameter. The 5th parameter is the name 529 ** of the database ("main", "temp", etc.) if applicable. The 6th parameter 530 ** is the name of the inner-most trigger or view that is responsible for 531 ** the access attempt or NULL if this access attempt is directly from 532 ** input SQL code. 533 ** 534 ** Arg-3 Arg-4 535 */ 536 #define SQLITE_COPY 0 /* Table Name File Name */ 537 #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */ 538 #define SQLITE_CREATE_TABLE 2 /* Table Name NULL */ 539 #define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */ 540 #define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */ 541 #define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */ 542 #define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */ 543 #define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */ 544 #define SQLITE_CREATE_VIEW 8 /* View Name NULL */ 545 #define SQLITE_DELETE 9 /* Table Name NULL */ 546 #define SQLITE_DROP_INDEX 10 /* Index Name Table Name */ 547 #define SQLITE_DROP_TABLE 11 /* Table Name NULL */ 548 #define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */ 549 #define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */ 550 #define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */ 551 #define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */ 552 #define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */ 553 #define SQLITE_DROP_VIEW 17 /* View Name NULL */ 554 #define SQLITE_INSERT 18 /* Table Name NULL */ 555 #define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */ 556 #define SQLITE_READ 20 /* Table Name Column Name */ 557 #define SQLITE_SELECT 21 /* NULL NULL */ 558 #define SQLITE_TRANSACTION 22 /* NULL NULL */ 559 #define SQLITE_UPDATE 23 /* Table Name Column Name */ 560 #define SQLITE_ATTACH 24 /* Filename NULL */ 561 #define SQLITE_DETACH 25 /* Database Name NULL */ 562 563 564 /* 565 ** The return value of the authorization function should be one of the 566 ** following constants: 567 */ 568 /* #define SQLITE_OK 0 // Allow access (This is actually defined above) */ 569 #define SQLITE_DENY 1 /* Abort the SQL statement with an error */ 570 #define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */ 571 572 /* 573 ** Register a function that is called at every invocation of sqlite_exec() 574 ** or sqlite_compile(). This function can be used (for example) to generate 575 ** a log file of all SQL executed against a database. 576 */ 577 void *sqlite_trace(sqlite*, void(*xTrace)(void*,const char*), void*); 578 579 /*** The Callback-Free API 580 ** 581 ** The following routines implement a new way to access SQLite that does not 582 ** involve the use of callbacks. 583 ** 584 ** An sqlite_vm is an opaque object that represents a single SQL statement 585 ** that is ready to be executed. 586 */ 587 typedef struct sqlite_vm sqlite_vm; 588 589 /* 590 ** To execute an SQLite query without the use of callbacks, you first have 591 ** to compile the SQL using this routine. The 1st parameter "db" is a pointer 592 ** to an sqlite object obtained from sqlite_open(). The 2nd parameter 593 ** "zSql" is the text of the SQL to be compiled. The remaining parameters 594 ** are all outputs. 595 ** 596 ** *pzTail is made to point to the first character past the end of the first 597 ** SQL statement in zSql. This routine only compiles the first statement 598 ** in zSql, so *pzTail is left pointing to what remains uncompiled. 599 ** 600 ** *ppVm is left pointing to a "virtual machine" that can be used to execute 601 ** the compiled statement. Or if there is an error, *ppVm may be set to NULL. 602 ** If the input text contained no SQL (if the input is and empty string or 603 ** a comment) then *ppVm is set to NULL. 604 ** 605 ** If any errors are detected during compilation, an error message is written 606 ** into space obtained from malloc() and *pzErrMsg is made to point to that 607 ** error message. The calling routine is responsible for freeing the text 608 ** of this message when it has finished with it. Use sqlite_freemem() to 609 ** free the message. pzErrMsg may be NULL in which case no error message 610 ** will be generated. 611 ** 612 ** On success, SQLITE_OK is returned. Otherwise and error code is returned. 613 */ 614 int sqlite_compile( 615 sqlite *db, /* The open database */ 616 const char *zSql, /* SQL statement to be compiled */ 617 const char **pzTail, /* OUT: uncompiled tail of zSql */ 618 sqlite_vm **ppVm, /* OUT: the virtual machine to execute zSql */ 619 char **pzErrmsg /* OUT: Error message. */ 620 ); 621 622 /* 623 ** After an SQL statement has been compiled, it is handed to this routine 624 ** to be executed. This routine executes the statement as far as it can 625 ** go then returns. The return value will be one of SQLITE_DONE, 626 ** SQLITE_ERROR, SQLITE_BUSY, SQLITE_ROW, or SQLITE_MISUSE. 627 ** 628 ** SQLITE_DONE means that the execute of the SQL statement is complete 629 ** an no errors have occurred. sqlite_step() should not be called again 630 ** for the same virtual machine. *pN is set to the number of columns in 631 ** the result set and *pazColName is set to an array of strings that 632 ** describe the column names and datatypes. The name of the i-th column 633 ** is (*pazColName)[i] and the datatype of the i-th column is 634 ** (*pazColName)[i+*pN]. *pazValue is set to NULL. 635 ** 636 ** SQLITE_ERROR means that the virtual machine encountered a run-time 637 ** error. sqlite_step() should not be called again for the same 638 ** virtual machine. *pN is set to 0 and *pazColName and *pazValue are set 639 ** to NULL. Use sqlite_finalize() to obtain the specific error code 640 ** and the error message text for the error. 641 ** 642 ** SQLITE_BUSY means that an attempt to open the database failed because 643 ** another thread or process is holding a lock. The calling routine 644 ** can try again to open the database by calling sqlite_step() again. 645 ** The return code will only be SQLITE_BUSY if no busy handler is registered 646 ** using the sqlite_busy_handler() or sqlite_busy_timeout() routines. If 647 ** a busy handler callback has been registered but returns 0, then this 648 ** routine will return SQLITE_ERROR and sqltie_finalize() will return 649 ** SQLITE_BUSY when it is called. 650 ** 651 ** SQLITE_ROW means that a single row of the result is now available. 652 ** The data is contained in *pazValue. The value of the i-th column is 653 ** (*azValue)[i]. *pN and *pazColName are set as described in SQLITE_DONE. 654 ** Invoke sqlite_step() again to advance to the next row. 655 ** 656 ** SQLITE_MISUSE is returned if sqlite_step() is called incorrectly. 657 ** For example, if you call sqlite_step() after the virtual machine 658 ** has halted (after a prior call to sqlite_step() has returned SQLITE_DONE) 659 ** or if you call sqlite_step() with an incorrectly initialized virtual 660 ** machine or a virtual machine that has been deleted or that is associated 661 ** with an sqlite structure that has been closed. 662 */ 663 int sqlite_step( 664 sqlite_vm *pVm, /* The virtual machine to execute */ 665 int *pN, /* OUT: Number of columns in result */ 666 const char ***pazValue, /* OUT: Column data */ 667 const char ***pazColName /* OUT: Column names and datatypes */ 668 ); 669 670 /* 671 ** This routine is called to delete a virtual machine after it has finished 672 ** executing. The return value is the result code. SQLITE_OK is returned 673 ** if the statement executed successfully and some other value is returned if 674 ** there was any kind of error. If an error occurred and pzErrMsg is not 675 ** NULL, then an error message is written into memory obtained from malloc() 676 ** and *pzErrMsg is made to point to that error message. The calling routine 677 ** should use sqlite_freemem() to delete this message when it has finished 678 ** with it. 679 ** 680 ** This routine can be called at any point during the execution of the 681 ** virtual machine. If the virtual machine has not completed execution 682 ** when this routine is called, that is like encountering an error or 683 ** an interrupt. (See sqlite_interrupt().) Incomplete updates may be 684 ** rolled back and transactions cancelled, depending on the circumstances, 685 ** and the result code returned will be SQLITE_ABORT. 686 */ 687 int sqlite_finalize(sqlite_vm*, char **pzErrMsg); 688 689 /* 690 ** This routine deletes the virtual machine, writes any error message to 691 ** *pzErrMsg and returns an SQLite return code in the same way as the 692 ** sqlite_finalize() function. 693 ** 694 ** Additionally, if ppVm is not NULL, *ppVm is left pointing to a new virtual 695 ** machine loaded with the compiled version of the original query ready for 696 ** execution. 697 ** 698 ** If sqlite_reset() returns SQLITE_SCHEMA, then *ppVm is set to NULL. 699 ** 700 ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ****** 701 */ 702 int sqlite_reset(sqlite_vm*, char **pzErrMsg); 703 704 /* 705 ** If the SQL that was handed to sqlite_compile contains variables that 706 ** are represeted in the SQL text by a question mark ('?'). This routine 707 ** is used to assign values to those variables. 708 ** 709 ** The first parameter is a virtual machine obtained from sqlite_compile(). 710 ** The 2nd "idx" parameter determines which variable in the SQL statement 711 ** to bind the value to. The left most '?' is 1. The 3rd parameter is 712 ** the value to assign to that variable. The 4th parameter is the number 713 ** of bytes in the value, including the terminating \000 for strings. 714 ** Finally, the 5th "copy" parameter is TRUE if SQLite should make its 715 ** own private copy of this value, or false if the space that the 3rd 716 ** parameter points to will be unchanging and can be used directly by 717 ** SQLite. 718 ** 719 ** Unbound variables are treated as having a value of NULL. To explicitly 720 ** set a variable to NULL, call this routine with the 3rd parameter as a 721 ** NULL pointer. 722 ** 723 ** If the 4th "len" parameter is -1, then strlen() is used to find the 724 ** length. 725 ** 726 ** This routine can only be called immediately after sqlite_compile() 727 ** or sqlite_reset() and before any calls to sqlite_step(). 728 ** 729 ******* THIS IS AN EXPERIMENTAL API AND IS SUBJECT TO CHANGE ****** 730 */ 731 int sqlite_bind(sqlite_vm*, int idx, const char *value, int len, int copy); 732 733 /* 734 ** This routine configures a callback function - the progress callback - that 735 ** is invoked periodically during long running calls to sqlite_exec(), 736 ** sqlite_step() and sqlite_get_table(). An example use for this API is to keep 737 ** a GUI updated during a large query. 738 ** 739 ** The progress callback is invoked once for every N virtual machine opcodes, 740 ** where N is the second argument to this function. The progress callback 741 ** itself is identified by the third argument to this function. The fourth 742 ** argument to this function is a void pointer passed to the progress callback 743 ** function each time it is invoked. 744 ** 745 ** If a call to sqlite_exec(), sqlite_step() or sqlite_get_table() results 746 ** in less than N opcodes being executed, then the progress callback is not 747 ** invoked. 748 ** 749 ** Calling this routine overwrites any previously installed progress callback. 750 ** To remove the progress callback altogether, pass NULL as the third 751 ** argument to this function. 752 ** 753 ** If the progress callback returns a result other than 0, then the current 754 ** query is immediately terminated and any database changes rolled back. If the 755 ** query was part of a larger transaction, then the transaction is not rolled 756 ** back and remains active. The sqlite_exec() call returns SQLITE_ABORT. 757 */ 758 void sqlite_progress_handler(sqlite*, int, int(*)(void*), void*); 759 760 #ifdef __cplusplus 761 } /* End of the 'extern "C"' block */ 762 #endif 763 764 #endif /* _SQLITE_H_ */ 765
