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